智能体运行框架路由HarnessRouter/harnessrouter

智能体运行框架的统一接口。

无需处理运行框架工程即可构建智能体产品。 HarnessRouter 是基础设施层，可将 Codex 和 Claude Code 等现有运行框架转变为即插即用的智能体后端，让你的产品通过一个 API 运行任务、获取结果并切换运行框架。

HarnessRouter 实现了统一运行框架协议（UHP），并提供兼容 OpenAI Responses 的 API，处理持久会话、流式进度、文件、产物、取消和结构化失败。

切换测试框架。优化成本与延迟。

同一任务上的八种测试框架 × 模型配置。每项指标均比较其最佳与最差结果。成本最低和速度最快的配置因任务而异。方法论

[!TIP]
开始使用： 本地运行 · 集成到你的产品中 · 入门套件 · 使用托管云服务

快速开始

在你掌控的基础设施上，使用你自己的提供商密钥自托管社区版。

从一条 Docker 命令开始，等待首次启动，然后连接模型提供商并运行你的第一个任务。

你需要： Docker · 约 4 GB 磁盘空间 · 一个提供商 API 密钥

无需 HarnessRouter 账户。不捆绑模型或试用密钥。

1. 启动 HarnessRouter

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

Docker 会在需要时拉取镜像。该命名卷会在重启之间保留你的数据库、文件、已安装的测试框架 CLI 和工作区。

已有安装或自定义设置

已经安装？ docker pull harnessrouter/harnessrouter 会下载最新镜像，但不会升级正在运行的容器。请遵循升级与备份指南。

端口 3000 被占用？ 改用 -p 127.0.0.1:3100:3000，并改为打开端口 3100。在使用初始凭据期间，请保持回环绑定。

不要添加 --user。 入口点和 Runner 需要 root 权限来管理每个会话的用户。Console 和 Gateway 以非特权方式运行；代理进程以各自会话的用户身份运行。

有关版本固定、Compose 和脚本化设置，请参阅设置指南。

2. 等待首次启动

docker logs -f harnessrouter

首次启动会安装已启用的测试框架 CLI。当日志显示以下内容时继续：

[harnessrouter] ready on :3000

按 Ctrl+C 停止跟踪日志。容器会继续运行。

Console 未就绪或缺少某个测试框架？

如果浏览器拒绝连接，请在 Console 完成启动期间等待几秒后重试。如果缺少某个测试框架，请检查日志中的 backends available: 以及任何 requested but not installed 警告。

3. 打开控制台
打开 http://localhost:3000，或你选择的主机端口，然后登录：

用户名harnessrouter密码harnessrouter

[!WARNING]
请在个人资料中更改默认密码。 在更改密码之前，请保持实例仅限本地访问。保存操作会短暂重启控制台，并使其他浏览器退出登录。

查看登录界面

HarnessRouter 社区版登录界面

使用现有卷或自定义凭据？查看凭据优先级和设置。

这些凭据用于登录控制台。在此运行任务不需要 HarnessRouter API 密钥。

4. 连接模型提供商

打开侧边栏中的 Bring Your Own Key，然后按 Add Integration。选择一个提供商，为该集成命名，并添加其 API 密钥。其支持的模型将在控制台中可用。

此提供商密钥用于授权模型请求。它与下方用于产品集成的 HarnessRouter API 密钥是分开的。

查看提供商设置界面

在 HarnessRouter 中添加模型提供商

5. 运行你的第一个任务

打开 Agent harnesses，选择一个受支持的 harness，然后选择 New task。选择一个可用的模型，并给智能体一个具体的任务。在同一会话中跟踪实时进度并打开它生成的文件。

Hermes 审阅一份虚构的 NDA 并打开红线修订输出

在上面的示例运行中，Hermes 审阅了一份虚构的 NDA，并生成了红线修订版、干净副本和谈判备忘录。

配置自定义 harness（可选）

内置 harness 无需此步骤即可使用。当你想要针对你的产品量身定制可复用的行为时，请创建自定义 harness。

1. 创建。 在 Agent harnesses 中选择 New harness。在 Add harness 中，一并设置 Name、Base harness 和 Default model，然后选择 Create and configure。
2. 自定义。 在 Harness Settings 中，添加 Agent instructions，配置 Tools（使用 Add MCP 添加可选的 MCP 服务器），并按需添加 Skills。
3. 保存并测试。 选择 Save Changes，然后选择 Run Task 以测试已保存的配置。

你可以稍后在 Settings 中更改默认模型，但基础 harness 在创建后无法更改。

观看配置演示 · 48 秒

创建和配置自定义 harness 的动画演示，包括指令、工具和技能。

为客户反馈分析配置 DeepSeek Harness。

使用一个 API 将你的 harness 集成到你的产品后端

使用内置或自定义 harness 作为可插拔的 agent 后端来运行产品任务。调用你自托管实例的兼容 OpenAI Responses 的 API，并通过 metadata.harness_id 选择 harness。无需 Cloud 部署。

一旦你的 harness 在 Console 中成功运行：

1. 在同一个 CE 实例的 Console 侧边栏中打开 API Keys（默认本地地址），然后选择 Create API key。
2. 将仅显示一次的密钥存储为你产品后端中的 HARNESSROUTER_API_KEY。切勿在浏览器代码中暴露它。此 CE 签发的密钥与你的 Console 密码和 provider 密钥是分开的。
3. 使用 Console 中显示的 Harness ID 以及你已连接 provider 所提供的模型来调用 API。

export HARNESSROUTER_BASE_URL=http://localhost:3000/api/harness

curl --fail-with-body -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
}'

该任务及其记录会出现在 Console 中的同一工作区中。设置 "stream": true 以接收服务器发送事件。

当你的后端和 CE 运行在同一台计算机上时，默认 URL 可用。从另一台机器或容器访问时，请使用 CE 实例的可访问 URL。阅读完整的自托管 API 和网络指南 →

你的应用程序可以…如何实现

启动任务发送指令并检查执行状态
继续会话使用 previous_response_id 发送后续指令
流式传输进度在 agent 工作时接收实时更新
处理文件附加输入文件并获取生成的输出
取消任务停止不再需要的工作
检查执行情况查看结构化错误和执行跟踪

将 agent harness 作为你产品的可插拔后端

使用 agent harness 为你产品中的 agentic 功能提供支持，包括知识工作任务，例如创建内容和分析数据。探索这些即用型套件，了解 harness 作为可插拔后端的实际应用。

幻灯片
代理框架将你的简报转化为幻灯片内容和布局，生成可编辑的演示文稿。

表格
代理框架使用每一行的数据来执行任务，并将结果写回表格中。

仪表板
代理框架读取你的数据库架构，并编写 SQL 查询来驱动仪表板图表。

视频
代理框架将你的简报转化为镜头计划，并调用视频工具为时间线生成片段。

探索入门套件 →

设置说明与许可

开始： 在控制台中打开 入门套件，选择你已连接的提供商所支持的框架和模型。

仪表板： 使用可访问的数据库和只读数据库账户。设置 HR_SECRET_KEY 来加密存储的连接，并在连接前查看示例行设置。

许可： 入门套件使用与社区版不同的条款。

设置指南 →

部署选择

自托管以掌控一切

- 你的基础设施。 一次 Docker 部署即可运行控制台、网关和运行器。
- 你的凭据和状态。 提供商密钥、会话、文件和工作区均由你掌控。模型请求仍会发送到你配置的提供商。
- 真实工作区。 原生文件系统、shell 和 Git 工作流，并支持独立的会话工作区。
- 无控制台产品分析。 社区版禁用了控制台分析管道。

选择你的云端路径

选择 HarnessRouter Cloud 以获得托管部署、维护和扩展能力，任务通过相同的 API 契约在无服务器、隔离的沙箱中运行。

| 本地 → 云端 | 直接在云端开始 |
|---|---|
| 带上你在本地配置的自定义框架。按照上传指南操作 → | 无需本地部署即可创建和运行框架。打开 HarnessRouter Cloud → |
对于本地上传： 在本地实例上设置 HR_SECRET_KEY，以加密保存的目标密钥。在设置中保存你的自定义 harness，选择上传到云端，然后使用目标 Cloud 工作区 API 密钥连接目标。

上传会复制 harness 配置，而不会复制提供商密钥、会话或生成的文件。再次上传会替换该目标的托管副本。

社区版内部

┌─ HarnessRouter container ─────────────────────────────────┐
│  Console :3000   ← only published port                    │
│       │ same-origin proxy                                 │
│       ▼                                                   │
│  Gateway :8080   Responses API + harness lifecycle        │
│       │ loopback                                          │
│       ▼                                                   │
│  Runner  :8081   runs harnesses in session workspaces     │
│                                                           │
│  /data volume   database · files · secrets · workspaces   │
└───────────────────────────────────────────────────────────┘

Gateway 和 Runner 在容器内监听回环地址。会话使用独立的工作区和操作系统用户，而不是独立的容器。Console 是 UI 和 API 的入口点。

参见配置、升级和备份，以及使用 TLS 的公共部署。

统一 Harness 协议

统一 Harness 协议（UHP）是由社区版和 HarnessRouter Cloud 实现的公开、带版本的契约。其任务接口有意兼容 OpenAI Responses API，因此现有的 Responses SDK、流式解析器和 UI 组件可以与 UHP 服务器配合使用。UHP 定义了 harness 执行语义，涵盖 harness 选择、持久会话、文件、取消以及 harness 管理的工具和技能。

本仓库包含 Apache 2.0 参考实现、机器可读的 schema 以及一致性测试套件。

资源用途

规范规范性协议行为
OpenAI Responses 兼容性与现有 OpenAI Responses API 客户端的兼容性
OpenAPI 和 JSON Schema机器可读契约
一致性测试套件可测试的兼容性要求
治理标准如何演进

资源

| 目标 | 资源 |
|---|---|
| 构建 | 云与集成文档 · API 指南 · 入门套件 |
| 部署 | 设置与运维 · 本地 → 云端 · HarnessRouter Cloud |
| 协议 | 统一 Harness 协议 (UHP) |
| 社区 | 加入社区 (Discord) · 贡献 · LinkedIn · X · 安全 |

Star 历史

许可证

HarnessRouter 社区版基于 Apache 2.0 许可。Agent harness CLI 在首次启动时安装，并仍受其各自上游许可证的约束。有关第三方声明，请参阅 NOTICE；有关其单独的许可条款，请参阅 入门套件仓库。

HarnessRouter 是全球首个面向 agent harness 的统一接口。