OpenClaw常用命令实战手册：从安装到高阶调试

最近在折腾 OpenClaw，这玩意儿作为统一聊天渠道的聚合网关确实好用，但官方文档散落在各处，新手上手时容易对着一堆参数发懵。我把这段时间高频使用的命令整理了一下，按实际操作场景分类，建议收藏备用。

1. 核心服务的起停与监控

Gateway 是 OpenClaw 的心脏，它负责所有消息的路由。

• 启动网关：openclaw gateway 默认占用 18789 端口。建议初次配置时在前台运行，方便直接看报错。
• 停止服务：openclaw gateway stop 修改配置或需要释放端口时执行。注意，如果不正常停止，有时候会出现端口占用的残留。
• 状态检查：openclaw gateway status 用来确认进程 PID 和端口占用情况。
• 实时日志：openclaw logs --follow 调试时的“神”命令。类似于 Linux 的 tail -f，能看到每一条消息的收发轨迹。
• 快速体检：openclaw health 简单的返回 OK 或 Error，适合写在自动化脚本里做监控。

2. 渠道绑定（WhatsApp / 飞书 / TG）

渠道（Channels）是你连接外界的触角。

• 登录绑定：openclaw channels login 会启动交互式向导。如果是 WhatsApp，终端会跳出二维码让你扫；如果是飞书，则会引导你输入 Token。
• 查看连接：openclaw channels list 看看哪些号是在线（ON）的，哪些断开了。
• 解绑退出：openclaw channels logout <id> 需要切换账号时使用。

3. AI 模型与 Agent 管理

有了通道，接下来就是配置大模型大脑。

• 模型列表：openclaw models 查看当前挂载了哪些模型，以及它们的上下文限制。
• 自动扫描：openclaw models scan 如果你在环境变量里新加了 API Key，跑一下这个命令，它会自动识别并同步新模型。
• Agent 状态：openclaw agents status 检查当前 Agent 的内存占用和活跃对话数。
• 记忆搜索：openclaw memory search <查询词> OpenClaw 的特色功能，看看 Agent 到底“记住”了关于你的哪些信息。

4. 调试与排错

当消息发不出去，或者 Agent 没反应时，按这个顺序排查：

1. 全景报告：openclaw status 这是我最常用的命令，一键显示网关、渠道、模型、安全审计的汇总信息。
2. 自动诊断：openclaw doctor 类似 Homebrew 的 doctor，它会尝试检查目录权限、配置文件格式等常见低级错误并自动修复。
3. 手动模拟测试：openclaw message send --target <ID> --message "测试内容" 跳过聊天软件端，直接从 CLI 模拟发送。如果这一步通了，说明网关没问题，问题出在渠道连接上。

5. 维护与重置

• 版本更新：openclaw update
• 重置配置：openclaw reset 慎用！ 这会清空所有本地配置和数据，通常只在环境搞乱了准备重装时才用。
• 查看帮助：openclaw --help 或 openclaw <子命令> --help

---

💡 进阶：几个典型的操作套路

场景一：修改配置后如何平滑重启？ 不要直接 kill 进程，按这个流程走：

1. openclaw gateway stop
2. 修改 ~/.openclaw/ 下的 json 配置文件。
3. (可选) 如果想清理旧的对话状态，执行：rm ~/.openclaw/agents/main/sessions/sessions.json
4. openclaw gateway

场景二：如何确定飞书 ID 是否正确？ 直接用测试命令投喂： openclaw message send --target "ou_xxxxxx" --message "系统测试成功"

总结

对于日常维护来说，其实记住这三个就够了：

• openclaw gateway (启动)
• openclaw gateway stop (停止)
• openclaw status (看状态)