跳转到主要内容

CLI 参考

本页描述当前的 CLI 行为。如果命令发生变化,请更新此文档。

命令页面

全局标志

  • --dev:将状态隔离到 ~/.openclaw-dev 下并调整默认端口。
  • --profile <name>:将状态隔离到 ~/.openclaw-<name> 下。
  • --no-color:禁用 ANSI 颜色。
  • --updateopenclaw 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 voicecall)。

安全

  • openclaw security audit — 审计配置 + 本地状态中常见的安全隐患。
  • openclaw security audit --deep — 尽力进行实时 Gateway 网关探测。
  • 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 — 报告插件加载错误。
大多数插件更改需要重启 Gateway 网关。参见 /plugin

记忆

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>:远程 Gateway 网关 URL。
  • --remote-token <token>:远程 Gateway 网关令牌。
当存在任何向导标志(--non-interactive--mode--remote-url--remote-token)时,向导自动运行。

onboard

交互式向导,用于设置 Gateway 网关、工作区和 Skills。 选项:
  • --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>(非交互式;例如 365d12h
  • --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 用于 Gateway 网关运行时)
  • --json

configure

交互式配置向导(模型、渠道、Skills、Gateway 网关)。

config

非交互式配置辅助工具(get/set/unset)。不带子命令运行 openclaw config 会启动向导。 子命令:
  • config get <path>:打印配置值(点/括号路径)。
  • config set <path> <value>:设置值(JSON5 或原始字符串)。
  • config unset <path>:删除值。

doctor

健康检查 + 快速修复(配置 + Gateway 网关 + 旧版服务)。 选项:
  • --no-workspace-suggestions:禁用工作区记忆提示。
  • --yes:无提示接受默认值(无头模式)。
  • --non-interactive:跳过提示;仅应用安全迁移。
  • --deep:扫描系统服务以查找额外的 Gateway 网关安装。

渠道辅助工具

channels

管理聊天渠道账户(WhatsApp/Telegram/Discord/Google Chat/Slack/Mattermost(插件)/Signal/iMessage/MS Teams)。 子命令:
  • channels list:显示已配置的渠道和认证配置文件。
  • channels status:检查 Gateway 网关可达性和渠道健康状况(--probe 运行额外检查;使用 openclaw healthopenclaw 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 支持的)。
  • --json:输出 JSON(除非设置 --no-usage,否则包含用量)。
channels logs 选项:
  • --channel <name|all>(默认 all
  • --lines <n>(默认 200
  • --json
更多详情:/concepts/oauth 示例:

skills

列出和检查可用的 Skills 及就绪信息。 子命令:
  • skills list:列出 Skills(无子命令时的默认行为)。
  • skills info <name>:显示单个 Skill 的详情。
  • skills check:就绪与缺失需求的摘要。
选项:
  • --eligible:仅显示就绪的 Skills。
  • --json:输出 JSON(无样式)。
  • -v--verbose:包含缺失需求详情。
提示:使用 npx clawhub 搜索、安装和同步 Skills。

pairing

批准跨渠道的私信配对请求。 子命令:
  • 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|ban
  • message thread <create|list|reply>
  • message emoji <list|upload>
  • message sticker <send|upload>
  • message role <info|add|remove>
  • message channel <info|list>
  • message member info
  • message voice status
  • message 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

通过 Gateway 网关运行一个智能体回合(或使用 --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 到 Gateway 网关的 ACP 桥接。 完整选项和示例参见 acp

status

显示关联会话健康状况和最近的收件人。 选项:
  • --json
  • --all(完整诊断;只读,可粘贴)
  • --deep(探测渠道)
  • --usage(显示模型提供商用量/配额)
  • --timeout <ms>
  • --verbose
  • --debug--verbose 的别名)
说明:
  • 概览包含 Gateway 网关 + 节点主机服务状态(如可用)。

用量跟踪

当 OAuth/API 凭证可用时,OpenClaw 可以显示提供商用量/配额。 显示位置:
  • /status(可用时添加简短的提供商用量行)
  • openclaw status --usage(打印完整的提供商明细)
  • macOS 菜单栏(上下文下的用量部分)
说明:
  • 数据直接来自提供商用量端点(非估算)。
  • 提供商:Anthropic、GitHub Copilot、OpenAI Codex OAuth,以及启用这些提供商插件时的 Gemini CLI/Antigravity。
  • 如果没有匹配的凭证,用量会被隐藏。
  • 详情:参见用量跟踪

health

从运行中的 Gateway 网关获取健康状态。 选项:
  • --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

卸载 Gateway 网关服务 + 本地数据(CLI 保留)。 选项:
  • --service
  • --state
  • --workspace
  • --app
  • --all
  • --yes
  • --non-interactive
  • --dry-run
说明:
  • --non-interactive 需要 --yes 和明确的范围(或 --all)。

Gateway 网关

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

管理 Gateway 网关服务(launchd/systemd/schtasks)。 子命令:
  • gateway status(默认探测 Gateway 网关 RPC)
  • gateway install(服务安装)
  • gateway uninstall
  • gateway start
  • gateway stop
  • gateway restart
说明:
  • gateway status 默认使用服务解析的端口/配置探测 Gateway 网关 RPC(使用 --url/--token/--password 覆盖)。
  • gateway status 支持 --no-probe--deep--json 用于脚本化。
  • gateway status 在检测到旧版或额外的 Gateway 网关服务时也会显示(--deep 添加系统级扫描)。配置文件命名的 OpenClaw 服务被视为一等公民,不会被标记为”额外”。
  • gateway status 打印 CLI 使用的配置路径与服务可能使用的配置(服务环境),以及解析的探测目标 URL。
  • gateway install|uninstall|start|stop|restart 支持 --json 用于脚本化(默认输出保持人类友好)。
  • gateway install 默认使用 Node 运行时;不建议使用 bun(WhatsApp/Telegram bug)。
  • gateway install 选项:--port--runtime--token--force--json

logs

通过 RPC 跟踪 Gateway 网关文件日志。 说明:
  • TTY 会话渲染彩色、结构化视图;非 TTY 回退到纯文本。
  • --json 输出行分隔的 JSON(每行一个日志事件)。
示例:

gateway <subcommand>

Gateway 网关 CLI 辅助工具(RPC 子命令使用 --url--token--password--timeout--expect-final)。 子命令:
  • gateway call <method> [--params <json>]
  • gateway health
  • gateway status
  • gateway probe
  • gateway discover
  • gateway install|uninstall|start|stop|restart
  • gateway run
常见 RPC:
  • config.apply(验证 + 写入配置 + 重启 + 唤醒)
  • config.patch(合并部分更新 + 重启 + 唤醒)
  • update.run(运行更新 + 重启 + 唤醒)
提示:直接调用 config.set/config.apply/config.patch 时,如果配置已存在,请传入来自 config.getbaseHash

模型

回退行为和扫描策略参见 /concepts/models 首选 Anthropic 认证(setup-token):

models(根命令)

openclaw modelsmodels status 的别名。 根选项:
  • --status-jsonmodels status --json 的别名)
  • --status-plainmodels 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>
始终包含认证概览和认证存储中配置文件的 OAuth 过期状态。--probe 运行实时请求(可能消耗令牌并触发速率限制)。

models set <model>

设置 agents.defaults.model.primary

models set-image <model>

设置 agents.defaults.imageModel.primary

models aliases list|add|remove

选项:
  • list--json--plain
  • add <alias> <model>
  • remove <alias>

models fallbacks list|add|remove|clear

选项:
  • list--json--plain
  • add <model>
  • remove <model>
  • clear

models image-fallbacks list|add|remove|clear

选项:
  • list--json--plain
  • add <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)、--yes
  • paste-token--provider <name>--profile-id <id>--expires-in <duration>

models auth order get|set|clear

选项:
  • get--provider <name>--agent <id>--json
  • set--provider <name>--agent <id><profileIds...>
  • clear--provider <name>--agent <id>

系统

system event

将系统事件加入队列并可选触发心跳(Gateway 网关 RPC)。 必需:
  • --text <text>
选项:
  • --mode <now|next-heartbeat>
  • --json
  • --url--token--timeout--expect-final

system heartbeat last|enable|disable

心跳控制(Gateway 网关 RPC)。 选项:
  • --json
  • --url--token--timeout--expect-final

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>(别名:removedelete
  • 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 18789
  • node status
  • node install [--host <gateway-host>] [--port <port>] [--tls] [--tls-fingerprint <sha256>] [--node-id <id>] [--display-name <name>] [--runtime <node|bun>] [--force]
  • node uninstall
  • node stop
  • node 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 pending
  • nodes 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 status
  • browser start
  • browser stop
  • browser reset-profile
  • browser tabs
  • browser open <url>
  • browser focus <targetId>
  • browser close [targetId]
  • browser profiles
  • browser 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

打开连接到 Gateway 网关的终端 UI。 选项:
  • --url <url>
  • --token <token>
  • --password <password>
  • --session <key>
  • --deliver
  • --thinking <level>
  • --message <text>
  • --timeout-ms <ms>(默认为 agents.defaults.timeoutSeconds
  • --history-limit <n>