上篇回顾

上一篇 〖OpenClaw系列〗日志系统与调试技巧，我们深入介绍了 OpenClaw 的日志系统。你学会了用 openclaw logs 查看日志、设置日志级别、以及用日志排查 Gateway 启动失败、消息发送失败等常见问题。

日志排查只是 CLI 的一部分功能。OpenClaw 提供了 30+ 个命令，覆盖安装配置、Gateway 管理、渠道接入、会话管理等全流程。这篇是 CLI 的完全手册，适合放在手边随时查阅。

本文定位：CLI 命令的完整参考。读完这篇，你能熟练使用所有常用命令，理解命令结构和选项，编写自动化脚本。

一、CLI 概览

设计哲学

OpenClaw CLI 遵循几个设计原则：

1. 一致性：所有命令遵循 openclaw <command> <subcommand> [options] 结构
2. 自描述：每个命令都有 --help，无需查文档
3. 交互友好：向导式配置（setup/configure/onboard），降低入门门槛
4. 脚本友好：支持 --non-interactive 和 --json 输出，便于自动化

命令结构

这张图展示了 CLI 的命令结构。从左到右：基础命令 → 命令 → 子命令 → 选项/参数。

openclaw -v debug gateway start --bind 0.0.0.0 --port 8080
│       │    │       │      │      │            │
│       │    │       │      │      └─ 选项      └─ 选项
│       │    │       │      └─ 子命令
│       │    │       └─ 命令
│       │    └─ 全局选项
│       └─ 全局选项
└─ 基础命令

二、命令分类速查

OpenClaw 有 30+ 个命令，分为 7 大类：

这张图展示了所有命令的分类。7个彩色区域代表 7 大功能类别，每个区域列出了该类别的常用命令。

三、核心命令详解

第一类：安装与配置（Setup & Config）

openclaw setup

初始化 OpenClaw 环境，创建配置文件和工作区。

# 交互式初始化
openclaw setup

# 非交互式（使用默认值）
openclaw setup --non-interactive

执行内容：

• 创建 ~/.openclaw/ 目录
• 生成初始 openclaw.json
• 初始化 Agent 工作区

openclaw onboard

交互式引导，一站式配置 Gateway、渠道、Agent。

openclaw onboard
# 按提示完成 5 步配置

openclaw configure

交互式配置特定组件。

openclaw configure
# 选择：credentials / channels / gateway / agent

openclaw config

非交互式配置操作（适合脚本）。

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

# 设置配置值
openclaw config set gateway.port 8080
openclaw config set agents.defaults.model "anthropic/claude-sonnet-4-6"

# 删除配置项
openclaw config unset gateway.auth.password

# 验证配置语法
openclaw config validate

# 查看配置文件路径和内容
openclaw config file

openclaw doctor

健康检查与自动修复。

# 基本检查
openclaw doctor

# 检查并尝试修复
openclaw doctor --fix

# 非交互模式
openclaw doctor --non-interactive --fix

第二类：Gateway 管理

openclaw gateway

管理 Gateway 服务的生命周期。

# 启动 Gateway（前台运行）
openclaw gateway start

# 后台运行（使用 systemd/launchd）
openclaw gateway start --daemon

# 停止 Gateway
openclaw gateway stop

# 查看状态
openclaw gateway status

# 重启
openclaw gateway restart

# 热重载配置（不重启服务）
openclaw gateway reload

openclaw dashboard

在浏览器中打开 Control UI。

openclaw dashboard
# 自动打开 http://localhost:18789 并携带认证 token

openclaw health

检查 Gateway 健康状态。

openclaw health
# 输出：Gateway is healthy (v2.1.0)

第三类：渠道管理

openclaw channels

管理消息渠道（Telegram、WhatsApp 等）。

# 列出所有渠道
openclaw channels list

# 添加渠道
openclaw channels add telegram --bot-token "${BOT_TOKEN}"

# 移除渠道
openclaw channels remove telegram

# 查看渠道状态
openclaw channels status

openclaw pairing

管理 DM（私信）配对。

# 列出配对请求
openclaw pairing list

# 接受配对
openclaw pairing accept <peer-id>

# 拒绝配对
openclaw pairing reject <peer-id>

第四类：Agent 与会话

openclaw agents

管理多 Agent。

# 列出 Agent
openclaw agents list

# 创建新 Agent
openclaw agents create --id my-agent --model "anthropic/claude-sonnet-4-6"

# 删除 Agent
openclaw agents delete my-agent

# 切换默认 Agent
openclaw agents default my-agent

openclaw sessions

管理会话。

# 列出所有会话
openclaw sessions list

# 查看会话详情
openclaw sessions show <session-id>

# 清理会话
openclaw sessions clear <session-id>
# 或清理所有
openclaw sessions clear --all

# 导出会话
openclaw sessions export <session-id> --format json

openclaw message

发送消息（用于测试）。

# 发送测试消息
openclaw message send --channel telegram --to <peer-id> --text "Hello"

第五类：工具与技能

openclaw skills

管理 Skill。

# 列出已安装 Skill
openclaw skills list

# 启用 Skill
openclaw skills enable <skill-name>

# 禁用 Skill
openclaw skills disable <skill-name>

# 从 ClawHub 安装
openclaw skills install <skill-id>

openclaw browser

管理浏览器（用于浏览器自动化）。

# 检查浏览器状态
openclaw browser status

# 安装/更新浏览器
openclaw browser install

# 启动浏览器（调试用）
openclaw browser launch

openclaw cron

管理定时任务。

# 列出定时任务
openclaw cron list

# 添加任务
openclaw cron add --name "daily-report" --schedule "0 9 * * *" --command"agent run generate-report"

# 删除任务
openclaw cron remove <task-id>

第六类：数据与日志

openclaw logs

查看日志（详见第8篇）。

openclaw logs
openclaw logs --follow
openclaw logs --limit 100
openclaw logs --since 1h

openclaw memory

搜索和重建记忆索引。

# 搜索记忆
openclaw memory search "project requirements"

# 重建索引
openclaw memory reindex

openclaw backup

备份与恢复。

# 创建备份
openclaw backup create

# 列出备份
openclaw backup list

# 恢复备份
openclaw backup restore <backup-id>

# 验证备份完整性
openclaw backup verify <backup-id>

第七类：系统维护

openclaw update

更新 CLI。

# 检查更新
openclaw update check

# 执行更新
openclaw update

# 更新到特定版本
openclaw update --version 2.2.0

openclaw completion

安装 Shell 自动补全。

# Bash
openclaw completion install bash

# Zsh
openclaw completion install zsh

# Fish
openclaw completion install fish

openclaw reset

重置本地状态（保留 CLI 安装）。

# 重置配置
openclaw reset config

# 重置所有数据（危险！）
openclaw reset all --confirm

openclaw uninstall

卸载 Gateway 服务和本地数据。

openclaw uninstall
# CLI 本身保留，需手动 npm uninstall -g @openclaw/cli

四、全局选项

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

使用示例

# 调试模式运行任何命令
openclaw -v debug gateway start

# 使用自定义配置
openclaw -c /path/to/config.json gateway start

# 非交互模式（适合脚本）
openclaw --non-interactive doctor --fix

# JSON 输出（程序解析）
openclaw --json sessions list

五、环境变量大全

OpenClaw 支持以下环境变量：

核心环境变量

Gateway 相关

渠道相关

模型 API Key

使用示例

# 一次性设置环境变量运行
OPENCLAW_LOG_LEVEL=debug OPENCLAW_GATEWAY_TOKEN=abc123 openclaw logs -f

# 或在 .env 文件中配置
export OPENCLAW_STATE_DIR=/custom/path
export ANTHROPIC_API_KEY=sk-ant-...
openclaw gateway start

六、自动化脚本技巧

技巧1：非交互模式

在 CI/CD 或脚本中使用 --non-interactive：

#!/bin/bash
set -e

# 健康检查
openclaw --non-interactive doctor

# 启动 Gateway
openclaw --non-interactive gateway start --daemon

# 等待 Gateway 就绪
sleep 5
openclaw --non-interactive health

技巧2：JSON 输出解析

使用 --json 获取结构化数据：

#!/bin/bash

# 获取会话列表并解析
sessions=$(openclaw --json sessions list)
count=$(echo"$sessions" | jq '.sessions | length')
echo"Active sessions: $count"

# 获取 Gateway 状态
status=$(openclaw --json health)
version=$(echo"$status" | jq -r '.version')
echo"Gateway version: $version"

技巧3：错误处理

#!/bin/bash

# 检查命令是否成功
if ! openclaw gateway status > /dev/null 2>&1; then
echo"Gateway is not running, starting..."
    openclaw gateway start --daemon
fi

# 带重试的检查
for i in {1..5}; do
if openclaw health > /dev/null 2>&1; then
echo"Gateway is healthy"
break
fi
echo"Waiting for Gateway... ($i/5)"
    sleep 2
done

技巧4：批量操作

#!/bin/bash

# 批量清理旧会话
openclaw --json sessions list | \
    jq -r '.sessions[] | select(.lastActive < "2026-01-01") | .id' | \
whileread session_id; do
echo"Clearing $session_id"
        openclaw sessions clear "$session_id"
done

七、常用命令速查表

日常操作

配置管理

故障排查

数据管理

八、踩坑

坑1：命令找不到

现象：command not found: openclaw

解决：

# 检查是否安装
npm list -g @openclaw/cli

# 重新安装
npm install -g @openclaw/cli

# 检查 PATH
echo$PATH
# 确保包含 npm global bin 目录

坑2：权限不足

现象：EACCES: permission denied

解决：

# 不要 sudo 运行 openclaw
# 正确做法：修复 npm 权限
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH=~/.npm-global/bin:$PATH
npm install -g @openclaw/cli

坑3：–non-interactive 仍然提示

现象：加了 --non-interactive 还是有交互提示

解决：

# 某些命令需要额外参数才能完全非交互
openclaw doctor --non-interactive --fix --generate-gateway-token

# 或设置环境变量
export OPENCLAW_NON_INTERACTIVE=1
openclaw doctor --fix

坑4：JSON 输出包含非 JSON 内容

现象：--json 输出解析失败

解决：

# 过滤掉非 JSON 行（如 banner、警告）
openclaw --json sessions list 2>/dev/null | grep "^{"

# 或使用 jq 的 -R 和 fromjson
openclaw --json sessions list | jq -R 'fromjson? // empty'

九、常见问题（FAQ）

Q：如何查看某个命令的详细用法？

A：使用 --help：

openclaw gateway --help
openclaw config set --help

Q：命令缩写/别名有哪些？

A：部分命令支持简写：

openclaw gw start      # gateway start
openclaw cfg get       # config get
openclaw ch list       # channels list
openclaw sk list       # skills list

Q：如何批量执行多个命令？

A：使用脚本或 && 连接：

openclaw gateway stop && openclaw doctor --fix && openclaw gateway start

Q：CLI 配置和环境变量哪个优先级高？

A：优先级从高到低：

1. 命令行选项（如 -v debug）
2. 环境变量（如 OPENCLAW_LOG_LEVEL）
3. 配置文件（openclaw.json）
4. 默认值

Q：如何查看 CLI 版本？

A：

openclaw --version
openclaw -V
openclaw version

Q：Windows 支持吗？

A：支持，但建议用 WSL2 获得最佳体验。部分功能（如 systemd）在原生 Windows 上不可用。

总结

OpenClaw CLI 的 30+ 命令覆盖 7 大类别：

再看两张图：

• 命令分类图（第二章）：7 大类 30+ 命令的全景
• 命令结构图（第一章）：openclaw <cmd> <subcmd> [opts] 的结构

一句话记住：不确定用什么命令？先 openclaw --help，再 openclaw <command> --help。

下一篇预告

〖OpenClaw系列〗从零到一：搭建你的第一个AI助手

前面 9 篇介绍了 OpenClaw 的各个组件。下一篇综合运用这些知识，手把手带你从零搭建一个完整的 AI 助手：从安装到配置，从渠道接入到自定义提示词，最终拥有一个可用的 AI 助手。

本文是系列第9篇，前序文章：

〖OpenClaw系列〗日志系统与调试技巧

〖OpenClaw系列〗openclaw doctor 诊断工具详解

〖OpenClaw系列〗Control UI 与 WebChat 使用指南

〖OpenClaw系列〗Gateway网关深度剖析

📌 觉得有用？点个「在看」 👇 👨‍💻 关注「敏叔侃技术」，每周更新 OpenClaw 实战干货 ⭐ 收藏这篇文章，作为 CLI 命令速查手册