OpenClaw 本地部署全流程，新手跟着做不会踩坑

这篇文章覆盖 macOS / Windows / Linux 三端，从环境准备到跑通第一条消息，每个坑都替你踩过了。文中所有命令和配置均来自 OpenClaw 官方文档。

在开始之前，先搞清楚 OpenClaw 是什么

OpenClaw 是一个开源的个人 AI 助手框架，核心思路是：把 LLM 接入你平时用的聊天软件（Telegram、WhatsApp、Slack 等），让 AI 能真正替你”干活”——读文件、跑命令、控制浏览器、定时执行任务。

整个系统只有一个核心进程叫 Gateway，你在手机上发条消息，Gateway 收到之后调用 LLM，LLM 决定要用哪些工具，执行完结果返回给你。整个链路跑在你自己的机器上，数据不离本地。

第一步：确认环境依赖

OpenClaw 只有一个硬性依赖：Node.js 22 或更高版本。版本装低了会报奇怪的错误，这是新手最常踩的第一个坑。

检查当前 Node.js 版本

node --version

输出应该是 v22.x.x 或更高。如果版本不对，按下面的方式安装。

macOS

推荐用 Homebrew 安装，或者用 nvm 管理多版本：

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
nvm install 22
nvm use 22

Windows

去 nodejs.org 下载 22.x 的 LTS 安装包，一路下一步即可。安装完打开 PowerShell 验证版本。官方推荐 Windows 用户使用 WSL2 来运行 OpenClaw，兼容性更好。

Linux（Ubuntu / Debian）

curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs

第二步：安装 OpenClaw

macOS / Linux

curl -fsSL https://openclaw.ai/install.sh | bash

Windows（PowerShell）

iwr -useb https://openclaw.ai/install.ps1 | iex

也可以用 npm 全局安装（三端通用）：

npm install -g openclaw

安装完验证：

openclaw --version

第三步：准备 API Key

OpenClaw 本身不内置模型，你需要自己提供 LLM 的 API Key。支持的主流模型：

⚠️ 注意：如果你有 Claude Pro / Max 订阅但没有 API Key，可以用 setup-token 的方式认证。在终端运行 claude setup-token（需要先安装 Claude Code CLI），复制生成的 token，在 onboarding 时选择「Anthropic token (paste setup-token)」。

第四步：运行初始化引导

官方推荐加上 --install-daemon 参数，这样引导完成后会自动安装后台服务，不需要手动保持终端窗口：

openclaw onboard --install-daemon

引导会依次配置：

1. 模型和认证：选择 AI 提供商，输入 API Key 或 OAuth 登录
2. 选择默认模型：从检测到的可用模型中选择
3. Gateway 配置：本地模式或连接远程 Gateway
4. 健康检查：自动启动 Gateway 并验证是否正常运行
5. 安装 Skills：可安装推荐的扩展能力，也可以跳过

引导完成后，配置文件会保存在 ~/.openclaw/openclaw.json。

第五步：验证 Gateway 是否正常运行

如果你用了 --install-daemon，Gateway 应该已经在后台运行了。验证一下：

openclaw gateway status

然后打开控制面板：

openclaw dashboard

浏览器会打开 http://127.0.0.1:18789/，你可以直接在这里发消息测试，不需要配置任何 Channel。

如果想手动在前台运行 Gateway（调试用）：

openclaw gateway --port 18789

第六步：连接 Telegram（可选但推荐）

控制面板只能在本机访问，接入 Telegram 后可以随时随地用手机控制 AI。

1. 创建 Telegram Bot

打开 Telegram，搜索 @BotFather，发送 /newbot，按提示取名后复制 Bot Token，格式类似 123456789:AAHxxxxxxx。

2. 用 CLI 添加 Telegram 渠道

最简单的方式是用命令直接添加：

openclaw channels add --channel telegram --token 你的BotToken

或者手动编辑 ~/.openclaw/openclaw.json，加入以下配置：

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "你的BotToken",
      dmPolicy: "pairing",
    },
  },
}

3. 重启 Gateway 并完成配对

openclaw gateway restart

在 Telegram 里找到你的 Bot 发一条消息，Bot 会回复一个配对码。然后在终端里审批：

openclaw pairing list telegram
openclaw pairing approve telegram <配对码>

⚠️ 配对码有效期只有 1 小时，超时需要重新发起。

常见报错与解决办法

❌ Gateway 起不来 / 配置出错

先跑官方的健康检查工具，它能自动检测并修复大部分配置问题：

openclaw doctor
# 加 --fix 自动修复
openclaw doctor --fix

❌ Telegram Bot 配置后没有响应

排查步骤：

1. 确认 botToken 格式正确，没有多余空格
2. 确认已完成 pairing 配对流程（openclaw pairing list telegram 查看状态）
3. 确认 dmPolicy 配置正确，默认值 pairing 需要完成配对才能通信
4. 运行 openclaw doctor 检查配置合法性

❌ npm 全局安装报权限错误（Linux / macOS）

不要用 sudo npm install -g，改用 nvm 管理 Node，nvm 安装的 npm 不需要 sudo：

nvm install 22
nvm use 22
npm install -g openclaw

❌ 配置文件改了但没生效

好消息：Gateway 会自动监听 ~/.openclaw/openclaw.json 的变化并热加载，大多数设置不需要重启。如果改动涉及 gateway 模式等核心配置，才需要手动重启：

openclaw gateway restart

❌ 想让 Gateway 开机自启

如果 onboarding 时没有加 --install-daemon，可以事后补装：

openclaw gateway install
openclaw gateway start

下一步可以做什么

跑通之后，可以继续探索：

• 安装 Skills：给 AI 增加新能力，社区技能库在 ClawHub
• 接入更多 Channel：WhatsApp、Slack、Discord、iMessage、Signal 等
• 配置多 Agent：不同的聊天来源路由到不同的 AI 实例
• 开启 Cron 任务：让 AI 定时执行任务，主动给你发消息

总结

整个流程顺利的话 20 分钟内可以跑通。遇到问题先跑 openclaw doctor，大部分配置问题它都能检测出来。更多细节参考 官方文档。