OpenClaw 高效使用指南
把自托管 AI Agent 用稳、用好、用出自动化
OpenClaw 是一个开源、自托管的个人 AI Agent 平台（前身 Clawdbot、Moltbot，2026 年 1 月正式更名为 OpenClaw）。它不是浏览器里的聊天框，而是常驻在你机器上的守护进程：能执行命令、读写文件、接管消息渠道、按计划主动干活。这篇指南整合了社区教程的实战经验，讲清楚怎么把它装好、配好，并真正用出生产力。
// 它是什么
一、先搞清楚 OpenClaw 到底是什么
很多人把 OpenClaw 当成又一个聊天机器人，结果用得很别扭。它的定位完全不同：这是一个自托管、单用户的个人 AI Agent 平台，跑在你自己的电脑或 VPS 上。
它和普通聊天工具的关键区别在于：
- 它是常驻守护进程，关掉终端也继续在后台运行
- 它能执行 shell 命令、读写文件、调用工具，不只是回话
- 它能主动找你：按计划（Cron）触发任务，把结果推到你的聊天软件
- 它桥接消息渠道：Telegram、WhatsApp、Slack、Discord、iMessage 等
💡 一句话记忆：OpenClaw = 一个住在你机器上、能动手、还能主动汇报的 AI 助理。
名字的来龙去脉
这个项目早期叫 Clawdbot，2026 年 1 月一度改名 Moltbot，最终在 2026 年 1 月 30 日定名 OpenClaw，强调其开源属性。你在老教程里看到 Clawdbot / Moltbot，指的都是它。
// 核心概念
二、四个核心概念，理解了就不会乱
OpenClaw 的所有命令和配置，都围绕下面四个概念展开。先建立这张地图，后面就不会迷路。
| 概念 | 作用 | 可以类比为 |
|---|---|---|
Gateway | 常驻的 WebSocket 服务，是所有渠道、Agent、应用的中枢控制面 | 总机 / 大脑 |
Channel | 消息渠道桥接，把 Telegram、Slack 等接进来 | 对外的电话线 |
Agent | 真正干活的 AI 实体，绑定模型、工具和人设 | 员工 |
Workspace | 存放 Markdown 记忆、配置、技能的工作目录 | 办公桌和档案柜 |
其中 Gateway 是心脏。它不跑，其它一切都不工作 —— 渠道收不到消息，Agent 也不会响应。后面排障时，第一件事永远是确认 Gateway 在不在跑。
// 安装
三、安装与初始化：三条命令起步
OpenClaw 基于 Node.js。建议用 Node 24，最低需要 Node 22.14+。先确认环境，再安装。
# 1. 检查 Node 版本（需要 22.14+，推荐 24）
node -v
# 2. 全局安装 OpenClaw
npm install -g openclaw
# 3. 交互式初始化：配置模型 API Key、工作目录等
openclaw setupopenclaw setup 会引导你填入模型 API Key（Claude、GPT、Gemini、本地模型等都支持），并生成基础配置。完成后启动 Gateway：
# 前台运行，方便第一次观察日志
openclaw gateway run
# 确认状态：Runtime 应为 running，RPC probe 应为 ok
openclaw gateway status💡 macOS 用户也可以直接装桌面 App，让它托管内置 Gateway，省去手动维护守护进程。命令行玩家则更适合用gateway run 自己掌控。
// SOUL 与 AGENTS
四、SOUL.md 与 AGENTS.md：把 Agent 调教成你想要的样子
这是 OpenClaw 最有特色、也最容易被忽视的两个文件。它们都放在工作目录里，决定了 Agent 的行为风格。
SOUL.md —— 定义“人设与价值观”
SOUL.md 描述 Agent 是谁、说话什么风格、有哪些边界。它解决的是“你的助理是个什么样的人”。
# SOUL.md
你是我的私人技术助理，名字叫 Claw。
- 语气：简洁、直接，不说废话，不用感叹号堆叠
- 默认中文回复，代码和命令用英文
- 涉及删除文件、改生产环境等高风险操作前，必须先问我
- 不确定的事直说不确定，不要编AGENTS.md —— 定义“工作规则与流程”
AGENTS.md 更偏操作规范：干活时遵守哪些流程、用什么工具、交付前做什么检查。它解决的是“你的助理该怎么干活”。
# AGENTS.md
- 改代码前先读相关文件，理解现状再动手
- 优先最小改动，不主动重构无关代码
- 每次任务结束汇报：改了什么、验证了什么、还有什么风险
- 长任务用 todo 拆分，逐步推进
- 涉及外发数据 / 公开操作前先确认💡 经验法则：SOUL.md 管“性格”，AGENTS.md 管“纪律”。把重复叮嘱的话写进这两个文件，比每次对话里重新交代高效得多。
// 接入渠道
五、接入消息渠道：让它住进你常用的聊天软件
OpenClaw 的杀手锏是主动性 —— 而主动性要通过渠道才能体现。把它接进 Telegram 或 Slack，你就能随时随地给它发指令、收它的汇报。
# 查看支持的渠道与当前状态
openclaw channels list
openclaw channels status --probe
# 添加一个渠道（按提示填入 bot token 等）
openclaw channels add telegram
# 配对：批准某个 DM 会话，防止陌生人调用你的 Agent
openclaw pairing approve <channel> <id>⚠️ 配对（pairing）是关键的安全闸门。OpenClaw 是单用户系统，务必只批准你自己的会话，否则别人就能借你的机器执行命令。
常见的“机器人不回话”，绝大多数是这三种原因：Gateway 没跑、渠道权限/Token 不对、或 DM 配对没批准。
// 自动化
六、用 Cron 把它变成自动化引擎
这一步才是 OpenClaw 真正拉开差距的地方。普通聊天机器人等你开口；OpenClaw 能按计划主动干活。
- 每天早上 9 点汇总昨天的 GitHub issue 和 PR，推到 Telegram
- 每小时检查一次服务器磁盘和服务状态，异常才提醒你
- 每周一整理本周日程并生成待办清单
这些都靠内置的 Cron 调度器实现。你可以用自然语言让 Agent 帮你创建计划任务，也可以在配置里直接写：
让 Agent 自建定时任务
帮我创建一个定时任务：
- 每个工作日早上 9:00 执行
- 拉取我关注仓库的新 issue 和 PR
- 汇总成一条简短消息发到我的 Telegram
先告诉我你打算怎么配，确认后再写入。💡 把 Cron 想成“给 Agent 排班”。一旦排好，你不在电脑前它也照常工作。
// 本地执行
七、agent 命令与 --local：随手跑一轮
除了通过聊天软件交互，你也能在终端直接喊它干活。openclaw agent 默认会把任务送进 Gateway 守护进程处理。
# 通过 Gateway 跑一轮任务（推荐，复用守护进程上下文）
openclaw agent "总结一下当前目录的项目结构"
# 用 --local 强制走内嵌执行路径
# 适合快速实验，或 Gateway 暂时不可用时
openclaw agent --local "把 README 翻译成英文"--local 绕开守护进程，独立跑一次，不依赖 Gateway 是否在线，但也拿不到守护进程里的长期上下文。日常优先用默认模式，调试时再用 --local。
// 排障
八、排障三件套：status、doctor、logs
OpenClaw 是个有 Gateway、渠道适配器、记忆层、调度器的复杂系统，出问题时按固定顺序排查最快。
| 命令 | 用途 | 健康信号 |
|---|---|---|
openclaw gateway status | 看守护进程在不在跑 | Runtime: running，RPC probe: ok |
openclaw doctor | 体检：配置和服务有没有阻塞性问题 | 报告 no blocking issues |
openclaw channels status --probe | 主动探测各渠道连通性 | 渠道显示 connected / ready |
openclaw logs | 通过 RPC 读 Gateway 日志，远程也能看 | 能看到实时日志输出 |
标准排障顺序：先 status 确认进程活着 → 再 doctor 体检配置 → 然后 channels status 看渠道 → 最后 logs 看具体报错。
# 重启是最常用的“一招回血”
openclaw gateway restart
# 看不出原因时，开调试日志再复现一次
openclaw logs --follow// 安全
九、自托管安全：能动手，就得管住手
OpenClaw 能执行 shell、读写文件、还连着你的聊天账号 —— 能力越大，配置不当的代价越大。把下面几条当成底线。
- 只批准自己的 DM 配对，
pairing列表里不该有陌生人 - API Key、Token 放进环境变量或配置文件，不要提交到 Git
- 在 SOUL.md / AGENTS.md 里写明：删除文件、改生产环境等高风险操作前必须先问
- 放到公网 VPS 时，限制端口暴露，配好防火墙，定期
openclaw doctor体检 - 定期清理 / 轮转日志，避免敏感信息长期堆积
⚠️ 记住它是真的会执行命令的。给它的权限和它能碰到的数据，都要按“它可能会照做”来评估。
// 命令速查
十、常用命令速查表
把这张表收藏起来，覆盖了日常 90% 的操作。
| 场景 | 命令 |
|---|---|
| 安装 | npm install -g openclaw |
| 初始化配置 | openclaw setup |
| 启动 Gateway | openclaw gateway run |
| 查看状态 | openclaw gateway status |
| 重启 Gateway | openclaw gateway restart |
| 列出渠道 | openclaw channels list |
| 添加渠道 | openclaw channels add <channel> |
| 批准配对 | openclaw pairing approve <channel> <id> |
| 跑一轮任务 | openclaw agent "..." |
| 本地执行 | openclaw agent --local "..." |
| 体检 | openclaw doctor |
| 看日志 | openclaw logs --follow |
// 总结
总结
把 OpenClaw 用好，关键不在记多少命令，而在建立正确的心智模型。
01
当它是守护进程
常驻、能动手、会主动，不是聊天框
02
调教两份文件
SOUL.md 管性格，AGENTS.md 管纪律
03
排障看三件套
status → doctor → channels → logs
先把 Gateway 跑稳，再用 SOUL.md / AGENTS.md 把行为定下来，最后用 Cron 把重复劳动自动化 —— 这三步走完，OpenClaw 就从“又一个聊天机器人”变成你真正的私人自动化助理。