CLI 参考
CLI 参考
Section titled “CLI 参考”本页描述当前的 CLI 行为。如果命令发生变化,请更新此文档。
setuponboardconfigureconfigdoctordashboardresetuninstallupdatemessageagentagentsacpstatushealthsessionsgatewaylogssystemmodelsmemorynodesdevicesnodeapprovalssandboxtuibrowsercrondnsdocshookswebhookspairingplugins(插件命令)channelssecurityskillsvoicecall(插件; 如果已安装)
--dev: 在~/.openclaw-dev下隔离状态并偏移默认端口。--profile <name>: 在~/.openclaw-<name>下隔离状态。--no-color: 禁用 ANSI 颜色。--update:openclaw update的简写 (仅源码安装)。-V,--version,-v: 打印版本并退出。
- ANSI 颜色和进度指示器仅在 TTY 会话中渲染。
- OSC-8 超链接在支持的终端中渲染为可点击链接;否则回退到普通 URL。
--json(以及支持的地方--plain) 禁用样式以获得干净的输出。--no-color禁用 ANSI 样式;NO_COLOR=1也被遵守。- 长时间运行的命令显示进度指示器 (支持时使用 OSC 9;4)。
OpenClaw 使用龙虾调色板用于 CLI 输出。
accent(#FF5A2D): 标题, 标签, 主要高亮。accentBright(#FF7A3D): 命令名称, 强调。accentDim(#D14A22): 次要高亮文本。info(#FF8A5B): 信息值。success(#2FBF71): 成功状态。warn(#FFB020): 警告, 回退, 注意。error(#E23D2D): 错误, 失败。muted(#8B7F77): 去强调, 元数据。
调色板真理来源: src/terminal/palette.ts (又名 “lobster seam”)。
openclaw [--dev] [--profile <name>] <command> setup onboard configure config get set unset doctor security audit reset uninstall update channels list status logs add remove login logout skills list info check plugins list info install enable disable doctor memory status index search message agent agents list add delete acp status health sessions gateway call health status probe discover install uninstall start stop restart run logs system event heartbeat last|enable|disable presence models list status set set-image aliases list|add|remove fallbacks list|add|remove|clear image-fallbacks list|add|remove|clear scan auth add|setup-token|paste-token auth order get|set|clear sandbox list recreate explain cron status list add edit rm enable disable runs run nodes devices node run status install uninstall start stop restart approvals get set allowlist add|remove browser status start stop reset-profile tabs open focus close profiles create-profile delete-profile screenshot snapshot navigate resize click type press hover drag select upload fill dialog wait evaluate console pdf hooks list info check enable disable install update webhooks gmail setup|run pairing list approve docs dns setup tui注意:插件可以添加额外的顶级命令 (例如 openclaw voicecall)。
openclaw security audit— 审计配置 + 本地状态以查找常见的安全隐患。openclaw security audit --deep— 尽力而为的实时 Gateway 探测。openclaw security audit --fix— 收紧安全默认值并 chmod state/config。
管理扩展及其配置:
openclaw plugins list— 发现插件 (使用--json获取机器输出)。openclaw plugins info <id>— 显示插件详情。openclaw plugins install <path|.tgz|npm-spec>— 安装插件 (或添加插件路径到plugins.load.paths)。openclaw plugins enable <id>/disable <id>— 切换plugins.entries.<id>.enabled。openclaw plugins doctor— 报告插件加载错误。
大多数插件更改需要 gateway 重启。参见 /plugin。
对 MEMORY.md + memory/*.md 进行向量搜索:
openclaw memory status— 显示索引统计。openclaw memory index— 重建内存文件索引。openclaw memory search "<query>"— 对内存进行语义搜索。
聊天斜杠命令
Section titled “聊天斜杠命令”聊天消息支持 /... 命令 (文本和原生)。参见 /tools/slash-commands。
亮点:
/status快速诊断。/config持久化配置更改。/debug运行时配置覆盖 (仅内存,不存盘; 需要commands.debug: true)。
安装 + 引导
Section titled “安装 + 引导”初始化配置 + 工作区。
选项:
--workspace <dir>: agent 工作区路径 (默认~/.openclaw/workspace)。--wizard: 运行引导向导。--non-interactive: 运行无提示向导。--mode <local|remote>: 向导模式。--remote-url <url>: 远程 Gateway URL。--remote-token <token>: 远程 Gateway token。
当存在任何向导标志时 (--non-interactive, --mode, --remote-url, --remote-token),向导自动运行。
onboard
Section titled “onboard”交互式向导,用于设置 gateway, workspace, 和 skills。
选项:
--workspace <dir>--reset(在向导前重置 config + credentials + sessions + workspace)--non-interactive--mode <local|remote>--flow <quickstart|advanced|manual>(manual 是 advanced 的别名)--auth-choice <setup-token|token|chutes|openai-codex|openai-api-key|openrouter-api-key|ai-gateway-api-key|moonshot-api-key|kimi-code-api-key|synthetic-api-key|venice-api-key|gemini-api-key|zai-api-key|apiKey|minimax-api|minimax-api-lightning|opencode-zen|skip>--token-provider <id>(非交互式; 与--auth-choice token一起使用)--token <token>(非交互式; 与--auth-choice token一起使用)--token-profile-id <id>(非交互式; 默认:<provider>:manual)--token-expires-in <duration>(非交互式; 例如365d,12h)--anthropic-api-key <key>--openai-api-key <key>--openrouter-api-key <key>--ai-gateway-api-key <key>--moonshot-api-key <key>--kimi-code-api-key <key>--gemini-api-key <key>--zai-api-key <key>--minimax-api-key <key>--opencode-zen-api-key <key>--gateway-port <port>--gateway-bind <loopback|lan|tailnet|auto|custom>--gateway-auth <token|password>--gateway-token <token>--gateway-password <password>--remote-url <url>--remote-token <token>--tailscale <off|serve|funnel>--tailscale-reset-on-exit--install-daemon--no-install-daemon(别名:--skip-daemon)--daemon-runtime <node|bun>--skip-channels--skip-skills--skip-health--skip-ui--node-manager <npm|pnpm|bun>(推荐 pnpm; Gateway 运行时不推荐 bun)--json
configure
Section titled “configure”交互式配置向导 (models, channels, skills, gateway)。
config
Section titled “config”非交互式配置助手 (get/set/unset)。运行不带子命令的 openclaw config 会启动向导。
子命令:
config get <path>: 打印配置值 (点/方括号路径)。config set <path> <value>: 设置值 (JSON5 或原始字符串)。config unset <path>: 移除值。
doctor
Section titled “doctor”健康检查 + 快速修复 (config + gateway + 旧版服务)。
选项:
--no-workspace-suggestions: 禁用工作区内存提示。--yes: 接受默认值而不提示 (headless)。--non-interactive: 跳过提示;仅应用安全迁移。--deep: 扫描系统服务以查找额外的 gateway 安装。
channels
Section titled “channels”管理聊天频道账户 (WhatsApp/Telegram/Discord/Google Chat/Slack/Mattermost (插件)/Signal/iMessage/MS Teams)。
子命令:
channels list: 显示配置的频道和认证 profile。channels status: 检查 gateway 可达性和频道健康状况 (--probe运行额外检查;使用openclaw health或openclaw status --deep进行 gateway 健康探测)。- 提示:
channels status在检测到常见错误配置时会打印带有建议修复的警告 (然后指向openclaw doctor)。 channels logs: 显示来自 gateway 日志文件的最近频道日志。channels add: 未传递标志时为向导式设置;传递标志时切换到非交互模式。channels remove: 默认禁用;传递--delete以在不提示的情况下移除配置条目。channels login: 交互式频道登录 (仅 WhatsApp Web)。channels logout: 登出频道会话 (如果支持)。
通用选项:
--channel <name>:whatsapp|telegram|discord|googlechat|slack|mattermost|signal|imessage|msteams--account <id>: 频道账户 id (默认default)--name <label>: 账户显示名称
channels login 选项:
--channel <channel>(默认whatsapp; 支持whatsapp/web)--account <id>--verbose
channels logout 选项:
--channel <channel>(默认whatsapp)--account <id>
channels list 选项:
--no-usage: 跳过模型提供商用量/配额快照 (仅限 OAuth/API-backed)。--json: 输出 JSON (包含用量,除非设置了--no-usage)。
channels logs 选项:
--channel <name|all>(默认all)--lines <n>(默认200)--json
更多详情: /concepts/oauth
示例:
openclaw channels add --channel telegram --account alerts --name "Alerts Bot" --token $TELEGRAM_BOT_TOKENopenclaw channels add --channel discord --account work --name "Work Bot" --token $DISCORD_BOT_TOKENopenclaw channels remove --channel discord --account work --deleteopenclaw channels status --probeopenclaw status --deepskills
Section titled “skills”列出并检查可用技能以及就绪信息。
子命令:
skills list: 列出技能 (无子命令时默认)。skills info <name>: 显示单个技能的详情。skills check: 就绪 vs 缺失需求的摘要。
选项:
--eligible: 仅显示就绪的技能。--json: 输出 JSON (无样式)。-v,--verbose: 包含缺失需求的详情。
提示: 使用 npx clawhub 搜索、安装和同步技能。
pairing
Section titled “pairing”批准跨频道的 DM 配对请求。
子命令:
pairing list <channel> [--json]pairing approve <channel> <code> [--notify]
webhooks gmail
Section titled “webhooks gmail”Gmail Pub/Sub hook 设置 + 运行器。参见 /automation/gmail-pubsub。
子命令:
webhooks gmail setup(需要--account <email>; 支持--project,--topic,--subscription,--label,--hook-url,--hook-token,--push-token,--bind,--port,--path,--include-body,--max-bytes,--renew-minutes,--tailscale,--tailscale-path,--tailscale-target,--push-endpoint,--json)webhooks gmail run(用于相同标志的运行时覆盖)
dns setup
Section titled “dns setup”广域发现 DNS 助手 (CoreDNS + Tailscale)。参见 /gateway/discovery。
选项:
--apply: 安装/更新 CoreDNS 配置 (需要 sudo; 仅 macOS)。
消息 + Agent
Section titled “消息 + Agent”message
Section titled “message”统一的出站消息 + 频道动作。
参见: /cli/message
子命令:
message send|poll|react|reactions|read|edit|delete|pin|unpin|pins|permissions|search|timeout|kick|banmessage thread <create|list|reply>message emoji <list|upload>message sticker <send|upload>message role <info|add|remove>message channel <info|list>message member infomessage voice statusmessage event <list|create>
示例:
openclaw message send --target +15555550123 --message "Hi"openclaw message poll --channel discord --target channel:123 --poll-question "Snack?" --poll-option Pizza --poll-option Sushi
通过 Gateway 运行一轮 agent (或 --local 嵌入式)。
必填:
--message <text>
选项:
--to <dest>(用于会话键和可选投递)--session-id <id>--thinking <off|minimal|low|medium|high|xhigh>(仅 GPT-5.2 + Codex 模型)--verbose <on|full|off>--channel <whatsapp|telegram|discord|slack|mattermost|signal|imessage|msteams>--local--deliver--json--timeout <seconds>
agents
Section titled “agents”管理隔离的 agent (工作区 + 认证 + 路由)。
agents list
Section titled “agents list”列出配置的 agent。
选项:
--json--bindings
agents add [name]
Section titled “agents add [name]”添加一个新的隔离 agent。除非传递标志 (或 --non-interactive),否则运行引导向导;非交互模式下 --workspace 是必填的。
选项:
--workspace <dir>--model <id>--agent-dir <dir>--bind <channel[:accountId]>(可重复)--non-interactive--json
绑定规范使用 channel[:accountId]。当 WhatsApp 省略 accountId 时,使用默认账户 id。
agents delete <id>
Section titled “agents delete <id>”删除 agent 并修剪其工作区 + 状态。
选项:
--force--json
运行连接 IDE 到 Gateway 的 ACP 桥接。
参见 acp 获取完整选项和示例。
status
Section titled “status”显示链接的会话健康状况和最近的接收者。
选项:
--json--all(完整诊断; 只读, 可粘贴)--deep(探测频道)--usage(显示模型提供商用量/配额)--timeout <ms>--verbose--debug(--verbose的别名)
注意:
- 概览包含 Gateway + 节点主机服务状态 (如果可用)。
OpenClaw 可以在 OAuth/API 凭据可用时展示提供商用量/配额。
展示位置:
/status(可用时添加一行简短的提供商用量)openclaw status --usage(打印完整的提供商明细)- macOS 菜单栏 (Context 下的 Usage 部分)
注意:
- 数据直接来自提供商用量端点 (无估算)。
- 提供商:Anthropic, GitHub Copilot, OpenAI Codex OAuth, 加上 Gemini CLI/Antigravity (当这些插件启用时)。
- 如果不存在匹配的凭据,用量将被隐藏。
- 详情:参见 用量跟踪。
health
Section titled “health”从运行中的 Gateway 获取健康状况。
选项:
--json--timeout <ms>--verbose
sessions
Section titled “sessions”列出存储的对话会话。
选项:
--json--verbose--store <path>--active <minutes>
重置 / 卸载
Section titled “重置 / 卸载”重置本地配置/状态 (保留 CLI 安装)。
选项:
--scope <config|config+creds+sessions|full>--yes--non-interactive--dry-run
注意:
--non-interactive需要--scope和--yes。
uninstall
Section titled “uninstall”卸载 gateway 服务 + 本地数据 (CLI 保留)。
选项:
--service--state--workspace--app--all--yes--non-interactive--dry-run
注意:
--non-interactive需要--yes和明确的范围 (或--all)。
Gateway
Section titled “Gateway”gateway
Section titled “gateway”运行 WebSocket Gateway。
选项:
--port <port>--bind <loopback|tailnet|lan|auto|custom>--token <token>--auth <token|password>--password <password>--tailscale <off|serve|funnel>--tailscale-reset-on-exit--allow-unconfigured--dev--reset(重置 dev 配置 + 凭据 + 会话 + 工作区)--force(杀死端口上现有的监听者)--verbose--claude-cli-logs--ws-log <auto|full|compact>--compact(--ws-log compact的别名)--raw-stream--raw-stream-path <path>
gateway service
Section titled “gateway service”管理 Gateway 服务 (launchd/systemd/schtasks)。
子命令:
gateway status(默认探测 Gateway RPC)gateway install(服务安装)gateway uninstallgateway startgateway stopgateway restart
注意:
gateway status默认使用服务的解析端口/配置探测 Gateway RPC (可用--url/--token/--password覆盖)。gateway status支持--no-probe,--deep, 和--json用于脚本。gateway status还能检测旧版或额外的 gateway 服务 (--deep增加系统级扫描)。以 Profile 命名的 OpenClaw 服务被视为一等公民,不会被标记为“额外”。gateway status打印 CLI 使用的配置路径 vs 服务可能使用的配置 (服务 env),加上解析的探测目标 URL。gateway install|uninstall|start|stop|restart支持--json用于脚本 (默认输出保持人类友好)。gateway install默认为 Node 运行时;bun 不推荐 (WhatsApp/Telegram bug)。gateway install选项:--port,--runtime,--token,--force,--json。
通过 RPC 跟踪 Gateway 文件日志。
注意:
- TTY 会话渲染彩色、结构化视图;非 TTY 回退到纯文本。
--json发射行分隔的 JSON (每行一个日志事件)。
示例:
openclaw logs --followopenclaw logs --limit 200openclaw logs --plainopenclaw logs --jsonopenclaw logs --no-colorgateway <subcommand>
Section titled “gateway <subcommand>”Gateway CLI 助手 (使用 --url, --token, --password, --timeout, --expect-final 用于 RPC 子命令)。
子命令:
gateway call <method> [--params <json>]gateway healthgateway statusgateway probegateway discovergateway install|uninstall|start|stop|restartgateway run
常见 RPC:
config.apply(验证 + 写入配置 + 重启 + 唤醒)config.patch(合并部分更新 + 重启 + 唤醒)update.run(运行更新 + 重启 + 唤醒)
提示:当直接调用 config.set/config.apply/config.patch 时,如果配置已存在,传递来自 config.get 的 baseHash。
参见 /concepts/models 了解回退行为和扫描策略。
首选 Anthropic 认证 (setup-token):
claude setup-tokenopenclaw models auth setup-token --provider anthropicopenclaw models statusmodels (root)
Section titled “models (root)”openclaw models 是 models status 的别名。
根选项:
--status-json(models status --json的别名)--status-plain(models status --plain的别名)
models list
Section titled “models list”选项:
--all--local--provider <name>--json--plain
models status
Section titled “models status”选项:
--json--plain--check(退出码 1=过期/缺失, 2=即将过期)--probe(实时探测配置的认证 profile)--probe-provider <name>--probe-profile <id>(重复或逗号分隔)--probe-timeout <ms>--probe-concurrency <n>--probe-max-tokens <n>
总是包含认证存储中 profile 的认证概览和 OAuth 过期状态。 --probe 运行实时请求 (可能会消耗 token 并触发速率限制)。
models set <model>
Section titled “models set <model>”设置 agents.defaults.model.primary。
models set-image <model>
Section titled “models set-image <model>”设置 agents.defaults.imageModel.primary。
models aliases list|add|remove
Section titled “models aliases list|add|remove”选项:
list:--json,--plainadd <alias> <model>remove <alias>
models fallbacks list|add|remove|clear
Section titled “models fallbacks list|add|remove|clear”选项:
list:--json,--plainadd <model>remove <model>clear
models image-fallbacks list|add|remove|clear
Section titled “models image-fallbacks list|add|remove|clear”选项:
list:--json,--plainadd <model>remove <model>clear
models scan
Section titled “models scan”选项:
--min-params <b>--max-age-days <days>--provider <name>--max-candidates <n>--timeout <ms>--concurrency <n>--no-probe--yes--no-input--set-default--set-image--json
models auth add|setup-token|paste-token
Section titled “models auth add|setup-token|paste-token”选项:
add: 交互式认证助手setup-token:--provider <name>(默认anthropic),--yespaste-token:--provider <name>,--profile-id <id>,--expires-in <duration>
models auth order get|set|clear
Section titled “models auth order get|set|clear”选项:
get:--provider <name>,--agent <id>,--jsonset:--provider <name>,--agent <id>,<profileIds...>clear:--provider <name>,--agent <id>
system event
Section titled “system event”入队系统事件并可选地触发心跳 (Gateway RPC)。
必填:
--text <text>
选项:
--mode <now|next-heartbeat>--json--url,--token,--timeout,--expect-final
system heartbeat last|enable|disable
Section titled “system heartbeat last|enable|disable”心跳控制 (Gateway RPC)。
选项:
--json--url,--token,--timeout,--expect-final
system presence
Section titled “system presence”列出系统存在条目 (Gateway RPC)。
选项:
--json--url,--token,--timeout,--expect-final
管理计划任务 (Gateway RPC)。参见 /automation/cron-jobs。
子命令:
cron status [--json]cron list [--all] [--json](默认表格输出; 使用--json获取原始数据)cron add(别名:create; 需要--name和恰好一个--at|--every|--cron, 以及恰好一个负载--system-event|--message)cron edit <id>(修补字段)cron rm <id>(别名:remove,delete)cron enable <id>cron disable <id>cron runs --id <id> [--limit <n>]cron run <id> [--force]
所有 cron 命令接受 --url, --token, --timeout, --expect-final。
node 运行一个 无头节点主机 或作为后台服务管理它。参见 openclaw node。
子命令:
node run --host <gateway-host> --port 18789node statusnode install [--host <gateway-host>] [--port <port>] [--tls] [--tls-fingerprint <sha256>] [--node-id <id>] [--display-name <name>] [--runtime <node|bun>] [--force]node uninstallnode stopnode restart
nodes 与 Gateway 对话并目标配对的节点。参见 /nodes。
通用选项:
--url,--token,--timeout,--json
子命令:
nodes status [--connected] [--last-connected <duration>]nodes describe --node <id|name|ip>nodes list [--connected] [--last-connected <duration>]nodes pendingnodes approve <requestId>nodes reject <requestId>nodes rename --node <id|name|ip> --name <displayName>nodes invoke --node <id|name|ip> --command <command> [--params <json>] [--invoke-timeout <ms>] [--idempotency-key <key>]nodes run --node <id|name|ip> [--cwd <path>] [--env KEY=VAL] [--command-timeout <ms>] [--needs-screen-recording] [--invoke-timeout <ms>] <command...>(mac 节点或无头节点主机)nodes notify --node <id|name|ip> [--title <text>] [--body <text>] [--sound <name>] [--priority <passive|active|timeSensitive>] [--delivery <system|overlay|auto>] [--invoke-timeout <ms>](仅 mac)
摄像头:
nodes camera list --node <id|name|ip>nodes camera snap --node <id|name|ip> [--facing front|back|both] [--device-id <id>] [--max-width <px>] [--quality <0-1>] [--delay-ms <ms>] [--invoke-timeout <ms>]nodes camera clip --node <id|name|ip> [--facing front|back] [--device-id <id>] [--duration <ms|10s|1m>] [--no-audio] [--invoke-timeout <ms>]
Canvas + 屏幕:
nodes canvas snapshot --node <id|name|ip> [--format png|jpg|jpeg] [--max-width <px>] [--quality <0-1>] [--invoke-timeout <ms>]nodes canvas present --node <id|name|ip> [--target <urlOrPath>] [--x <px>] [--y <px>] [--width <px>] [--height <px>] [--invoke-timeout <ms>]nodes canvas hide --node <id|name|ip> [--invoke-timeout <ms>]nodes canvas navigate <url> --node <id|name|ip> [--invoke-timeout <ms>]nodes canvas eval [<js>] --node <id|name|ip> [--js <code>] [--invoke-timeout <ms>]nodes canvas a2ui push --node <id|name|ip> (--jsonl <path> | --text <text>) [--invoke-timeout <ms>]nodes canvas a2ui reset --node <id|name|ip> [--invoke-timeout <ms>]nodes screen record --node <id|name|ip> [--screen <index>] [--duration <ms|10s>] [--fps <n>] [--no-audio] [--out <path>] [--invoke-timeout <ms>]
位置:
nodes location get --node <id|name|ip> [--max-age <ms>] [--accuracy <coarse|balanced|precise>] [--location-timeout <ms>] [--invoke-timeout <ms>]
Browser
Section titled “Browser”浏览器控制 CLI (专用 Chrome/Brave/Edge/Chromium)。参见 openclaw browser 和 浏览器工具。
通用选项:
--url,--token,--timeout,--json--browser-profile <name>
管理:
browser statusbrowser startbrowser stopbrowser reset-profilebrowser tabsbrowser open <url>browser focus <targetId>browser close [targetId]browser profilesbrowser create-profile --name <name> [--color <hex>] [--cdp-url <url>]browser delete-profile --name <name>
检查:
browser screenshot [targetId] [--full-page] [--ref <ref>] [--element <selector>] [--type png|jpeg]browser snapshot [--format aria|ai] [--target-id <id>] [--limit <n>] [--interactive] [--compact] [--depth <n>] [--selector <sel>] [--out <path>]
动作:
browser navigate <url> [--target-id <id>]browser resize <width> <height> [--target-id <id>]browser click <ref> [--double] [--button <left|right|middle>] [--modifiers <csv>] [--target-id <id>]browser type <ref> <text> [--submit] [--slowly] [--target-id <id>]browser press <key> [--target-id <id>]browser hover <ref> [--target-id <id>]browser drag <startRef> <endRef> [--target-id <id>]browser select <ref> <values...> [--target-id <id>]browser upload <paths...> [--ref <ref>] [--input-ref <ref>] [--element <selector>] [--target-id <id>] [--timeout-ms <ms>]browser fill [--fields <json>] [--fields-file <path>] [--target-id <id>]browser dialog --accept|--dismiss [--prompt <text>] [--target-id <id>] [--timeout-ms <ms>]browser wait [--time <ms>] [--text <value>] [--text-gone <value>] [--target-id <id>]browser evaluate --fn <code> [--ref <ref>] [--target-id <id>]browser console [--level <error|warn|info>] [--target-id <id>]browser pdf [--target-id <id>]
docs [query...]
Section titled “docs [query...]”搜索实时文档索引。
打开连接到 Gateway 的终端 UI。
选项:
--url <url>--token <token>--password <password>--session <key>--deliver--thinking <level>--message <text>--timeout-ms <ms>(默认为agents.defaults.timeoutSeconds)--history-limit <n>