openharness CLI命令大全:login、start、machines等核心命令实战解析
openharness CLI命令大全:login、start、machines等核心命令实战解析
openharness 是一款面向 AI 编码代理(coding agents)的统一指挥中心,让你在笔记本电脑、家庭服务器和 GPU 机器之间用一条命令调度 Claude Code、Codex、OpenCode 等代理。本文带你系统掌握 openharness CLI 的 login、start、machines、link 等核心命令,从安装登录到多机互联,快速成为多机代理调度的高手。
什么是 openharness CLI?
openharness 的核心是一条名为 harness 的命令行工具:每台机器运行一个轻量守护进程(daemon),自动发现你运行在 tmux 里的代理进程,并把它们的对话、工具调用实时桥接到桌面应用、网页甚至硬件设备。
它的设计理念是"桥接而非包装"(a bridge, not a wrapper)——你的代理依然以原生 CLI 身份运行,凭据留在本机,所有跨机通道端到端加密。
📌 完整命令文档见 docs/cli.md,CLI 细节见 cli/README.md,命令分发逻辑在 cli/src/cli.ts。
快速上手:安装与登录三步走
一键安装 openharness CLI
在目标机器(macOS 或 Linux,需 Node ≥ 20 和 tmux)上执行官方安装脚本,即可得到 harness 命令:
curl -fsSL https://harness.autonomous.ai/cli/install.sh | bash
安装器自带 Node 运行时,写入 ~/.local/bin/harness,本地使用无需登录。
harness login:多种登录方式详解
harness login 会询问你选择 Google、Apple 还是手机扫二维码登录,并把会话安全保存在 ~/.harness/auth/session.json:
| 命令 | 作用 |
|---|---|
harness login |
交互式选择登录方式(浏览器或手机扫码) |
harness login --google |
直接走 Google 浏览器登录 |
harness login --apple |
直接走 Apple 浏览器登录 |
harness login --qr |
用手机扫码登录 |
harness login --force |
停止守护进程并切换账号登录 |
harness auth status --json |
查看本机保存的登录状态 |
harness start / status / stop:守护进程生命周期
harness start # 用已保存的会话启动守护进程
harness start -f # 前台模式运行(供 launchd/systemd 等监督者使用)
harness status # 查看是否运行、pid 和会话链接
harness stop # 停止后台守护进程(保留登录态)
harness logout # 停止并清除本机 SSO 会话
harness version # 查看已安装版本
harness update # 立即更新到最新构建(平时也会后台自更新)
💡 想让守护进程开机自启、崩溃自恢复?执行 harness service install,它会挂到 macOS 的 launchd 或 Linux 的 systemd 上。
核心命令实战解析
harness new:从终端一句话创建代理会话
harness new 是 shell 里最快启动 agent 的方式,词语顺序随意,@ 标记机器:
harness new # 在当前目录启动 claude
harness new codex @mini ~/code # 在名为 mini 的机器上启动 codex
harness new --prompt "fix the flaky test"
harness send / ps / show:查看与协作
harness ps:列出本机所有 harness 的状态、启动者和任务概要harness show <name>:查看某个 harness 的最近一问一答harness send <name> "text":在开启 Agent Messages 的标签页内向队友代理发消息harness search <words>:全文搜索本机所有代理的每一轮对话
harness tui 与 hn:把整个指挥中心装进终端
harness tui(或安装时附带的短命令 hn)在纯终端里还原完整体验:所有机器、标签页、分屏,全靠快捷键操作(⌘P 搜索任意 harness,⌘D 分屏)。详见 tui/README.md。
多机互联命令:把服务器变成算力节点
openharness 的多机互联不需要 SSH 密钥、端口转发或 Tailscale——守护进程主动外拨,通道端到端加密(ChaCha20-Poly1305)。
给新机器设置远程密码并互联
在一台新机器上装好 CLI 后,只需:
harness remote-password set # 设置本机持久远程密码
harness start
然后在已登录的机器上一键连接:
harness link connect <id> # 用对方密码连接(完全自动)
harness link list # 列出本机已互联的机器
harness link unlink <id> # 撤销信任
harness group list / harness group sync 则让组内所有机器两两互通,无需再输密码。
harness machines:查看与管理账号下的机器
harness machines # 列出账号下所有机器(本机有标记)
harness machines delete <id> # 移除其它机器(拒绝删除本机)
harness pair:浏览器端到端加密配对
在网页端查看某台机器时,页面会显示一个配对码,本机执行 harness pair <code> 即可完成加密配对;harness pairings 列出已配对客户端,harness unpair --all 一键全部解除。浏览器通道内所有代码、密钥与按键均加密传输,中转服务器只转发密文。
进阶命令速览
harness dsh:安装领域专用 harness(DSH)
DSH(domain-specific harness)把一个编码代理变成 CAD、电路、音乐等专业的"专家",Store 里已有 49 个。常用子命令:
harness dsh list # 查看已安装与注册表内容
harness dsh install <id|url> # 按注册表 id、git 地址或本地路径安装
harness dsh update <id> # 更新包并保留工作区
harness dsh check <path> # 对自己的 harness 做合规检查
编写自己的 DSH 可参考 store/README.md。
harness grid:调度本地模型集群
Grid 是一组本地 AI 引擎的编队,harness grid login 可以直接复用本机 openharness 账号完成 grid 登录;harness grid env <grid> 输出中继地址与密钥,供 OpenAI 兼容客户端 eval 后使用。
harness devices:设备信任与审计
harness devices list / show / history / dismiss / rebaseline 管理账号下的设备信任日志——任何设备登录即被其它设备信任,陌生设备会立刻在每台机器上标记为 new,是安全审计的利器。
openharness CLI 核心命令速查表
| 分类 | 命令 | 一句话说明 |
|---|---|---|
| 账号 | harness login / logout / auth status |
登录、登出、查登录态 |
| 守护进程 | harness start / stop / status / reset |
启停、状态、清状态 |
| 服务化 | harness service install / status |
交给 launchd / systemd 托管 |
| 机器 | harness machines / link connect / remote-password set |
列出机器、互联、设密码 |
| 会话 | harness new / ps / show / wait / close / send |
创建、查看、等待、关闭、发消息 |
| 搜索 | harness search <words> |
全量对话搜索 |
| 浏览器 | harness pair / pairings / unpair |
E2EE 配对管理 |
| 扩展 | harness dsh / harness grid / harness api |
领域 harness、模型集群、保存的 API |
| 终端 | harness tui(hn) |
纯终端指挥中心 |
| 维护 | harness version / update / logs export |
版本、更新、导出日志 |
从源码构建 openharness
想参与开发或跑最新代码?克隆仓库后用 Makefile 安装 CLI 即可(开发环境另需 Flutter):
git clone https://gitcode.com/gh_mirrors/ope/openharness
cd openharness
make install-cli
make install-cli 会把当前代码构建成本机可用的 harness 命令并重启本地守护进程(此模式下自动自更新关闭)。开发细节见 docs/development.md。
常见问题 FAQ
Q1:本地使用必须登录吗?
不需要。harness start 之后本机功能完全可用;只有连接其它机器(link / pair / machines)时才需要 harness login。
Q2:守护进程会自动升级吗?
会。它每分钟检查一次发布清单,发现新版本会自动下载、校验、热替换并在坏版本时回滚;可用环境变量 ADAPTER_UPDATE_DISABLE=true 关闭。
Q3:日志在哪里?
原始日志在 ~/.harness/cli/data 目录下(harness status 会显示实际路径),单文件上限 10 MB 自动裁剪;harness logs export 可一键打包近 7 天日志。
Q4:支持 Windows 吗? 目前不支持。官方支持 macOS 与 Linux(Ubuntu 22.04+ 已验证),详见 cli/README.md 的环境要求表格。
掌握以上 login、start、machines、link、new 等核心命令,你就拥有了 openharness 的完整操作能力:一条命令登录、一条命令启动、一句话把任何一台机器纳入你的 AI 代理指挥中心。



