AgentCli 使用指南

安装、命令参考、用量上报、常见问题

目录

1. 安装

方式一：一键安装脚本（推荐）

curl -fsSL https://yancyuu.github.io/Hermit/install.sh | bash

脚本会自动检测系统环境，如果没有 Node.js 会自动安装。支持 macOS 和 Linux。

方式二：npm 全局安装

npm install -g @yancyyu/openhermit@latest --prefer-online
openhermit

方式三：npx 免安装运行

npx @yancyyu/openhermit@latest
前置要求

2. CLI 命令参考

所有命令都支持 --json 返回机器可读结果（适合脚本和 Claude Code 调用）。不带参数运行 openhermit 进入终端导航。openhermit 与 hermit 是同一程序的别名。

启动与状态

命令说明
openhermit打开终端导航（控制面菜单）：用量同步、本地工作台、用户、token 池
openhermit web直接启动并打开 Web 工作台，跳过终端导航；可加 --daemon 后台运行
openhermit --daemon --port 8080后台运行 Web 工作台并指定端口（默认 5680）
openhermit status查看后台 daemon / Web 运行状态
openhermit doctor只读本地诊断：配置、服务、路径
openhermit stop停止后台 daemon
openhermit services终端服务菜单，按项启动/停止 web / usage / collaboration
openhermit --version · --help查看版本 / 完整命令帮助

用量采集与上报（核心）

命令说明
openhermit usage status查看后台 worker 是否运行、消息上报是否开启、上报运行时
openhermit usage today查看今日本地 usage 摘要（不上传）
openhermit usage start开启轻量后台 usage 采集，默认配置开机自启；仅扫描本机 JSONL
openhermit usage stop停止后台采集；默认关闭开机自启（--keep-autostart 保留）
openhermit usage report立即扫描并按服务端游标增量上报新增消息；--full 忽略游标全量重扫，用于补报历史
openhermit usage autostart status|enable|disable管理开机自启（macOS launchd）

用户授权（上报目标）

命令说明
openhermit auth status查看 AgentBus 用户授权状态
openhermit auth login通过飞书授权登录 AgentBus；登录后用量才有上报目标
openhermit auth logout退出 AgentBus 用户（不影响本地 runtime 登录）

团队与任务

命令说明
openhermit teams list列出本地团队（不启动 Web）
openhermit teams create创建本地团队元数据；支持 --name / --harness / --bind-project / --work-dir
openhermit tasks list --team <team>查看某个团队的活跃任务
openhermit collaboration start启用本地/自托管团队协作配置

维护与插件

命令说明
openhermit update检查并自更新到最新版本
openhermit add <plugin>安装能力插件到 MCP library（例：add worker-society）
openhermit aikey认领 token 池密钥（功能开发中，暂未开放）
提示

openhermit 不带参数进入终端导航（控制面菜单）。只想打开浏览器工作台用 openhermit web。任何命令加 --help 看完整说明，加 --json 输出机器可读结果。

默认路径和端口

项目默认值说明
Web UIhttp://127.0.0.1:5680/teams团队工作台入口
本地状态~/.hermit/团队、任务、消息、设置、审计
Claude Code 会话~/.claude/projects用量和会话数据来源
Codex 会话~/.codex/sessionsCodex 用量数据来源

3. 首次使用流程

  1. 运行 openhermit 或 openhermit web
  2. 浏览器打开 http://127.0.0.1:5680/teams
  3. 点击「创建数字员工」，填写团队名称和 slug
  4. 选择运行时（如 claudecode、codex）
  5. 绑定本地项目目录
  6. 创建任务，开始使用

支持的 Agent 运行时

级别运行时
一等适配Claude Code、Codex、Gemini、OpenCode、Cursor
兼容注册Devin、Qoder、Kimi、iFlow、ACP、tmux

4. 用量上报

配置自动上报（完整步骤）

自动上报需要三个条件同时满足：① 已登录 AgentBus + ② 消息上报已开启 + ③ 后台采集 worker 运行中。缺任何一个都不会上报。

  1. 登录上报目标 — 运行 openhermit auth login（飞书授权绑定 AgentBus 用户），用 openhermit auth status 确认已登录。未登录则上报没有目标服务端。
  2. 启用消息上报 — 运行 openhermit →「用量同步」→ 回车展开 →「消息上报」→ 回车开启，首次选择上报运行时（Claude Code / Codex）。启用上报的开关目前只在终端导航里，没有单独的子命令。
  3. 启动后台采集 — 运行 openhermit usage start，开启轻量后台 worker 并默认配置开机自启，持续扫描本地 JSONL。
  4. 立即补报一次 — 运行 openhermit usage report，按服务端游标增量上报新增消息；--full 忽略游标全量重扫，用于补报历史漏掉的消息。
  5. 查看状态 — openhermit usage status（worker 是否运行 / 上报是否开启）、openhermit usage today（今日摘要），或 Web 工作台「用量」Tab。
上报不工作？三要素自检

按顺序排查：openhermit auth status（已登录?）→ openhermit usage status（worker running 且 消息上报 enabled?）→ openhermit usage report（手动触发一次，看输出 / 报错）。补报历史用 usage report --full；开机不自启用 usage autostart enable。

Web 工作台查看用量

  1. 运行 openhermit web 或在终端导航器选择「本地工作台」
  2. 浏览器打开 http://127.0.0.1:5680
  3. 进入任意团队页面，顶部 Tab 切换到「用量」查看 token 消耗趋势、会话数、消息量
  4. 支持按成员、运行时、时间段筛选
提示

Web 工作台在后台持续运行时（openhermit --daemon）会自动定时采集，无需手动触发。打开浏览器即可查看最新数据。

上报目标与看板

用量统一上报到 AgentBus（中心化服务端 / 数据总线）。完成 openhermit auth login 后，后台 worker 会自动把增量数据上报到 AgentBus；企业管理者可在 AgentBus 看板查看全团队、按成员 / 运行时 / 时间段汇总的用量。

支持的数据源

运行时数据位置采集内容
Claude Code~/.claude/projects/**/*.jsonltoken 用量、会话数、消息量；支持 IM 归因
Codex~/.codex/sessions/**/*.jsonltoken 用量（output_tokens 为主）
上报机制

Codex 已知限制

Codex 本地 JSONL 中 input_tokens 和 cached_input_tokens 经常为 0，因此无法精确计算上下文窗口占比。output_tokens 上报正常，不影响整体用量统计。

停止上报

关闭消息上报：运行 openhermit →「用量同步」→「消息上报」关闭；停止后台采集用 openhermit usage stop。两者相互独立——关掉 worker 不影响「消息上报」开关状态，反之亦然。

5. 常见问题

Q: EACCES: permission denied 权限报错

典型报错
Error: EACCES: permission denied, open '~/.hermit/telemetry/worker.pid'
# 或
npm error code EACCES syscall rename

原因：之前以 sudo 运行过 hermit 或 npm，导致部分文件被 root 占有。

修复：

# 修复 telemetry 文件权限
sudo chown $(whoami) ~/.hermit/telemetry/worker.pid

# 如果 npm global 目录也报权限错误
sudo chown -R $(whoami) ~/.npm-global
预防

不要用 sudo 运行 openhermit 或 npm install -g。如果 npm global 目录权限正确（属于当前用户），全局安装不需要 sudo。

Q: openhermit 命令找不到

npm 全局 bin 目录可能不在 PATH 中。检查并添加：

# 查看 npm 全局 bin 目录
npm config get prefix

# 添加到 PATH（写入 ~/.zshrc 或 ~/.bashrc）
export PATH="$(npm config get prefix)/bin:$PATH"

Q: 更新失败

如果 openhermit update 失败，可以直接用 npm 重新安装：

npm install -g @yancyyu/openhermit@latest --prefer-online

Q: Windows 安装/更新报 EBUSY: resource busy or locked

典型报错
npm error code EBUSY
npm error syscall rename
npm error path D:...
ode_modules@yancyyuopenhermit
npm error errno -4082
npm error EBUSY: resource busy or locked, rename '...' -> '...'

原因：这不是权限问题（EBUSY ≠ EACCES），所以 sudo 或"以管理员身份运行"都无效（Windows 也没有 sudo）。是之前运行过的 openhermit 后台进程（daemon / usage worker / 反复重启的子进程）还占着包里的文件，npm 无法替换。

解决：按顺序试，多数情况第 ① 步就够了。先释放文件占用，再安装。

① 首选 —— 用 openhermit 自己关掉后台（最干净，1.8.4 上也能跑）：

openhermit stop
openhermit usage stop   # 如果开过后台用量采集
npm install -g @yancyyu/openhermit@latest --prefer-online
openhermit --version

② 还报 EBUSY —— 有残留进程没退，杀掉它们（只杀 openhermit/hermit 相关，不碰 VS Code 等）：

# PowerShell
Get-CimInstance Win32_Process -Filter "name='node.exe'" |
  Where-Object { $_.CommandLine -match 'openhermit|hermit' } |
  ForEach-Object { Stop-Process -Id $_.ProcessId -Force

npm install -g @yancyyu/openhermit@latest --prefer-online
③ 兜底 —— 重启

如果上面都不行，或不想敲命令：重启电脑 → 直接 npm install -g @yancyyu/openhermit@latest --prefer-online。重启后没有任何进程占用，必成。

Q: Web UI 打不开

Q: 本地用量里为什么有 IM 用量？

IM 触发的 Agent 执行最终仍落到本地 Claude Code session。AgentCli 统一读取本地 JSONL，再根据 bridge 元数据归因为 source=feishu 或 source=wechat。

Q: worktree 是安全沙箱吗？

不是。worktree 是 Git 工作区隔离，用来降低并行编辑冲突；不等于容器隔离或权限沙箱。

Q: AgentCli 会上传代码或消息内容吗？

默认 metadata-only：不上传消息正文、助手回复、工具输入输出、cron prompt 或 MCP 密钥。具体上报范围取决于管理员在 Settings 中的 Task Bus / Redis 配置。

Q: Codex 上报数据不完整？

这是已知限制。Codex 本地 JSONL 中 input_tokens 字段经常为 0（OpenAI 本地客户端未完整记录），但 output_tokens 正常。不影响总用量统计，只是无法精确展示输入 token 占比。