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(又名”龙虾接缝”)。
命令树
openclaw voicecall)。
安全
openclaw security audit— 审计配置 + 本地状态的常见安全漏洞。openclaw security audit --deep— 尽力实时网关探测。openclaw security audit --fix— 加强安全默认值并 chmod 状态/配置。
插件
管理扩展及其配置: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— 报告插件加载错误。
内存
向量搜索MEMORY.md + memory/*.md:
openclaw memory status— 显示索引统计信息。openclaw memory index— 重新索引内存文件。openclaw memory search "<query>"— 对内存进行语义搜索。
聊天斜杠命令
聊天消息支持/... 命令(文本和原生)。参见 /tools/slash-commands。
亮点:
/status用于快速诊断。/config用于持久化配置更改。/debug用于仅运行时的配置覆盖(内存,而非磁盘;需要commands.debug: true)。
设置 + 入职
setup
初始化配置 + 工作区。
选项:
--workspace <dir>:代理工作区路径(默认~/.openclaw/workspace)。--wizard:运行入职向导。--non-interactive:运行向导而不提示。--mode <local|remote>:向导模式。--remote-url <url>:远程网关 URL。--remote-token <token>:远程网关令牌。
--non-interactive、--mode、--remote-url、--remote-token)。
onboard
交互式向导以设置网关、工作区和技能。
选项:
--workspace <dir>--reset(在向导之前重置配置 + 凭据 + 会话 + 工作区)--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;不推荐 bun 用于网关运行时)--json
configure
交互式配置向导(模型、频道、技能、网关)。
config
非交互式配置助手(获取/设置/取消设置)。运行不带子命令的 openclaw config
会启动向导。
子命令:
config get <path>:打印配置值(点/括号路径)。config set <path> <value>:设置值(JSON5 或原始字符串)。config unset <path>:删除值。
doctor
健康检查 + 快速修复(配置 + 网关 + 遗留服务)。
选项:
--no-workspace-suggestions:禁用工作区内存提示。--yes:接受默认值而不提示(无头)。--non-interactive:跳过提示;仅应用安全迁移。--deep:扫描系统服务以查找额外的网关安装。
频道助手
channels
管理聊天频道账户(WhatsApp/Telegram/Discord/Google Chat/Slack/Mattermost(插件)/Signal/iMessage/MS Teams)。
子命令:
channels list:显示配置的频道和身份验证配置文件。channels status:检查网关可达性和频道健康状况(--probe运行额外检查;使用openclaw health或openclaw status --deep进行网关健康探测)。- 提示:
channels status在可以检测到常见错误配置时打印带有建议修复的警告(然后指向您到openclaw doctor)。 channels logs:从网关日志文件显示最近的频道日志。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 支持)。--json:输出 JSON(除非设置了--no-usage,否则包括使用情况)。
channels logs 选项:
--channel <name|all>(默认all)--lines <n>(默认200)--json
skills
列出并检查可用技能以及准备就绪信息。
子命令:
skills list:列出技能(无子命令时默认)。skills info <name>:显示一个技能的详细信息。skills check:准备就绪与缺少要求的摘要。
--eligible:仅显示准备就绪的技能。--json:输出 JSON(无样式)。-v、--verbose:包括缺少的要求详细信息。
npx clawdhub 搜索、安装和同步技能。
pairing
批准跨频道的 DM 配对请求。
子命令:
pairing list <channel> [--json]pairing approve <channel> <code> [--notify]
webhooks gmail
Gmail Pub/Sub 钩子设置 + 运行器。参见 /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
广域发现 DNS 助手(CoreDNS + Tailscale)。参见 /gateway/discovery。
选项:
--apply:安装/更新 CoreDNS 配置(需要 sudo;仅限 macOS)。
消息 + 代理
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
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
管理隔离的代理(工作区 + 身份验证 + 路由)。
agents list
列出配置的代理。
选项:
--json--bindings
agents add [name]
添加新的隔离代理。除非传递标志(或 --non-interactive),否则运行指导向导;在非交互模式下需要 --workspace。
选项:
--workspace <dir>--model <id>--agent-dir <dir>--bind <channel[:accountId]>(可重复)--non-interactive--json
channel[:accountId]。当 WhatsApp 省略 accountId 时,使用默认账户 ID。
agents delete <id>
删除代理并修剪其工作区 + 状态。
选项:
--force--json
acp
运行将 IDE 连接到网关的 ACP 桥接。
有关完整选项和示例,请参见 acp。
status
显示链接的会话健康状况和最近的收件人。
选项:
--json--all(完整诊断;只读,可粘贴)--deep(探测频道)--usage(显示模型提供商使用/配额)--timeout <ms>--verbose--debug(--verbose的别名)
- 概述包括网关 + 节点主机服务状态(如果可用)。
使用跟踪
OpenClaw 可以在 OAuth/API 凭据可用时显示提供商使用/配额。 界面:/status(在可用时添加简短的提供商使用行)openclaw status --usage(打印完整的提供商细分)- macOS 菜单栏(上下文下的使用部分)
- 数据直接来自提供商使用端点(无估计)。
- 提供商:Anthropic、GitHub Copilot、OpenAI Codex OAuth,以及启用这些提供商插件时的 Gemini CLI/Antigravity。
- 如果不存在匹配的凭据,则隐藏使用情况。
- 详细信息:参见 使用跟踪。
health
从正在运行的网关获取健康状况。
选项:
--json--timeout <ms>--verbose
sessions
列出存储的对话会话。
选项:
--json--verbose--store <path>--active <minutes>
重置/卸载
reset
重置本地配置/状态(保留已安装的 CLI)。
选项:
--scope <config|config+creds+sessions|full>--yes--non-interactive--dry-run
--non-interactive需要--scope和--yes。
uninstall
卸载网关服务 + 本地数据(CLI 保留)。
选项:
--service--state--workspace--app--all--yes--non-interactive--dry-run
--non-interactive需要--yes和明确的范围(或--all)。
网关
gateway
运行 WebSocket 网关。
选项:
--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(重置开发配置 + 凭据 + 会话 + 工作区)--force(杀死端口上的现有监听器)--verbose--claude-cli-logs--ws-log <auto|full|compact>--compact(--ws-log compact的别名)--raw-stream--raw-stream-path <path>
gateway service
管理网关服务(launchd/systemd/schtasks)。
子命令:
gateway status(默认探测网关 RPC)gateway install(服务安装)gateway uninstallgateway startgateway stopgateway restart
gateway status默认使用服务的解析端口/配置探测网关 RPC(使用--url/--token/--password覆盖)。gateway status支持--no-probe、--deep和--json用于脚本编写。gateway status在可以检测到遗留或额外的网关服务时也会显示它们(--deep添加系统级扫描)。配置文件命名的 OpenClaw 服务被视为一流的,不会被标记为”额外”。gateway status打印 CLI 使用的配置路径与服务可能使用的配置(服务环境),以及解析的探测目标 URL。gateway install|uninstall|start|stop|restart支持--json用于脚本编写(默认输出保持人性化)。gateway install默认为 Node 运行时;不推荐 bun(WhatsApp/Telegram 错误)。gateway install选项:--port、--runtime、--token、--force、--json。
logs
通过 RPC 尾随网关文件日志。
注意:
- TTY 会话渲染彩色结构化视图;非 TTY 回退到纯文本。
--json发出行分隔的 JSON(每行一个日志事件)。
gateway <subcommand>
网关 CLI 助手(对 RPC 子命令使用 --url、--token、--password、--timeout、--expect-final)。
子命令:
gateway call <method> [--params <json>]gateway healthgateway statusgateway probegateway discovergateway install|uninstall|start|stop|restartgateway run
config.apply(验证 + 写入配置 + 重启 + 唤醒)config.patch(合并部分更新 + 重启 + 唤醒)update.run(运行更新 + 重启 + 唤醒)
config.set/config.apply/config.patch 时,如果配置已存在,
则从 config.get 传递 baseHash。
模型
有关回退行为和扫描策略,请参见 /concepts/models。 首选 Anthropic 身份验证(setup-token):models(根)
openclaw models 是 models status 的别名。
根选项:
--status-json(models status --json的别名)--status-plain(models status --plain的别名)
models list
选项:
--all--local--provider <name>--json--plain
models status
选项:
--json--plain--check(退出 1=过期/缺失,2=即将过期)--probe(对配置的身份验证配置文件进行实时探测)--probe-provider <name>--probe-profile <id>(重复或逗号分隔)--probe-timeout <ms>--probe-concurrency <n>--probe-max-tokens <n>
--probe 运行实时请求(可能消耗令牌并触发速率限制)。
models set <model>
设置 agents.defaults.model.primary。
models set-image <model>
设置 agents.defaults.imageModel.primary。
models aliases list|add|remove
选项:
list:--json、--plainadd <alias> <model>remove <alias>
models fallbacks list|add|remove|clear
选项:
list:--json、--plainadd <model>remove <model>clear
models image-fallbacks list|add|remove|clear
选项:
list:--json、--plainadd <model>remove <model>clear
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
选项:
add:交互式身份验证助手setup-token:--provider <name>(默认anthropic)、--yespaste-token:--provider <name>、--profile-id <id>、--expires-in <duration>
models auth order get|set|clear
选项:
get:--provider <name>、--agent <id>、--jsonset:--provider <name>、--agent <id>、<profileIds...>clear:--provider <name>、--agent <id>
系统
system event
将系统事件排队并可选择触发心跳(网关 RPC)。
必需:
--text <text>
--mode <now|next-heartbeat>--json--url、--token、--timeout、--expect-final
system heartbeat last|enable|disable
心跳控制(网关 RPC)。
选项:
--json--url、--token、--timeout、--expect-final
system presence
列出系统存在条目(网关 RPC)。
选项:
--json--url、--token、--timeout、--expect-final
Cron
管理计划作业(网关 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 与网关通信并定位配对的节点。参见 /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>]
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>]
浏览器
浏览器控制 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...]
搜索实时文档索引。
TUI
tui
打开连接到网关的终端 UI。
选项:
--url <url>--token <token>--password <password>--session <key>--deliver--thinking <level>--message <text>--timeout-ms <ms>(默认为agents.defaults.timeoutSeconds)--history-limit <n>