OpenClaw 完整命令参考指南

版本: OpenClaw 2026.3.13 (61d=171a)
文档来源: 官方 CLI 帮助输出 (openclaw --help 及各子命令 --help)
官方文档: https://docs.openclaw.ai/cli

前期回归：

OpenClaw 本地操控机制详解

OpenClaw 接入 Telegram Bot（纸飞机机器人）实现机制详解

OpenClaw 故障转移配置实战指南：让你的AI助手永不掉线

1. 快速入门

安装与初始化

# 安装 OpenClaw CLI (通过 npm/pnpm)
npm install -g openclaw

# 初始化配置和工作空间
openclaw setup

# 启动交互式配置向导
openclaw configure

# 启动网关服务
openclaw gateway start

检查状态

# 查看整体状态
openclaw status

# 深度状态检查
openclaw status --deep

# 健康检查
openclaw health

# 查看日志
openclaw logs --follow

2. 全局选项

所有 openclaw 命令都支持以下全局选项：

选项	说明
`--dev`	开发模式：隔离状态到 `~/.openclaw-dev`，默认网关端口 19001
`--profile <name>`	使用命名配置文件，隔离状态到 `~/.openclaw-<name>`
`--log-level <level>`	全局日志级别：`silent`\|`fatal`\|`error`\|`warn`\|`info`\|`debug`\|`trace`
`--no-color`	禁用 ANSI 颜色输出
`-h, --help`	显示帮助信息
`-V, --version`	显示版本号

示例:

# 在开发模式下运行网关
openclaw --dev gateway run

# 使用特定配置文件
openclaw --profile work status

3. 核心命令详解

3.1 Gateway 网关管理

Gateway 是 OpenClaw 的核心服务，负责 WebSocket 通信和代理管理。

openclaw gateway [options] [command]

服务生命周期

命令	功能
`gateway run`	前台运行网关
`gateway start`	启动网关服务 (launchd/systemd/schtasks)
`gateway stop`	停止网关服务
`gateway restart`	重启网关服务
`gateway status`	查看服务状态和连通性
`gateway install`	安装网关服务
`gateway uninstall`	卸载网关服务

探测与诊断

命令	功能
`gateway probe`	显示网关可达性 + 发现 + 健康 + 状态摘要
`gateway discover`	通过 Bonjour 发现本地和广域网关
`gateway health`	获取网关健康状态
`gateway call <method>`	直接调用网关 RPC 方法
`gateway usage-cost`	从会话日志获取使用成本摘要

启动选项

选项	说明
`--port <port>`	指定网关 WebSocket 端口
`--bind <mode>`	绑定模式：`loopback`\|`lan`\|`tailnet`\|`auto`\|`custom`
`--auth <mode>`	认证模式：`none`\|`token`\|`password`\|`trusted-proxy`
`--token <token>`	共享令牌 (默认使用 `OPENCLAW_GATEWAY_TOKEN` 环境变量)
`--password <password>`	密码认证模式的密码
`--force`	强制关闭占用端口的现有进程
`--allow-unconfigured`	允许无配置启动网关
`--tailscale <mode>`	Tailscale 暴露模式：`off`\|`serve`\|`funnel`
`--verbose`	详细日志输出

示例:

# 前台运行网关
openclaw gateway run

# 指定端口运行
openclaw gateway run --port 18789

# 开发模式运行
openclaw --dev gateway run

# 强制启动（关闭占用端口的进程）
openclaw gateway run --force

# 查看网关状态
openclaw gateway status

# 探测网关连通性
openclaw gateway probe

3.2 Security 安全审计

openclaw security [command]

命令	功能
`security audit`	审计配置和本地状态的安全问题
`security audit --deep`	包含实时网关探测检查
`security audit --fix`	应用安全修复（收紧默认值 + 文件权限）
`security audit --json`	JSON 格式输出

安全审计检查项:

• 危险的配置标志（如 dangerouslyAllowHostHeaderOriginFallback）
• 文件权限问题
• 攻击面摘要（工具组权限、elevated 权限、webhooks 等）
• 通道安全状态
• 浏览器控制配置

示例:

# 运行基础安全审计
openclaw security audit

# 深度审计
openclaw security audit --deep

# 自动修复安全问题
openclaw security audit --fix

# JSON 输出供脚本处理
openclaw security audit --json

3.3 Channels 通道管理

管理已连接的聊天通道（Telegram、Discord、WhatsApp 等）。

openclaw channels [command]

命令	功能
`channels list`	列出已配置的通道和认证配置文件
`channels add`	添加或更新通道账户
`channels remove`	禁用或删除通道账户
`channels login`	链接通道账户（如 WhatsApp Web）
`channels logout`	登出通道会话
`channels status`	显示网关通道状态
`channels logs`	显示通道日志
`channels capabilities`	显示提供商能力（意图/范围 + 支持功能）
`channels resolve`	解析通道/用户名到 ID

示例:

# 列出所有通道
openclaw channels list

# 添加 Telegram Bot
openclaw channels add --channel telegram --token <bot_token>

# 链接 WhatsApp
openclaw channels login --channel whatsapp

# 检查通道状态
openclaw channels status

# 深度探测
openclaw channels status --probe

3.4 Models 模型管理

openclaw models [command]

命令	功能
`models list`	列出模型（默认显示已配置的）
`models set <model>`	设置默认模型
`models set-image <model>`	设置图像模型
`models status`	显示配置的模型状态
`models scan`	扫描 OpenRouter 免费模型（工具 + 图像支持）
`models aliases`	管理模型别名
`models auth`	管理模型认证配置文件
`models fallbacks`	管理模型回退列表
`models image-fallbacks`	管理图像模型回退列表

全局选项:

选项	说明
`--agent <id>`	指定要检查的代理 ID
`--status-json`	JSON 格式输出状态
`--status-plain`	纯文本格式输出状态

示例:

# 列出所有模型
openclaw models list

# 设置默认模型
openclaw models set kimi-coding/k2p5

# 设置图像模型
openclaw models set-image gpt-4o

# 查看模型状态
openclaw models status

# 扫描 OpenRouter 免费模型
openclaw models scan

3.5 Cron 定时任务

通过 Gateway 调度器管理定时任务。

openclaw cron [command]

命令	功能
`cron list`	列出定时任务
`cron add`	添加定时任务
`cron edit <id>`	编辑定时任务（修补字段）
`cron rm <id>`	删除定时任务
`cron run <id>`	立即运行任务（调试）
`cron runs <id>`	显示任务运行历史（JSONL 支持）
`cron status`	显示调度器状态
`cron enable <id>`	启用定时任务
`cron disable <id>`	禁用定时任务

任务类型:

• systemEvent: 向会话注入系统事件
• agentTurn: 运行代理（仅隔离会话）

调度类型:

• at: 一次性任务（ISO-8601 时间戳）
• every: 周期性间隔（毫秒）
• cron: Cron 表达式

示例:

# 列出所有定时任务
openclaw cron list

# 添加每日安全审计
openclaw cron add --name "daily-audit" \
  --schedule "0 9 * * *" \
  --command "openclaw security audit"

# 查看任务运行历史
openclaw runs healthcheck:security-audit

# 立即运行任务
openclaw cron run healthcheck:security-audit

3.6 Config 配置管理

openclaw config [command]

命令	功能
`config file`	打印活动配置文件路径
`config get <path>`	通过点路径获取配置值
`config set <path> <value>`	通过点路径设置配置值
`config unset <path>`	通过点路径删除配置值
`config validate`	验证当前配置是否符合模式
(无子命令)	启动交互式设置向导

配置向导选项:

选项	说明
`--section <section>`	指定配置向导区域（可重复）

示例:

# 查看配置文件位置
openclaw config file

# 获取特定配置值
openclaw config get gateway.port

# 设置配置值
openclaw config set gateway.port 19001

# 删除配置项
openclaw config unset gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback

# 验证配置
openclaw config validate

# 启动配置向导（仅特定区域）
openclaw config --section gateway --section models

3.7 Sessions 会话管理

openclaw sessions [options] [command]

选项	说明
`--active <minutes>`	仅显示过去 N 分钟内更新的会话
`--agent <id>`	指定代理 ID
`--all-agents`	聚合所有配置的代理的会话
`--json`	JSON 格式输出
`--store <path>`	指定会话存储路径
`--verbose`	详细日志

命令	功能
`sessions cleanup`	运行会话存储维护

示例:

# 列出所有会话
openclaw sessions

# 仅显示最近2小时的活跃会话
openclaw sessions --active 120

# 查看特定代理的会话
openclaw sessions --agent work

# 聚合所有代理
openclaw sessions --all-agents

# JSON 输出
openclaw sessions --json

3.8 Skills 技能管理

openclaw skills [command]

命令	功能
`skills list`	列出所有可用技能
`skills info <skill>`	显示技能详细信息
`skills check`	检查哪些技能已就绪 vs 缺少依赖

示例:

# 列出所有技能
openclaw skills list

# 查看技能详情
openclaw skills info healthcheck

# 检查技能依赖
openclaw skills check

3.9 Browser 浏览器自动化

管理 OpenClaw 的专用浏览器（Chrome/Chromium），支持完整的浏览器自动化。

openclaw browser [command]

生命周期管理

命令	功能
`browser start`	启动浏览器
`browser stop`	停止浏览器
`browser status`	显示浏览器状态
`browser profiles`	列出所有浏览器配置文件
`browser create-profile <name>`	创建新配置文件
`browser delete-profile <name>`	删除配置文件
`browser reset-profile <name>`	重置配置文件（移到回收站）

标签页管理

命令	功能
`browser tabs`	列出打开的标签页
`browser open <url>`	在新标签页打开 URL
`browser focus <targetId>`	聚焦标签页
`browser close [targetId]`	关闭标签页
`browser tab <index>`	标签页快捷方式（基于索引）

页面操作

命令	功能
`browser navigate <url>`	导航到 URL
`browser click <ref>`	点击元素
`browser type <ref> <text>`	在元素中输入文本
`browser press <key>`	按下按键
`browser hover <ref>`	悬停在元素上
`browser drag <from> <to>`	从一个元素拖动到另一个
`browser select <ref> <options...>`	选择下拉选项
`browser fill --fields <json>`	用 JSON 字段描述符填充表单
`browser upload <path>`	准备文件上传
`browser scrollintoview <ref>`	滚动元素到视图
`browser highlight <ref>`	高亮元素

等待与条件

命令	功能
`browser wait`	等待时间/选择器/URL/加载状态/JS 条件
`browser waitfordownload`	等待下载完成

数据捕获

命令	功能
`browser snapshot`	捕获页面快照（默认 AI 格式）
`browser screenshot`	截图
`browser pdf`	保存页面为 PDF
`browser evaluate --fn <function>`	在页面或元素上执行函数
`browser console`	获取最近控制台消息
`browser errors`	获取最近页面错误
`browser requests`	获取最近网络请求
`browser responsebody`	等待网络响应并返回内容
`browser trace`	录制 Playwright 追踪

存储与 Cookie

命令	功能
`browser cookies`	读取/写入 Cookie
`browser storage`	读取/写入 localStorage/sessionStorage

对话框处理

命令	功能
`browser dialog`	处理模态对话框（alert/confirm/prompt）

浏览器选项

选项	说明
`--browser-profile <name>`	浏览器配置文件名
`--timeout <ms>`	超时（默认 30000ms）
`--json`	JSON 输出
`--url <url>`	Gateway WebSocket URL
`--token <token>`	Gateway 令牌

示例:

# 启动浏览器
openclaw browser start

# 打开页面
openclaw browser open https://example.com

# 捕获快照
openclaw browser snapshot

# 使用 aria 格式快照
openclaw browser snapshot --format aria --limit 200

# 截图
openclaw browser screenshot
openclaw browser screenshot --full-page
openclaw browser screenshot --ref 12

# 点击元素（引用来自快照）
openclaw browser click 12 --double

# 输入文本并提交
openclaw browser type 23 "hello" --submit

# 导航
openclaw browser navigate https://example.com

# 调整窗口大小
openclaw browser resize 1280 720

# 等待页面加载
openclaw browser wait --text "Done"

# 保存为 PDF
openclaw browser pdf

3.10 Message 消息操作

发送、读取和管理消息及通道操作。

openclaw message [command]

消息操作

命令	功能
`message send`	发送消息
`message read`	读取最近消息
`message edit`	编辑消息
`message delete`	删除消息
`message react`	添加或移除反应
`message reactions`	列出消息反应
`message pin`	置顶消息
`message unpin`	取消置顶
`message pins`	列出置顶消息

成员管理

命令	功能
`message kick`	踢出成员
`message ban`	封禁成员
`message timeout`	成员超时
`message member`	成员操作

频道操作

命令	功能
`message channel`	频道操作
`message permissions`	获取频道权限
`message role`	角色操作
`message thread`	线程操作

高级功能

命令	功能
`message broadcast`	广播消息到多个目标
`message poll`	发送投票
`message search`	搜索 Discord 消息
`message emoji`	表情操作
`message sticker`	贴纸操作
`message event`	事件操作
`message voice`	语音操作

示例:

# 发送文本消息
openclaw message send --target +15555550123 --message "Hi"

# 发送带媒体的消息
openclaw message send --target +15555550123 --message "Hi" --media photo.jpg

# 创建 Discord 投票
openclaw message poll \
  --channel discord \
  --target channel:123 \
  --poll-question "Snack?" \
  --poll-option Pizza \
  --poll-option Sushi

# 对消息添加反应
openclaw message react \
  --channel discord \
  --target 123 \
  --message-id 456 \
  --emoji "✅"

3.11 Devices & Nodes 设备管理

Devices - 设备配对和令牌管理

openclaw devices [command]

命令	功能
`devices list`	列出待处理和已配对设备
`devices approve`	批准待处理的设备配对请求
`devices reject`	拒绝待处理的设备配对请求
`devices remove`	移除已配对设备
`devices clear`	清除网关表中的配对设备
`devices revoke`	撤销角色的设备令牌
`devices rotate`	轮换角色的设备令牌

Nodes - 网关节点管理

openclaw nodes [command]

命令	功能
`nodes status`	列出已知节点及其连接状态和能力
`nodes list`	列出待处理和已配对节点
`nodes pending`	列出待处理的配对请求
`nodes approve`	批准配对请求
`nodes reject`	拒绝配对请求
`nodes rename`	重命名配对节点
`nodes describe`	描述节点（能力 + 支持的调用命令）
`nodes invoke`	在配对节点上调用命令
`nodes run`	在节点上运行 shell 命令（仅 mac）
`nodes camera`	从配对节点捕获相机媒体
`nodes canvas`	捕获或渲染配对节点的画布内容
`nodes screen`	从配对节点捕获屏幕录制
`nodes location`	从配对节点获取位置
`nodes notify`	在节点上发送本地通知（仅 mac）
`nodes push`	向 iOS 节点发送 APNs 测试推送

示例:

# 查看节点状态
openclaw nodes status

# 查看待处理请求
openclaw nodes pairing pending

# 批准配对
openclaw nodes approve --id <device_id>

# 在节点上运行命令
openclaw nodes run --node <id> --raw "uname -a"

# 捕获照片
openclaw nodes camera snap --node <id>

# 获取位置
openclaw nodes location get --node <id>

3.12 Agents 隔离代理

管理隔离代理（工作空间 + 认证 + 路由）。

openclaw agents [command]

命令	功能
`agents list`	列出配置的代理
`agents add`	添加新隔离代理
`agents delete`	删除代理并清理工作空间/状态
`agents set-identity`	更新代理身份（名称/主题/表情/头像）
`agents bind`	添加路由绑定
`agents unbind`	移除路由绑定
`agents bindings`	列出路由绑定

示例:

# 列出所有代理
openclaw agents list

# 添加新代理
openclaw agents add --id work --name "Work Agent"

# 设置代理身份
openclaw agents set-identity --id work --name "Work Helper" --emoji "💼"

# 添加路由绑定
openclaw agents bind --id work --channel telegram --target @workchat

3.13 其他重要命令

Update 更新管理

openclaw update [options] [command]

命令	功能
`update status`	显示更新通道和版本状态
`update wizard`	交互式更新向导
(无子命令)	执行更新

选项	说明
`--channel <stable\|beta\|dev>`	持久化更新通道
`--tag <dist-tag\|version>`	覆盖 npm dist-tag 或版本
`--dry-run`	预览更新操作而不执行
`--no-restart`	更新后不重启网关服务
`--yes`	跳过确认提示
`--timeout <seconds>`	更新步骤超时

示例:

# 检查更新状态
openclaw update status

# 执行更新
openclaw update

# 切换到 beta 通道
openclaw update --channel beta

# 预览更新
openclaw update --dry-run

# 不重启更新
openclaw update --no-restart

Doctor 健康检查

openclaw doctor [options]

选项	说明
`--fix` / `--repair`	应用推荐修复
`--force`	应用激进修复（覆盖自定义服务配置）
`--deep`	扫描系统服务中的额外网关安装
`--generate-gateway-token`	生成并配置网关令牌
`--non-interactive`	无提示运行（仅安全迁移）
`--yes`	接受默认值

示例:

# 运行健康检查
openclaw doctor

# 自动修复问题
openclaw doctor --fix

# 生成网关令牌
openclaw doctor --generate-gateway-token

Backup 备份管理

openclaw backup [command]

命令	功能
`backup create`	创建备份归档（配置、凭证、会话、工作空间）
`backup verify`	验证备份归档及其嵌入清单

示例:

# 创建备份
openclaw backup create

# 验证备份
openclaw backup verify <backup-file>

ACP (Agent Control Protocol)

openclaw acp [command]

用于管理 ACP 工具和代理控制协议。

Memory 记忆管理

openclaw memory [command]

搜索和重新索引记忆文件。

Webhooks Webhook 管理

openclaw webhooks [command]

Webhook 助手和集成。

Logs 日志查看

openclaw logs

通过 RPC 查看网关文件日志。

Dashboard 控制面板

openclaw dashboard

使用当前令牌打开控制 UI。

TUI 终端界面

openclaw tui

打开连接到网关的终端 UI。

4. 实用场景示例

场景 1: 初次设置 OpenClaw

# 1. 初始化
openclaw setup

# 2. 配置凭证和通道
openclaw configure

# 3. 验证配置
openclaw config validate

# 4. 启动网关
openclaw gateway start

# 5. 检查状态
openclaw status

# 6. 运行安全审计
openclaw security audit --fix

场景 2: 配置 Telegram Bot

# 1. 添加 Telegram Bot
openclaw channels add --channel telegram --token "YOUR_BOT_TOKEN"

# 2. 验证通道状态
openclaw channels status

# 3. 发送测试消息
openclaw message send \
  --channel telegram \
  --target @your_channel \
  --message "Hello from OpenClaw!"

场景 3: 设置定时安全审计

# 1. 创建定时任务（每天早上 9 点运行）
openclaw cron add \
  --name "daily-security-audit" \
  --schedule "cron" \
  --cron-expr "0 9 * * *" \
  --payload-type "systemEvent" \
  --payload-text "Run security audit"

# 2. 列出所有定时任务
openclaw cron list

# 3. 查看任务运行历史
openclaw cron runs daily-security-audit

场景 4: 浏览器自动化任务

# 1. 启动浏览器
openclaw browser start

# 2. 打开目标网站
openclaw browser open https://example.com

# 3. 捕获页面快照
openclaw browser snapshot > page.json

# 4. 截图
openclaw browser screenshot --full-page

# 5. 执行操作（根据快照中的 ref）
openclaw browser click 12
openclaw browser type 23 "search query" --submit

# 6. 等待结果
openclaw browser wait --text "Results"

# 7. 保存 PDF
openclaw browser pdf

# 8. 停止浏览器
openclaw browser stop

场景 5: 多代理设置

# 1. 创建工作代理
openclaw agents add --id work --name "Work Assistant"
openclaw agents set-identity --id work --emoji "💼" --theme professional

# 2. 创建个人代理
openclaw agents add --id personal --name "Personal Assistant"
openclaw agents set-identity --id personal --emoji "🏠" --theme casual

# 3. 绑定路由
openclaw agents bind --id work --channel telegram --target @work_group
openclaw agents bind --id personal --channel telegram --target @personal_chat

# 4. 列出代理
openclaw agents list

场景 6: 备份与迁移

# 1. 创建完整备份
openclaw backup create --output openclaw-backup-$(date +%Y%m%d).zip

# 2. 验证备份
openclaw backup verify openclaw-backup-20260323.zip

# 3. 导出配置（供手动检查）
openclaw config file

# 4. 在新机器上恢复：
# - 安装 OpenClaw
# - 解压备份到配置目录
# - 运行 doctor 修复权限
openclaw doctor --fix

5. 故障排查

5.1 网关无法启动

# 检查端口占用
openclaw gateway probe

# 强制启动（关闭占用进程）
openclaw gateway run --force

# 查看详细日志
openclaw logs --follow

# 运行诊断
openclaw doctor --deep --fix

5.2 通道连接问题

# 检查通道状态
openclaw channels status --probe

# 查看通道日志
openclaw channels logs

# 重新登录
openclaw channels logout --channel telegram
openclaw channels login --channel telegram

5.3 安全问题修复

# 运行安全审计
openclaw security audit --deep

# 自动修复
openclaw security audit --fix

# 手动修复特定配置
openclaw config unset gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback

5.4 性能问题

# 清理会话存储
openclaw sessions cleanup

# 检查资源使用
openclaw gateway usage-cost

# 深度检查
openclaw doctor --deep

参考资源

• 官方文档: https://docs.openclaw.ai
• CLI 文档: https://docs.openclaw.ai/cli
• GitHub: https://github.com/openclaw/openclaw
• Discord 社区: https://discord.com/invite/clawd