OpenClaw CLI 完整命令手册

版本命令会显示 CLI 版本、Node.js 版本和操作系统信息，这是确认安装成功最直接的方式。帮助命令则列出所有可用命令，方便快速查阅。doctor 命令会执行全面的系统诊断，检查配置文件、网络连接、模型 API 等是否正常。

3. 命令结构总览

3.1 层级命令体系

OpenClaw CLI 采用层级化的命令结构，主命令 openclaw 下设多个子命令，每个子命令又可以有进一步的子命令和选项。这种设计使得命令组织清晰，功能边界明确。

• openclaw
  • gateway *
  • status
  • config *
  • sessions *
  • skills *
  • nodes *
  • logs
  • doctor
  • channels *
  • models *
  • agents *
  • start
  • stop
  • restart
  • status
  • run
  • health
  • get
  • set
  • unset
  • list
  • info
  • check
  • invoke
  • camera
  • screen

上图展示了 OpenClaw CLI 的主要命令层级结构。可以看到，gateway、config、sessions、skills、nodes 等命令都有各自的子命令，形成了一个完整的命令树。带有 * 标记的命令表示它们还有更深层的子命令。

3.2 全局选项

除了各命令的特定参数外，OpenClaw CLI 还提供了一系列全局选项，可以在任何命令前使用：

全局选项的使用示例：

# 开发模式启动 Gateway
openclaw --dev gateway run
# 指定日志级别
openclaw --log-level debug gateway status
# 使用命名配置
openclaw --profile production gateway start

全局选项为命令提供了额外的控制能力，在脚本自动化和日志分析场景中特别有用。

4. Gateway 网关命令

4.1 Gateway 概述

Gateway（网关）是 OpenClaw 系统的核心组件，负责处理所有消息渠道的接入和路由。它作为一个常驻后台服务运行，接收来自 Telegram、飞书、Discord 等平台的消息，并将其分发给对应的 Agent 进行处理。

Gateway 命令提供了对网关服务的完整生命周期管理，包括启动、停止、重启和状态查询。熟练掌握这些命令是运维 OpenClaw 系统的基础。

4.2 Gateway 子命令一览

4.3 启动网关

# 前台运行（开发调试）
openclaw gateway run
# 后台启动系统服务
openclaw gateway start
# 指定端口和认证模式
openclaw gateway run --port 18789 --auth token --token my-secret-token
# 强制启动（杀死占用端口的进程）
openclaw gateway run --force
# 开发模式（隔离配置）
openclaw --dev gateway run
# 绑定到局域网
openclaw gateway run --bind lan
# 通过 Tailscale 暴露
openclaw gateway run --tailscale serve

启动命令的常用参数说明：

4.4 停止与重启

# 停止网关服务
openclaw gateway stop
# 重启网关服务
openclaw gateway restart
# 查看服务状态
openclaw gateway status

4.5 Gateway 运行流程

Gateway 启动流程如下：CLI 首先加载配置，检查端口占用情况。如果端口被占用且未指定 --force，则报错；若指定 --force，则杀死占用进程。随后启动 Gateway 服务，初始化消息渠道和技能系统，最终显示 Gateway online on ws://127.0.0.1:18789。

5. Status 状态命令

5.1 系统状态概览

Status 命令提供了 OpenClaw 系统的整体运行状态视图，包括 Gateway 状态、活跃会话、资源使用等关键指标。这是了解系统健康状况的第一入口。

# 查看系统状态
openclaw status
# 输出示例：
# Gateway: online
# Channels: telegram ✓, feishu ✓, discord ✗
# Sessions: 3 active
# Model: gpt-4o-mini (default)

状态输出采用可视化的表格形式，一目了然地展示系统各组件的运行情况。绿色勾号表示正常，红色叉号表示异常或未启用。

5.2 详细状态选项

# 完整诊断（只读，可粘贴分享）
openclaw status --all
# 深度探测消息渠道
openclaw status --deep
# 显示模型使用配额
openclaw status --usage
# 以 JSON 格式输出
openclaw status --json
# 设置探测超时
openclaw status --deep --timeout 5000

JSON 格式输出特别适合在监控脚本中使用，可以通过 jq 等工具进行解析：

# 获取 Gateway 状态
openclaw status --json | jq '.gateway.status'
# 获取活跃会话数
openclaw status --json | jq '.sessions.active'

5.3 Status 命令参数

6. Config 配置管理命令

6.1 配置文件结构

OpenClaw 的配置采用 YAML 格式，默认位于 ~/.openclaw/openclaw.json。配置文件包含 Gateway、模型、渠道、技能等多个部分的设置。

{
  "gateway": {
    "mode": "local",
    "port": 18789,
    "bind": "loopback",
    "auth": "token"
  },
  "model": {
    "default": "gpt-4o-mini",
    "reasoning": "o1-mini"
  },
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "${TELEGRAM_BOT_TOKEN}"
    },
    "feishu": {
      "enabled": true,
      "appId": "${FEISHU_APP_ID}",
      "appSecret": "${FEISHU_APP_SECRET}"
    }
  },
  "agents": {
    "defaults": {
      "workspace": "~/.openclaw/workspace"
    }
  }
}

上述配置文件展示了 OpenClaw 的主要配置项。使用环境变量（如 ${TELEGRAM_BOT_TOKEN}）可以避免在配置文件中硬编码敏感信息，这是推荐的安全实践。

6.2 配置管理命令

# 交互式配置向导
openclaw configure
# 获取配置值
openclaw config get gateway.port
openclaw config get model.default
# 设置配置值
openclaw config set gateway.port 19000
openclaw config set model.default "gpt-4o"
# 删除配置值
openclaw config unset channels.discord.enabled
# 指定配置部分运行向导
openclaw config --section gateway --section model

配置命令提供了对配置文件的完整管理能力。config get 和 config set 支持点号路径访问嵌套配置，非常直观。

6.3 Config 命令详解

配置路径支持点号和方括号两种语法：

# 点号语法
openclaw config get gateway.port
# 方括号语法（用于数组或特殊键名）
openclaw config get "channels[0].name"

7. Sessions 会话控制命令

7.1 会话概念

在 OpenClaw 中，Session（会话）代表一个独立的对话上下文。每次用户与 Agent 开始对话，系统都会创建或关联一个会话。会话管理命令让你能够查看、监控和管理这些对话。

会话的设计使得同一个 Agent 可以同时处理多个用户的对话，每个对话都有独立的上下文和历史记录。这对于多用户场景和长期运行的服务非常重要。

7.2 会话管理命令

# 列出所有会话
openclaw sessions
# 输出示例：
# Session ID Channel Recipient Updated
# sess_abc123... telegram user_001 2h ago
# sess_def456... feishu user_002 1d ago
# 仅显示最近活跃的会话
openclaw sessions --active 120
# 指定 Agent 查看
openclaw sessions --agent work
# 聚合所有 Agent 的会话
openclaw sessions --all-agents
# JSON 格式输出
openclaw sessions --json
# 运行会话存储维护
openclaw sessions cleanup

7.3 Sessions 命令参数

会话列表会显示 Token 使用量（如果 Agent 报告），可以通过设置 agents.defaults.contextTokens 来限制上下文窗口大小。

8. Skills 技能系统命令

8.1 Skill 系统概述

Skill（技能）是 OpenClaw 的核心扩展机制。每个技能定义了一组特定的能力和行为，Agent 可以根据用户请求动态调用相关技能。技能系统让 OpenClaw 能够灵活地适应各种应用场景。

OpenClaw 提供了丰富的官方技能库，同时也支持用户自定义开发技能。Skill 命令提供了对技能的完整生命周期管理。

8.2 技能管理命令

# 列出已安装技能
openclaw skills list
# 输出示例：
# Name Description
# weather 天气查询与预报
# translator 多语言翻译
# calendar 日程管理
# web-search 网络搜索
# 查看技能详情
openclaw skills info weather
# 检查技能状态
openclaw skills check
# 输出示例：
# ✓ weather: ready
# ✓ translator: ready
# ✗ custom-helper: missing requirements

8.3 技能开发流程

技能开发的完整流程如下：

1. 创建技能目录
2. 编写 SKILL.md
3. 实现工具函数
4. 本地测试
5. 验证配置
6. 部署使用

上述流程展示了技能开发的完整步骤，每个环节都有对应的 CLI 命令支持。

9. Nodes 节点管理命令

9.1 节点系统介绍

Node（节点）是 OpenClaw 的分布式扩展机制。通过节点系统，OpenClaw 可以连接和控制远程设备，实现跨设备的协同工作。典型应用场景包括：连接手机发送通知、控制智能家居设备、访问远程摄像头等。

节点系统采用配对机制，确保只有授权的设备才能连接。每个节点都有唯一标识和权限配置。

9.2 节点管理命令

# 列出节点状态
openclaw nodes status
# 输出示例：
# ID Name Platform Status Last Seen
# node_001 我的手机 android online 2m ago
# node_002 工作电脑 mac online 1h ago
# 列出待审批的配对请求
openclaw nodes pending
# 批准配对请求
openclaw nodes approve <request-id>
# 拒绝配对请求
openclaw nodes reject <request-id>
# 查看节点详情
openclaw nodes describe node_001
# 重命名节点
openclaw nodes rename node_001 --name "我的手机"

9.3 节点高级功能

节点系统支持丰富的高级功能，如摄像头访问、屏幕录制、位置获取等：

# 拍照
openclaw nodes camera snap --node node_001 --facing back
# 录制屏幕
openclaw nodes screen record --node node_002 --duration 10
# 获取位置
openclaw nodes location --node node_001
# 发送通知
openclaw nodes notify --node node_001 --title "测试" --body "消息内容"
# 在节点上执行命令（仅 Mac）
openclaw nodes run --node node_002 --command "uname -a"
# 调用节点命令
openclaw nodes invoke --node node_001 --command <cmd>

9.4 Nodes 子命令一览

10. Logs 日志查看命令

10.1 日志系统概述

日志是诊断和排查问题的重要依据。OpenClaw 提供了完善的日志系统，记录所有关键操作和事件。Logs 命令提供了便捷的日志查看和分析能力。

10.2 日志查看命令

# 查看最新日志
openclaw logs
# 实时跟踪日志
openclaw logs --follow
# 限制行数
openclaw logs --limit 100
# JSON 格式输出
openclaw logs --json
# 显示本地时间
openclaw logs --local-time
# 禁用颜色
openclaw logs --no-color
# 纯文本输出
openclaw logs --plain

10.3 Logs 命令参数

11. Doctor 诊断工具命令

11.1 Doctor 功能介绍

Doctor 命令是 OpenClaw 的系统诊断工具，能够自动检测系统配置、依赖项、网络连接等各方面的潜在问题。当遇到问题时，首先运行 doctor 命令往往能快速定位原因。

11.2 诊断命令使用

# 运行完整诊断
openclaw doctor
# 输出示例：
# ✓ Node.js version: v22.22.0 (supported)
# ✓ OpenClaw CLI: 2026.2.26
# ✓ Configuration file: valid
# ✓ Gateway: running
# ✓ Model API: connected
# ✓ Telegram channel: configured
# ✗ Discord channel: not configured
# ⚠ Skills: 1 skill has errors
# 自动修复问题
openclaw doctor --fix
# 非交互模式
openclaw doctor --non-interactive
# 深度扫描（检查系统服务）
openclaw doctor --deep
# 生成 Gateway 令牌
openclaw doctor --generate-gateway-token

11.3 Doctor 检查项

11.4 Doctor 参数说明

12. 其他重要命令

12.1 Channels 渠道管理

Channels 命令用于管理消息渠道的连接和认证：

# 列出已配置渠道
openclaw channels list
# 查看渠道状态
openclaw channels status --probe
# 登录渠道（如 WhatsApp Web）
openclaw channels login --channel whatsapp
# 登出渠道
openclaw channels logout --channel whatsapp
# 添加渠道配置
openclaw channels add --channel telegram --token <token>
# 移除渠道
openclaw channels remove --channel discord
# 查看渠道日志
openclaw channels logs --channel telegram
# 解析用户/群组 ID
openclaw channels resolve --channel telegram --query "username"

12.2 Models 模型管理

Models 命令用于管理 AI 模型配置：

# 列出可用模型
openclaw models list
# 查看模型状态
openclaw models status
# 设置默认模型
openclaw models set gpt-4o
# 设置图像模型
openclaw models set-image dall-e-3
# 扫描 OpenRouter 免费模型
openclaw models scan
# 管理模型别名
openclaw models aliases
# 管理认证配置
openclaw models auth
# 管理回退模型列表
openclaw models fallbacks

12.3 Agents 代理管理

Agents 命令用于管理隔离的 Agent 实例：

# 列出已配置 Agent
openclaw agents list
# 添加新 Agent
openclaw agents add --id work --workspace ~/work-agent
# 删除 Agent
openclaw agents delete work
# 设置 Agent 身份
openclaw agents set-identity work --name "工作助手" --emoji "💼"
# 管理路由绑定
openclaw agents bind --agent work --channel telegram --target @mygroup
openclaw agents unbind --agent work --channel telegram
openclaw agents bindings

12.4 Setup 与 Onboard

初始化和引导命令：

# 初始化配置和工作区
openclaw setup
# 交互式引导向导
openclaw onboard
# 非交互模式
openclaw setup --non-interactive
# 远程模式
openclaw setup --mode remote --remote-url wss://gateway.example.com

13. 实战场景示例

13.1 场景一：从零搭建 OpenClaw 服务

以下是一个完整的从零搭建流程，展示了如何使用 CLI 命令快速部署：

#!/bin/bash
# OpenClaw 快速部署脚本
# 1. 安装 OpenClaw
npm install -g @openclaw/cli
# 2. 初始化配置
openclaw setup --modelocal
# 3. 配置模型 API
openclaw config set model.default "gpt-4o-mini"
openclaw config set model.apiKey "${OPENAI_API_KEY}"
# 4. 配置 Telegram 渠道
openclaw channels add --channel telegram --token "${TELEGRAM_BOT_TOKEN}"
# 5. 安装 Gateway 服务
openclaw gateway install
# 6. 启动服务
openclaw gateway start
# 7. 验证状态
openclaw status --all
# 8. 运行诊断
openclaw doctor

上述脚本展示了从安装到启动的完整流程。每个步骤都有对应的 CLI 命令，整个过程可以完全自动化。

13.2 场景二：健康检查与告警脚本

以下脚本展示了如何使用 CLI 构建健康监控系统：

#!/bin/bash
# OpenClaw 健康检查脚本
# 检查 Gateway 是否运行
GATEWAY_STATUS=$(openclaw gateway status --json 2>/dev/null | jq -r '.status')
if [ "$GATEWAY_STATUS" != "running" ]; then
  echo "Gateway not running, attempting to start..."
  openclaw gateway start
  sleep 5
  # 再次检查
  GATEWAY_STATUS=$(openclaw gateway status --json 2>/dev/null | jq -r '.status')
  if [ "$GATEWAY_STATUS" != "running" ]; then
    echo "Failed to start Gateway"
    # 发送告警通知
    openclaw nodes notify --node node_001 --title "OpenClaw Alert" --body "Gateway 启动失败"
    exit 1
  fi
fi
# 检查渠道状态
CHANNEL_ERRORS=$(openclaw status --deep --json 2>/dev/null | jq '[.channels[] | select(.status != "ok")] | length')
if [ "$CHANNEL_ERRORS" -gt 0 ]; then
  echo "Channel errors detected: $CHANNEL_ERRORS"
  openclaw nodes notify --node node_001 --title "OpenClaw Alert" --body "检测到 $CHANNEL_ERRORS 个渠道异常"
fi
# 检查错误日志
ERROR_COUNT=$(openclaw logs --level error --limit 1000 2>/dev/null | grep -c "error")
if [ "$ERROR_COUNT" -gt 10 ]; then
  echo "High error rate: $ERROR_COUNT errors"
fi
# 清理过期会话
openclaw sessions cleanup
echo "Health check completed at $(date)"

这个脚本展示了如何组合使用多个 CLI 命令构建完整的健康检查流程：检查服务状态、监控渠道健康、统计错误日志、清理过期数据，并在异常时发送通知。

13.3 场景三：多环境配置管理

使用 Profile 功能管理多个环境：

# 开发环境
openclaw --profile dev config set gateway.port 19001
openclaw --profile dev config set model.default "gpt-4o-mini"
openclaw --profile dev gateway run
# 生产环境
openclaw --profile prod config set gateway.port 18789
openclaw --profile prod config set model.default "gpt-4o"
openclaw --profile prod gateway start
# 测试环境
openclaw --profile test config set gateway.port 19002
openclaw --profile test gateway run

每个 Profile 都有独立的配置目录（~/.openclaw-<name>），可以轻松切换不同环境。

14. 命令速查表

以下是 OpenClaw CLI 的常用命令速查表，方便快速查阅：

故障排查：doctor, logs, doctor --fix 扩展管理：skills list, skills info, nodes status 会话管理：sessions, sessions cleanup 配置管理：config get, config set, configure 日常运维：gateway status, status, logs --follow

15. 常见问题与解决方案

15.1 Gateway 启动失败

问题：执行 openclaw gateway start 时报错

排查步骤：

# 1. 检查端口是否被占用
lsof -i :18789
# 2. 运行诊断
openclaw doctor
# 3. 查看详细错误
openclaw gateway run --verbose
# 4. 强制启动
openclaw gateway run --force

常见原因与解决：

• 端口被占用：使用 --force 参数或修改端口
• 配置文件错误：运行 openclaw doctor 检查
• 权限不足：检查文件权限或使用 sudo

15.2 模型 API 连接失败

问题：Agent 无法响应，日志显示 API 连接错误

排查步骤：

# 检查 API 配置
openclaw config get model
# 测试网络连接
curl -I https://api.openai.com
# 检查诊断结果
openclaw doctor --check network

解决方案：

• 确认 API Key 正确且未过期
• 检查网络是否能访问模型 API
• 如需代理，配置 HTTP_PROXY 环境变量

15.3 技能加载失败

问题：某个技能显示 error 状态

排查步骤：

# 查看技能状态
openclaw skills check
# 查看相关日志
openclaw logs --grep "skill"

解决方案：

• 检查 SKILL.md 语法
• 确认依赖项已安装
• 查看错误日志定位具体问题

15.4 渠道连接问题

问题：消息渠道无法正常工作

排查步骤：

# 深度检查渠道状态
openclaw status --deep
# 查看渠道日志
openclaw channels logs --channel telegram
# 重新登录渠道
openclaw channels login --channel whatsapp

16. 总结

本文全面介绍了 OpenClaw CLI 的各项命令和使用方法，从基础的安装验证到高级的自动化脚本，覆盖了日常运维的各个方面。以下是核心要点的回顾：

1. 命令体系：OpenClaw CLI 采用层级化命令结构，主命令下设 gateway、status、config、sessions、skills、nodes、logs、doctor、channels、models、agents 等子命令，每个子命令又支持多个操作和选项。这种设计既保证了命令的清晰组织，又提供了足够的灵活性。

2. 网关管理：Gateway 是 OpenClaw 的核心服务，通过 gateway 命令可以实现启停、重启、状态查询等完整生命周期管理。支持前台运行（开发调试）和系统服务模式（生产部署），熟练掌握这些命令是运维的基础。

3. 配置与诊断：config 命令提供了配置管理能力，支持点号路径访问嵌套配置。doctor 命令则能自动诊断系统问题并提供修复建议。两者结合使用，可以快速定位和解决大部分配置问题。

4. 扩展能力：Skills 和 Nodes 系统是 OpenClaw 的核心扩展机制。通过 skills 命令可以管理技能，通过 nodes 命令可以控制远程设备，实现功能的无限扩展。节点系统支持摄像头、屏幕录制、位置获取等丰富功能。

5. 运维效率：通过命令组合、脚本自动化和 Profile 配置，可以大幅提升运维效率。OpenClaw CLI 的设计充分考虑了与其他 Unix 工具的配合，使得集成到现有运维体系变得简单。

思考题：

1. 在你的实际场景中，哪些命令会最频繁使用？如何为它们设计更高效的 Shell 别名？
2. 如果要将 OpenClaw 集成到现有的监控告警系统中（如 Prometheus/Grafana），你会如何设计健康检查脚本？
3. 当系统出现异常时，你会按照什么顺序使用 CLI 命令进行排查？如何构建一个自动化的故障恢复流程？

参考资料

• OpenClaw 官方文档
• OpenClaw CLI 文档
• OpenClaw GitHub 仓库
• Node.js 官方文档
• jq 命令手册