OpenClaw CLI 完整命令手册

七夜zippoe2026-03-20 11:32

目 录

    • 摘要
    • [1. 引言](#1. 引言)
    • [2. OpenClaw CLI 概述与安装验证](#2. OpenClaw CLI 概述与安装验证)
      • [2.1 什么是 OpenClaw CLI](#2.1 什么是 OpenClaw CLI)
      • [2.2 安装与环境要求](#2.2 安装与环境要求)
      • [2.3 验证安装](#2.3 验证安装)
    • [3. 命令结构总览](#3. 命令结构总览)
      • [3.1 层级命令体系](#3.1 层级命令体系)
      • [3.2 全局选项](#3.2 全局选项)
    • [4. Gateway 网关命令](#4. Gateway 网关命令)
      • [4.1 Gateway 概述](#4.1 Gateway 概述)
      • [4.2 Gateway 子命令一览](#4.2 Gateway 子命令一览)
      • [4.3 启动网关](#4.3 启动网关)
      • [4.4 停止与重启](#4.4 停止与重启)
      • [4.5 Gateway 运行流程](#4.5 Gateway 运行流程)
    • [5. Status 状态命令](#5. Status 状态命令)
      • [5.1 系统状态概览](#5.1 系统状态概览)
      • [5.2 详细状态选项](#5.2 详细状态选项)
      • [5.3 Status 命令参数](#5.3 Status 命令参数)
    • [6. Config 配置管理命令](#6. Config 配置管理命令)
      • [6.1 配置文件结构](#6.1 配置文件结构)
      • [6.2 配置管理命令](#6.2 配置管理命令)
      • [6.3 Config 命令详解](#6.3 Config 命令详解)
    • [7. Sessions 会话控制命令](#7. Sessions 会话控制命令)
      • [7.1 会话概念](#7.1 会话概念)
      • [7.2 会话管理命令](#7.2 会话管理命令)
      • [7.3 Sessions 命令参数](#7.3 Sessions 命令参数)
    • [8. Skills 技能系统命令](#8. Skills 技能系统命令)
      • [8.1 Skill 系统概述](#8.1 Skill 系统概述)
      • [8.2 技能管理命令](#8.2 技能管理命令)
      • [8.3 技能开发流程](#8.3 技能开发流程)
    • [9. Nodes 节点管理命令](#9. Nodes 节点管理命令)
      • [9.1 节点系统介绍](#9.1 节点系统介绍)
      • [9.2 节点管理命令](#9.2 节点管理命令)
      • [9.3 节点高级功能](#9.3 节点高级功能)
      • [9.4 Nodes 子命令一览](#9.4 Nodes 子命令一览)
    • [10. Logs 日志查看命令](#10. Logs 日志查看命令)
      • [10.1 日志系统概述](#10.1 日志系统概述)
      • [10.2 日志查看命令](#10.2 日志查看命令)
      • [10.3 Logs 命令参数](#10.3 Logs 命令参数)
    • [11. Doctor 诊断工具命令](#11. Doctor 诊断工具命令)
      • [11.1 Doctor 功能介绍](#11.1 Doctor 功能介绍)
      • [11.2 诊断命令使用](#11.2 诊断命令使用)
      • [11.3 Doctor 检查项](#11.3 Doctor 检查项)
      • [11.4 Doctor 参数说明](#11.4 Doctor 参数说明)
    • [12. 其他重要命令](#12. 其他重要命令)
      • [12.1 Channels 渠道管理](#12.1 Channels 渠道管理)
      • [12.2 Models 模型管理](#12.2 Models 模型管理)
      • [12.3 Agents 代理管理](#12.3 Agents 代理管理)
      • [12.4 Setup 与 Onboard](#12.4 Setup 与 Onboard)
    • [13. 实战场景示例](#13. 实战场景示例)
      • [13.1 场景一：从零搭建 OpenClaw 服务](#13.1 场景一：从零搭建 OpenClaw 服务)
      • [13.2 场景二：健康检查与告警脚本](#13.2 场景二：健康检查与告警脚本)
      • [13.3 场景三：多环境配置管理](#13.3 场景三：多环境配置管理)
    • [14. 命令速查表](#14. 命令速查表)
    • [15. 常见问题与解决方案](#15. 常见问题与解决方案)
      • [15.1 Gateway 启动失败](#15.1 Gateway 启动失败)
      • [15.2 模型 API 连接失败](#15.2 模型 API 连接失败)
      • [15.3 技能加载失败](#15.3 技能加载失败)
      • [15.4 渠道连接问题](#15.4 渠道连接问题)
    • [16. 总结](#16. 总结)
    • 参考资料

摘要

本文是 OpenClaw 命令行工具的完整参考手册，系统性地介绍了 OpenClaw CLI 的全部命令及其使用方法。文章从安装验证开始，逐步深入讲解 Gateway 网关管理、Status 状态查询、Config 配置管理、Sessions 会话控制、Skills 技能系统、Nodes 节点管理、Logs 日志查看、Doctor 诊断工具等核心命令。通过丰富的代码示例、流程图和实战场景，帮助开发者快速掌握 OpenClaw 的运维管理技能。无论你是初次接触 OpenClaw 的新手，还是需要深入定制的高级用户，本文都将是你不可或缺的案头参考。

1. 引言

在现代 AI Agent 开发领域，命令行工具扮演着至关重要的角色。一个设计良好的 CLI 不仅能提升开发效率，还能让运维管理变得更加轻松。OpenClaw 作为新一代 AI Agent 框架，提供了一套功能完备、设计优雅的命令行工具，覆盖了从安装部署到日常运维的全生命周期管理。

OpenClaw CLI 的设计理念是"简单的事情简单做，复杂的事情也能做"。对于日常操作，一条命令即可完成；对于高级需求，丰富的参数选项提供了足够的灵活性。这种设计使得新手能够快速上手，同时不限制高级用户的定制需求。

本文将按照由浅入深的顺序，全面介绍 OpenClaw CLI 的各项功能。每个命令都配有详细的参数说明、使用示例和注意事项，确保读者能够真正理解并应用到实际工作中。

2. OpenClaw CLI 概述与安装验证

2.1 什么是 OpenClaw CLI

OpenClaw CLI（Command Line Interface）是 OpenClaw 框架的官方命令行管理工具。它提供了对 OpenClaw 系统的全生命周期管理能力，包括服务启停、配置管理、会话监控、技能管理、节点控制等功能。

作为一个本地自托管的 AI Agent 框架，OpenClaw 强调用户对系统的完全控制权。CLI 正是这种理念的体现------所有操作都在本地执行，数据不离开你的服务器，隐私和安全完全掌握在自己手中。

2.2 安装与环境要求

在开始使用 OpenClaw CLI 之前，需要确保系统满足以下环境要求：

环境要求 最低配置 推荐配置
操作系统 Linux / macOS / Windows WSL Linux (Ubuntu 22.04+)
Node.js v18.0.0+ v22.0.0+ LTS
内存 2GB 4GB+
磁盘空间 1GB 5GB+
网络 能访问 AI 模型 API 稳定的网络连接

安装 OpenClaw 非常简单，只需一条 npm 命令：

bash 复制代码 
# 全局安装 OpenClaw
npm install -g @openclaw/cli

# 或者使用 yarn
yarn global add @openclaw/cli

# 或者使用 pnpm
pnpm add -g @openclaw/cli

# 验证安装
openclaw --version
# 输出: 🦞 OpenClaw 2026.2.26

上述安装命令会将 OpenClaw CLI 安装到全局环境，使其可以在任意目录下直接调用。安装过程会自动处理依赖关系，包括核心运行时、工具链和必要的系统组件。

2.3 验证安装

安装完成后，首先需要验证安装是否成功。OpenClaw CLI 提供了多种方式来确认安装状态：

bash 复制代码 
# 查看版本信息
openclaw --version
# 输出示例：
# 🦞 OpenClaw 2026.2.26 (unknown) --- Gateway online

# 查看帮助信息
openclaw --help
# 输出所有可用命令和全局选项

# 查看详细系统信息
openclaw doctor
# 执行系统诊断，检查所有依赖项

版本命令会显示 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
list
status
invoke
camera
screen

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

3.2 全局选项

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

选项 说明
--dev 开发模式：使用 ~/.openclaw-dev 目录隔离状态，默认端口 19001
-h, --help 显示命令帮助信息
--log-level <level> 日志级别覆盖（silent/fatal/error/warn/info/debug/trace）
--no-color 禁用彩色输出
--profile <name> 使用命名配置文件（隔离状态目录）
-V, --version 显示版本信息

全局选项的使用示例：

bash 复制代码 
# 开发模式启动 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 子命令一览

子命令 说明
run 前台运行 Gateway（开发调试用）
start 启动 Gateway 服务（systemd/launchd）
stop 停止 Gateway 服务
restart 重启 Gateway 服务
status 查看服务状态和可达性
health 获取 Gateway 健康状态
install 安装 Gateway 系统服务
uninstall 卸载 Gateway 系统服务
discover 通过 Bonjour 发现 Gateway
probe 显示 Gateway 可达性和发现状态
call 直接调用 Gateway RPC 方法
usage-cost 获取使用成本统计

4.3 启动网关

bash 复制代码 
# 前台运行（开发调试）
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

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

参数 说明 默认值
--port <port> 监听端口 18789（开发模式 19001）
--auth <mode> 认证模式（none/token/password/trusted-proxy） token
--token <token> 认证令牌 环境变量 OPENCLAW_GATEWAY_TOKEN
--bind <mode> 绑定模式（loopback/lan/tailnet/auto/custom） loopback
--force 强制启动，杀死占用端口的进程 false
--verbose 详细日志输出 false
--tailscale <mode> Tailscale 暴露模式（off/serve/funnel） off

4.4 停止与重启

bash 复制代码 
# 停止网关服务
openclaw gateway stop

# 重启网关服务
openclaw gateway restart

# 查看服务状态
openclaw gateway status

4.5 Gateway 运行流程

Channels 配置文件 Gateway 服务 OpenClaw CLI 用户 Channels 配置文件 Gateway 服务 OpenClaw CLI 用户 alt [端口被占用- ] openclaw gateway run 加载配置 配置数据 检查端口占用 --force? 杀死进程 启动 Gateway 初始化消息渠道 渠道就绪 加载 Skills 启动成功 Gateway online on ws://127.0.0.1:18789

上述时序图展示了 Gateway 启动的完整流程。CLI 首先加载配置，检查端口占用情况，然后启动 Gateway 服务并初始化消息渠道和技能系统。

5. Status 状态命令

5.1 系统状态概览

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

bash 复制代码 
# 查看系统状态
openclaw status

# 输出示例：
# Gateway: online
# Channels: telegram ✓, feishu ✓, discord ✗
# Sessions: 3 active
# Model: gpt-4o-mini (default)

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

5.2 详细状态选项

bash 复制代码 
# 完整诊断（只读，可粘贴分享）
openclaw status --all

# 深度探测消息渠道
openclaw status --deep

# 显示模型使用配额
openclaw status --usage

# 以 JSON 格式输出
openclaw status --json

# 设置探测超时
openclaw status --deep --timeout 5000

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

bash 复制代码 
# 获取 Gateway 状态
openclaw status --json | jq '.gateway.status'

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

5.3 Status 命令参数

参数 说明
--all 完整诊断输出（只读，便于分享）
--deep 深度探测消息渠道（WhatsApp/Telegram/Discord/Slack/Signal）
--json JSON 格式输出
--timeout <ms> 探测超时时间（毫秒）
--usage 显示模型提供商使用配额
--verbose 详细日志

6. Config 配置管理命令

6.1 配置文件结构

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

yaml 复制代码 
# OpenClaw 配置文件示例
{
  "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 配置管理命令

bash 复制代码 
# 交互式配置向导
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 命令详解

命令 说明 示例
config get <path> 获取配置值 openclaw config get gateway.port
config set <path> <value> 设置配置值 openclaw config set gateway.port 19000
config unset <path> 删除配置值 openclaw config unset channels.discord

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

bash 复制代码 
# 点号语法
openclaw config get gateway.port

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

7. Sessions 会话控制命令

7.1 会话概念

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

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

7.2 会话管理命令

bash 复制代码 
# 列出所有会话
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 命令参数

参数 说明
--active <minutes> 仅显示最近 N 分钟内更新的会话
--agent <id> 指定 Agent ID
--all-agents 聚合所有 Agent 的会话
--json JSON 格式输出
--store <path> 指定会话存储路径
--verbose 详细日志

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

8. Skills 技能系统命令

8.1 Skill 系统概述

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

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

8.2 技能管理命令

bash 复制代码 
# 列出已安装技能
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 技能开发流程

否
是
创建技能目录
编写 SKILL.md
实现工具函数
本地测试
测试通过?
验证配置
部署使用

上述流程图展示了技能开发的完整流程：从创建目录到部署使用，每个环节都有对应的 CLI 命令支持。

9. Nodes 节点管理命令

9.1 节点系统介绍

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

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

9.2 节点管理命令

bash 复制代码 
# 列出节点状态
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 节点高级功能

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

bash 复制代码 
# 拍照
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 子命令一览

子命令 说明
status 列出节点状态和能力
list 列出待审批和已配对节点
pending 列出待审批配对请求
approve 批准配对请求
reject 拒绝配对请求
describe 查看节点详情
rename 重命名节点
notify 发送本地通知
camera 摄像头操作
screen 屏幕录制
location 获取位置
run 执行命令（仅 Mac）
invoke 调用节点命令

10. Logs 日志查看命令

10.1 日志系统概述

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

10.2 日志查看命令

bash 复制代码 
# 查看最新日志
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 命令参数

参数 说明 默认值
--follow 实时跟踪日志 false
--interval <ms> 轮询间隔 1000
--json JSON 格式输出 false
--limit <n> 最大行数 200
--local-time 显示本地时间 false
--max-bytes <n> 最大字节数 250000
--no-color 禁用颜色 false
--plain 纯文本输出 false
--timeout <ms> 超时时间 30000
--token <token> Gateway 令牌 -
--url <url> Gateway WebSocket URL -

11. Doctor 诊断工具命令

11.1 Doctor 功能介绍

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

11.2 诊断命令使用

bash 复制代码 
# 运行完整诊断
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 检查项

检查项 说明
Node.js 版本 是否满足最低要求
CLI 版本 是否为最新版本
配置文件 语法是否正确，必填项是否完整
Gateway 状态 是否正常运行
模型 API 是否能正常连接和调用
渠道配置 各消息渠道是否正确配置
技能状态 是否有加载失败的技能
系统服务 是否有多个 Gateway 安装

11.4 Doctor 参数说明

参数 说明
--deep 深度扫描系统服务
--fix 自动修复问题
--force 强制修复（覆盖自定义配置）
--generate-gateway-token 生成并配置 Gateway 令牌
--non-interactive 非交互模式
--no-workspace-suggestions 禁用工作区建议
--yes 接受默认值

12. 其他重要命令

12.1 Channels 渠道管理

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

bash 复制代码 
# 列出已配置渠道
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 模型配置：

bash 复制代码 
# 列出可用模型
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 实例：

bash 复制代码 
# 列出已配置 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

初始化和引导命令：

bash 复制代码 
# 初始化配置和工作区
openclaw setup

# 交互式引导向导
openclaw onboard

# 非交互模式
openclaw setup --non-interactive

# 远程模式
openclaw setup --mode remote --remote-url wss://gateway.example.com

13. 实战场景示例

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

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

bash 复制代码 
#!/bin/bash
# OpenClaw 快速部署脚本

# 1. 安装 OpenClaw
npm install -g @openclaw/cli

# 2. 初始化配置
openclaw setup --mode local

# 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 构建健康监控系统：

bash 复制代码 
#!/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 功能管理多个环境：

bash 复制代码 
# 开发环境
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 的常用命令速查表，方便快速查阅：

命令 说明 示例
openclaw --version 查看版本 openclaw -V
openclaw gateway run 前台运行网关 openclaw gateway run --port 18789
openclaw gateway start 启动网关服务 openclaw gateway start
openclaw gateway stop 停止网关服务 openclaw gateway stop
openclaw gateway status 查看网关状态 openclaw gateway status
openclaw status 查看系统状态 openclaw status --deep
openclaw config get 获取配置值 openclaw config get gateway.port
openclaw config set 设置配置值 openclaw config set gateway.port 19000
openclaw sessions 列出会话 openclaw sessions --active 120
openclaw skills list 列出技能 openclaw skills list
openclaw skills info 查看技能详情 openclaw skills info weather
openclaw nodes status 列出节点状态 openclaw nodes status
openclaw nodes notify 发送通知 openclaw nodes notify --node xxx --title "Hello"
openclaw logs 查看日志 openclaw logs --follow
openclaw doctor 系统诊断 openclaw doctor --fix
openclaw channels list 列出渠道 openclaw channels list
openclaw models status 查看模型状态 openclaw models status

故障排查
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 时报错

排查步骤：

bash 复制代码 
# 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 连接错误

排查步骤：

bash 复制代码 
# 检查 API 配置
openclaw config get model

# 测试网络连接
curl -I https://api.openai.com

# 检查诊断结果
openclaw doctor --check network

解决方案：

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

15.3 技能加载失败

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

排查步骤：

bash 复制代码 
# 查看技能状态
openclaw skills check

# 查看相关日志
openclaw logs --grep "skill"

解决方案：

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

15.4 渠道连接问题

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

排查步骤：

bash 复制代码 
# 深度检查渠道状态
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 命令进行排查？如何构建一个自动化的故障恢复流程？

参考资料

相关推荐
桌面运维家2 小时前
理解 Linux Front Page：构建动态Web首页指南
linux·运维·服务器
旺仔.2912 小时前
死锁 详解
linux·开发语言·计算机网络·安全
季明洵2 小时前
预处理详解（上）
linux·c语言·数据结构·预定义
toooooop82 小时前
linux常用命令nano和vim有啥区别
linux·运维·vim
gallonyin2 小时前
【企业级龙虾】OpenClaw Bash/SH Wrapper 环境变量持久化
openclaw
i建模2 小时前
在Ubuntu中解压ZIP文件
linux·chrome·ubuntu
小赖同学啊2 小时前
飞书集成openclaw
服务器·飞书
BUTCHER52 小时前
Netty Channel 生命周期
java·服务器·网络
说实话起个名字真难啊2 小时前
深入学习openclaw之记忆基础
人工智能·学习·openclaw
热门推荐
01GitHub 镜像站点02Qwen3.5 开源全解析：从 0.8B 到 397B，代际升级 + 全场景选型指南03OpenClaw 使用和管理 MCP 完全指南04Labelme从安装到标注：零基础完整指南05AI 编程三剑客：Spec-Kit、OpenSpec、Superpowers 深度对比与实战指南06UV安装并设置国内源07小黑课堂计算机二级WPSoffice题库软件下载安装教程（2026年3月最新版）08OpenClaw Control UI安全上下文访问配置09Claude Code + GLM4.7 避坑指南：解决 Unable to connect to Anthropic services10让 Trae IDE 智能体 “读懂”文档 Excel+PDF+DOCX ：mcp-documents-reader 工具使用指南