HarnessRouter：用一个 API 调用多种 Agent Harness

把 Claude Code、Codex 等 coding agent 接进一个产品时，除了请求模型，还要分别处理会话、文件、流式进度和取消任务。HarnessRouter 是一个自托管的 AI agent harness API：它通过 OpenAI Responses 兼容接口连接不同的执行 harness，并由 metadata.harness_id 选择实际后端。截至 2026 年 11 月 1 日，README 列出 30 种 harness 基础项；GitHub 仓库有 3,805 颗星，采用 Apache-2.0 许可证。

核心功能

HarnessRouter 把不同 coding agent 的运行入口放在一个产品接口后面，让应用可以替换后端 harness，而不必为每种工具从头维护一套会话协议。它实现了 Unified Harness Protocol（UHP），并兼容 OpenAI Responses API 的请求表面。

• 接入多种 harness：README 于 2026 年 11 月 1 日列出 30 种基础 harness，包括 Codex、Claude Code、Hermes、Pi、Gemini CLI、OpenCode 和 OpenHands。具体可用项还取决于 provider 与部署配置。
• 沿用 Responses 风格 API：产品后端可以向同一 API 提交任务，再用 metadata.harness_id 选择执行 harness。已有的 Responses SDK、流式解析器和界面组件可以复用相同请求结构。
• 管理完整任务过程：支持持久会话、流式进度、输入文件和生成物、取消操作，以及结构化错误与执行 trace。相同的会话也可以继续接收后续指令。
• 通过本地控制台试跑：内置 Console 可配置 harness、模型、技能、插件和工具。README 中的示例任务可以回放录制结果，让团队先查看界面流程，不必为该演示调用模型。
• 自托管社区版：Apache-2.0 社区版把 Console、Gateway 和 Runner 放进一个 Docker 部署中，provider key、会话、文件和工作区由部署者管理。模型请求仍会发送到你配置的模型提供商。

README 的 30 项指当前列出的 harness 基础项，不代表每种都能在任意操作系统、provider 或容器配置中立即运行；仓库的 support matrix 按 harness 列出安装方式和 provider 限制。项目对外提供 Responses API，内部由 Gateway 连接 Runner 执行任务，因此它整合的是运行时接口，而不是模型本身。

典型使用场景

1. 给产品增加 coding agent：产品团队可以复用一个 Responses 风格的 API，在后端选择 Codex、Claude Code 或其他已启用 harness，并接收文件与流式结果。
2. 在自有基础设施运行任务：需要本机 CLI、文件系统或 Git 工作流的团队，可以把社区版部署在自己管理的服务器上，再由后端系统调用。
3. 评估 harness 组合：用控制台先创建一个设置，逐项选择 harness 与模型，观察任务如何运行；切换到新的 harness 不需要重写产品侧的整个 API 接口。

部署边界也值得提前确认。社区版把 Console、Gateway 和 Runner 放在一个容器中；每个 session 使用独立工作区和操作系统用户，但不是每个任务各跑一个容器。需要更强隔离时，应结合受信任的主机和网络环境设计，不要直接把 loopback 端口暴露出去。

HarnessRouter 负责接入 agent 执行环境；如果要在模型、MCP 和 A2A 流量之间做路由，可以看相邻方向的 agentgateway。

快速上手

README 的社区版快速启动命令使用 Docker，并把服务仅绑定到本机回环地址：

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

首次启动会安装已启用的 harness CLI；README 建议准备约 4 GB 磁盘空间，并自行提供模型 provider API key。浏览器打开 http://localhost:3000 后，需要立刻更改 README 公布的默认控制台密码，再考虑其他访问路径。接入产品时，HarnessRouter API key 应保存在服务端，不能放进浏览器代码。

控制台密码、模型 provider key 和产品调用用的 HarnessRouter API key 用途不同。provider key 授权模型请求；API key 访问你的 HarnessRouter 实例。应分别保存和轮换这些凭据，避免写入公开代码仓库。

小结

HarnessRouter 适合需要在产品里调用多个 coding-agent runtime、又希望将任务、会话和文件统一管理的开发团队。它把 OpenAI Responses 兼容接口、UHP 和多种开源 harness 连接起来；仓库为 Python，使用 Apache-2.0，星标数核验于 2026 年 11 月 1 日。

社区版自托管并不等于本地模型推理：provider key 仍用于向你配置的模型服务发请求，也没有附带模型或试用额度。首次启动要安装 harness CLI，部署需要 Docker 和约 4 GB 空间；每个 CLI 仍受其上游许可约束。实例先保持本机访问，并更改默认凭据后再规划对外连接。