<span id="cli"></span>
# CLI 命令参考

`openprogram` 全部子命令的速查表。每条命令都可以用 `openprogram <command> -h` 查看自己的帮助；子命令的动词再套一层，如 `openprogram logs tail -h`。

> [!NOTE]
> 侧栏的 **CLI 命令** 分区里每条命令有一页生成文档——完整参数表，
> 每次构建文档站时从参数解析器重新生成，永不与代码脱节。本页是人工整理的总览。

## 全局用法

```bash
openprogram                      # 打开终端聊天 UI（TUI）
openprogram --print "..."        # 一次性 prompt：发送、打印回复、退出
openprogram --resume <id>        # 恢复此前的 CLI 聊天会话
openprogram --profile <name>     # 状态目录 profile，改道到 ~/.openprogram-<name>/
```

| 选项 | 作用 |
|------|------|
| `--print PROMPT` | 一次性 prompt，打印回复后退出 |
| `--profile PROFILE` | 状态目录 profile，等价于环境变量 `OPENPROGRAM_PROFILE` |
| `--resume SESSION_ID` | 恢复会话；id 用 `openprogram sessions list` 或 Web UI 侧栏查 |
| `--no-alt-screen` | 使用行内 TUI 并保留终端滚屏 |
| `--screen-reader` | 使用不启用鼠标追踪的行内无障碍模式 |

## 聊天与运行

| 命令 | 作用 | 关键参数 |
|------|------|----------|
| `openprogram` | 打开聊天；裸跑会先问开终端 UI 还是 Web UI，没有 worker 时自动拉起 | — |
| `openprogram tui`（别名 `chat`） | 在 Windows、macOS 或 Linux 直接启动 Ink 终端 UI；无法提供 raw input 的终端回退到 Rich | `--print`、`--resume`、`--no-alt-screen`、`--screen-reader` 在动词后同样可用 |
| `openprogram web` | 启动服务并打开浏览器 UI（`http://localhost:18100`） | `--web-port`（仅本次运行；默认：已存偏好，否则 18100）、`--no-browser` |

## 后台服务

| 命令 | 作用 |
|------|------|
| `status` | 后台服务是否在跑（PID、端口、运行时长） |
| `stop` | 停止后台服务 |
| `restart` | 重启（改了代码 / 配置之后用） |

`worker` 子命令提供更细的控制：

| 命令 | 作用 |
|------|------|
| `worker run` | 前台运行 worker（阻塞），调试用，Ctrl-C 停止 |
| `worker start` | 后台启动一个 worker 并返回 |
| `worker stop` | 停止（SIGTERM，必要时升级为 SIGKILL） |
| `worker restart` | 停掉再起一个新的 |
| `worker status` | 是否在跑、PID、端口、运行时长 |
| `worker install` | 安装为系统服务（macOS launchd / Linux systemd --user），随登录启动、崩溃重启 |
| `worker uninstall` | 移除系统服务 |

## 安装与配置

| 命令 | 作用 | 关键参数 / 动词 |
|------|------|----------|
| `setup` | 首次运行的设置向导 | `menu` 打开交互选择器；给一个分区名直达（model / tools / agent / skills / ui / memory / profile / search / tts / channels / backend） |
| `config` | 查看 / 修改设置 | `list`（全部设置：值、分组、生效方式）、`get <key>`、`set <key> <value>` |
| `ports` | 查看 / 持久化 Web UI 的单端口 | `--port PORT`（默认 18100） |
| `completion` | 输出 shell 补全脚本 | `bash` / `zsh` / `powershell` / `pwsh` |

### providers —— LLM provider 与凭据

`secrets` 是 `providers` 的别名。

| 动词 | 作用 |
|------|------|
| `login <provider>` | 登录一个 provider；`--api-key` / `--api-key-stdin` 非交互提供 key，`--account` 指定账号，`--method` 强制指定登录方式 |
| `logout` | 移除一个 provider 的凭据 |
| `list` | 按账号列出凭据池 |
| `available`（别名 `search`、`catalog`） | 列出全部可配置的 provider，可加 QUERY 过滤 |
| `status` | 检查一个 provider 当前的凭据 |
| `use` | 设置一个 provider 使用哪个账号 |
| `discover` / `adopt` | 扫描外部来源的凭据 / 收编进凭据库 |
| `doctor` | 诊断凭据（过期、刷新、冷却、冲突） |
| `setup` | 交互式首次配置 |
| `aliases` | 列出 provider 短名别名 |
| `accounts` | 账号管理（`list` / `create` / `delete`） |
| `migrate` | 把存储的凭据迁移到当前格式 |

不带动词的 `openprogram providers` 打印当前全部凭据的状态表。

### mcp —— MCP server

| 动词 | 作用 |
|------|------|
| `token create` | 创建并打印本地 stdio MCP server 的认证 token |
| `serve` | 通过本地 stdio 提供认证后的 MCP server |
| `list` | 列出全部已配置的 MCP server 及状态 |
| `show` | 显示一个 server 的工具与完整 schema |
| `add` | 添加 stdio 命令型 server，写入 `mcp_servers.json` 并立即启动 |
| `rm` | 移除（停止 + 删配置） |
| `restart` / `enable` / `disable` | 重启 / 启用并启动 / 停止并标记禁用（保留配置） |
| `edit` | 兼容入口：报告直接编辑配置已移除；请用 `add` / `rm` 或 MCP 设置页 |
| `test` | 临时启动一个配置，验证能起来并返回工具列表，不落盘 |

`token create` 把原始 token 打印为一行，但不会设置
`OPENPROGRAM_MCP_TOKEN`。只运行一次，复制打印出的那一行，在 `serve` 前设置变量：

```bash
openprogram mcp token create
export OPENPROGRAM_MCP_TOKEN="<把上一步打印的 token 粘贴到这里>"
openprogram mcp serve
```

如果 token 已经存在，请使用此前保存的 token。`serve` 要求
`OPENPROGRAM_MCP_TOKEN` 与已保存的 token 完全匹配。

### browser —— 浏览器工具

| 动词 | 作用 |
|------|------|
| `install` | 开发者用于增加或替换 Browser backend（patchright/camoufox/agent-browser）的命令。release 安装已包含默认 Playwright Chromium backend。 |
| `status` | 显示安装情况、sidecar Chrome 是否在跑、保存的登录数 |
| `refresh` | 重新把真实 Chrome profile 拷到 sidecar（在主 Chrome 登录新站点后用） |
| `reset` | 完全重置：杀 sidecar、清 profile + 登录态 + 端口文件 |
| `list` / `rm` | 列出 / 删除 `~/.openprogram/browser-states/` 下保存的登录 |

## 内容管理

### agents

| 动词 | 作用 |
|------|------|
| `list` / `show` / `add` / `rm` | 列出 / 查看 / 创建 / 删除 agent（删除会连带其全部会话） |
| `set-default` | 设为默认 agent |

### sessions

| 动词 | 作用 |
|------|------|
| `list` | 列出所有 agent 的全部会话 |
| `resume` | 回答一个等待中的会话 |
| `attach` / `detach` | 把频道用户的消息路由进某会话 / 取消别名（`--channel`、`--peer` 必填；`--account`、`--peer-kind` 可选） |
| `aliases` | 列出全部会话与频道用户的别名 |

### subagent

| 动词 | 作用 |
|------|------|
| `spawn` | 在某会话里生成一个新分支的 agent：`--session` 和 `--prompt` 必填；`--parent-msg` 指定分叉节点，`--label` 命名分支，`--agent` 选 agent profile（默认 `main`），`--context inherit\|clean`（或 `--clean`），`--no-json` 打印人类可读摘要 |
| `merge` | 把多个 subagent 会话合并进目标会话形成新 turn：`--target` 与可重复的 `--branch SID` 必填；`--message` 是合并指令，`--agent` 选合并 agent，`--base N` 把某个分支标记为合并基底，`--no-json` 打印人类可读摘要 |

### programs

| 动词 | 作用 |
|------|------|
| `run <name>` | 运行一个 program；`--arg key=value`（可重复）、`--provider`、`--model` |
| `list` | 列出保存的 program |
| `available` | 列出可安装的 program 与已装的第三方 harness |
| `install` / `uninstall` | 开发者使用的第一方源码 overlay（gui/research/wiki/all），或安装/卸载额外第三方 harness（git URL / owner/repo）；受支持的 release 已包含全部第一方 Program，并拒绝修改 immutable runtime |

### skills

| 动词 | 作用 |
|------|------|
| `list` | 列出发现的技能 |
| `search` / `install` | 在发现源（默认 ClawHub）搜索 / 安装技能 |
| `update` | 重拉过期技能（比对 SKILL.md 哈希） |
| `remove` | 删除已装技能 |
| `doctor` | 扫描技能目录的问题 |

### plugins

| 动词 | 作用 |
|------|------|
| `list` / `search` | 列出已装插件 / 搜索 marketplace |
| `install` / `uninstall` / `update` | 从 pip / npm / git / 路径安装、卸载、升级 |
| `enable` / `disable` | 启用 / 禁用 |

### channels —— 聊天频道机器人

| 动词 | 作用 |
|------|------|
| `list` | 各平台的启用与配置状态 |
| `setup` | 交互向导：选频道、登录（扫码 / token）、绑定 agent |
| `accounts` | 管理频道机器人账号（WeChat、Telegram 等） |
| `bindings` | 把入站频道消息路由到 agent |
| `access` | 谁能进到 agent：`list`、`approve <code>`、`allow <user_id>`、`revoke <user_id>`。未知发信人走默认 pairing 流程；owner 可以用 `allow <user_id>` 将已知的平台 user ID 直接加入 allowlist（见[聊天渠道](../integrations/channels.zh.md#谁能和你的机器人说话)） |

### memory —— 持久记忆

每个实例只有一份工作区，所有agent、所有对话（含聊天渠道）共用。

| 动词 | 作用 |
|------|------|
| `status` | 显示 workspace 内容、revision、writer 健康状态和 pending turns |
| `recall QUERY...` | 搜索记忆并打印匹配段落 |
| `show PATH` / `edit PATH` | 打印 / 用 `$EDITOR` 编辑一个记忆文件 |
| `sleep` | 立即整理 topic 文件；`--model MODEL` 指定整理模型 |
| `backfill` | 写入没有被 Topic 引用的可信 source 记录；`--model MODEL` 指定写入模型 |
| `export` | 把整个记忆目录 tar+gzip 打包；`--out PATH` 指定输出文件（默认 `./openprogram-memory-<date>.tar.gz`） |

## 维护

| 命令 | 作用 | 关键参数 / 动词 |
|------|------|----------|
| `doctor` | 端到端健康检查 | `--json` 输出 JSON |
| `rescue` | 诊断问题并直接打印修复命令 | — |
| `diagnostics` | 生成脱敏支持包 zip（版本、配置、日志、探测），可直接附在故障报告里，见[诊断包](diagnostics.zh.md) | `--output PATH`（默认 `./openprogram-diagnostics-<日期>.zip`） |
| `logs` | 查看日志 | `list`；`tail [name]`（`-n` 行数、`-f` 跟踪）；`path [name]`。name 为 worker / runtime / ink，默认 worker |
| `update` | 检查并应用更新 | `--check` 只检查；`--force` 绕过 6 小时节流 |
| `scheduler-worker`（兼容别名 `cron-worker`） | 前台循环，触发一次性、周期和监控 Scheduler 任务；daemon 的普通 tick 失败会把 warning 和 traceback 写入 stderr，并在下一分钟边界继续，不重放失败的初始 `@reboot` tick（常驻 worker 重定向后的 stderr 进入其 worker 日志） | `--once` 只评估一个 tick，失败原样传播后退出；`--list` 显示当前任务匹配状态 |