Local-first · 本地控制面 · v1.9.31

AgentCli

本地优先的 AI 数字员工工作台。CLI 给 agent，Web 给人——自动采集 Claude Code / Codex / Cursor 等运行时用量，统一管理数字员工团队。

AgentCli 管本地运行时与工作台，数据默认落在本机 ~/.hermit/；AgentBus 负责消息路由、团队协作与组织级用量汇总。

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

npm install -g @yancyyu/agentcli

# 无需安装，直接运行
npx @yancyyu/agentcli

安装 / 更新报错？ Windows 遇到 EBUSY: resource busy or locked 不是权限问题（别用 sudo / 管理员），通常是 Web daemon 或用量 worker 还占着文件。先按需停掉后台服务再装：

agentcli services stop web
agentcli usage stop
npm install -g @yancyyu/agentcli@latest --prefer-online

agentcli stop 只显示停止指引，不会主动关闭后台服务；完整排查见下方 FAQ。

卸载先停掉后台服务，再卸载包：

agentcli services stop web
agentcli usage stop
npm uninstall -g @yancyyu/agentcli

裸 agentcli stop 不会停止 worker；本地数据 ~/.hermit/ 不会自动删除；确认无需保留后可手动 rm -rf ~/.hermit。

本地控制面 + 消息总线

先把本机 AI 运行时管起来，再把团队消息、任务与用量接入统一总线。AgentCli 负责本地控制面，AgentBus 负责跨团队协调。

本地控制面

AgentCli

本地优先的 CLI + Web 工作台。你现在就能装、立刻能用。

交互式终端菜单 + 全套子命令（账号 / 用量 / 团队 / 服务 / 插件）
本地 Web 工作台：团队、看板、运行时、代码评审
自动采集本机 AI 运行时用量（token / 会话 / 消息）
数据默认落 ~/.hermit/，单机完整可用，无需注册
token 池认领：签发网关 key → 直接写入所选 Claude Code / Codex 配置；不修改 shell 启动文件、不安装 shell hook
支持自托管、可二次开发

装好之后从这几条命令开始 →

消息总线 · 协调层

AgentBus

统一消息、任务与用量的协调层，把多个本地控制面连接成团队协作网络。

企业级用量看板：按团队 / 成员 / 运行时 / 时间段汇总
IM 消息路由：飞书、微信等消息直达数字员工、触发任务
跨团队任务派发与 Task Bus（offer / bid / lease）
完整审计轨迹、权限与渠道白名单
统一收敛全组织的 AI 工程用量与协作数据

关系一句话

AgentCli（本地控制面）是操作面，读写本地数据；AgentBus（消息总线）是协调骨干，提供团队协作、IM 路由与组织级看板。不接 Bus = 本地控制面独立运行；接入 Bus = 消息、任务、用量进入统一协调层。

核心能力

从用量可见，到数字员工团队化。

⚙

自动采集

无侵入扫描本地 AI Agent 会话日志，自动识别 token 消耗、会话数、消息量，零配置开箱即用。

⇄

统一上报

多运行时、多场景汇总至 AgentBus。断点续传、幂等去重、背压控制。

📊

用量看板

按团队、成员、工具、场景维度展示 token 用量与会话活跃度。

👥

数字员工团队

创建团队、配置成员与运行时、看板派活、评论协作、审核交付。

🔌

多运行时协调

Claude Code、Codex、Cursor、Gemini、OpenCode 在一个面板里启动与监控。

🔒

本地优先 · 安全

默认 metadata-only 上报，不上传消息正文、代码或密钥。数据在你本机。

常用命令

装好之后从这几条开始。命令统一为 agentcli，所有命令支持 --json 输出机器可读结果（适合 agent / 脚本调用）。也可以直接把本说明书链接 https://yancyuu.github.io/agentcli/ 丢给 Claude Code / Codex，让 agent 按步骤安装、登录、上报和自检。

启动与状态

agentcli打开终端导航（控制面菜单）：工作台、用量同步、用户、token 池(beta)

工作台 → 开通数字员工快速创建并绑定飞书；仅支持 Claude Code / Codex。以 lark-cli 的个人 as user 身份校验数字员工必需权限，成功后静默尝试一次凭证上报

agentcli init快速初始化：默认启动 Web 工作台 + 用量后台 worker（默认开机自启）

agentcli web直接启动 Web 工作台（默认 127.0.0.1:5680）；加 --daemon 后台运行

agentcli status · doctor查看后台运行状态 / 只读本地诊断

agentcli stop显示停止指引（不会主动关闭 Web / 用量 worker）

agentcli services stop web停止 Web 后台 daemon

agentcli restart重启 Web daemon + 用量 worker（更新后用它让新代码生效；本地命令，免登录）

用户授权（上报前提）

agentcli auth login飞书授权登录 AgentBus——登录后用量才有上报目标

agentcli auth status查看 AgentBus 用户授权状态

用量采集与上报

agentcli usage status后台 worker 是否运行、消息上报是否开启

agentcli usage start开启轻量后台采集，默认配置开机自启

agentcli usage stop停止用量后台 worker，并默认关闭开机自启

agentcli usage report立即扫描并按服务端游标增量上报；--full 手动补报最近 7 天

agentcli usage today查看今日本地用量摘要（不上传）

团队 / 任务 / 维护

agentcli teams list · create查看 / 创建本地团队

agentcli tasks list --team <t>查看某团队活跃任务

agentcli update检查并自更新到最新版本

agentcli add <plugin>安装能力插件到 MCP library

快速创建数字员工

运行 agentcli，进入「工作台 → 开通数字员工」：填写名称与描述，选择 Claude Code 或 Codex，并绑定飞书。系统以本次飞书应用对应的 lark-cli profile 为创建者申请个人 as user 授权（新 profile 固定为 agentcli-user-<appId>）。--domain all 只能请求 lark-cli、飞书应用与租户允许授予的权限，完成后仍必须通过文档、云盘、消息收发、通讯录与用户信息的权限校验；仅有 contact:user.basic_profile:readonly 不会通过。CLI 优先在终端显示二维码，并同时尝试打开默认浏览器；无法渲染二维码或自动打开浏览器时，仍会显示完整授权链接。校验成功后会静默尝试一次凭证上报到 AgentBus；上报失败不影响本地授权和数字员工创建，也不会打印凭证。若仍缺权限，请更新 lark-cli，再在飞书应用和租户后台启用/审批缺失权限后重试。成员、权限与高级参数可随后在 Web 工作台调整。

配置 AI 运行时（客户端配置）

AgentCli 读写的本机配置位置，以及如何把网关 key 写进 Claude / Codex。

本机数据来源

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

把网关 Key 写进 Claude / Codex（token 池认领）

登录后，在终端菜单 agentcli →「token 池(测试版)」→「认领」，会自动签发一个一次性网关 key，当前默认且唯一写入目标是 Codex（Claude Code 保留为后续可恢复选项），然后直写进本地配置：

Claude Code ~/.claude/settings.json：写入网关 endpoint（ANTHROPIC_BASE_URL）+ ANTHROPIC_AUTH_TOKEN，deep-merge 保留其它键，不固定模型。
Codex ~/.codex/auth.json（OPENAI_API_KEY）+ ~/.codex/config.toml：surgical 改写 model_provider / model / wire_api 与 [model_providers.*]，原样保留 [projects.*]。Codex base_url 由网关 proxyPaths 按所选 wire_api 解析，与 Claude endpoint 不同。

配置文件是 Claude Code / Codex 的常规生效路径：AgentCli 不再修改 .zshrc / .bashrc，也不安装 precmd / PROMPT_COMMAND shell hook；重新启动所选运行时即可读取新配置。~/.hermit/aikey.env 仍以 0600 权限保留为认领标记，外部 agent 需要时可手动 source。

api key 与 base url 怎么用

Claude Code 认 ANTHROPIC_AUTH_TOKEN，认领时已写入 ~/.claude/settings.json 的 env 块（不是 shell 环境变量）——重启 Claude Code 即生效，无需 source 或 export。Codex 认 ~/.codex/auth.json 的 OPENAI_API_KEY。外部 agent / 手动调用才 source ~/.hermit/aikey.env，里面导出的是 ANTHROPIC_API_KEY。ANTHROPIC_AUTH_TOKEN（Claude 专用）与 ANTHROPIC_API_KEY（aikey.env / 外部 agent）是两个不同的变量，别混用。

注意

首次写入前自动把原始 Claude/Codex 配置快照到 ~/.hermit/agentcli.env.bak（只创建一次，后续认领不覆盖）；在「token 池 → 一键恢复原始配置」可随时还原，token 池新建的文件会被删除、无残留。检查快照时会自动修正旧版本遗留的备份路径记录。认领到的 key 是即焚明文，不落库、不回显明文。该能力需服务端授权开通（部分账户暂未开放）。

开启用量上报（三要素）

自动上报需要三件事同时满足：已登录 + 消息上报已开启 + 后台采集运行中。缺一不上报。

登录上报目标 — agentcli auth login（飞书授权绑定 AgentBus），agentcli auth status 确认已登录。
启用消息上报 — agentcli →「用量同步」→ 回车展开 →「消息上报」开启，选择上报运行时。该开关只在终端菜单 / Web 里，没有单独子命令。
启动后台采集 — 推荐 agentcli services start web 启动 Web 工作台，agentcli usage start 启动后台 worker。后台 worker 默认开机自启，约 5 分钟按服务端 cursor 增量扫描。停止用 agentcli usage stop。
立即补报一次 — agentcli usage report（增量）；usage report --full 手动全量重扫最近 7 天。
核对状态 — agentcli usage status，或 Web 工作台「用量」Tab。

上报不工作？三要素自检

按顺序排查：auth status（已登录？）→ usage status（worker running 且消息上报 enabled？）→ usage report（手动触发一次看输出）。补报历史用 usage report --full。

隐私

默认 metadata-only：只上报 token 数、时间戳、维度，不上传消息正文、助手回复、工具输入输出或密钥。具体范围取决于 AgentBus 管理员配置。

安全更新 AgentCli

更新会替换全局安装目录中的文件。为避免 Windows 的 EBUSY、旧 worker 继续运行旧代码或渠道连接未释放，推荐先停止会加载 AgentCli 包文件的本地进程，再安装新版本。

使用内置更新命令

agentcli update 是内置自更新：免登录（本地生命周期命令），且固定走官方 registry.npmjs.org——避免默认镜像（如 npmmirror）同步延迟导致装到旧版或 ETARGET。它会在成功后热重载用量 worker，但不重启 Web daemon；更新后跑一次 agentcli restart 让 Web daemon / hermit-bridge / cc-connect 也切到新代码。为最大限度避免 Windows 文件锁，仍建议先运行 agentcli services stop web；如果更新报 EBUSY，改用上面的完整手动流程。

不要漏停这些进程

用量 worker 用 agentcli usage stop；Web daemon 和它托管的渠道运行时用 agentcli services stop web。独立运行的第三方 bridge 不属于 AgentCli 包更新范围；如果操作系统仍提示文件被占用，只终止与 agentcli / hermit / cc-connect 明确相关的残留进程，不要批量杀死所有 Node 进程。

数据不会因更新被删除

上述停止和更新命令不会删除 ~/.hermit/ 中的团队、渠道配置、登录态或用量状态。更新后使用 agentcli restart 恢复服务即可。

支持的 AI 编程工具

一等适配 + 兼容注册，持续扩展。

Claude Code Codex Cursor Gemini CLI OpenCode Kimi Devin Qoder

架构

开发者本地
Claude Code / Codex / Cursor / Gemini / OpenCode ...
    ↓ 会话日志 & token 用量
AgentCli (本地 CLI + Web 工作台)
    ↓ 统一上报
AgentBus (消息总线 · 协调层)
    ↓ 看板 & 协作
企业管理者 / 团队成员

常见问题

Q：EBUSY: resource busy or locked（Windows 安装 / 更新）

原因：不是权限问题（EBUSY ≠ EACCES），sudo / 管理员身份无效。是之前运行过的 agentcli 后台进程还占着包内文件，npm 无法替换。

解决（按顺序，多数第 ① 步就够）：

agentcli services stop web      # 停 Web daemon
agentcli usage stop            # 停用量后台 worker
npm install -g @yancyyu/agentcli@latest --prefer-online

agentcli stop 只显示停止指引，不会主动关闭 Web / 用量 worker；还不行就杀掉残留 node 进程（只杀 agentcli / hermit 相关），或直接重启电脑后重装。

Q：EACCES: permission denied（权限报错）

原因：之前用 sudo 运行过，部分文件被 root 占有。

sudo chown $(whoami) ~/.hermit/telemetry/worker.pid
# npm global 目录也报错时：
sudo chown -R $(whoami) ~/.npm-global

预防

不要用 sudo 运行 agentcli 或 npm install -g。

Q：agentcli 命令找不到

npm 全局 bin 目录不在 PATH。添加到 ~/.zshrc 或 ~/.bashrc：

export PATH="$(npm config get prefix)/bin:$PATH"

Q：更新失败 / 想强制重装

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

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

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

Q：AgentCli 和 AgentBus 是什么关系？

AgentCli 是本地 CLI + Web 控制面，负责管理本机 AI 运行时、用量采集、工作台与团队任务。AgentBus 是消息总线与协调层，负责 IM 路由、跨团队任务派发、组织级用量汇总与审计。不接 Bus 时，AgentCli 仍可作为本地控制面独立运行；接入 Bus 后进入团队协作网络。

AgentCli

本地控制面 + 消息总线

AgentCli

AgentBus

核心能力

自动采集

统一上报

用量看板

数字员工团队

多运行时协调

本地优先 · 安全

常用命令

配置 AI 运行时（客户端配置）

本机数据来源

把网关 Key 写进 Claude / Codex（token 池认领）

开启用量上报（三要素）

安全更新 AgentCli

推荐流程（手动更新，最稳妥）

使用内置更新命令

支持的 AI 编程工具

架构

常见问题