OpenClaw 安装指南
OpenClaw 安装指南
这不是一篇泛泛介绍 OpenClaw 的文章，而是一份真正帮你把第一次安装走通的页面。
它主要服务两类人：
- 第一次接触 OpenClaw 的新手
- 已经知道 OpenClaw 是什么，但想把第一套环境搭干净的人
如果你只做一件事，就把这 5 步跑通
第一次成功，不是“我装上了”，而是：
- 你选定了一条安装路线
- setup 跑完并生成 workspace
- Gateway 可以正常启动
- 你接通了一个真实 channel
- 一条真实消息能完成闭环
如果第五步还没做到，就不能算真正安装完成。
快速信息
- 适合谁：第一次安装 OpenClaw 的用户
- 预计耗时：20 到 45 分钟
- 难度：入门到中等
- 验证时间：2026-03-12
- 测试环境：基于当前官方文档的安装路径整理，正式生产使用前请再确认你的 OpenClaw 版本
新手安装就按这 4 步走
如果你现在只想要一条最稳妥、最容易跑通的路径，就照下面走：
第一步：先选一条安装路线
第一次安装只选一条：
- 稳定优先的 app-first 路线
- 开发者优先的源码路线
不要第一天就把两条路线混在一起。
第二步：先把机器准备好
先确认基础环境：
- Node.js 22+
pnpm- Docker 只有在你的实际流程需要容器时才需要
这些条件不对，后面所有问题都会被放大。
第三步：跑 setup，生成 workspace 和 config
第一次安装成功，不是“我看到了仓库”，而是：
- setup 跑完了
- workspace 生成了
- config 生成了
- Gateway 可以正常启动
第四步：只接一个 channel，并做 health check
第一次只接一个真实 channel 就够了。
然后确认：
- channel 登录成功
- health check 成功
- 真实消息能完成一轮往返
这三件事成立，第一次安装就算真正跑通了。
安装前先做 4 个决策
先别急着执行命令，先把下面 4 件事想清楚：
- 你要走稳定路径，还是源码路径？
当前官方文档更推荐把 macOS app 作为稳定路径，而源码模式更适合想深度调试和自定义的人。
- OpenClaw 要先跑在哪里？
- 先在本地电脑上跑通
- 跑在一台长期在线的个人机器
- 等本地验证稳定后，再迁移到托管环境
- 你第一条要打通的 channel 是什么？
不要第一天就接满所有渠道。只选一个你最在意的入口，例如 Telegram、Discord 或其他聊天渠道。
- 什么叫“安装成功”？
一个合理的第一里程碑是：
- OpenClaw 已完成安装
- setup 流程跑通
- 至少一个 channel 已成功连接
- health check 能通过
核心前置条件
根据当前官方 setup 文档，源码路径至少需要：
- Node.js 22 或更高版本
pnpm- Docker 仅在你需要容器化流程或本地 e2e 时才需要
如果这些基础条件没准备好，先解决它们，再排查 OpenClaw 本身。
推荐的第一次安装路径
方案 A：先走稳定路径
如果你的目标是“尽快把 OpenClaw 跑起来”，这是更稳妥的方案。
- 安装并启动 OpenClaw app（如果你的平台可用）。
- 完成 onboarding 和权限确认。
- 让 app 管理本地 Gateway。
- 连接你的第一个 channel。
- 跑一次 health check。
这里最重要的不是速度，而是减少第一次安装时的变量数量。
方案 B：源码优先路径
如果你更偏开发者工作流，就走这条：
- 先准备好 Node.js 和
pnpm。 - 跑 setup 流程，生成本地 OpenClaw workspace 和 config。
- 如果你是从源码运行，先完成 build。
- 在终端里启动 Gateway。
- 连接一个 channel，再执行一次 health check。
源码模式下，最好把你的个人 workspace 和 config 放在仓库之外，这样后续更新不会把你的定制内容冲掉。
首次运行检查表
安装完成后，请按顺序确认这些点：
- setup 流程没有卡在权限或认证错误
- workspace 和 config 已成功生成
- Gateway 已经在运行
- 第一个 channel 登录成功
- health check 成功返回
- 你能发出一条真实消息，并收到符合预期的回复
如果这一步不做，你很容易误以为 OpenClaw 已经“安装成功”，但其实只有一半链路是通的。
最常见的失败点
1. 把不同运行模式混在一起
很多人会把 app-first 的路径和 source-first 的路径混着用。建议先选一条跑通，再组合。
2. 基础环境没准备好
如果 Node.js 或 pnpm 本身不对，后面的模型、channel、权限错误都会显得很混乱。先确认基础环境，再看 OpenClaw。
3. 太早连接多个 channel
在本地健康状态未确认前就接多个渠道，会让排错难度大幅上升。第一次只接一个就够了。
4. 只连上 channel，没有做 health check
能登录不代表链路真的可用。一定要在配对后再跑一次 health check。
5. Linux 长驻假设错误
官方文档提到，Linux 用户服务在退出登录后可能会停掉；如果你想要长期在线，就要尽早考虑 lingering 或 system service。
看完这一页后，下一步不要自己猜
请按这个顺序继续：
- OpenClaw Setup Checklist —— 逐项确认环境、Gateway、一个 channel 和真实回复闭环。
- OpenClaw Discord Guide —— 先用一个真实渠道验证第一条可用路径。
- OpenClaw Heartbeat Guide —— 在 setup 可用后，再加上第一个周期性健康信号。
- OpenClaw 资源列表 —— 当核心链路已经跑通后，再进入资源目录看更深的资料与官方文档。
什么时候从本地迁移到托管部署
不要因为“看起来更正式”就一开始直接上托管部署。
只有当下面这些问题都能回答“是”时，再去做 Cloudflare Workers 之类的托管部署：
- 本地环境已经稳定
- 你已经知道第一个 channel 和第一个 workflow 是什么
- 你的 prompt 和 heartbeat 预期足够明确
- 你已经理解 config、secret、workspace 分别该放什么
托管部署是放大步骤，不是第一次证明 OpenClaw 能工作的步骤。
当你真的准备进入这一步时，不要自己临时拼接部署路径，直接看 OpenClaw Cloudflare 新手指南。