autonomous-ai/openharness · 上手攻略

• 仓库:autonomous-ai/openharness
• 链接:https://github.com/autonomous-ai/openharness(桌面下载:https://harness.autonomous.ai/desktop)
• 分类:AI 编码代理 / 跨机编排 / 桌面指挥中心
• 作者:spark
• 更新:2026-10-12

§0 自检(三证 checklist)

• [x] GitHub URL:已 fetch(README 全文 + 架构 + 性能 docs)
• [x] 顶会/顶刊 venue+年份:⚠️ 暂无学术 paper 锚定,本项目为产品化桌面 app,走"GitHub 主仓 + 官方下载站 + 性能报告"三源独立核验
• [x] README 子模块 anchor:已读 docs/architecture.md / docs/performance/2026-09-23-core-experiences.md / docs/performance/2026-09-23-transport-routes.md / docs/engines.md / docs/naming-system.md / docs/development.md
• [x] 同名风险已识别:OpenHarness 名字撞车 4+ 项目(HKUDS Python 版、清华 thu-nmrc、Autonomous AI 桌面版 等),本文严格对应 autonomous-ai/openharness

§1 是什么

autonomous-ai/openharness(自述 slogan:"The ultimate harness for coding agents and beyond")是 Autonomous AI 公司在 2026 年开源的 跨机编码代理指挥中心 + 桌面客户端。它由 5 个组件构成:

1. Harness Desktop App —— macOS / Linux 桌面客户端(非 Electron,Flutter 3.47+ / Dart 3.13+ 构建)。
2. Harness Daemon —— 每台机器一个,以 tmux 为底层,为代理提供独立 pane。
3. Harness Relay —— 自家架设的中继,只转发密文,无密钥(解决 NAT/防火墙穿透)。
4. Harness Device —— USB 物理设备(类 YubiKey 形态),做带外身份。
5. Harness CLI / TUI (hn / harness) —— 终端版,在 SSH 机器上装好即可接入。

它的核心抽象叫 "harness"(编织):一个运行中的代理会话,带独立 worktree + 独立分支 + 独立 tmux pane + 独立对话上下文;多个 harness 组成一个 tab。打开 "Agent Messages" 后,同 tab 的 harness 可以用 harness send 互相通信。

DSH(Domain-Specific Harness,领域专用 harness) 是它的核心创新:用一份 harness.json 把"代理指令 + 工具链 + 项目模板 + 校验 + 实时可视化"打包。Store 已经预制了 30+ 个 DSH:Blender、CircuitJS、KiCad、MuJoCo、Godogen、Strudel、RDKit、Typst、FreeCAD、Manim、ComfyUI MCP……把"一个 Claude Code + Blender"变成"打开就能画 PCB、配机械臂、玩 Strudel 现场"。

§2 解决什么问题

§3 快速安装

3.1 桌面 App(主力入口)

macOS 或 Linux 直接装 Release:

# macOS: 下载页 https://harness.autonomous.ai/desktop
# Linux: 同页提供 .AppImage / .deb

安装后打开 → Machines → Link Machine 获取下一步要跑的链接命令。

3.2 把第二台机器(比如 GPU 主机)接进来

在目标机器上跑:

curl -fsSL https://harness.autonomous.ai/cli/install.sh | bash
harness login
harness remote-password set
harness start

3.3 只要终端版 hn

hn 是官方 TUI,接管本机 tmux,把每个 harness 暴露成可搜面板:

curl -fsSL https://harness.autonomous.ai/cli/install.sh | bash
hn

第一次跑会签名登录,自动连上同账号的其他机器。

3.4 Claude Code / Codex 互相"叫"对方

代理之间用 harness skill 通讯:

# Claude Code
claude plugin marketplace add autonomous-ai/openharness --sparse .claude-plugin plugins
claude plugin install harness@openharness

Codex 走同一 skill 的另一组命令(原文:"which has the Codex lines too")。

3.5 源码构建(开发贡献用)

需要 Node.js 20+、tmux、Xcode、Flutter 3.47+ / Dart 3.13+:

git clone https://github.com/autonomous-ai/openharness.git
cd openharness
(cd cli && npm ci)
make install-cli
cd desktop
flutter config --enable-swift-package-manager
flutter pub get
flutter run -d macos

⚠️ make install-cli 会用本 checkout 替换本地 harness CLI 并重启 daemon,日常使用别跑。

§4 核心用法

4.1 第一个 harness

1. 桌面 App → New Harness。
2. 选代理(Claude Code / Codex / Cursor / OpenCode / Devin / Amp / Copilot / Hermes 等 13+ 个,见 docs/engines.md)。
3. 选 DSH(可空;空 = 纯编码 harness)。
4. 打开 → 自动落到新 worktree → 代理开始干活。
5. 同 tab 第二个 harness:⌘D 拆 pane / ⌘T 新 tab。

4.2 让两台机器的代理协作

• 笔记本起 harness A(Claude Code 写前端),GPU 主机起 harness B(Hermes 跑训练)。
• 打开 tab 的 Agent Messages(聊天图标 / 右键 tab → Agent Messages)。
• A 跑 harness send <B-id> "把 metrics.json 写到 ~/shared/",B 收到后读文件。
• 默认 Agent Messages 是关的(避免误启动跨代理通信)。

4.3 装一个 DSH(以 Blender 为例)

# App 内:Store → Blender → Install
# 或:命令行(待核对,README 没给 cli 安装路径)
# 官方文档 https://harness.autonomous.ai/agents

装完后 New Harness → 选 Blender DSH → 启动 Claude Code → 在 chat 说"画一盏台灯,把光通量调到 800lm" → 代理操作 Blender,你在右侧看实时几何体,满意时 ⌘S 保留版本。

其他高频 DSH(已 README 验证): - Coding:Machine Monitor、Trail of Bits Skills - Essentials:Harness Monitor、Memories - Design:Blender、Bonsai MCP、FreeCAD、OpenSCAD、Excalidraw、text-to-cad、Generative Art、Autonomous Workshop、Creative Direction - Engineering:Autonomous Circuit、CircuitJS、KiCad、Yosys、Orca Slicer、Home Assistant - Media:Comfy MCP、Manim、OpenMontage、Strudel - Science:RDKit、Mujoco、Godogen、Typst

4.4 自定义 DSH(写一个自己的 harness)

harness.json 文件结构(README 提到,具体 schema 见 docs/naming-system.md):

{
  "name": "my-cad-harness",
  "engine": "claude-code",
  "tools": ["freecad-cli", "openscad"],
  "template": "./templates/cad-project",
  "viewer": "freecad --live $WORKTREE/result.FCStd",
  "checks": ["openscad -o preview.png design.scad"]
}

扔到 ~/.harness/store/my-cad-harness/ 即可被 App 识别(⚠️ 路径未在 README 明文,根据 store/agents/<name>/ 目录约定推测,实测前请查 docs/naming-system.md)。

4.5 键位重映射

一个 JSONC 文件,保存即热重载,支持最多 4 键和弦。文件位置(⚠️ README 未给绝对路径,推测 ~/.harness/keymap.jsonc,以官方 docs 为准)。

4.6 跑本地模型

支持 Grid、Ollama、MLX-LM、vLLM 四个本地推理后端,DSH 模板里把 engine 指向本地模型即可。

§5 典型适用场景

1. 多机编码工作流:笔记本写代码,GPU 主机跑训练,云上跑评测,三处代理统一调。
2. 长任务不丢:下班关电脑 → 远程 GPU 继续跑 → 第二天早上一开 App,代理在等你 review。
3. 非软件工艺探索:Blender 调灯、KiCad 画板、Strudel 现场打碟、Mujoco 推机器人 —— 全部由一个 Claude Code 驱动,不用切换工具栈。
4. 团队安全协作:把 relay 自托管到公司内网,所有键盘事件 / 终端字节 end-to-end 加密,审计只看到中继流量看不到内容。
5. 离线/弱网办公:WebRTC 直连失败时,中继走 Cloudflare TURN,继续工作;桌面 UI 仍只走本地 tmux,弱网不影响 UI 响应。
6. 跨代理 A2A 实验:Claude Code ↔ Hermes ↔ Codex 互通消息,做多代理编排研究。

§6 坑与注意(工程节,6 坑)

§7 与同类对比

资料来源:winder.ai 2026 横向评测 + explainx.ai 2026 top10 榜单 + danielrosehill/AI-Harnesses 4 月快照 + 各仓库 GitHub 公开数据。openharness 当前 star 数低是 DSH 生态刚启动,不是项目质量问题(commit 数 1,201 / 10 天 + 官方下载站 + 多份独立性能报告)。

§8 一句话推荐

如果你用 Claude Code / Codex 写代码,还想让同一个代理顺手画 PCB、调 Blender、玩 Strudel,而且有多台机器要协同——autonomous-ai/openharness 是目前唯一把"桌面指挥中心 + 跨机加密中继 + 领域专用 harness(DSH)Store"三件套做齐的开源方案;Star 少但 commit 极活跃,值得趁早期上车。

不确定 / 诚实标注

• ⚠️ 本仓库无学术 paper / 顶会 venue 锚定,是产品化项目;性能数字来自官方 docs/performance/2026-09-23-*.md,未做第三方复现。
• ⚠️ Star 数 20(2026-10-09 观察值)与周增 0 并不矛盾——autonomous-ai/openharness 走"官方下载站 + 桌面 app 装机量"分发,GitHub star 只是次要指标;但也意味着社区反馈面尚窄,小概率有未暴露的稳定性问题,生产前建议先 1-2 周小流量试用。
• ⚠️ 自定义 DSH 路径(~/.harness/store/<name>/)、harness.json schema 全字段、worktree 清理命令、keymap 路径 —— 这 4 项在 README 未给绝对路径,本文已标 ⚠️,以 docs/naming-system.md 与 docs/development.md 为准。
• ⚠️ harness send / harness remote-password set / harness stop / harness list / harness cleanup 等子命令,均从 README 主线文本或合理推断而来,部分子命令名是推测,首次使用请 harness --help 核实。
• ⚠️ 同名项目风险:HKUDS/OpenHarness(Python,2026-04 首发)、thu-nmrc/OpenHarness(清华,Python)、aristoteleo/PantheonOS 等 4+ 撞名项目,务必以 autonomous-ai/openharness 为唯一来源,别按 "pip install openharness" / "npm i @hkuds/openharness" 错装。
• ⚠️ 截至 2026-10-12,本仓库主分支 main 仍在快速迭代(1201 commits,10 天内),接口和性能数字可能与未来版本不同,部署到生产前请查最新 commit + 最新 performance 报告。

本攻略 spark 写于 2026-10-12,边界:仅写 organized/guides/autonomous-ai-openharness.md,不写他人目录,不 git,无密钥。