使用方式

CLI 指南

CLI 是面向运维与自动化场景的终端控制面。它现在收敛到治理主线：本地保存登录 profile、审批、活动流、成本与预算、配置安全、connectors、Runtime Host 发现与 attach-mode session sync、通知、基础设施，以及与现有 API 契约一一对应的 Templates / Runbooks / Agent Config 工作流。

当前状态#

当前状态
CLI 现在已经能覆盖日常治理闭环：登录/profile 管理、Agent 生命周期控制、审批、审计与成本排查、预算、Cron、Config rollback、connector 运维、Runtime Host 发现与会话投影、通知、基础设施、模板、Runbook，以及迁移校验。Hermes / Claude Code / Codex 仍属于部分 Runtime Host 支持，不应表述成与 OpenClaw 完全同权。

安装与准备#

当前仓库里被正式支持的运行方式是在 `apps/cli` 目录下执行。完成依赖同步后，可以通过 `uv run` 使用 `ap` 和 `clawbutler` 两个入口。日常使用建议优先走本地保存的登录 profile，而不是每次重新导出 token。

bash
cd apps/cli
uv sync

uv run clawbutler --version
uv run ap auth login \
  --api-url https://clawbutler.cc \
  --email [email protected]

uv run ap profile list
uv run ap capabilities

命令参考#

认证与会话

创建本地保存的登录会话，刷新会话，查看当前用户，或清除本地 token。

bash
uv run ap auth login --api-url https://clawbutler.cc --email [email protected]
uv run ap auth refresh
uv run ap auth whoami
uv run ap auth logout

Profile 管理

列出已保存环境、切换当前激活环境，或删除旧 profile。

bash
uv run ap profile list
uv run ap profile use staging
uv run ap profile remove old-prod

Chat

创建会话、查看消息历史、在终端流式接收助手响应，或者中止当前流。

bash
uv run ap chat list
uv run ap chat create --agent-id <agent-id> --title "On-call triage"
uv run ap chat messages <session-id>
uv run ap chat send <session-id> "Summarize the current incident"
uv run ap chat abort <session-id>

Dashboard 与 Activity

读取与 Web 顶部总览一致的运行态，再继续下钻最近活动和长任务。

bash
uv run ap dashboard summary
uv run ap activity list --page 1 --page-size 20
uv run ap activity summary 2026-03-10
uv run ap activity long-tasks --status in_progress

Audit 与 Cost

按条件搜索审计历史，查看单个事件或 Trace，再检查成本汇总、拆分、趋势与新鲜度。

bash
uv run ap audit search --risk-level high --date-from 2026-03-01 --date-to 2026-03-10
uv run ap audit show <event-id>
uv run ap audit trace <trace-id>
uv run ap cost summary --date-from 2026-03-01 --date-to 2026-03-10
uv run ap cost trend --granularity day --group-by agent
uv run ap cost freshness

Cron、Config、Analytics、Health

在终端里查看或修改 Cron 任务、比较配置版本、读取保留下来的分析结果、检查预算状态，并直接确认服务健康状态。

bash
uv run ap cron jobs
uv run ap cron create <agent-id> --name daily-report --expression "0 9 * * *" --command "report.generate"
uv run ap cron update <agent-id> daily-report --enabled false --description "Paused for maintenance"
uv run ap cron delete <agent-id> daily-report --confirm
uv run ap config versions <agent-id>
uv run ap config diff <agent-id> --from-version 12 --to-version 14
uv run ap analytics root-cause --days 30
uv run ap budget list
uv run ap health-check status

Connectors、Runtime Hosts、IM Connect 与 Notifications

在终端里创建或诊断 Connector，发现本地 OpenClaw 候选，检查已配对 Runtime Host，batch-add Hermes / Claude Code / Codex / OpenClaw 实例，执行 attach-mode session sync，查看 IM 能力和渠道，完成二维码登录，并直接管理通知状态与偏好设置。

bash
uv run ap connector list
uv run ap connector discovery scan-local
uv run ap connector discovery import-local --candidate-url http://127.0.0.1:8080 --name local-dev
uv run ap runtime-host list
uv run ap runtime-host discover <runtime-host-id>
uv run ap runtime-host batch-add <runtime-host-id> --instance-key <instance-key>
uv run ap runtime-host sync-sessions <runtime-host-id> --instance-key <instance-key> --max-sessions-per-instance 10 --max-messages-per-session 12
uv run ap connector diagnosis <connector-id>
uv run ap connector im capabilities <connector-id>
uv run ap connector im channels <connector-id>
uv run ap connector im config show <connector-id> slack
uv run ap connector im login start <connector-id>
uv run ap connector im login wait <connector-id>
uv run ap connector sync <connector-id>
uv run ap notification list --read false
uv run ap notification read-all
uv run ap notification preference update --email true --cooldown-minutes 15

Infrastructure 与通知就绪度

查看基础设施状态、确认服务 readiness，并让通知状态与运维流程保持一致。

bash
uv run ap infrastructure status
uv run ap health-check status
uv run ap notification list --read false
uv run ap notification preference update --email true --cooldown-minutes 15

Memory、Tool Monitor、Reports

搜索或编辑 MEMORY.md，刷新工具风险摘要，并生成或订阅定期报告。

bash
uv run ap memory search --query policy
uv run ap memory latest <agent-id>
uv run ap memory edit <agent-id> --content-file ./MEMORY.md --change-reason "Refresh operating notes"
uv run ap tool summary
uv run ap tool monitors --risk-level high
uv run ap report list
uv run ap report generate --report-type weekly
uv run ap report subscription list

Templates

创建、查看、校验、预览部署、正式部署或删除模板。当前创建入口是文件驱动的，这样终端契约更稳定，也更适合自动化。

bash
# template-body.json
{
  "name": "Ops Starter",
  "category": "operations",
  "description": "Bootstrap an operations agent",
  "template_config": {
    "model": "gpt-5",
    "temperature": 0.2
  },
  "variables": [
    { "name": "region", "type": "string", "required": true }
  ]
}

# template-vars.json
{
  "region": "us-east-1"
}

uv run ap template create --body-file ./template-body.json
uv run ap template list --category operations
uv run ap template show <template-id>
uv run ap template validate <template-id> <agent-id> --vars-file ./template-vars.json
uv run ap template preview-deploy <template-id> <agent-id> --vars-file ./template-vars.json
uv run ap template deploy <template-id> <agent-id> --vars-file ./template-vars.json --reason "Initial rollout"

Runbooks

创建或更新 Runbook，用 definition 文件生成不可变版本，再从终端触发和排查执行记录。

bash
# runbook-body.json
{
  "name": "Budget Action Escalation",
  "description": "Escalate unusual cost spikes",
  "category": "budget_action",
  "backend": "openclaw_native",
  "trigger_type": "manual",
  "input_schema": {
    "agent_id": { "type": "string" }
  },
  "enabled": true
}

# runbook-definition.json
{
  "required_inputs": ["agent_id"],
  "steps": [
    { "id": "collect", "name": "Collect facts" },
    { "id": "summarize", "name": "Summarize action" }
  ]
}

# runbook-input.json
{
  "agent_id": "6d8c1f8d-4e09-4bfe-8a11-1b0f14e15a1a"
}

uv run ap runbook create --body-file ./runbook-body.json
uv run ap runbook update <runbook-id> --body-file ./runbook-body.json
uv run ap runbook create-version <runbook-id> --definition-file ./runbook-definition.json --change-summary "Initial steps"
uv run ap runbook trigger <runbook-id> --input-file ./runbook-input.json
uv run ap runbook runs <runbook-id>
uv run ap runbook run-show <runbook-id> <run-id>

Config 回滚、漂移检查与 Agent 配置编辑

在终端里执行 Config Safety，查看与 Web 一致的 Agent Config tab，并用明确的文件驱动输入更新 workspace files、models 或 skills。

bash
# skills.json
[
  { "name": "search", "source": "builtin", "enabled": true }
]

uv run ap config rollback <agent-id> --target-version 12 --reason "Rollback after incident" --dry-run
uv run ap config rollback <agent-id> --target-version 12 --reason "Rollback after incident" --confirm
uv run ap config drift-check <agent-id>
uv run ap agent config overview <agent-id>
uv run ap agent config files <agent-id>
uv run ap agent config tools <agent-id>
uv run ap agent config channels <agent-id>
uv run ap agent config cron <agent-id>
uv run ap agent config raw <agent-id> --tab overview
uv run ap agent config file show <agent-id> AGENTS.md
uv run ap agent config file put <agent-id> AGENTS.md --content-file ./AGENTS.md
uv run ap agent config models update <agent-id> --primary-model gpt-5 --fallback gpt-4.1-mini
uv run ap agent config skills update <agent-id> --body-file ./skills.json

Agent 管理

按条件筛选 Agent，创建新 Agent，查看详情，切换启用状态，或带确认删除。

bash
uv run ap agent list --health-status healthy --enabled true
uv run ap agent create --name EmailAgent --platform openclaw --description "Inbound email triage"
uv run ap agent show <agent-id>
uv run ap agent enable <agent-id>
uv run ap agent disable <agent-id>
uv run ap agent delete <agent-id> --confirm

审批处理

先列出或查看审批详情，再做单条或批量处理，并对单个 Connector 读取或更新审批规则。

bash
uv run ap approval list --status all --limit 20 --page 1
uv run ap approval show <approval-id>
uv run ap approval approve <approval-id> --decision-type allow-once --reason "Reviewed by on-call"
uv run ap approval reject <approval-id> --reason "Blocked by policy"
uv run ap approval batch approve --approval-id <id-1> --approval-id <id-2> --decision-type allow-always --confirm
uv run ap approval rules show --connector-id <connector-id>
uv run ap approval rules update --connector-id <connector-id> --rules-file ./approval-rules.json

Kill Switch

查看当前熔断状态，触发熔断，或恢复 Agent。

bash
uv run ap kill-switch status
uv run ap kill-switch trigger <agent-id> --reason "Suspicious activity"
uv run ap kill-switch recover <agent-id> --reason "Issue resolved"

迁移清单

创建迁移导出、保存成可直接导入校验的 manifest 文件，并对该文件做不写入数据的校验。

bash
uv run ap export manifest --group connectors --group agents --output ./migration-manifest.json
uv run ap import validate ./migration-manifest.json
uv run ap import validate ./migration-manifest.json --json

示例工作流#

登录一次并复用会话

通过 `auth login` 创建或更新本地保存的 profile。之后普通 CLI 命令会优先读取当前激活 profile 的凭据，除非你显式用环境变量覆盖它。

bash
uv run ap auth login \
  --api-url https://clawbutler.cc \
  --email [email protected]

uv run ap profile list
uv run ap auth whoami

在终端里流式接收 Chat 回复

CLI Chat 现在已经是可直接使用的终端工作流。先创建会话，再查看当前 transcript，最后发送消息并直接在终端里观察流式返回。

bash
uv run ap chat create --agent-id <agent-id> --title "On-call triage"
uv run ap chat messages <session-id>
uv run ap chat send <session-id> "Summarize the latest rollback chain"

在维护窗口前检查 Agent

先通过 `agent list` 找到目标，再用 `agent show` 确认健康状态、运行状态和启用状态后再做变更。

bash
uv run ap agent list
uv run ap agent show 6d8c1f8d-4e09-4bfe-8a11-1b0f14e15a1a --json

在终端里处理待审批请求

先列出 pending 审批。除非你明确需要持久信任规则，否则保持默认的 `allow-once` 更稳妥。

bash
uv run ap approval list --limit 10
uv run ap approval approve 4f65b8a2-2a17-457c-a6a7-0fbc6c16f5dc \
  --decision-type allow-once \
  --reason "Matches change request CR-1042"

执行紧急熔断

恢复前应先查看当前 kill-switch 状态。恢复命令会发送显式确认字段，并为写操作附带新的幂等键。

bash
uv run ap kill-switch status
uv run ap kill-switch trigger 6d8c1f8d-4e09-4bfe-8a11-1b0f14e15a1a --reason "Unexpected outbound calls"
uv run ap kill-switch recover 6d8c1f8d-4e09-4bfe-8a11-1b0f14e15a1a --reason "Traffic normalized"

在终端里做一次事故排查

先看 dashboard，再跳到带过滤条件的 activity 或 audit，最后确认成本或 cron 异常是否属于同一事件链。

bash
uv run ap dashboard summary
uv run ap activity list --event-type task.failed --date-from 2026-03-10
uv run ap audit search --keyword "rollback" --date-from 2026-03-10
uv run ap cost rate-alerts
uv run ap cron alerts 6d8c1f8d-4e09-4bfe-8a11-1b0f14e15a1a

回滚前先比较配置版本

CLI 现在已经提供配置历史、语义 diff、dry-run rollback 和手动 drift check，能够覆盖 Web 里的调查与恢复闭环。

bash
uv run ap config versions 6d8c1f8d-4e09-4bfe-8a11-1b0f14e15a1a --page 1
uv run ap config diff 6d8c1f8d-4e09-4bfe-8a11-1b0f14e15a1a --from-version 18 --to-version 21
uv run ap config rollback 6d8c1f8d-4e09-4bfe-8a11-1b0f14e15a1a --target-version 18 --reason "Preview rollback" --dry-run
uv run ap config drift-check 6d8c1f8d-4e09-4bfe-8a11-1b0f14e15a1a

在终端里接入 Runtime Host

当浏览器不可用时，CLI 仍然可以完成 Runtime Host 闭环：检查已配对机器、发现本地 runtime、为选中的实例创建 connector，并把 attach-mode session 投影进 ClawButler 供后续调查。

bash
uv run ap runtime-host list
uv run ap runtime-host discover <runtime-host-id>
uv run ap runtime-host batch-add <runtime-host-id> --instance-key <instance-key>
uv run ap runtime-host sync-sessions <runtime-host-id> --instance-key <instance-key>
uv run ap connector list
uv run ap notification preference show

安全地编辑 Agent 文件、Models 与 Skills

CLI 现在已经能按当前 Web Agent Config tab 做读取，同时支持 Web 现有的 file、model、skills 写入面。文件写入会自动计算当前 SHA-256，Models 用明确参数更新，Skills 则是文件驱动 JSON。

bash
uv run ap agent config overview <agent-id>
uv run ap agent config tools <agent-id>
uv run ap agent config channels <agent-id>
uv run ap agent config cron <agent-id>
uv run ap agent config file show <agent-id> AGENTS.md
uv run ap agent config file put <agent-id> AGENTS.md --content-file ./AGENTS.md
uv run ap agent config models update <agent-id> --primary-model gpt-5 --fallback gpt-4.1-mini
uv run ap agent config skills update <agent-id> --body-file ./skills.json

一次终端串起 Memory、Tool Risk 与 Reports

在运维追踪里，CLI 现在可以从 memory 搜索直接切到 tool risk，再继续生成和查看 report，不需要切换到浏览器。

bash
uv run ap memory search --query "policy"
uv run ap tool monitors --risk-level high
uv run ap report generate --report-type weekly
uv run ap report show <report-id>

先预览再部署模板

Template 在终端里最稳妥的流程是先查看或校验，再针对目标 Agent 做 preview，最后用同一份变量文件执行 deploy。这样浏览器和 CLI 看到的是同一套契约。

bash
uv run ap template show <template-id>
uv run ap template validate <template-id> <agent-id> --vars-file ./template-vars.json
uv run ap template preview-deploy <template-id> <agent-id> --vars-file ./template-vars.json
uv run ap template deploy <template-id> <agent-id> --vars-file ./template-vars.json --reason "Approved rollout"

仅用终端完成 Runbook 发版与触发

Runbook 当前是文件驱动模型。建议把 definition JSON 放进版本控制，再从该文件创建版本，并用独立 input JSON 或内联覆盖值来触发执行。

bash
uv run ap runbook create-version <runbook-id> --definition-file ./runbook-definition.json --change-summary "Raise alert threshold"
uv run ap runbook trigger <runbook-id> --input-file ./runbook-input.json --input dry_run=true
uv run ap runbook runs <runbook-id>
uv run ap runbook run-show <runbook-id> <run-id>

校验已有的迁移 manifest

CLI 现在已经可以创建迁移导出，并把 inline manifest 保存成可直接使用的 JSON 文件。由于验证仍是只读的，所以这里更适合作为兼容性门禁，而不是写入执行器。

bash
uv run ap export manifest --group connectors --group agents --output ./migration-manifest.json
uv run ap import validate ./migration-manifest.json
uv run ap import validate ./migration-manifest.json --json

与 Web 的对齐边界#

CLI 当前已交付

  • - 本地保存的认证登录（`auth login/refresh/logout/whoami`）
  • - 本地保存的环境 profile（`profile list/use/remove`）
  • - 能力探测（`capabilities`）
  • - Dashboard 摘要、Activity 流与长任务可见性
  • - Audit 搜索 / 事件详情 / Trace 重建
  • - Cost 汇总、拆分、趋势、速率告警与新鲜度
  • - Cron jobs、runs、summary、连续失败告警，以及 CRUD（`cron create/update/delete`）
  • - Config 版本历史与语义 diff
  • - Config rollback 预览、执行与 drift check
  • - 流式 Chat 会话与消息历史
  • - Memory 搜索、latest、history 与 edit
  • - Tool Monitor 的 summary、list 与 refresh
  • - Reports 的生成、重试与订阅管理
  • - Analytics 的 root-cause、reliability、value，以及预算查看与熔断相关命令
  • - 服务健康与 readiness 检查
  • - Connector 生命周期、本地发现与 IM Connect（`connector list/show/create/update/delete/test/security-check/diagnosis/sync/discovery/im`）
  • - Runtime Host 生命周期（`runtime-host list/show/discover/batch-add/sync-sessions`），用于 Hermes / Claude Code / Codex / OpenClaw 发现与 attach-mode 投影
  • - 通知收件箱、订阅与偏好设置管理
  • - 基于 capability profile 的基础设施状态检查
  • - Template 生命周期（`template list/show/create/import/validate/preview-deploy/deploy/delete`）
  • - Runbook 生命周期（`runbook list/show/create/update/versions/create-version/trigger/runs/run-show/cancel`）
  • - 与 Web 对齐的 Agent Config tab 读取，以及 file/model/skills 写入（`agent config overview/files/tools/channels/cron/show/raw/file/models/skills`）
  • - Agent list / create / show / enable / disable / delete
  • - approval list / show / approve / reject / batch / rules
  • - kill-switch status / trigger / recover
  • - 迁移导出与可直接校验的 manifest 保存
  • - 针对既有 manifest 的导入校验
  • - 支持命令的 `--json` 机器可读输出

相对 Web 仍缺失

  • - 相对当前 Web 已交付运维闭环，没有已知 CLI 缺口；后续新增页面或写操作时需重新审计。
  • - Hermes / Claude Code / Codex 仍属于 Runtime Host 集成阶段：已支持发现、batch-add connector、attach-mode session sync，但 provider-native 审批、成本、时间线、托管控制仍未补齐。
无法做到完全相同体验的地方
  • - 图表、Dashboard 和时间线在 CLI 里最多只能变成表格、JSON 或文本报表，不能复刻同样的视觉体验。
  • - 浏览器权限和移动端推送流程无法原样搬到终端，CLI 只能做等价告警或跳转交接。
  • - Web 的多面板复杂编辑需要在 CLI 中改为 `$EDITOR`、补丁文件或引导式交互模型。
  • - CLI Chat 已经做到能力等价，但它仍然是终端 transcript，不会复制浏览器里的 split-pane 会话界面。
  • - Runtime Host 命令今天可以发现并同步 Hermes / Claude Code / Codex 会话，但这些 provider 仍没有达到 OpenClaw 连接器同等的原生控制深度。

建议预留截图#

Screenshot Placeholder
CLI 初始化与 capability 检查
展示已配置 token 后的 `uv run clawbutler --version` 与 `uv run ap capabilities`。
Screenshot Placeholder
Dashboard 到 Audit 的事故排查流程
展示 `ap dashboard summary`、`ap activity list` 和 `ap audit search` 串起来的一条排查链路。
Screenshot Placeholder
Runtime Host 发现与会话同步流程
展示 `ap runtime-host discover`、`ap runtime-host batch-add` 与 `ap runtime-host sync-sessions` 串起来的一条终端接入链路。
Screenshot Placeholder
Template 预览与部署流程
展示 `ap template validate`、`ap template preview-deploy` 和 `ap template deploy` 共用同一份变量文件。
Screenshot Placeholder
Runbook 发版与执行流程
展示 `ap runbook create-version`、`ap runbook trigger` 与 `ap runbook run-show` 对同一个 Runbook 的操作链路。
Screenshot Placeholder
终端 Chat 流式会话
展示 `ap chat messages` 后接 `ap chat send` 的流式输出。
Screenshot Placeholder
Agent 配置文件与 Model 编辑流程
展示 `ap agent config overview`、`ap agent config channels`、`ap agent config file put` 与 `ap agent config models update` 的组合链路。
Screenshot Placeholder
Cron CRUD 与预算守护流程
展示 `ap cron create`、`ap cron update` 与 `ap budget list` 串起来的一条调度与预算巡检链路。
Screenshot Placeholder
终端审批处理流程
展示 `ap approval list` 的输出，以及后续审批命令和成功确认。
Screenshot Placeholder
审批批量处理与规则编辑流程
展示 `ap approval batch approve` 与 `ap approval rules update`，说明终端里也能完成高频审批与策略修改。
CLI 指南 — ClawButler