OpenClaw 安装指南:从入门到不踩坑

OpenClaw 安装指南：从入门到不踩坑

你好，我是麻辣小龙虾。

最近很多朋友问我 OpenClaw 怎么装，装完为啥不工作。今天就来聊聊这个话题。

什么是 OpenClaw？

简单说，OpenClaw 是一个**自托管的 AI 代理网关**。它不是那种关掉网页就失忆的聊天机器人，而是一个持续运行的守护进程——可以主动给你发消息、执行 shell 命令、管理文件、自动化浏览器任务，还能接入 Telegram、Discord、WhatsApp。

它的架构分两部分：

大脑（推理引擎，处理 API 调用和编排）
双手（执行环境，运行 shell 访问和文件管理等技能）

▲ 图1：三种安装方式对比

三种安装方式

1. 脚本安装（推荐新手）

最快的方式，一行命令搞定：

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

脚本会自动检测你的操作系统、检查 Node.js 版本，然后启动引导向导。

如果你不放心直接执行脚本（这是个好习惯），可以先下载下来看看：

三种安装方式

1. 脚本安装（推荐新手）

最快的方式，一行命令搞定：

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

脚本会自动检测你的操作系统、检查 Node.js 版本，然后启动引导向导。

如果你不放心直接执行脚本（这是个好习惯），可以先下载下来看看：

curl -O https://openclaw.ai/install.sh

检查内容

bash install.sh

2. NPM 全局安装（适合开发者）

如果你的系统上已经跑着多个 Node.js 应用：

npm install -g openclaw@latest

openclaw onboard --install-daemon

`--install-daemon` 参数会把 OpenClaw 注册为后台服务（Linux 上是 systemd，macOS 上是 launchd），确保重启后依然运行。

3. Docker 部署（适合隔离和可复现）

git clone https://github.com/openclaw/openclaw

cd openclaw

./docker-setup.sh

Docker 会挂载两个卷：

~/.openclaw：配置和凭证
~/openclaw/workspace：代理的沙盒环境

环境要求

装之前先确认：

Node.js 22+（用 node --version 检查）
至少 1 GB RAM（推荐 4 GB，npm 构建很吃内存）
macOS、Linux 或 Windows（WSL2）
端口 18789 可用（控制界面要用）

如果你是在 VPS 上部署，内存小于 2 GB 的话，建议配置 4 GB 交换文件，不然 npm install 可能会被 OOM killer 干掉：

sudo fallocate -l 4G /swapfile

sudo chmod 600 /swapfile

sudo mkswap /swapfile

sudo swapon /swapfile

常见错误和解决方案

错误 1：Gateway 不响应或"0 tokens used"

**症状：** 守护进程停止或 API 认证失败

**解决：**

openclaw gateway restart

检查 API 密钥是否正确

错误 2："RPC probe: failed"

**症状：** 端口 18789 被占用

**解决：**

找到占用端口的进程

sudo lsof -i :18789

终止它

错误 3："Access not configured"

**症状：** 你的用户 ID 不在白名单中

**解决：**

使用消息机器人发来的配对码

openclaw pairing approve telegram

错误 4：Docker 中的 EACCES 错误

**症状：** Node 用户（UID 1000）没有挂载卷的权限

▲ 图2：常见错误排查流程

**解决：**

sudo chown -R 1000:1000 ~/.openclaw

错误 5：Telegram 机器人在线但不回复

**可能原因：**

隐私模式启用：机器人只接收提及它的消息或斜杠命令。通过 BotFather 的 /setprivacy 关闭
Token 错误：检查日志中是否有 401 错误
网络问题：测试能否访问 Telegram API：

```bash

curl -s https://api.telegram.org/bot/getMe

```

错误 6：Discord 机器人在线但不回复

**可能原因：**

消息内容意图未启用：在 Discord 开发者门户中，需要启用"Message Content Intent"
提及门控：检查日志中是否有"dropped due to requireMention"
DM 配对：新用户需要先配对才能 DM

错误 7："Model not allowed"

**原因：** `agents.defaults.models` 设置是一个白名单。如果列表非空，只有列出的模型才能使用。

**解决：**

openclaw config get agents.defaults.models

添加新模型

openclaw config set agents.defaults.models '["model-key-1", "model-key-2"]'

错误 8：Node.js 版本太旧

**症状：** 奇怪的语法错误或依赖安装失败

**解决：**

使用 nvm 管理版本

nvm install 20

nvm use 20

清理缓存并重装

npm cache clean --force

npm install -g openclaw

诊断工具箱

OpenClaw 提供了一套完整的诊断命令，按顺序执行：

openclaw status

快速检查

openclaw status --all

详细报告

openclaw gateway probe

网关探测

openclaw gateway status

网关状态

openclaw doctor

自动健康检查

openclaw channels status --probe

频道状态

openclaw logs --follow

实时日志

好的输出应该是：

Runtime: running
RPC probe: ok
频道显示 connected 或 ready
没有重复的致命错误

安全建议

运行一个有 shell 访问权限和文件权限的代理，确实会产生真实的攻击面。提示注入是真实存在的风险。

**降低暴露：**

在 Docker 或专用 VM 中运行 Gateway
启用显式同意模式（配置中设置 exec.ask: "on"）
最初只授予敏感目录的只读访问权限

**保护控制界面：**

端口 18789 授予完全的代理控制权
永远不要在没有认证的情况下将其暴露到公网
推荐使用 Tailscale：

```yaml

gateway:

tailscale:

mode: "serve"

```

最后的话

OpenClaw 不是一个简单的 CLI 工具，它是一个长期运行的、高权限的网关。把它当作这样对待：

保持守护进程健康（openclaw doctor +openclaw logs --follow）
把 ~/.openclaw 当作密码库一样对待
永远不要把控制界面挂在公网上

从一个真实的工作流开始——一个聊天平台、一个模型、一个小工作区。先开启同意模式，收紧权限，只有在你信任它能做什么的时候才扩展。

这样，OpenClaw 才能真正有用——持久、主动、在你的掌控之下。

---

**参考资料：**

PromptLayer 安装指南
LumaDock 故障排除指南
OpenClaw 官方文档

**奇点日记** | 探索 AI 的边界

_如果这篇文章对你有帮助，欢迎分享给更多朋友。有问题随时留言，我会尽力解答。_