OpenClaw 2026.10.6 常用 CLI 命令与工具详解

目标：系统梳理 OpenClaw（v2026.10.6）CLI（openclaw 命令）的命令全景、全局参数与日常运维高频命令的用法，每条命令均给出实测回显。已在 Ubuntu 24.04 + Node 24.22.1 + OpenClaw 2026.10.6（fe06181）环境实测；涉及真实模型调用与渠道收发的命令（message send、agent 等）需要模型凭据与渠道凭据，本环境未接入，按官方用法如实说明。

一、环境信息

操作系统：Ubuntu 24.04.5 LTS（x86_64）
OpenClaw：2026.10.6（fe06181），全局安装路径 /usr/bin/openclaw（npm 全局包）
Node.js：24.22.1；npm：11.19.1
Gateway：以 systemd 用户服务 openclaw-gateway.service 常驻运行，ws://127.0.0.1:18789
状态目录：~/.openclaw/
实测时间：2026-10-23

二、工具概览

OpenClaw 的所有能力都从单一入口 openclaw 出发，命令按域分组。实测 openclaw --help 的完整命令域如下（带 * 表示有子命令）：

域	命令	职责
安装与设置	`setup`、`onboard `、`configure`、`config `、`completion`、`dashboard`	引导安装、基线创建、交互配置、非交互配置读写
状态与诊断	`status`、`health`、`doctor`、`triage`、`logs`、`system *`	全景状态、健康检查、体检修复、诊断收集、日志
Gateway 管理	`gateway `、`daemon `（旧别名）、`sandbox *`、`tui`、`attach`	启停/服务托管/探测/调用、终端界面
渠道与消息	`channels `、`message `、`pairing `、`qr`、`devices `、`directory `、`users `	渠道接入、消息收发、DM 配对、设备配对
Agent 与模型	`agent `、`agents `、`models `、`infer `（别名 `capability`）、`memory `、`wiki `	Agent 运行/隔离管理、模型发现与鉴权、推理、记忆
会话与记录	`sessions `、`resume`、`transcripts `、`audit`	会话清单、TUI 恢复、转录、审计
自动化	`cron `（别名 `automations`）、`hooks `、`webhooks *`	定时任务、内部钩子、Webhook
扩展	`plugins `、`skills `、`mcp `、`secrets `、`promos `、`worktrees `、`worker`、`proxy *`	插件、技能、MCP、密钥、优惠、工作树、云 worker、调试代理
维护	`update `、`backup `、`database `、`migrate `、`reset`、`uninstall`、`storage `、`telemetry `	升级、备份、数据库迁移、重置、卸载
安全	`security `、`approvals `（别名 `exec-approvals`）、`exec-policy *`	安全审计、执行审批、执行策略
网络	`connect`、`nodes `、`node `、`dns `、`webhooks `	节点接入、网关发现、DNS

💡 说明：插件还可追加顶层命令（如安装 voicecall 插件后出现 openclaw voicecall）。任何命令的权威子命令清单以 <命令> --help 为准——OpenClaw 迭代快，帮助输出永远比文章新。

三、前置条件

已安装 OpenClaw 并能执行 openclaw --version（安装见《OpenClaw Ubuntu 24.04 安装指南》）：

openclaw --version

实测输出：

OpenClaw 2026.10.6 (fe06181)

诊断类命令（status/health/gateway status/logs）需要 Gateway 已启动（前台或服务方式）；配置类命令（config get/set、doctor）不需要 Gateway 运行。

四、各工具详解

4.1 全局参数

openclaw --help 实测的全局参数：

参数	作用
`-V, --version`	打印版本号并退出
`-h, --help`	显示帮助；`<命令> --help` 看子命令
`--profile <name>`	使用命名 profile，状态/配置隔离到 `~/.openclaw-<name>`
`--dev`	开发模式：状态隔离到 `~/.openclaw-dev`，Gateway 端口改 19001，派生端口顺移
`--container <name>`	让 CLI 在指定 Podman/Docker 容器内执行（默认读环境变量 `OPENCLAW_CONTAINER`）
`--log-level <level>`	全局日志级别（`silent\|fatal\|error\|warn\|info\|debug\|trace`）
`--no-color`	关闭 ANSI 彩色（环境变量 `NO_COLOR=1` 同效）

实测版本与无色输出组合：

openclaw --no-color --version

OpenClaw 2026.10.6 (fe06181)

💡 说明：全局参数放在子命令之前（如 openclaw --profile work status），命令专属参数放在子命令之后（如 openclaw status --json）。未知根参数会直接报参数错误并给出帮助提示，不会误入 onboarding。

4.2 安装引导与配置命令

openclaw onboard：交互式引导（模型鉴权 → 工作区 → Gateway → 渠道 → 技能），--install-daemon 在引导末尾安装守护服务；--non-interactive 配合参数可脚本化（Docker 无终端引导即用此模式，见官方 Docker 文档）。

openclaw setup：与 Agent 对话式完成初始化；setup --baseline 只创建基线配置、工作区与会话目录，不走向导。

openclaw configure：对既有安装做定点修改（模型鉴权、Gateway、渠道、插件、技能分节引导）。

openclaw config：非交互配置读写，实测子命令：

openclaw config --help

实测输出（节选）：

Non-interactive config helpers (get/set/patch/unset/file/schema/validate). Run
without subcommand for guided setup.

Commands:
  file                 Print the active config file path
  get                  Get a config value by dot path
  patch                Patch config from a JSON5 object in one validated write.
                       Objects merge recursively, arrays/scalars replace, and
                       null deletes a path.
  schema               Print the JSON schema for openclaw.json
  set                  Set config values by path (value mode, ref/provider
                       builder mode, or batch JSON mode).
  validate             Validate the active config against the schema

高频用法与实测回显：

openclaw config file

/root/.openclaw/openclaw.json

openclaw config get gateway.mode

local

openclaw config set agents.defaults.userTimezone "Asia/Shanghai"

Updated agents.defaults.userTimezone. Change will apply without restarting the gateway.

openclaw config validate

Config valid: ~/.openclaw/openclaw.json

4.3 状态与诊断命令

openclaw status：全景状态总表（Gateway/渠道/Agent/会话/备份/遥测一屏看全）：

openclaw status

实测输出（节选）：

OpenClaw status

Overview
┌──────────────────────┬─────────────────────────────────────────────────────────────┐
│ OS                   │ linux 6.8.0-138-generic (x64) · node 24.22.1                │
│ Dashboard            │ http://127.0.0.1:18789/                                     │
│ Channel              │ stable (default)                                            │
│ Update               │ npm                                                         │
│ Gateway              │ local · ws://127.0.0.1:18789 (local loopback) · reachable   │
│                      │ 325ms · auth token                                          │
│ Agents               │ 1 · no workspaces bootstrapping · sessions 0 · default main │
│ Sessions             │ 0 stored · default gpt-6-astra (272k ctx)                   │
└──────────────────────┴─────────────────────────────────────────────────────────────┘

Channels
No channels configured

Sessions
No sessions

常用变体：--json（机器可读，实测输出 runtimeVersion: 2026.10.6 等 JSON 文档）、--deep（含渠道深检）、--usage（供应商用量配额，需已配置 OAuth/API 凭据）。

openclaw health：只看 Gateway 健康（事件循环延迟、Agent、心跳、会话库）：

openclaw health

实测输出：

Gateway event loop: ok max=21ms p99=21ms util=0.018 cpu=0.023
Gateway check duration: 11ms
Agents: main (default)
Heartbeat interval: 30m (main)
Session store (main): /root/.openclaw/agents/main/agent/openclaw-agent.sqlite (0 entries)

openclaw doctor：体检 + 快速修复。无配置时实测会明确列出缺口与修复命令（节选）：

◇  Gateway ──────────────────────────────────────────────────────╮
│  gateway.mode is unset; gateway start will be blocked.         │
│  Or set directly: openclaw config set gateway.mode local       │
├────────────────────────────────────────────────────────────────┤
│  Gateway auth is off or missing a token.                       │
│  Run `openclaw doctor --fix --generate-gateway-token` to generate a │
│  token, then restart the Gateway.                              │
└────────────────────────────────────────────────────────────────┘

修复执行：openclaw doctor --fix --non-interactive（--repair 为同义参数，--yes 跳过确认）。实测修复完成后回显 └ Doctor complete.。

openclaw triage：收集脱敏诊断并唤起本地编码 Agent 修复；openclaw logs 经 RPC 拉取 Gateway 文件日志（--follow 持续跟踪）。

4.4 Gateway 管理命令

openclaw gateway 实测子命令清单（gateway --help）：

子命令	作用
`run`	前台运行 Gateway（调试用）
`install` / `uninstall`	安装/卸载系统服务（launchd/systemd/schtasks）
`start` / `stop` / `restart`	通过服务管理器启停
`status`	服务状态 + 连通性/能力检查
`health` / `stability` / `diagnostics`	健康 / 稳定性 / 诊断导出
`call`	调用 Gateway RPC 方法
`probe`	本地+远端可达性与鉴权能力探测
`discover`	Bonjour 发现局域网/广域网关
`auth-token`	交互式查看共享令牌
`usage-cost`	从会话日志汇总用量成本
`suspend` / `resume`	协作式挂起（主机休眠前准备/恢复）

gateway run 关键参数（gateway --help 实测）：

参数	说明
`--port <port>`	WebSocket 监听端口
`--bind <mode>`	绑定档位（`loopback\|lan\|tailnet\|auto\|custom`），默认取配置 `gateway.bind` 或 loopback
`--auth <mode>`	鉴权方式（`none\|token\|password\|trusted-proxy`）
`--token <token>`	共享令牌（默认读 `OPENCLAW_GATEWAY_TOKEN` 环境变量）
`--force`	强杀占用目标端口的进程后启动
`--allow-unconfigured`	放行未配置启动（不修复配置，调试用）
`--verbose`	详细日志

前台启动（实测日志节选）：

openclaw gateway run

2026-10-22T21:30:13.839+00:00 [gateway] ready
2026-10-22T21:30:15.374+00:00 [gateway] remote model catalog applied

服务安装与状态（Linux 生成 systemd 用户服务，实测）：

openclaw gateway install

Installed systemd service: /root/.config/systemd/user/openclaw-gateway.service
Gateway service installed. Runtime readiness has not been checked; startup may still be in progress. Check with openclaw gateway status and openclaw health.

openclaw gateway status

实测输出（节选）：

Service: systemd user (enabled)
Gateway: bind=loopback (127.0.0.1), port=18789 (service args)
Gateway version: 2026.10.6
Connectivity check: ok

启停操作对应 systemd 用户单元，亦可直接用 systemctl：systemctl --user start|stop|restart openclaw-gateway。

4.5 会话与 Agent 命令

openclaw sessions list：列出会话存储：

openclaw sessions list

实测输出：

Session store: /root/.openclaw/agents/main/agent/openclaw-agent.sqlite
Sessions listed: 0
No sessions found.

openclaw agents list：Agent 清单与路由（实测）：

Agents:
- main (default)
  Workspace: ~/.openclaw/workspace
  Agent dir: ~/.openclaw/agents/main/agent
  Routing rules: 0
  Routing: default (no explicit rules)

配套子命令：agents add/delete/bindings/set-identity 管理多代理。openclaw resume 在 TUI 中恢复最近会话。

openclaw agent：经 Gateway 跑一轮 Agent 对话（--local 用内嵌运行时）；openclaw message 发送/读取渠道消息。两者都需要可用模型凭据与渠道凭据，本环境未接入真实凭据，不展示执行结果——配置好后用法形如 openclaw agent --message "总结今天的日程"、openclaw message send --channel telegram --to <chatId> "你好"（参数以 --help 为准）。

4.6 渠道与配对命令

openclaw channels list

实测输出（未接入渠道时）：

Chat channels:
- no configured chat channels (run `openclaw channels list --all` to see installable channels)

Model provider usage moved out of `channels list` — see `openclaw status` or `openclaw models list`.
Docs: https://docs.openclaw.ai/gateway/configuration

channels add 引导式接入渠道账号（带凭据参数时走直连路径适合脚本）；channels status --probe 做渠道活体探测。DM 配对：陌生发送者会生成配对请求，用 openclaw pairing list <channel> 查看、openclaw pairing approve <channel> <code> 批准（实测查询回显 No pending telegram pairing requests.）。移动端配对用 openclaw qr 生成二维码与 setup code；设备管理走 openclaw devices list（实测 No device pairing entries.）。

4.7 模型命令

openclaw models list

实测输出（未配置凭据时）：

No models found.

openclaw models status

实测输出（节选）：

Config        : ~/.openclaw/openclaw.json
Agent dir     : ~/.openclaw/agents/main/agent
Default       : openai/gpt-6-astra
Fallbacks (0) : -
Utility model : openai/gpt-5.6-luna (provider default)
Image model   : -
Auth overview
Auth store    : ~/.openclaw/agents/main/agent/openclaw-agent.sqlite

💡 说明：models status 是跑 Agent 前的"预检"命令——一眼看清默认模型、故障转移链、工具模型与鉴权库存放位置。模型鉴权子命令在 openclaw models auth（login/logout/list/setup-token/paste-token 等）。官方模型目录带默认分工：主对话 gpt-6-astra（272k 上下文）、工具型任务 gpt-5.6-luna，可经 agents.defaults.utilityModel 等参数覆盖。

4.8 插件、技能与记忆命令

openclaw plugins list

实测输出（节选）：

Plugins (41/66 enabled)
Source roots:
  stock: /usr/lib/node_modules/openclaw/dist/extensions
┌───────────────────────────────┬───────────────────┬──────────┬──────────┐
│ Name                          │ ID                │ Format   │ Status   │
├───────────────────────────────┼───────────────────┼──────────┼──────────┤
│ A2A                           │ a2a               │ openclaw │ disabled │
│ Active Memory                 │ active-memory     │ openclaw │ disabled │
│ @openclaw/admin-http-rpc      │ admin-http-rpc    │ openclaw │ disabled │
└───────────────────────────────┴───────────────────┴──────────┴──────────┘

openclaw skills list

实测输出（节选）：

Skills (19/55 ready)
┌───────────────┬──────────────────────────┬──────────────────────────────────────┐
│ Status        │ Skill                    │ Description                          │
├───────────────┼──────────────────────────┼──────────────────────────────────────┤
│ △ needs setup │ 🔐 1password             │ Set up and use 1Password CLI for...  │
│ ✓ ready       │ add-model-provider       │ Add and live-prove a model provider  │
└───────────────┴──────────────────────────┴──────────────────────────────────────┘

配套子命令：plugins install/uninstall/update/inspect/doctor、skills install/update/verify（ClawHub 技能市场生态）。

openclaw memory status

实测输出（节选）：

Memory Search (main)
Provider: openai (requested: openai)
Model: text-embedding-3-small
Sources: memory, sessions
Indexed: 0/0 files · 0 chunks
Dirty: yes
Store: ~/.openclaw/agents/main/agent/openclaw-agent.sqlite

配套子命令：memory index/search/reindex（索引与检索记忆文件）。

4.9 自动化与其他运维命令

openclaw cron status（automations 的存储与调度状态，实测输出为 JSON）：

{
  "enabled": true,
  "triggersEnabled": true,
  "storePath": "/root/.openclaw/state/openclaw.sqlite",
  "storage": "sqlite",
  "jobs": 2,
  "nextWakeAtMs": 1792706146445
}

配套：cron add/edit/rm/enable/disable/runs 管理定时任务。

openclaw nodes status（设备节点，实测 Known: 0 · Paired: 0 · Connected: 0）；openclaw security audit（安全体检，status 输出里提示"Full report: openclaw security audit"）；openclaw backup create/verify/restore（状态归档）；openclaw database port --to postgres --dry-run（SQLite→PostgreSQL 迁移预检）；openclaw update status（升级通道状态）；openclaw uninstall（卸载服务+本地数据）。

4.10 输出模式与 JSON 约定

彩色与进度条只在 TTY 会话渲染；--json 保留 stdout 给单个 JSON 文档，告警走 stderr。
JSON 模式失败时以统一信封退出非零（官方约定，脚本解析用）：

{
  "ok": false,
  "error": {
    "type": "cli_error",
    "message": "Description of the failure"
  }
}

实测 openclaw status --json 返回的顶层键含 runtimeVersion、hostDesktop、heartbeat、channelSummary、sessions 等，可直接 jq 消费。
重跑失败命令前加 OPENCLAW_DEBUG=1 附带诊断信息。

五、注意事项

所有者与白名单是两道权限：pairing approve/allowFrom 决定"谁能跟机器人说话"，commands.ownerAllowFrom 决定"谁能执行管理命令"；两者互不替代。
gateway. 改动需重启*：config set 输出会注明是否需要重启（详见《OpenClaw 2026.10.6 配置参数详解》第三章）。
gateway run --force 谨慎使用：它会杀掉占用端口的既有进程，生产环境先 gateway status 排查再决定。
--allow-unconfigured 只放行不修复：缺 gateway.mode 时用它启动属于调试行为，正式使用应补齐配置。
升级后先 doctor：版本跨越大时跑 openclaw update 会自动处理迁移；手工升级后建议 openclaw doctor 复核。
JSON 模式看 stdout、人读看 stderr：脚本里解析 stdout 并检查退出码，不要抓 stderr 拼结果。

六、常见问题（FAQ）

Q1：openclaw doctor --fix 报 GatewayStateOwnerContentionError？ Gateway 正在运行并持有状态库维护锁，先停服务再修复：systemctl --user stop openclaw-gateway → openclaw doctor --fix --non-interactive → 重新启动服务（实测完整回显见《OpenClaw Ubuntu 24.04 安装指南》第九章 Q2）。

Q2：命令输出乱码或没有颜色？ 远程 SSH/CI 里 TTY 缺失时颜色自动关闭；需要强制关闭用 --no-color 或 NO_COLOR=1。日志级别用 --log-level debug 提升排查信息量。

Q3：openclaw gateway status 显示 Service: no supported service manager detected？ 说明当前环境没有可识别的服务管理器（或服务未安装），Gateway 是手工前台/后台方式运行的。诊断不影响使用；需要常驻时执行 openclaw gateway install 安装服务（需 systemd 的 Linux 真机/WSL2，或 macOS launchd）。

Q4：连接 Gateway 失败，如何自证 Gateway 正常？ 按序执行：openclaw gateway status（服务与连通性）→ openclaw health（事件循环与会话库）→ openclaw gateway probe（可达性+鉴权能力）。三者任一失败再查端口与令牌。

Q5：哪里看 Gateway 运行日志？ 三条路径：openclaw logs --follow（RPC 拉取）、journalctl --user -u openclaw-gateway -f（systemd 服务）、文件日志 ~/.openclaw/logs/（gateway status 回显中的 File logs 路径）。

七、参考链接

官方 CLI 参考：https://docs.openclaw.ai/cli
Gateway 运行手册：https://docs.openclaw.ai/gateway
Doctor 文档：https://docs.openclaw.ai/doctor
自动化（cron）：https://docs.openclaw.ai/automation
聊天斜杠命令：https://docs.openclaw.ai/slash-commands
本站认知篇：《OpenClaw 介绍与选型指南》
本站部署篇：《OpenClaw Ubuntu 24.04 安装指南》
本站配置篇：《OpenClaw 2026.10.6 配置参数详解》