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

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

做智能体产品，不必自己啃运行框架工程。 HarnessRouter 是基础设施层，把 Codex、Claude Code 这类现成的运行框架变成开箱即用的智能体后端。你的产品只需调一个 API，就能跑任务、取结果、换运行框架。

HarnessRouter 实现 Unified Harness Protocol (UHP)，并提供兼容 OpenAI Responses 的 API，负责持久会话、流式进度、文件、产物、取消和结构化失败。

切换 harness，优化成本与延迟。

同一任务上，八种 harness × 模型配置。每项指标对比其最好与最差结果。成本最低、速度最快的配置因任务而异。方法说明

目前支持 30 种 harness 基础： Codex、Claude Code、Hermes、Pi、DeepSeek Harness、OpenCode、Kilo Code、Qwen Code、Gemini CLI、Cline、Oh My Pi、goose、Kimi Code CLI、MiniMax Code、Aider、OpenHands、CheetahClaws、Grok Build、Agent Zero、System One、Qoder Cloud Agent、MiMo Code、jcode、OpenSquilla、nanobot、ZeroClaw、Mistral Vibe、Docker Agent、fast-agent 和 Deep Agents Code。支持矩阵列出哪些能在哪个服务商上运行。

[!TIP]
快速上手：本地运行 · 集成到你的产品 · 入门套件 · 使用托管 Cloud

快速开始

自托管社区版，用你自己的服务商密钥，跑在你掌控的基础设施上。

一条 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 会拉取镜像。命名卷会在重启之间保留你的数据库、文件、已安装的 harness 命令行和 workspace。

已有安装或自定义配置

已经装过？ docker pull harnessrouter/harnessrouter 只下载最新镜像，不会升级正在运行的容器。请按升级与备份指南操作。

3000 端口被占用？ 改用 -p 127.0.0.1:3100:3000，然后打开 3100 端口。使用初始凭据期间，保持回环地址绑定。

不要加 --user。 入口脚本和 Runner 需要 root 权限来管理每个会话的用户。Console 和 Gateway 以非特权身份运行；智能体进程以各自会话的用户身份运行。

版本锁定、Compose 和脚本化安装，见安装指南。

2. 等待首次启动

docker logs -f harnessrouter
首次启动会安装已启用的 harness 命令行。当日志出现以下内容时继续：

[harnessrouter] ready on :3000

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

控制台没就绪，或者缺少某个 harness？

如果浏览器拒绝连接，等几秒再重试，控制台还在启动。如果缺少某个 harness，检查日志里的 backends available: 和 requested but not installed 警告。

3. 打开控制台

打开 http://localhost:3000，或你选定的主机端口，然后登录：

用户名harnessrouter密码harnessrouter

[!WARNING]
在配置档里修改默认密码。 改好之前，让实例只在本机运行。保存会短暂重启控制台，并让其他浏览器退出登录。

查看登录界面

HarnessRouter Community Edition 登录界面

用的是已有卷或自定义凭据？查看凭据优先级与设置。

这组凭据用来登录控制台。在这里跑任务不需要 HarnessRouter API key。

4. 连接模型服务商

打开侧栏底部的账户菜单，选择 Bring your own key。找到你的服务商，按 Add key，粘贴它的 API key。它支持的模型就会出现在控制台里。

这个服务商 key 用来授权模型请求。它和下面做产品集成用的 HarnessRouter API key 是两回事。

查看服务商设置界面

在 Bring your own key 下添加 OpenAI key

5. 设置你的第一个智能体

打开 Start，说明你的智能体该为用户做什么，然后按 Continue。在 Set up an agent harness 里，把 agent harness 和模型留在 Auto，或者自己选，然后保存。HarnessRouter 用你自己的模型搭好整套设置：它写出智能体的指令，挑出任务需要的 harness、模型、技能、插件和工具，并在输入框里留一条示例请求。发送它，跑第一个任务。

HarnessRouter 根据一句话搭好的设置，示例请求在输入框里等着

先试个示例。 在 Start in HarnessRouter 下，挑三个示例任务之一。它的请求会回放一段录制好的运行，这样不花 token 就能看到一个完成的任务。在下面接着写，就能用你自己的模型继续。

产品图片示例：一段录制好的运行和它生成的图片

修改设置（可选）

在 Studio 中打开配置，选择 Settings，即可修改模型、指令、技能、插件、工具、环境和限制。在 Add-ons 下，为整个工作区添加插件、技能、MCP 服务器和环境。配置一旦保存，智能体框架就固定下来：想换用其他框架，请新建一个配置。

查看 New setup

Set up an agent harness: one sentence, with the agent harness and model on Auto

用一个 API 把智能体框架集成进你的产品后端

把内置或自定义框架当作可插拔的智能体后端，用来运行产品任务。调用你自托管实例的 OpenAI Responses 兼容 API，用 metadata.harness_id 选择框架。无需部署到 Cloud。

框架在 Console 中运行成功后：

1. 在同一 CE 实例的 Console 侧栏打开 API Keys（默认本地地址），给密钥起名，按 Create。
2. 把只显示一次的密钥存为产品后端的 HARNESSROUTER_API_KEY。绝不要把它暴露在浏览器代码里。这个 CE 签发的密钥与你的 Console 密码、服务商密钥相互独立。
3. 用 Console 中显示的 Harness ID 和你已连接服务商提供的模型调用 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 可接收服务器发送事件。

把调用方的链路接到任务上。

在请求中发送 W3C Trace Context 头 traceparent 和 tracestate，任务的模型调用就会带上该链路的子链路：相同的 trace id、新的 span id 和采样标志，这样服务商的日志和你的日志就是同一条链路。不符合 W3C 语法的值会被丢弃，绝不会被拒绝：损坏的链路头不会让任务失败。baggage 从不读取，也从不离开实例。

重试任务时不重复运行。

重试任务时，用同一个 Idempotency-Key 发送同一个请求。例如，用上面的 URL 和 API key 把这个请求发送两次（生成 key 需要 Python 3）：

IDEMPOTENCY_KEY=$(python3 -c 'import uuid; print(uuid.uuid4())')

for attempt in 1 2; do
curl --fail-with-body -sS "$HARNESSROUTER_BASE_URL/v1/responses" \
-H "Authorization: Bearer ${HARNESSROUTER_API_KEY:?}" \
-H 'content-type: application/json' \
-H "Idempotency-Key: $IDEMPOTENCY_KEY" \
-d '{
"input":"Reply with exactly: it works.",
"metadata":{"harness_id":"codex"},
"model":"gpt-5.4-mini",
"stream":false
}'
printf '\n'
done

两次响应的 id 相同，会话里只有一轮：重试返回第一次请求的结果，不会再启动一次执行。如果第一次请求还在运行，重试会等它结束。每个新的逻辑请求都要用新 key。同一个 key 配上不同的请求体，会返回 409；只改 stream 仍算同一个请求。见 Tasks §6: Idempotency。

不要把 token、id、hash 这类很长的精确值放进提示词：智能体会把它读到的内容重新打一遍，而模型在这种字符串上会丢字符、换字符。把它作为文件附上（POST /v1/files，再加一个 input_file 块；每次带上它的那一轮开始前，文件会以原文件名落到智能体的工作目录里），或者通过 harness 的环境变量交给智能体。harness 接收一个 env 映射，其中的值在每一轮都会解析：$headers.X-Name 取请求里的对应请求头（先在 additional_headers 里声明它），vault:name 取已存储的密钥，其他值按原样使用。智能体的 shell 和工具启动时就带着这些变量，所以任务里可以直接写「token 在 $DEPLOY_TOKEN 里」。通过引用得到的值，会从离开沙箱的一切内容里抹掉，包括响应、流、trace 和存储记录，即使智能体把它打印出来也一样。vault: 引用只读取你自己工作区通过 PUT /v1/mcp-secrets/{ref} 存储的密钥。抹除保护的是记录，不是智能体：智能体能读到的值，只要提示词或网页让它发出去，它也能发到别处。所以交给它的 token 要限定到该用户和该任务，短期有效，最小权限。

整个 API 在 $HARNESSROUTER_BASE_URL/v1/openapi.json 有描述，由路由生成，/v1/docs 有可浏览的副本。

后端和 CE 跑在同一台电脑上时，默认 URL 就能用。从另一台机器或容器访问，要用 CE 实例可达的 URL。阅读完整的自托管 API 与网络指南 →

你的应用可以…怎么做

启动任务发送指令并查看执行状态继续会话用 previous_response_id 发送后续指令流式获取进度智能体工作时接收实时更新处理文件附加输入文件，取回生成的输出取消任务停止不再需要的工作检查执行查看结构化错误与执行轨迹

把智能体运行框架当作可插拔后端，接入你的产品

用智能体运行框架为你的产品提供强大的智能体能力，覆盖内容创作、数据分析等知识工作任务。浏览这些开箱即用的套件，看看运行框架作为可插拔后端如何运作。

幻灯片智能体运行框架把你的需求变成幻灯片内容和版式，生成可编辑的演示文稿。

表格智能体运行框架用每一行的数据执行任务，再把结果写回表格。

仪表盘智能体运行框架读取你的数据库 schema，编写 SQL 查询，为仪表盘图表提供数据。

视频智能体运行框架把你的需求变成分镜计划，调用视频工具生成片段，放进时间线。

Harness Bot
招聘智能体面试你，把每位队友安装成独立的运行框架；队友分组协作，互相传递文件和 @提及，产出物统一放进共享库。

浏览入门套件 →

安装说明与许可

开始： 在控制台打开 Shop，选一个套件，再选一个运行框架和模型，两者都要受你已连接的服务商支持。

仪表盘： 使用可访问的数据库，并配一个只读数据库账号。设置 HR_SECRET_KEY 加密存储的连接，连接前先检查示例行设置。

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

安装指南 →

部署方式

自托管，掌控一切

- 你的基础设施。 一次 Docker 部署，搞定控制台、网关和运行器。
- 你的凭据和状态。 服务商密钥、会话、文件和工作区都由你掌控。模型请求仍会发往你配置的服务商。
- 真实工作区。 原生文件系统、shell 和 Git 工作流，会话工作区彼此独立。
- 不做 Console 产品分析。 社区版关闭 Console 分析管道。

选择你的上云路径

选 HarnessRouter Cloud，托管部署、维护和扩缩容都交给它，任务在无服务器隔离沙箱中运行，走同一套 API 契约。

| 本地 → 云 | 直接在云上开始 |
| 带上你在本地配置好的自定义 harness。按上传指南操作 → | 无需本地部署，直接创建并运行 harness。打开 HarnessRouter Cloud → |

本地上传： 在本地实例上设置 HR_SECRET_KEY，用来加密保存的目标密钥。在 Settings 中保存自定义 harness，选择 Upload to Cloud，再用目标端的 Cloud 工作区 API 密钥建立连接。

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

社区版内部结构 text ┌─ 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 协议 Unified Harness Protocol (UHP) 是一份公开的、带版本号的契约，由 Community Edition 和 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 |
| 协议 | Unified Harness Protocol (UHP) |
| 社区 | 加入社区（Discord） · 参与贡献 · LinkedIn · X · 安全 |

Star 历史

许可证 HarnessRouter Community Edition 采用 Apache 2.0 协议授权。智能体 harness 命令行工具在首次启动时安装，仍受各自上游协议约束。第三方声明见 NOTICE，Starter Kits 仓库的独立授权条款见 Starter Kits repository。

HarnessRouter 是全球首个面向智能体 harness 的统一接口。