OpenClaw 使用指南:常见命令速查手册

现在养的龙虾多了，经常需要查询一些命令，官方的内容太多了，我就基于官方文档和实际使用经验整理一个简单的版本，方便我需要的时候可以随手查。如果你也需要，可以收藏。

📌 什么是 OpenClaw？

一句话解释：OpenClaw 是一个自己搭建的 AI 助手网关，让你可以在 WhatsApp、飞书、微信、钉钉、Discord 等聊天软件里跟 AI 对话。

为什么叫 "Self-hosted"（自建）？

数据存在你自己的电脑上，不是存在别人的服务器

你自己控制谁能用、怎么用

不用依赖第三方服务，不用担心被封

适合谁用？

开发者、技术爱好者

想要一个随时能用的 AI 助手（手机发消息就能用）

不想把数据交给大厂的人

🚀 快速开始

安装 OpenClaw

需要 Node.js 环境（推荐 Node 24，或 Node 22 LTS 22.14+）：

macOS / Linuxcurl -fsSL https://openclaw.ai/install.sh | bashWindows (PowerShell)iwr -useb https://openclaw.ai/install.ps1 | iex

初始化配置

交互式配置向导 `openclaw onboard` 或者一键安装并设置开机启动 `openclaw onboard --install-daemon`

配置过程中会问你：

用什么 AI 模型（OpenAI、Claude、Kimi、Minimax 等）

API Key 在哪里

要连接哪些聊天频道（WhatsApp、Telegram 等）

启动 Gateway前台运行（看日志） `openclaw gateway run` 或者后台运行 `openclaw gateway start`
打开控制面板

`openclaw dashboard`

或者浏览器访问：http://127.0.0.1:18789/

http://127.0.0.1:18789/

🏗️ 核心概念解释

Gateway（网关）

是什么：OpenClaw 的核心进程，相当于"大脑"

作用：

接收来自各种聊天软件的消息

转发给 AI 处理

把 AI 的回复发回给用户

管理会话、记忆、定时任务

通俗理解：就像一个接线员，把用户的电话转给 AI，再把 AI 的回话转给用户。

Session（会话）

是什么：一次"对话记录"

类型：

Main Session：你跟 OpenClaw 的直接对话

Cron Session：定时任务产生的子会话

Subagent Session：子代理产生的会话

为什么要管 Session：

Session 多了会占用内存

卡住的 Session 可能导致问题

定期清理可以保持系统健康

Agent（代理）

是什么：一个"AI 身份"，有自己的配置、记忆、工具权限

例子：

main：主代理，处理日常对话

main

moss：专门处理 Reddit 商业雷达任务

moss

oracle：专门做商机分析

oracle

多代理的好处：

不同任务用不同代理，互相不干扰

可以给不同代理不同的工具权限

每个代理有自己的记忆和工作空间

Channel（频道）

是什么：消息的来源渠道

支持的频道：

Discord

iMessage

飞书 (Feishu)

微信 (通过插件)

通俗理解：就是你从哪个 App 发消息给 OpenClaw。

Node（节点）

是什么：配对的移动设备（iOS/Android）

功能：

用手机相机拍照传回

手机录语音

手机截屏

手机定位

通俗理解：让 OpenClaw 能"遥控"你的手机，用手机的各种传感器。

🔧 核心命令详解

Gateway 管理

查看状态 `openclaw status`

显示 Gateway 是否运行、绑定的端口、连接的频道、当前会话等。

启动 Gateway `openclaw gateway start`

openclaw gateway restart

后台启动，看不到日志。

前台运行 Gateway `openclaw gateway run`

在终端显示实时日志，适合排查问题。Ctrl+C 停止。

停止 Gateway `openclaw gateway stop`

重启 Gateway（最常用！） `openclaw gateway restart`

💡 遇到任何问题，先试试重启 Gateway

查看 Gateway 绑定地址 `openclaw config get gateway.bind`

`0.0.0.0` 表示监听所有网络接口（局域网可访问）。

0.0.0.0

Session（会话）管理

查看所有会话 `openclaw sessions`

输出示例：

Sessions listed: 6

Kind Key Age Model Tokens

direct agent:main:main 2m ago kimi-code 23k/262k (9%)

direct agent:main:cron:...f36b60 21h ago kimi-code 546k/262k (208%) ❌

关键字段：

Kind：direct = 主会话，cron = 定时任务

direct

cron

Age：最后活跃时间

Tokens：上下文占用率，超过 100% 就是爆了

结束所有子代理会话 `openclaw sessions kill --all-subagents`

彻底清理所有会话（终极方案）

bash

openclaw gateway stop

openclaw gateway start

rm -f ~/.openclaw/agents/main/sessions/*.json

openclaw gateway start

⚠️ 这会清空所有会话历史

Cron（定时任务）

查看所有定时任务 `openclaw cron list`

输出示例：

Jobs:

name: "Reddit商业雷达"

id: 022d9c82-ab48-44f9-a8d5-38bb787e76d7

schedule: "0 10 *" # 每天10点执行

enabled: true # 是否启用

state:

lastRunStatus: "error" # 上次运行状态

lastError: "rate_limit" # 失败原因

nextRunAtMs: 1774922400000 # 下次执行时间

暂停某个任务 `openclaw cron disable `

启用某个任务 `openclaw cron enable `

立即执行某个任务（测试用） `openclaw cron run `

暂停所有任务 `openclaw cron pause`

定时格式说明（Cron 表达式）：

0 10 * → 每天10:00

30 17 * → 每天17:30

0 0 0 → 每周日0:00

0 9 1-5 → 工作日9:00

配置操作

查看当前配置文件路径 `openclaw config file`

输出: `~/.openclaw/openclaw.json`

查看特定配置项

`openclaw config get agents.defaults.model`

`openclaw config get gateway.port`

设置配置项 `openclaw config set agents.defaults.model "minimax/MiniMax-M2.7"`

删除配置项 `openclaw config unset `

验证配置是否正确 `openclaw config validate`

日志查看

查看最近50行日志 `openclaw logs -l 50`

实时跟踪日志（像 tail -f） `openclaw logs --follow`

只看错误 `openclaw logs -l 100 | grep -i error`

日志文件位置 `/tmp/openclaw/openclaw-YYYY-MM-DD.log`

安全审计

`openclaw security audit`

输出安全检查结果：

🔴 CRITICAL：必须立即修复（如未设置允许来源）

🟡 WARN：建议修复（如权限过于开放）

🟢 INFO：参考信息

⚙️ 配置详解

配置文件位置

`~/.openclaw/openclaw.json`

核心配置项

Gateway 配置

json

{

"gateway": {

"port": 18314, // 监听端口

"bind": "lan", // 绑定方式: lan/localhost

"controlUi": {

"allowedOrigins": ["http://192.168.1.100:18314"]

}

模型配置

json

{

"models": {

"providers": {

"kimi-coding": {

"baseUrl": "https://api.kimi.com/coding/",

"apiKey": "sk-xxxx",

"models": [{ "id": "k2p5", "name": "Kimi for Coding" }]

}

"agents": {

"defaults": {

"model": {

"primary": "kimi-coding/k2p5"

}

频道配置（以 Telegram 为例）

json

{

"channels": {

"telegram": {

"enabled": true,

"accounts": {

"main": {

"token": "123456:ABC-DEF...",

"allowFrom": ["@your_username"], // 只允许特定用户

"groups": { "*": { "requireMention": true } // 群里需要@机器人

}

安全配置

json

{

"messages": {

"groupChat": {

"mentionPatterns": ["@openclaw", "@bot"]

}

"tools": {

"exec": {

"security": "full", // 执行命令前询问

"ask": "on"

}

🔍 常见问题与解决

Gateway 启动失败

现象：`openclaw gateway start` 报错

排查：

前台运行看详细错误 `openclaw gateway run`
检查端口占用 `lsof -i :18314`
检查配置文件语法 `openclaw config validate`

openclaw config validate

解决：

端口被占用 → 换端口或杀掉占用进程

配置语法错误 → 用 `openclaw config validate` 检查

API Key 无效 → 检查 `models.providers.xxx.apiKey`

models.providers.xxx.apiKey

"Unexpected event order" 错误

现象：

`error=Unexpected event order, got messagestart before receiving "messagestop"`

原因：AI 模型返回的 SSE 流事件乱序

解决：

重启 Gateway：`openclaw gateway restart`
换用其他模型（如从 Kimi 换成 Minimax）
检查网络（是否走了代理导致包乱序）

Session 卡住 / Token 爆了

现象：Session 显示 `tokens: 546k/262k (208%)`

tokens: 546k/262k (208%)

解决：

结束所有子代理 `openclaw sessions kill --all-subagents`

或彻底清理

bash

openclaw gateway stop

rm -f ~/.openclaw/agents/main/sessions/*.json

openclaw gateway start

定时任务失败 (rate_limit / timeout)

原因：

API 调用太频繁被限流

任务执行超时

网络问题

解决：

等几分钟再试 `openclaw cron run `
检查日志 `openclaw logs -l 50 | grep -i error`

频道连接失败（如 Telegram 无响应）

排查：

`openclaw status # 看 Channels 部分是否显示 "Telegram: OK"`
`openclaw logs -l 100 | grep -i telegram`

常见原因：

Token 无效

网络防火墙阻止

Bot 被禁言

模型列表里没有某个模型

原因：模型没有在 `agents.defaults.models` 中注册

agents.defaults.models

解决：

添加模型到选择列表 `openclaw config set agents.defaults.models.kimi-coding/k2p5 '{"alias": "kimi-k2p5"}'`
重启生效 `openclaw gateway restart`

🛠️ 高级用法

多代理路由

配置不同代理处理不同频道/用户：

json

{

"bindings": [

{

"agentId": "moss",

"match": { "channel": "feishu", "accountId": "moss" }

}

]

}

手机节点配对

在 Control UI 里生成配对码
手机 App 扫码配对

自定义工具（Skills）

OpenClaw 支持扩展功能，比如：

飞书文档操作

微信公众号发布

股票分析

天气查询

安装方式：

从 clawhub 安装 `openclaw skill install xxx`

或手动放到 `~/.openclaw/skills/`

📂 重要文件位置

文件/目录	位置	说明
主配置	`~/.openclaw/openclaw.json`	所有配置都在这里
Sessions	`~/.openclaw/agents/main/sessions/`	会话记录
Cron Jobs	`~/.openclaw/cron/jobs.json`	定时任务配置
日志	`/tmp/openclaw/openclaw-YYYY-MM-DD.log`	运行日志
扩展	`~/.openclaw/extensions/`	插件目录
Skills	`~/.openclaw/skills/`	自定义工具
工作空间	`~/.openclaw/workspace/`	Agent 工作目录

🆘 紧急救援指南

如果 OpenClaw 完全坏了，按这个顺序来：

重启 Gateway `openclaw gateway restart`
清理卡住的 Sessions `openclaw sessions kill --all-subagents`
看日志定位问题 `openclaw logs -l 100 | grep -i error`
验证配置 `openclaw config validate`
还不行？重置配置（谨慎！）

bash

cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.backup

openclaw onboard

终极方案：彻底清理

bash

openclaw gateway stop

rm -rf ~/.openclaw/agents/main/sessions/

openclaw gateway start

附录：

`openclaw onboard`：交互式引导你完成首次安装、配置模型和通道，像新手向导一样一步步设置好整个系统。

`openclaw setup / configure`：快速初始化工作区或调整配置，适合非交互式或重新配置时使用。

`openclaw doctor`：一键诊断系统问题并自动修复，像医生检查AI助手健康状况（加--deep更彻底）。

`openclaw gateway`（或 gateway start/restart/stop）：启动、停止或重启WebSocket网关服务，让AI代理持续在线运行。

`openclaw status / health`：查看AI助手当前运行状态、模型使用和健康情况，快速了解系统是否正常。

`openclaw logs`：实时查看运行日志，方便排查问题。

（Channels）`openclaw channels list / add / remove`：列出、管理连接的聊天通道（如添加飞书/微信），让AI能在你常用App里聊天。

`openclaw skills list / info`：列出或查看可用“技能”（自动化任务），了解AI能做什么。

`openclaw plugins list / install / uninstall`：管理插件扩展，安装新功能或移除不需要的。

`openclaw models status / list`：查看和管理连接的AI模型（如Claude/OpenAI），检查状态或切换使用。

`openclaw dashboard`：打开网页控制面板，图形化查看和管理系统。

`openclaw update`：检查并更新OpenClaw到最新版本。

`openclaw reset`：重置配置或会话（可指定范围），清理数据但不删核心文件。

`openclaw uninstall`：完全卸载OpenClaw。

官方文档：https://docs.openclaw.ai/