5 组关键问题问与答
Q1：运行 HarnessRouter 社区版，我需要准备什么？
A：需要 Docker 环境，约 4GB 磁盘空间，大模型服务商的 API 密钥；不需要注册平台账号，密钥仅用于调用模型接口，不会上传第三方。
Q2：Agent 的运行环境是什么，是模拟沙箱吗？
A：不是模拟沙箱。Agent 获得真实 POSIX 工作空间，可以直接使用 bash、git、文件系统，拥有完整命令执行与文件读写能力。
Q3：Starter‑Kit 模板套件都可以实现哪些功能？
A：4 套核心套件：①Slides：对话生成 PPT 演示文稿；②Sheets：Agent 逐行处理表格数据；③Dashboards：自然语言生成数据库可视化看板；④Videos：文本描述生成视频（成本高）。
Q4：API 调用和 Web 控制台是什么关系？
A：控制台只是 API 的轻量化前端。curl 调用 API 产生的任务会同步显示在 Web 控制台，二者操作同一个实例，数据完全互通。
Q5：本地部署有哪些重要安全风险？
A：默认账号密码公开，上线前必须修改；0.2.0 及更早版本无鉴权不可外网使用；对外暴露需配置反向代理；不要关闭鉴权网关，除非本机完全隔离。
附录 在本地机器运行 Agent Harnesses
单容器部署，使用你自己的 API 密钥与本地数据。配置一套 Harness，下发任务，观察执行全过程，无需注册账号、不上云、无遥测数据上报。社区版实现了统一 Harness 协议（Unified Harness Protocol，UHP）—— 这也是云端托管服务所遵循的开放标准。
💡提示 初次接触？可以先阅读产品简介，或访问 unifiedharnessprotocol.org 查阅协议原文。
安装部署
一共六个步骤，完成后即可获得运行实例、可登录控制台，以及可响应指令的智能 Agent。
前置条件
需要安装 Docker，磁盘预留约 4GB 空间，同时准备好模型服务商提供的 API Key。无需注册任何账号。服务商密钥仅在调用对应模型接口时对外传输，不会泄露到其他第三方。
- 拉取镜像
docker pull harnessrouter/harnessrouter
下载大小约 700 MB。
可以指定具体版本标签，而非直接使用
latest。
- 启动容器
直接复制执行以下命令，命令中无需填入服务商密钥、密码等占位参数：
docker run -d --name harnessrouter \
-p 127.0.0.1:3000:3000 \
-v harnessrouter:/data \
harnessrouter/harnessrouter
若本机 3000 端口已被占用，只需修改 -p参数冒号左侧端口号，例如改为 -p 127.0.0.1:3100:3000；容器内部固定监听 3000 端口，请勿修改冒号右侧数字。
拓展阅读：命令各参数释义｜启动时自定义用户名密码｜使用 Docker Compose 部署
- 等待服务就绪不要立刻打开浏览器
。执行 docker run后命令行会迅速返回，但控制台还需要约半分钟完成初始化。此时访问http://localhost:3000会提示连接拒绝，属于首次启动的正常现象，并非容器故障。
执行下面命令查看实时日志：
docker logs -f harnessrouter
等待日志输出 ready on :3000，再打开浏览器访问页面。
[harnessrouter] installing Claude Code (Anthropic's terms apply)…
[harnessrouter] installing Codex (Apache‑2.0)…
[harnessrouter] installing Pi (MIT) and its MCP adapter (MIT)…
[harnessrouter] installing DeepSeek Harness (MIT, developer preview — version‑pinned)…
[harnessrouter] installing Hermes (check its upstream license before use)…
[harnessrouter] data=/data backends available: claude codex hermes pi dsh
[harnessrouter] ready on :3000
该安装流程仅在首次初始化卷数据时执行。后续重启仅需数秒，不会再输出组件安装日志。 拓展阅读：日志输出说明、首次启动耗时原因。
- 登录控制台
浏览器打开 http://localhost:3000，使用默认账号登录：
|
|
|
|---|---|
|
|
|
|
|
|
登录完成后，点击右上角账户菜单，进入「个人资料」页面修改密码。保存密码会重启控制台，耗时约 1 秒。
若在
docker run阶段设置了环境变量HR_AUTH_USER、HR_AUTH_PASSWORD，则必须使用自定义账号密码登录，默认凭据会直接拒绝访问。 拓展阅读：密码存储位置、忘记密码处理方案。
- 接入模型服务商
完成这一步 Agent 才可以正常工作。镜像内部不内置任何模型、试用密钥或者免费服务。
进入「集成（Integrations）」页面，点击「添加集成（Add Integration）」，依次填写连接名称、选择模型服务商、粘贴你的 API Key。
无需手动维护服务商支持的模型列表：产品会自动维护清单，服务商发布新模型后会自动同步。选定服务商、填入密钥，页面就会自动展示该密钥可用的全部模型。
拓展阅读：对接多个服务商｜通过环境变量配置，适配脚本化部署｜后端未对接密钥时的提示说明。
- 下发任务给 Agent
进入「任务（Tasks）」→「新建任务（New Task）」。在左侧切换选择 Harness，消息输入框旁选定模型，输入你的指令。
Agent 的执行过程会流式实时返回：包括运行的每一条命令、修改触碰的全部文件，以及最终输出结果。
至此安装全部完成。实例状态全部保存在 Docker 卷内，使用 SQLite 数据库与本地文件存储。直接删除卷即可销毁整套实例；复制卷文件，即可完整迁移实例，包含所有 Harness、对话记录。
拓展阅读：截图中执行流程详解。
示例模板套件（Starter kits）
模板套件是开箱即用的完整示例，用来展示平台的能力边界。 每一套套件都是完整 Agent 应用，包含前端页面、配置完成的 Agent、配套技能指令，并非简单代码片段。所有套件均开源。后续版本会持续新增套件，你的实例会自动展示已内置的套件。
点击启动仅需确认运行所使用的模型后端。
幻灯片套件（Slides）
一份演示文稿对应一次对话。你描述需求，Agent 自动完成设计：先搭建整体结构，再定义样式体系，逐页生成内容。生成过程中幻灯片实时预览，如果版式不符合预期，可以中途调整，不用等待全部 20 页生成完毕再修改。
下方演示案例，仅输入一句话指令：制作一份面向新手工程师，讲解容器镜像的 5 页演示文稿。
拓展阅读：右侧面板信息说明。
电子表格套件（Sheets）
表格行承载你的原始数据。开启 Agent 列后，会基于该行左侧所有单元格内容作为输入，调用指定 Harness，逐单元格自动填充结果。点击运行后会按行依次处理，界面展示实时进度，同时提供停止按钮 —— 面对上千行数据，你可以随时终止任务。
示例场景指令：帮我构建一张表格，梳理硅谷投资人信息，用来向硅谷以外的创业者展示这些投资人投过的初创企业。
拓展阅读：表格构建流程｜Agent 列菜单提示无可用 Agent 排查。
数据看板套件（Dashboards）
描述你想要分析的业务问题，对接数据库。Agent 自动读取数据表结构，针对每一个问题编写 SQL 查询，自动匹配合适图表，排版布局。每次打开看板都会重新执行全部查询，展示数据库实时最新数据，而非历史静态快照。
这是配置步骤相对多的套件，只需要填写两项信息：数据库连接字符串，以及是否拉取样例行。
拓展阅读：看板构建逻辑、数据可信度说明｜数据库对接指南。
视频套件（Videos）
描述影片内容，平台自动完成分镜规划、渲染每一帧画面；画布支持手动拖拽调整镜头顺序，最终合成完整视频可供下载。渲染在后台异步执行，生成视频片段时你可以继续其他操作。
⚠️重要提示：该套件和普通对话计费模式不同，每一秒输出都会产生实际费用，消耗成本较高。建议你熟悉控制台基础使用后再体验。
产品概念说明
Agent Harness：大模型之上的运行时层，Codex、Claude Code、Hermes 都属于 Harness。在 API 中，Harness 对象是一套保存好的配置：底层运行时基座、选定模型、系统提示词、各类限制参数。
Task（任务）：一套 Harness 配置的单次运行实例。Agent 在真实 POSIX 工作空间中运行，拥有 bash、git 能力；完整对话过程流式输出。
HarnessRouter 社区版完整实现 UHP 协议：提供兼容 OpenAI Responses 的接口，支持 Harness 的增删改查、会话管理、流式输出、任务终止、幂等调用。控制台本质就是这套 API 的轻量化前端。UI 可以做到的所有操作，都可以直接用 curl 调用接口完成。
控制台与云端托管版完全同源，并非阉割重构版本：页面、组件、API 客户端完全一致。本地部署不具备账号、计费、市场等云服务能力，对应页面直接隐藏不展示。
支持的 Harness：Codex、Claude Code、Hermes。组件不会打包进镜像，首次启动时按需下载安装，受各自开源许可证约束。使用前请阅读对应许可条款。
为什么选择本地自托管
- 密钥、账单、数据完全自主可控
除了调用模型服务商接口，不会有任何数据向外传输。 - 真实运行工作空间
Agent 原生拥有 bash、git、文件系统，不是受限模拟沙箱。 - 和云端完全一致 API
不是二次分叉裁剪版本。基于本地开发的代码，后续迁移到云端托管服务无需改动接口。 - 真正本地闭环
无需外部控制面上报，不需要外部托管数据库。
统一 Harness 协议（Unified Harness Protocol）
本仓库既是协议实现，也是协议标准本身。网关接口规范版本化、可测试，相关定义存放于 protocol/目录，文档发布在 unifiedharnessprotocol.org。
|
|
|
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
社区版是协议的参考实现。最新版本完整通过 Full 级别 0.3.0 一致性测试。该标准完全可以脱离 HarnessRouter 云服务独立实现，仅基于 HTTP 契约。
你可以针对自己部署的服务运行一致性测试：
pip install -e protocol/conformance
uhp‑conformance --base‑url https://your‑server --api‑key "$KEY" --class full
拓展阅读：后端选型配置、浏览器构建部署、入口环境变量说明。
API 使用指南
控制台属于可选组件，只是 API 的轻量化前端。默认安装下 API 和控制台共用同一个端口，登录鉴权网关会拦截接口请求，调用时需要携带会话 Cookie。
-
登录获取 Cookie
curl -s -c hr.cookies http://localhost:3000/api/selfhost/login \
-H 'content‑type: application/json' \
-d '{"username":"harnessrouter","password":"harnessrouter"}'
# 返回 {"ok":true}
-
发起一次对话调用 网关兼容 Responses API：
curl -s -b hr.cookies http://localhost:3000/api/harness/v1/responses \
-H 'content‑type: application/json' \
-d '{"input":"Reply with exactly this and nothing else: it works.",
"metadata":{"harness_id":"codex"},
"model":"gpt‑5.4‑mini",
"stream":false}'
返回示例：
{"id":"resp_284e450bc2be4de8bea94c4af6030292","object":"response","created_at":1786822334,
"status":"completed","error":null,"incomplete_details":null,"previous_response_id":null,
"model":"gpt‑5.4‑mini",
"output":[{"id":"msg_3d71e018c6584abbb063ee16d9a36e75","type":"message","status":"completed",
"role":"assistant",
"content":[{"type":"output_text","text":"it works.","annotations":[]}]}],
"store":true,
"usage":{"input_tokens":10878,"output_tokens":34,"total_tokens":10912},
"metadata":{"session_id":"hsessa79756fab07a4bf58fa072be24d5ce59"}}
API 执行的任务会同步展示在控制台「任务」页面，保存完整会话记录。控制台和 API 访问的是同一套实例。
拓展阅读：完整接口文档｜对外公网域名部署方案。
公网部署安全提醒
暴露到外网访问前务必修改默认密码。本文档公开默认账号密码，它仅作为占位值，绝非安全凭据。容器检测到默认凭据，每次启动都会输出安全告警。
设置环境变量 HR_AUTH_DISABLED=1可以关闭鉴权网关，仅允许完全隔离的本机使用，绝对不能对外暴露。
如需 TLS HTTPS，可以服务只监听本地回环地址，前端放置反向代理。以 Caddy 配置举例：
console.example.com {
encode zstd gzip
reverse_proxy 127.0.0.1:3000 {
flush_interval -1 # Agent任务会持续流式输出；禁止缓冲事件流，防止页面假死
}
}
flush_interval -1参数至关重要；缺少该配置，代理会缓存流式响应，任务未全部结束前端页面就会卡住。
版本选择提醒：请锁定镜像标签，不要使用 0.1.x、0.2.0，该版本完全没有登录鉴权，端口可被任何人访问。0.3.0是第一个引入鉴权网关的正式版本。
拓展阅读：修改密码会重启控制台的底层原因。
迁移到云端托管服务
本地调试完成一套 Harness 之后，进入「Harnesses → Push to cloud」，就可以将配置推送到你的云端 HarnessRouter 账号，使用云端 API Key。
该同步是单向流程：本地用于迭代调试；推送到云端之后，云端版本作为唯一可信源。不支持云端拉取回本地，避免本地、云端两份配置互相冲突。推送请求仅临时使用你的云端密钥，不会持久存储。
架构说明
┌─ container ─────────────────────────────────────────────┐
│ UI (Next.js) :3000 ← 唯一对外暴露端口 │
│ │ 同源代理 │
│ Gateway :8080 Responses API、Harness增删改查 │
│ │ 本地回环访问 │
│ Runner :8081 每个会话独立Agent CLI进程 │
└─────────────────────────┬───────────────────────────────┘
/data (卷): SQLite数据库、文件、密钥、Agent工作目录
网关与 Runner 仅在容器内部回环地址监听，不对外暴露；所有访问全部经由控制台 3000 端口，鉴权网关运行在容器内部，而不是依赖外部反向代理。
会话并发隔离：每个会话拥有独立工作目录、会话状态、检查点。最大并发任务默认等于机器 CPU 核心数。本地实例不像云平台可以弹性扩容沙箱，并发上限受本机硬件约束。
存储层通过一套适配器接口对接记录、文件、密钥。开源版本提供本地实现；云端托管复用同一套接口，替换后端实现。这也是本地版与云端版为同一套代码，而不是分叉版本的根本原因。
资源链接
-
文档与云服务：托管平台、操作指南、定价信息 -
统一 Harness 协议：本项目实现的开放标准 -
Starter Kit：社区版可直接运行示例应用 -
Discord：社区交流，用于提问、集成开发、方案提案 -
贡献指南 & 安全报告：提交改动、上报安全漏洞方式
许可证
主项目代码使用 Apache‑2.0 协议，详见 LICENSE 文件。第三方组件声明参考 NOTICE 文件。
Agent 命令行工具不会随镜像分发，首次运行按需下载，遵循各自上游许可证。启用对应后端前，请务必审阅许可条款。