OpenClaw 使用指南：从 0 到 1 搭建你的个人 AI 助手（含常见问题与解决案例）

1. OpenClaw 是什么？适合做什么

OpenClaw 可以理解为一个“能接入真实工具”的个人 AI 助手框架：它不止能聊天，还能通过工具去完成操作，比如：

• 读写本地文件、运行脚本、执行命令
• 打开浏览器自动化操作网页
• 连接消息渠道（如 Feishu / Telegram / Discord 等）在群里当助手
• 连接设备节点（node），做摄像头抓拍、屏幕录制、通知推送等（取决于你配了哪些能力）

适用场景：

• 自动化办公：生成周报、整理文档、批量处理文本
• DevOps/运维助手：状态检查、日志分析、健康巡检
• 内容助手：写教程、整理资料、发布到 CSDN/公众号
• 私人助理：提醒、查询、工作流串联

---

2. 安装与启动（通用思路）

不同平台/版本安装方式可能略有差异，建议以你本机的 OpenClaw CLI 为准。一般流程是：

2.1 检查 CLI 是否可用

openclaw help
openclaw --version

2.2 启动 Gateway（核心服务）

Gateway 可以理解为“OpenClaw 的后台服务/中枢”，负责承载会话、工具调用、连接渠道等。

常用命令：

openclaw gateway status
openclaw gateway start
openclaw gateway restart
openclaw gateway stop

建议先看状态：

openclaw gateway status

---

3. 核心概念速懂（新手必看）

3.1 Session（会话）

你在某个渠道（比如 Feishu 群）里跟机器人对话，就是一个会话上下文。会话里可以：

• 调工具（文件、命令、网页、消息）
• 读取 workspace 里的项目文件（如 SOUL.md、USER.md、HEARTBEAT.md 等）

3.2 Tools（工具）

OpenClaw 的“强”来自工具能力，例如：

• read / write / edit：读写文件
• exec / process：执行命令、管理后台进程
• web_search / web_fetch：联网搜索/抓取网页内容
• browser：浏览器自动化
• message：主动发消息到某个渠道
• nodes：连接设备节点（如果你有配对）

3.3 Workspace（工作区）

工作区是你的“本地大脑”，常见文件：

• SOUL.md：助手的人设/风格
• USER.md：用户偏好
• TOOLS.md：环境相关的备忘（摄像头名、服务器别名等）
• HEARTBEAT.md：心跳任务清单（定期检查事项）
• memory/*.md：日记式记录（可选）

---

4. 5 分钟快速上手（最短路径）

4.1 让它先“会用文件”

你可以直接对它说：

• “读取一下 workspace 里的 SOUL.md”
• “帮我生成一个 docs/openclaw-quickstart.md，写上快速上手步骤”

4.2 让它“会联网查资料”

例如：

• “帮我查一下 OpenClaw docs 里关于 gateway 的说明，并总结成 5 条”

4.3 让它“会操作浏览器”

例如：

• “打开某网站，登录后抓取某个页面内容并总结”（涉及账号时建议你自己登录后再让它继续）

---

5. 常用工作流示例

• 示例 A：生成 CSDN 教程并落盘
  • “以 CSDN 风格写一篇 OpenClaw 入门，包含安装、gateway、工具、常见问题，输出到 docs/csdn-openclaw.md。”
• 示例 B：把需求变成可执行清单
  • “我想做一个每天早上 9 点检查服务状态并在飞书群提醒的助手，帮我拆解步骤和配置项。”
• 示例 C：做一个故障排查助手
  • “当 gateway 启动失败时，帮我生成排查 checklist，并给出命令。”

---

6. 常见问题（FAQ）& 解决案例

Q1：gateway start 后没反应 / status 还是 stopped？

现象：

• 执行 start 之后无报错但也没起来
• openclaw gateway status 显示未运行

排查思路：

1. 尝试重启：

openclaw gateway restart

2. 看是否端口冲突（结合日志/端口占用）
3. 确认 Node/依赖版本是否满足（node 版本过低常见）

解决案例：

• 端口冲突：关闭冲突服务或修改配置端口后重启
• node 版本过旧：升级 node 后重启 gateway

Q2：群里 @ 了机器人但不说话？

排查思路：

1. 机器人是否在群里且有发言权限
2. 是否配置为“必须 @ 才响应”
3. 渠道侧（Feishu/Discord）是否开启事件订阅/回调

解决案例：

• 群权限未开：在群管理里允许机器人发言
• 只响应 mention：使用 @机器人 再提问

Q3：工具调用失败（exec / 读文件失败）

排查思路：

1. 路径是否正确、是否在 workspace
2. 是否需要更高权限（系统目录/管理员命令）
3. 命令是否依赖环境变量/虚拟环境

解决案例：

• 文件不在 workspace：放入 workspace 或使用绝对路径并确保权限
• 依赖 venv：先激活 venv 再执行

Q4：资料太旧/需要最新信息怎么办？

• 模型内置知识有截止时间，最新信息建议显式要求联网检索并指定来源

模板：

请联网搜索，优先使用官方 docs / GitHub / 发布说明，给出链接并总结要点。

Q5：浏览器自动化卡住/找不到按钮？

解决案例：

• 先截图/快照定位元素，再操作
• 你先手动登录并关闭弹窗，再让它继续自动化（最稳）

---

7. 最佳实践

• 把环境相关信息写进 TOOLS.md（服务器别名、目录结构等）
• 把固定检查项写进 HEARTBEAT.md（定期检查 gateway status 等）
• 内容先输出到文件再发布（方便版本迭代）
• 遇到问题先让它给 checklist，比直接问“怎么修”更快落地

---

8. 结语

OpenClaw 的优势不在“会聊”，而在“能把聊天变成行动”：读写文件、跑命令、查资料、操作网页、接入消息渠道——把 AI 真正嵌进你的工作流。