HarnessRouter 一文读懂用统一 API 驱动 Codex、Claude Code 等 10 AI Agent 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/harnessrouterHarnessRouter是一个自托管Apache-2.0 协议的 Agent Harness 统一接口项目它把 Codex、Claude Code、Hermes、Pi、DeepSeek Harness 等 10 个 AI Agent Harness 装进一个 Docker 容器对外只暴露一个 OpenAI Responses 兼容的统一 API。你的产品只需对接一次就能启动任务、流式接收进度、续接会话、取回文件、随时取消并在不同 Harness 之间自由切换——自带模型 Key跑在你自己的基础设施上。为什么需要 HarnessRouter一个 API 解决 10 个 Harness 的对接难题每个 Agent Harness比如 Codex、Claude Code都已经会干活但它们彼此之间没有统一的驱动方式怎么开始任务、怎么跟踪进度、怎么继续对话、怎么取消、怎么拿文件、怎么理解失败原因……每个产品都不得不为每个 Harness 重新写一遍对接代码。接 4 个 Harness 就是 4 × 9 36 份集成职责接得越多负担呈乘法增长。HarnessRouter 的做法是产品只对接一次 UHP 标准 API其余的交给它。痛点HarnessRouter 的解法每个 Harness 一套私有对接逻辑一个 OpenAI Responses 兼容 API用metadata.harness_id选择 Harness会话、文件、取消各自实现持久会话、SSE 流式进度、文件上传/下载、任务取消全部内置失败原因五花八门结构化错误分类统一处理重试与幂等想换 Harness 就要重写代码换harness_id即可同一任务可在不同 Harness 间切换控制台长什么样一眼看到 10 个 AI Agent Harness启动后的控制台首页就是 Harness 列表Codex、Claude Code、Hermes、Pi、DeepSeek Harness、OpenCode、Gemini CLI、Cline、Oh My Pi 等内置系统 Harness 一目了然还能看到每个 Harness 的健康状态、运行时模型与最近活动。除了内置 Harness你还可以通过New harness创建自定义 Harness指定基座 Harness、默认模型再配上 Agent 指令、MCP 工具和 Skills做出贴合自己业务的可复用专属 Agent。HarnessRouter 快速安装步骤一条 Docker 命令完成部署自托管 Community Edition 只需要三样东西Docker、约 4 GB 磁盘、一个模型厂商的 API Key。无需注册账号镜像里也不捆绑任何 Key。第 1 步启动容器docker run -d --name harnessrouter \ -p 127.0.0.1:3000:3000 \ -v harnessrouter:/data \ harnessrouter/harnessrouterharnessrouter命名卷会持久化保存数据库、文件、已安装的 Harness CLI 和各会话工作区。第 2 步等待首次启动完成docker logs -f harnessrouter首次启动会自动安装启用的 Harness CLIClaude Code、Codex、Hermes、Pi、Cline、Goose 等看到[harnessrouter] ready on :3000即可。第 3 步登录控制台打开http://localhost:3000用默认账号密码harnessrouter / harnessrouter登录然后尽快在 Profile 里修改默认密码。详细的六步安装流程、升级与备份、公网部署TLS等内容都在 docs/self-hosting-guide.md 中可配合 docker-compose.yml 与 Dockerfile 使用。如何连接模型提供商并运行第一个任务HarnessRouter 是自带 KeyBYOK模式Provider 的 API Key 只用于授权模型请求由你自己保管。在侧边栏打开Bring Your Own Key → Add Integration选择模型厂商、命名并填入 API Key该厂商支持的模型立即可用进入Agent harnesses选一个 Harness 点New task选择模型给 Agent 一个具体任务实时查看流式进度产物文件直接在同一个会话里打开。比如让 Hermes 审阅一份虚构的 NDA 合同它会生成红线标注版、干净副本和谈判备忘录三个文件全程进度可追踪、可取消。如何用统一 API 把 Harness 集成进你的产品在控制台跑通一个 Harness 后产品集成只需三步在控制台API Keys页面创建 API Key存入后端环境变量HARNESSROUTER_API_KEY切勿暴露在浏览器端调用POST /v1/responses请求体中带上metadata.harness_id指定 Harnessmodel使用已连接 Provider 提供的模型需要实时进度时设置stream: true即可获得 Server-Sent Events 流。curl --fail-with-body -sS http://localhost:3000/api/harness/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 }你的应用通过这一个 API 就能完成启动任务、用previous_response_id续接会话、流式跟踪、文件输入/产物下载、取消任务、查看结构化错误与执行轨迹。完整的 OpenAPI 描述在/v1/openapi.json浏览器可访问/v1/docs。由于任务面刻意与 OpenAI Responses API 兼容现有的 Responses SDK、流式解析器、UI 组件可以零改动地对接 UHP 服务器——这是一个兼容性设计而非偶然。什么是 Unified Harness ProtocolUHPHarness 的开放标准HarnessRouter 仓库同时是一个标准的参考实现。protocol/ 目录下的 Unified Harness ProtocolUHP定义了 Harness 与产品之间的公开、带版本号的契约资源作用protocol/versions/2026-09-28/规范章节架构、任务、流式、会话、文件、错误、安全、插件、环境等 12 章protocol/schema/机器可读契约OpenAPI 3.1 JSON Schemaprotocol/conformance/一致性测试套件通过它才算UHP 兼容protocol/GOVERNANCE.md标准的演进治理规则一个关键区别模型 API 给你的是一个轮次消息进、Token 出UHP 给你的是一个任务工作进一个会自己用工具、自己维护会话、最后交回结果和文件的运行中 Agent 出。UHP 不需要任何托管服务——合规服务器可以完全跑在你自己的机器、自己的 Provider Key 上。HarnessRouter 自托管架构三层设计数据全在自己手里自托管版是一个 Docker 容器里的三层结构┌─ HarnessRouter 容器 ────────────────────────────────┐ │ Console :3000 ← 唯一对外端口UI API 入口 │ │ ▼ 同源代理 │ │ Gateway :8080 Responses API Harness 生命周期 │ │ ▼ loopback │ │ Runner :8081 在各会话工作区中运行 Harness │ │ /data 卷 数据库 · 文件 · 密钥 · 工作区 │ └────────────────────────────────────────────────────┘你的基础设施一个容器部署 Console、Gateway、Runner 三层你的凭据与状态Provider Key、会话、文件、工作区全部本地可控真实工作区Agent 拥有原生文件系统、Shell 和 Git 工作流每个会话独立工作区 独立操作系统用户见 runner/environments.py 与 docs/environments.md 的项目环境设计无产品遥测Community Edition 关闭了控制台的统计分析管道。核心代码分别在 gateway/Responses API、会话与文件平面和 runner/各 Harness 的驱动适配如 runner/systemone_driver.py、runner/aider_driver.py协议一致性测试报告见 protocol/conformance/reports/。谁适合用 HarnessRouter适用场景速览✅适合想给自己的产品加 AI Agent 能力但不想为 Codex / Claude Code / Hermes 各写一套集成希望数据、Key、会话留在自己的服务器上自托管 Apache-2.0需要在成本与延迟不同的 Harness × 模型组合间切换——官方基准显示同一任务下最优与最差组合的成本差距可达99.8%、端到端延迟差距达3.2 倍方法见 docs/benchmark.md想基于开放标准UHP构建自己的 Agent 基础设施。❌不适合只需要普通 Chat 补全、用不到工具调用与会话任务的纯模型调用场景无法运行 Docker 的环境也可以 fork 仓库自行部署见 CONTRIBUTING.md。一句话总结HarnessRouter 一次对接N 个 Agent Harness 随便换。一条 Docker 命令起步一个 API 跑通任务、会话、流式、文件与取消UHP 标准保证未来生态互通。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考