夜雨聆风OpenClaw 常用指令完整参考,从基础操作到进阶CLI技巧
一、 命令行界面（CLI）概览
1.1 CLI 的设计哲学
OpenClaw 的 CLI 是基于 Node.js 构建的，其命令结构遵循非常经典的 POSIX 风格：openclaw <名词> [子命令] [参数]。核心命名规范： 绝大多数顶层资源名词均使用复数形式（如：models, channels, skills, hooks, agents, plugins, sessions）。少数几个核心功能命令才使用单数（如：gateway, doctor, config）。
1.2 全局帮助与版本信息
在任何子命令后追加 --help 或 -h 参数，都可以呼出该命令的详细说明文档：
# 显示所有可用的顶层命令以及简要说明openclaw --help# 深入查看特定模块的子命令说明openclaw gateway --helpopenclaw models --helpopenclaw channels add --help# 查看当前安装的 OpenClaw 版本号（注：没有 `openclaw version` 这个子命令）openclaw --version# 输出示例：2026.2.251.3 全局参数（Flags）
以下参数可以在绝大多数命令中使用，用于控制日志输出或运行环境：
--log-level <level> # 覆盖全局日志级别（silent|fatal|error|warn|info|debug|trace）--no-color # 禁用控制台的 ANSI 颜色输出（非常适合用于 CI/CD 流水线或日志文件重定向）--dev # 启用开发模式：将运行状态隔离到 ~/.openclaw-dev 目录下--profile <name> # 使用指定的配置环境：隔离状态到 ~/.openclaw-<name> 目录下-V, --version # 快速输出版本号-h, --help# 显示帮助信息二、 安装与运行环境管理
2.1 初次安装
OpenClaw 底层依赖 Node.js 生态，实际上是通过 npm install -g openclaw@latest 完成全局安装的。官方提供了针对不同操作系统的快捷安装脚本：
# 【macOS / Linux】使用 curl 下载并执行 bash 脚本curl -fsSL https://openclaw.ai/install.sh | bash# 【Windows PowerShell】使用 iwr 下载并执行iwr -useb https://openclaw.ai/install.ps1 | iex# 【Windows CMD】若遇执行策略限制，可先下载本地再运行curl -fsSL https://openclaw.ai/install.cmd -o install.cmd && install.cmd && del install.cmd安装完毕后，务必执行 doctor 命令来检查运行环境是否健康：
# 自动检测 Gateway 状态、依赖组件、技能包（Skills）等，并输出健康报告openclaw doctor2.2 版本更新
# 默认更新至最新稳定版 (Stable)openclaw update# 切换更新通道（如：beta 测试版 / dev 开发版）openclaw update --channel beta# 指定更新到特定的版本号或 npm dist-tagopenclaw update --tag 2026.2.20# 预览更新内容（Dry run：只显示将要执行的操作，不真正修改系统）openclaw update --dry-run# 非交互式静默更新，并以 JSON 格式输出结果（CI 环境必备）openclaw update --yes --json2.3 卸载与重置环境
# 卸载后台 Gateway 服务并清理本地数据（保留 CLI 工具本身）openclaw uninstall# 彻底卸载，包括所有的配置、状态和 Agent 工作区（非交互式静默执行）openclaw uninstall --all --yes# 恢复出厂设置：仅重置本地配置（保留 CLI 工具和个人数据）openclaw reset --scope config2.4 全局配置管理
OpenClaw 的配置文件默认存放在 ~/.openclaw/openclaw.json（支持注释和尾逗号的 JSON5 格式）。你可以通过 CLI 直接修改：
# 获取特定配置的值（支持 dot-path 语法读取嵌套 JSON）openclaw config get gateway.port# 输出示例：18789# 修改配置项：更改 Gateway 监听端口并绑定到本地回环地址openclaw config set gateway.port 18790openclaw config set gateway.bind loopback# 移除某个配置项openclaw config unset gateway.tailscale# 启动交互式的终端配置向导（适合新手）openclaw configure三、 Gateway（网关）管理
3.1 Gateway 概念简述
Gateway 是 OpenClaw 架构中的核心前后端通信枢纽（基于 WebSocket 开发）。默认在 ws://127.0.0.1:18789 运行，负责接收来自各大聊天渠道（Channels）的消息，管理 Agent 的会话状态，并调度各类 Skills。
3.2 启动与运行参数
# 在前台挂起运行 Gateway（按 Ctrl+C 终止）openclaw gateway# 指定启动端口与网络绑定模式 (loopback|lan|tailnet|auto|custom)openclaw gateway --port 18790 --bind lan# 强制启动：如果遇到 EADDRINUSE (端口被占用) 错误，会自动尝试杀掉占用该端口的进程openclaw gateway --force# 开启网关鉴权模式（增强安全性）openclaw gateway --auth token --token "your-secret-token"# 开启详细的调试日志（排查 WebSocket 连接问题时非常有用）openclaw gateway --verbose3.3 后台服务持久化
# 将 Gateway 安装为系统级后台服务 (兼容 launchd/systemd/schtasks)# 注意：Windows 下依赖 schtasks，必须以管理员权限运行终端！openclaw gateway install# 服务生命周期管理openclaw gateway start # 启动服务openclaw gateway stop # 停止服务openclaw gateway restart # 重启服务# 查看服务运行状态及探针检测结果openclaw gateway status3.4 日志监控
# 通过 RPC 获取 Gateway 的实时日志openclaw logs# 类似 tail -f，实时追踪滚动日志openclaw logs --follow# 仅输出最新的 100 行日志，并转换为本地时间显示openclaw logs --limit 100 --local-time四、 大语言模型（Models）配置
4.1 罗列与查看
# 列出当前已配置的所有大语言模型openclaw models list# 查看当前默认模型、别名映射及整体状态openclaw models status4.2 设置默认模型
# 设置默认的文本处理模型（可以使用完整的模型 ID 或简写别名）openclaw models set qwen-portal/coder-model# 设置默认的视觉/图像处理模型openclaw models set-image qwen-portal/vision-model4.3 鉴权与 API Token 管理
# 启动交互式向导，引导你选择云服务商并配置 API Keyopenclaw models auth add# 直接粘贴 Token 快速配置（设置有效期为 30 天）openclaw models auth paste-token --profile-id qwen --expires-in 30d五、 通信渠道（Channels）接入
5.1 渠道支持概况
截至 2026.2.25 版本，OpenClaw 已支持 20+ 种主流通信平台的接入，包括：Telegram, Discord, Slack, WhatsApp, 飞书 (Feishu) 等。
5.2 接入示例
# 接入 Telegram Bot（需要提供从 BotFather 获取的 Token）openclaw channels add --channel telegram --token "123456:ABC..."# 接入 Discord Botopenclaw channels add --channel discord --token "MTIz..."# 接入 WhatsApp（终端会渲染出 QR 二维码，需使用手机扫码登录）openclaw channels login --channel whatsapp5.3 渠道管理
# 查看所有已接入的 Channels 列表openclaw channels list# 主动探测并查看各个渠道的网络连通性健康状态openclaw channels status --probe# 移除特定渠道的绑定openclaw channels remove --channel telegram六、 技能（Skills）系统扩展
6.1 Skills 概念说明
Skills 是赋予 AI Agent 实际操作能力的扩展机制。类似于给 AI 安装了“双手”，让它能执行代码、读写文件、操作外部 API 等。
6.2 检查与管理
# 列出系统中所有的可用技能包openclaw skills list# 系统级环境检测：检查哪些技能缺少必要的系统依赖（如缺少某些 CLI 工具）openclaw skills check# 输出示例：# ✓ Eligible: 13 (环境就绪的技能)# ✗ Missing requirements: 39 (缺失依赖的技能)# 查看特定技能（如代码代理）的详细说明和使用方法openclaw skills info coding-agent七、 钩子（Hooks）与插件（Plugins）
7.1 事件驱动的 Hooks
Hooks 允许你在 OpenClaw 的特定生命周期事件触发时，自动执行回调任务（例如：新建会话时自动保存上下文）。
# 查看当前加载的 Hooksopenclaw hooks list# 启用或禁用特定的 Hookopenclaw hooks enable session-memoryopenclaw hooks disablecommand-logger# 从本地路径或 npm 仓库安装自定义 Hookopenclaw hooks install ./my-hook-pack7.2 插件（Plugins）管理
Plugins 提供了比 Hooks 更底层的框架扩展能力。
openclaw plugins list # 列出插件openclaw plugins install <name> # 安装插件openclaw plugins doctor # 诊断插件加载过程中的依赖冲突问题八、 智能代理（Agents）配置
8.1 隔离执行环境
OpenClaw 默认提供一个 main Agent。通过创建多个 Agent，你可以为不同的任务配置隔离的工作区（Workspace）、特定的权限和路由分发规则。
# 列出系统中配置的 Agentsopenclaw agents list# 新增一个名为 "work" 的专属 Agentopenclaw agents add work# 为 Agent 赋予个性化设定（名字、系统提示词基调等）openclaw agents set-identity work --name "Work Bot"九、 诊断与高级调试
在复杂的全栈运行环境中，难免会遇到网络、端口或依赖问题。以下命令是开发者必备的排障工具：
# 运行环境全身体检（强烈建议遇到问题时第一步运行此命令）openclaw doctor# 尝试让程序自动修复发现的常规问题openclaw doctor --fix# 本地配置文件的安全审计（检测是否泄露明文 Token 等）openclaw security audit# 搜索 AI 的本地记忆（Memory）数据库openclaw memory search --query "deployment notes"# 强制重建记忆库索引openclaw memory index --force# 在终端内开启 TUI（文本用户界面），直观监控系统指标openclaw tui# 唤起默认浏览器，打开可视化的控制台 Dashboardopenclaw dashboard十、 常见问题排坑指南 (FAQ)
1. 为什么经常报 unknown command 错误？
原因： 极大概率是忘记了 OpenClaw 的“资源复数命名”规范。
# ❌ 错误演示 (单数形式将报错)openclaw model listopenclaw channel list# ✅ 正确姿势 (使用复数)openclaw models listopenclaw channels list2. Gateway 启动失败，提示 bind: address already in use (EADDRINUSE)
原因： 默认的 18789 端口已被其他后台僵尸进程占用。解决方案：
# 方案 A：让 OpenClaw 自己清理占用端口的进程openclaw gateway --force# 方案 B：更换监听端口openclaw config set gateway.port 187903. 核心数据都在哪里？（全栈开发者的本地溯源）
全局配置文件： ~/.openclaw/openclaw.json主工作区数据： ~/.openclaw/agents/main/后台日志文件： Linux/macOS 在 /tmp/openclaw/；Windows 在\tmp\openclaw\
结语
熟练掌握 CLI 工具链，是提升开发和运维效率的关键。日常使用中，你只需牢记四大核心命令：openclaw doctor（健康检查）、openclaw gateway（服务管理）、openclaw models status（模型状态）、openclaw channels list（通信渠道）。 在遇到未知的配置需求时，随时在终端敲下 --help，它永远是你最可靠的开发助手。
