HarnessRouter OpenAI Responses 兼容 API 入门：如何用 metadata.harness

HarnessRouter OpenAI Responses 兼容 API 入门：如何用 metadata.harness_id 一行切换 Harness

【免费下载链接】harnessrouterHarnessRouter Community Edition: the self-hosted, Apache-2.0 edition of the unified interface for agent harnesses. Run Codex, Claude Code, Hermes, PI, DSH, and more through one API, with sessions, streaming, files, cancellation, and failure handling. Implements the Unified Harness Protocol (UHP), an open standard. Your keys, your infrastructure.项目地址: https://gitcode.com/gh_mirrors/ha/harnessrouter

HarnessRouter 是开源的 Agent Harness 统一路由网关（社区版，Apache-2.0），提供 OpenAI Responses 兼容 API，让你用一个接口驱动 Codex、Claude Code、Hermes、Pi 等多种 Agent Harness，只需在请求的metadata.harness_id中填一行，即可切换底层 Harness，并自带会话、流式输出、文件与失败处理。本文带你从零部署到发出第一个 API 请求。

为什么需要 HarnessRouter：一个接口搞定 N 个 Harness 🧩

如果你的产品要接入多个编码/工作 Agent，传统做法是每个 Harness 各写一套集成：部署、任务轮询、会话管理、流式解析、文件传输、失败恢复……Harness 越多，重复工作越多。

而 HarnessRouter 把这些收敛为一个 OpenAI Responses 兼容端点POST /v1/responses：

✅兼容生态：现有的 Responses SDK、流式解析器、UI 组件可以直接对接，零改造；
✅一行切换：通过metadata.harness_id选择 Harness，业务代码不用改；
✅生命周期齐全：会话续接（previous_response_id）、SSE 流式进度、文件上传下载、任务取消、结构化错误，开箱即用；
✅自托管：你的 Key、你的基础设施，一条 Docker 命令部署。

3 分钟快速安装 HarnessRouter 🐳

准备工作：Docker · 约 4 GB 磁盘 · 一个模型提供商的 API Key（无需注册 HarnessRouter 账号）。

docker run -d --name harnessrouter \ -p 127.0.0.1:3000:3000 \ -v harnessrouter:/data \ harnessrouter/harnessrouter

首次启动会自动安装已启用的 Harness CLI，看到日志输出[harnessrouter] ready on :3000即就绪。然后：

浏览器打开http://localhost:3000，用默认账号harnessrouter/harnessrouter登录控制台（登录后记得在 Profile 中修改密码）；
在侧边栏Bring Your Own Key中点击Add Integration，选择提供商并填入 API Key，其支持的模型即刻可用；

在侧边栏API Keys中点击Create API key，把只显示一次的密钥存为环境变量HARNESSROUTER_API_KEY——这是产品后端调用 API 用的密钥，与登录密码、提供商 Key 相互独立，切勿暴露在前端代码中。

找到你的 Harness ID：查看可用 Agent Harness 列表 🔍

打开控制台Agent harnesses页面，可以看到内置 Harness 一览：Codex、Claude Code、Hermes、Pi、DeepSeek Harness、OpenCode、Qwen Code、Gemini CLI、Cline、Oh My Pi 等，每个都标注了运行时的默认模型与健康状态。

页面里每个 Harness 都有唯一的 Harness ID（形如chrn_…）。也可以通过 API 枚举：

curl -sS "http://localhost:3000/api/harness/v1/harnesses" \ -H "Authorization: Bearer $HARNESSROUTER_API_KEY"

Harness 对象中还包含baseLabel（如 Claude Code）、base（运行时标识）、可用的 MCP Servers 与 Skills，帮助你判断它适合哪类任务。字段定义见 protocol/versions/2026-09-28/harnesses.md。

第一个请求：用 metadata.harness_id 一行切换 Harness ⚡

调用POST /v1/responses，请求体就是一个标准 Responses 请求，Harness 选择只占metadata里的一个字段：

export HARNESSROUTER_BASE_URL=http://localhost:3000/api/harness curl -sS "$HARNESSROUTER_BASE_URL/v1/responses" \ -H "Authorization: Bearer ${HARNESSROUTER_API_KEY:?}" \ -H 'content-type: application/json' \ -d '{ "input": "Reply with exactly: it works.", "metadata": {"harness_id": "codex"}, "model": "gpt-5.4-mini", "stream": false }'

想换 Harness？把harness_id改成另一个值，其余代码一行不动。协议层面对这个字段有明确的承诺（protocol/versions/2026-09-28/tasks.md）：

缺省：不带harness_id时使用默认 Harness，并会在响应metadata中告知用了哪个；
找不到：填了不存在的 ID，返回404+code: "harness_not_found"；
会话冲突：previous_response_id与harness_id不一致时，返回409+code: "harness_mismatch"；
模型不可用：要么报422 model_unavailable，要么回退到该 Harness 的默认模型，并如实记录在metadata.model_fallback中——绝不静默替换。

之所以把 Harness 放进metadata而不是顶层字段，正是因为metadata本就是 Responses 规范定义的扩展点，现有 Responses SDK 无需打补丁即可发送。

切换之后：会话、流式与文件也能无缝续接 🚀

切换 Harness 不只是换个执行器，整个任务生命周期都保留在同一套契约里：

能力	用法
继续会话	带上`previous_response_id`发送后续指令
流式进度	请求体加`"stream": true`，接收 Server-Sent Events
文件	`POST /v1/files`上传输入，按文件名在响应中取回产物
取消任务	通过生命周期端点停止不再需要的任务
排查	结构化错误码 + 执行轨迹，API 全量描述见`$HARNESSROUTER_BASE_URL/v1/openapi.json`

完整的接口契约（OpenAPI 与 JSON Schema）在 protocol/schema/ 目录下，机器可读、版本化管理，UHP 规范正文见 protocol/versions/2026-09-28/index.md。

进阶玩法：自定义 Harness 与部署选项 🛠️

自定义 Harness：在控制台New harness中指定基础 Harness、默认模型、Agent 指令、MCP 工具与 Skills，形成面向你产品的可复用行为封装，之后照样用harness_id一行调用；
多环境：UHP 支持通过metadata附加environment，为同一 Harness 挂载不同运行环境；
网络部署：跨机器或跨容器访问时请使用可达的实例地址，详见 docs/self-hosting-guide.md；
合规测试：想验证自己的服务器是否符合 UHP？仓库内置 protocol/conformance/ 一致性测试套件。

写在最后

HarnessRouter 把"Harness 工程"下沉为基础设施：你继续写熟悉的 OpenAI Responses 请求，用metadata.harness_id一行在 Codex、Claude Code、Hermes、Pi 之间自由切换，同时获得会话、流式、文件、取消与失败处理这些产品级能力。密钥在手里，基础设施在脚下，剩下的交给 API。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考