OpenClaw 安装与问题排查完全指南

一、OpenClaw 简介

OpenClaw 是一款完全开源的个人 AI 助手系统，允许你在自己的设备上运行，支持几乎所有主流聊天平台（WhatsApp、Telegram、Slack、Discord、微信飞书等），具备语音交互、浏览器控制、技能扩展等强大能力。它采用分布式架构，网关作为控制平面，可连接多个设备节点（macOS/iOS/Android），实现跨设备的 AI 能力。

核心特性

• 🚀 完全自主可控：所有数据和计算都在你的设备上运行，无云服务依赖
• 💬 多平台支持：支持 30+ 聊天平台，一个助手响应所有消息
• 🔧 技能扩展：通过 ClawHub 生态可以安装数百种功能技能
• 🎤 语音交互：支持唤醒词、连续对话，原生集成 ElevenLabs TTS
• 🤖 多Agent架构：支持隔离的工作空间，不同场景使用不同配置的助手
• 🌐 远程访问：通过 Tailscale 或 SSH 隧道实现安全的外网访问

二、系统要求

最低配置

• 操作系统：
  • macOS 13+ (Ventura 及以上)
  • Linux (Ubuntu 20.04+/Debian 11+/CentOS 8+ 等主流发行版)
  • Windows 10/11 (通过 WSL2 运行，推荐使用 Ubuntu 22.04 子系统)
• 硬件：
  • CPU：4 核以上，x86_64 或 ARM64 架构
  • 内存：8GB 以上（推荐 16GB）
  • 存储：至少 20GB 可用空间
• 依赖：
  • Node.js ≥ 22.0.0
  • npm/pnpm/bun 包管理器
  • Git

推荐配置

• CPU：8 核以上
• 内存：16GB+
• GPU：NVIDIA 显卡（显存 ≥16GB）用于本地大模型推理
• 网络：稳定的互联网连接（用于模型 API 调用和技能安装）

三、安装方法

方法一：一键安装（推荐）

这是最简单的安装方式，适合大多数用户。

# 1. 全局安装 OpenClaw CLI
npm install -g openclaw@latest
# 或者使用 pnpm（推荐，速度更快）
pnpm add -g openclaw@latest

# 2. 运行配置向导，自动安装后台服务
openclaw onboard --install-daemon

onboard 命令会引导你完成以下配置：

• 选择默认大模型提供商和 API 密钥
• 设置工作空间目录（默认 ~/.openclaw/workspace）
• 配置需要连接的聊天平台
• 安装必要的系统依赖
• 配置开机自启的后台服务（launchd/systemd）

方法二：Docker 安装

适合希望隔离运行环境的用户。

# 1. 拉取最新镜像
docker pull openclaw/openclaw:latest

# 2. 创建数据目录
mkdir -p ~/.openclaw

# 3. 运行容器
docker run -d \
  --name openclaw \
  -p 18789:18789 \
  -v ~/.openclaw:/root/.openclaw \
  --restart unless-stopped \
  openclaw/openclaw:latest

# 4. 进入容器执行配置
docker exec -it openclaw openclaw onboard

方法三：源码编译安装

适合开发者或需要自定义修改的用户。

# 1. 克隆源码
git clone https://github.com/openclaw/openclaw.git
cd openclaw

# 2. 安装依赖
pnpm install

# 3. 构建 UI 和核心代码
pnpm ui:build
pnpm build

# 4. 安装到全局
pnpm link --global

# 5. 运行配置向导
pnpm openclaw onboard --install-daemon

方法四：Nix 安装（NixOS 用户）

# 在 configuration.nix 中添加
services.openclaw = {
  enable = true;
  package = pkgs.openclaw;
  config = {
    agent.model = "anthropic/claude-opus-4-6";
    # 其他配置...
  };
};

四、安装后验证

1. 检查服务状态

# 查看网关运行状态
openclaw gateway status

# 预期输出：
# ✅ Gateway is running (pid: 1234, port: 18789, uptime: 2m 15s)

2. 访问控制界面

打开浏览器访问：http://localhost:18789，可以看到 OpenClaw 控制面板，包含 WebChat、配置管理、日志查看等功能。

3. 测试助手响应

# 发送测试消息
openclaw agent --message "你好，介绍一下你自己"

如果返回正常响应，说明安装成功。

五、基础配置

1. 模型配置

编辑 ~/.openclaw/openclaw.json 添加模型配置：

{
  "agent": {
    "model": "anthropic/claude-opus-4-6",
    "fallbackModels": ["openai/gpt-4o", "volcengine/ark-code-latest"],
    "thinking": "medium"
  },
  "models": {
    "anthropic/claude-opus-4-6": {
      "apiKey": "sk-xxx"
    },
    "openai/gpt-4o": {
      "apiKey": "sk-xxx"
    }
  }
}

2. 配置聊天平台

以 Telegram 为例，在配置文件中添加：

{
  "channels": {
    "telegram": {
      "botToken": "123456789:ABCdefGhIJKlmNoPQRstUvWxYz123456",
      "allowFrom": ["+8613800138000", "@your_username"],
      "groups": {
        "*": {
          "requireMention": true
        }
      }
    }
  }
}

支持的平台配置详情可参考：官方文档 - 通道配置

3. 安装常用技能

# 搜索技能
clawhub search "weather"

# 安装技能
clawhub install weather --dir ~/.openclaw/workspace/skills

六、常见问题与解决方案

❌ 问题 1：npm 安装权限错误

错误表现：

npm error EACCES: permission denied, mkdir '/usr/local/lib/node_modules/openclaw'

解决方案：

# 方法 1：使用 --prefix 指定用户目录安装
npm install -g openclaw@latest --prefix ~/.npm-global
echo 'export PATH=$PATH:~/.npm-global/bin' >> ~/.bashrc  # 或 ~/.zshrc
source ~/.bashrc

# 方法 2：修改 npm 全局目录权限
sudo chown -R $USER:$GROUP /usr/local/lib/node_modules

❌ 问题 2：Node.js 版本过低

错误表现：

Error: Node.js v18.x.x is not supported. Required >=22.0.0

解决方案：

# 使用 nvm 安装最新 LTS 版本
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
nvm install 22
nvm use 22
nvm alias default 22

❌ 问题 3：网关启动失败，端口被占用

错误表现：

Error: listen EADDRINUSE: address already in use 0.0.0.0:18789

解决方案：

# 查找占用端口的进程
lsof -i :18789
# 或
netstat -tulpn | grep 18789

# 杀死占用进程（替换 PID 为实际进程号）
kill -9 PID

# 或者修改 OpenClaw 端口
openclaw configure set gateway.port 18790

❌ 问题 4：WSL2 下无法访问控制面板

错误表现：在 Windows 浏览器中无法访问 http://localhost:18789

解决方案：

# 1. 在 WSL2 中获取虚拟机 IP
ip addr show eth0 | grep inet | awk '{ print $2; }' | sed 's/\/.*$//'

# 2. 使用该 IP 访问，例如 http://192.168.1.100:18789
# 3. 或者设置 WSL2 端口转发（在 Windows 管理员 PowerShell 中执行）
netsh interface portproxy add v4tov4 listenport=18789 listenaddress=0.0.0.0 connectport=18789 connectaddress=<WSL2 IP>

❌ 问题 5：消息发送失败，配对错误

错误表现：收到消息但助手不回复，日志显示 “Unknown sender, pairing required”

解决方案：

# 查看待配对的发送者
openclaw pairing list

# 批准配对
openclaw pairing approve +8613800138000
# 或
openclaw pairing approve @telegram_username

❌ 问题 6：技能安装失败，API 限流

错误表现：

Error: Rate limit exceeded (retry in 1s, remaining: 0/120)

解决方案：

1. 等待 1-2 分钟后重试
2. 手动下载技能包解压到 ~/.openclaw/workspace/skills/ 目录
3. 配置 ClawHub 镜像源：

export CLAWHUB_REGISTRY=https://mirror.clawhub.com

❌ 问题 7：macOS 权限错误

错误表现：无法访问摄像头、麦克风、屏幕录制等功能

解决方案：

1. 打开 “系统设置” → “隐私与安全性”
2. 找到 “终端”（或你使用的终端应用）
3. 开启 “摄像头”、“麦克风”、“屏幕录制” 等权限
4. 重启终端应用

❌ 问题 8：Docker 容器内无法访问主机服务

错误表现：无法连接到主机上运行的模型服务或其他 API

解决方案：

# 使用 host 网络模式运行容器
docker run -d \
  --name openclaw \
  --network host \
  -v ~/.openclaw:/root/.openclaw \
  --restart unless-stopped \
  openclaw/openclaw:latest

❌ 问题 9：大模型 API 调用失败

错误表现：调用 API 时返回 401/403/超时等错误

解决方案：

1. 检查 API 密钥是否正确配置
2. 确认账户有足够的余额
3. 测试网络连接：curl https://api.anthropic.com/v1/messages -H "x-api-key: sk-xxx"
4. 如果是网络问题，配置代理：

{
  "gateway": {
    "proxy": "http://127.0.0.1:7890"
  }
}

❌ 问题 10：后台服务崩溃，自动退出

解决方案：

# 查看日志排查问题
openclaw logs --tail 100

# 运行诊断工具，自动修复常见问题
openclaw doctor

# 重新安装服务
openclaw gateway uninstall-daemon
openclaw gateway install-daemon

七、诊断工具使用

OpenClaw 内置了强大的诊断工具，可以自动检测和修复常见问题：

# 全面诊断系统状态
openclaw doctor

# 预期输出：
# ✅ Node.js version: 22.11.0 (supported)
# ✅ Gateway is running
# ✅ Workspace directory exists
# ✅ Config file is valid
# ⚠️  Telegram bot token not configured (optional)
# ✅ All required dependencies are installed

# 查看实时日志
openclaw logs --follow

# 查看指定通道的日志
openclaw logs --channel telegram

八、升级与卸载

升级 OpenClaw

# 升级到最新稳定版
openclaw update --channel stable

# 升级到测试版
openclaw update --channel beta

# 查看当前版本
openclaw --version

完全卸载

# 1. 停止并卸载后台服务
openclaw gateway uninstall-daemon

# 2. 移除 npm 包
npm remove -g openclaw
# 或 pnpm remove -g openclaw

# 3. 删除配置文件（可选）
rm -rf ~/.openclaw

九、安全建议

1. 不要暴露网关到公网：除非你明确知道自己在做什么，否则不要将 18789 端口直接暴露到公网，推荐使用 Tailscale Funnel 或 SSH 隧道进行安全的远程访问。

2. 配置访问密码：如果需要外网访问，一定要开启密码验证：

{
  "gateway": {
    "auth": {
      "mode": "password",
      "password": "your-strong-password"
    }
  }
}

3. 限制消息来源：在通道配置中明确指定 allowFrom 列表，不要使用 "*" 允许所有人访问。

4. 定期备份配置：定期备份 ~/.openclaw 目录，避免数据丢失。

十、获取帮助

如果遇到本指南没有覆盖的问题，可以通过以下方式获取帮助：

• 📖 官方文档：最权威的使用说明
• 💬 Discord 社区：活跃的开发者和用户社区
• 🐛 GitHub Issues：提交 Bug 报告和功能请求
• 📝 运行 openclaw doctor：获取针对性的修复建议

---

本文基于 OpenClaw 2026.3.8 版本编写，不同版本可能略有差异，请以官方文档为准。