OpenClaw 史上最全手把手的保姆级安装配置教程（2026年1月31日最新版）

重要说明

OpenClaw 是 Moltbot/Clawdbot 的最新正式名称。项目经历了多次更名：Clawdbot → Moltbot → OpenClaw（当前名称），本教程基于官方中文社区文档 https://www.moltcn.com/start/getting-started.html 编写。

📋 目录

1. OpenClaw 是什么？

2. 核心特性

3. 系统要求

4. 安装前准备

5. 安装 OpenClaw

6. 首次配置向导

7. 启动 Gateway

8. 连接即时通讯平台

9. DM 安全配对

10. 常用命令大全

11. 日常维护

12. 故障排除

13. 安全加固

14. 从源码安装（开发模式）

15. 常见问题

一、OpenClaw 是什么？

OpenClaw 是由 Peter Steinberger（PSPDFKit 创始人）和 Mario Zechner（Pi 创建者）开发的开源个人 AI 助手项目。

🦞 名字由来

OpenClaw = CLAW + TARDIS — 因为每只太空龙虾都需要一台时间机器。

🎯 核心定位

“Any OS + WhatsApp/Telegram/Discord/iMessage gateway for AI agents (Pi). Send a message, get an agent response — from your pocket.”

OpenClaw 将多个即时通讯平台连接到 AI 编程代理（如 Pi），让你通过熟悉的聊天工具直接控制你的电脑。

📱 支持的平台

平台	类型	说明
WhatsApp	原生集成	通过 Baileys 使用 WhatsApp Web 协议
Telegram	Bot API	DMs + 群组 via grammY
Discord	Bot API	DMs + 频道 via discord.js
iMessage	本地集成	macOS 本地 imsg CLI
Mattermost	插件	Bot Token + WebSocket 事件

二、核心特性

✨ 主要功能

• 🤖 AI 代理桥接 — 连接 Pi 代理（RPC 模式），支持工具流式传输

• 💬 流式响应 — 块流式传输 + Telegram 草稿流式传输

• 🧠 多代理路由 — 将不同提供者/用户路由到隔离的代理

• 🔐 订阅认证 — Anthropic (Claude Pro/Max) + OpenAI (ChatGPT/Codex) via OAuth

• 💬 会话管理 — 私聊合并为共享的 main 会话；群聊隔离

• 👥 群聊支持 — @提及触发（可配置为始终响应）

• 📎 媒体支持 — 发送和接收图片、音频、文档

• 🎤 语音笔记 — 可选的转录钩子

• 🖥️ WebChat + macOS 应用 — 本地 UI + 菜单栏辅助

• 📱 iOS/Android 节点 — 配对后暴露 Canvas + 聊天 + 摄像头

🏗️ 架构图

WhatsApp / Telegram / Discord / iMessage (+ plugins)

│

▼

┌───────────────────────────┐

│ Gateway │ ws://127.0.0.1:18789 (loopback-only)

│ (single source) │

│ │ http://:18793

│ │ /openclaw/canvas/ (Canvas host)

└───────────┬───────────────┘

│

├─ Pi agent (RPC)

├─ CLI (openclaw …)

├─ Chat UI (SwiftUI)

├─ macOS app (OpenClaw.app)

├─ iOS node via Gateway WS + pairing

└─ Android node via Gateway WS + pairing

三、系统要求

基础要求

项目	要求	说明
Node.js	≥ 22.x	必需，运行时要求
pnpm	可选但推荐	从源码构建时推荐
内存	最低 2GB，推荐 4GB+
磁盘空间	最低 1GB，推荐 5GB+

各平台要求

• macOS：如果要构建应用，需安装 Xcode / Command Line Tools；仅 CLI + Gateway，Node.js 足够

• Windows：强烈推荐使用 WSL2（推荐 Ubuntu）；原生 Windows 未测试，问题更多，工具兼容性较差；必须先安装 WSL2，然后在 WSL 内运行 Linux 步骤

• Linux：无额外要求

🌐 网络要求

需要访问互联网（API 调用）；国内用户：必须使用代理，否则 Gateway 无法启动

四、安装前准备

4.1 获取 API Key

OpenClaw 需要连接 AI 模型服务。选择以下其一：

• Anthropic Claude （推荐）：访问 Anthropic Console，注册账号并获取 API Key；或使用 claude setup-token 复用 Claude Code 凭证

• OpenAI（ChatGPT/Codex）：访问 OpenAI Platform，创建 API Key

• 其他选项：MiniMax（国内推荐）、GLM（智谱AI）、本地 Ollama 模型

4.2 安装 Node.js

使用 nvm 安装（推荐）：

# 安装 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.1/install.sh | bash

# 重新加载
source ~/.bashrc  # 或 source ~/.zshrc

# 安装 Node.js 22
nvm install 22
nvm use 22

# 验证
node --version  # 应显示 v22.x.x
npm --version

直接安装（macOS）：

# 使用 Homebrew
brew install node@22
echo 'export PATH="/usr/local/opt/node@22/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

4.3 可选：安装 pnpm（推荐用于源码构建）

npm install -g pnpm

五、安装 OpenClaw

5.1 一键安装（推荐）

macOS / Linux：

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

Windows (PowerShell)：

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

5.2 NPM 安装（备选）

# 使用 npm
npm install -g openclaw@latest

# 或使用 pnpm
pnpm add -g openclaw@latest

5.3 验证安装

# 查看版本
openclaw --version

# 查看帮助
openclaw --help

5.4 Windows WSL2 安装

如果使用 Windows，必须通过 WSL2：

# 以管理员身份打开 PowerShell
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

# 重启电脑

# 安装 WSL2 内核更新
wslstorestorage.blob.core.windows.net/wslblob/wsl_update_x64.msi

# 设置 WSL2 为默认
wsl --set-default-version 2

# 在 Microsoft Store 安装 Ubuntu 22.04

然后在 WSL2 终端中：

# 安装 Node.js 22
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs

# 安装 OpenClaw
curl -fsSL https://openclaw.ai/install.sh | bash

六、首次配置向导

6.1 启动向导

运行向导并安装后台服务：

openclaw onboard --install-daemon

6.2 向导步骤说明

步骤 1：Gateway 模式

? Gateway mode: (Use arrow keys)
❯ Local    # 本地运行（推荐）
  Remote   # 连接到远程 Gateway

步骤 2：认证方式

? Auth provider: (Use arrow keys)
❯ Anthropic (API key)          # 推荐
  Anthropic (OAuth)            # Claude Code 凭证复用
  OpenAI (API key)             # ChatGPT/Codex
  OpenAI (OAuth)
  ...更多选项

推荐 Anthropic API key：claude setup-token 也支持用于复用 Claude Code 凭证。

步骤 3：选择模型

? Default model: (Use arrow keys)
❯ claude-sonnet-4-0           # 推荐，速度和智能平衡
  claude-opus-4-5             # 更强智能，但更慢
  claude-haiku-3-5            # 快速响应

步骤 4：频道配置

? Channels: (Select channels to configure)
❯⬡ WhatsApp                   # 需要 QR 登录
  ◉ Telegram                  # 需要 bot token
  ◯ Discord                   # 需要 bot token
  ◯ Mattermost                # 需要 plugin token
  ◯ iMessage                  # macOS 本地

步骤 5：配对安全设置

默认：未知私聊会收到简短代码，需要批准后才能处理消息。

步骤 6：工作区设置

? Workspace directory: (Use arrow keys)
❯ ~/.openclaw/workspace       # 默认工作区
  自定义路径

步骤 7：技能选择

? Install recommended skills: (y/N)
y  # 安装推荐技能

步骤 8：后台服务安装

? Install daemon: (y/N)
y  # 安装后台服务（推荐）

运行时：Node（推荐；WhatsApp/Telegram 必须）。Bun 不推荐。

步骤 9：Gateway Token

向导会生成一个 Gateway token（即使对于 loopback），并存储在 gateway.auth.token 中。

6.3 认证文件位置（重要）

OAuth 凭证（传统导入）：~/.openclaw/credentials/oauth.json

认证配置文件：~/.openclaw/agents//agent/auth-profiles.json

💡 无头服务器提示：先在普通机器上完成 OAuth，然后复制 oauth.json 到网关主机。

七、启动 Gateway

7.1 检查服务状态

如果向导中安装了服务，Gateway 应该已经在运行：

openclaw gateway status

7.2 手动启动

前台运行（调试）：

openclaw gateway --port 18789 --verbose

7.3 访问控制 UI

本地访问（Gateway 主机上）：

Dashboard: http://127.0.0.1:18789/

Control UI: http://127.0.0.1:18789/openclaw/

如果配置了 token，需要在 Control UI 设置中粘贴 token（存储为 connect.params.auth.token）。

7.4 停止/重启

# 停止
openclaw gateway stop

# 重启
openclaw gateway restart

7.5 快速验证（2分钟）

openclaw status
openclaw health
openclaw security audit --deep

💡 openclaw status --all 是最佳的可粘贴、只读调试报告。

八、连接即时通讯平台

8.1 WhatsApp（QR 登录）

# 启动配对登录
openclaw channels login

扫描说明：

• 打开手机 WhatsApp

• 进入 设置 → 已关联设备

• 扫描屏幕上的二维码

8.2 Telegram

方式一：向导配置

向导可以直接配置 Telegram Bot Token。

方式二：手动配置

创建 Telegram Bot：

• 访问 @BotFather

• 发送 /newbot

• 获取 Bot Token

配置：

openclaw configure --section channels.telegram
# 或手动编辑 ~/.openclaw/openclaw.json

Telegram DM 提示：你的第一条 DM 会返回配对代码。批准后（见下一节）机器人才能回复。

8.3 Discord

方式一：向导配置

向导可以直接配置 Discord Bot Token。

方式二：手动配置

创建 Discord 应用：

• 访问 Discord Developer Portal

• 创建应用，添加 Bot

• 获取 Bot Token

• 邀请 Bot 到服务器

配置：

openclaw configure --section channels.discord

8.4 iMessage（仅 macOS）

需要本地安装 imsg CLI：

# 安装 imsg
brew install keith/formulae/imsg

# 配置
openclaw configure --section channels.imessage

8.5 Mattermost（插件）

需要 Mattermost 插件 Token：

openclaw configure --section channels.mattermost

8.6 查看所有频道状态

# 查看所有频道状态
openclaw channels status

# 探测连通性
openclaw channels status --probe

九、DM 安全配对

9.1 默认安全策略

默认情况下：未知私聊会收到一个简短代码，消息不会被处理直到你批准。

9.2 批准配对

如果你的第一条 DM 没有回复，批准配对：

# 查看待处理配对
openclaw pairing list whatsapp
openclaw pairing list telegram

# 批准配对
openclaw pairing approve whatsapp <CODE>
openclaw pairing approve telegram <CODE>

# 拒绝配对
openclaw pairing deny whatsapp <CODE>

9.3 配置配对策略

{
  "channels": {
    "whatsapp": {
      "dmPolicy": "pairing",  // 配对策略
      "allowFrom": ["+15555550123"]  // 允许的白名单
    },
    "telegram": {
      "dmPolicy": "pairing",
      "allowFrom": [123456789]  // 用户 ID
    }
  }
}

十、常用命令大全

10.1 基础命令

# 查看版本
openclaw --version

# 查看帮助
openclaw --help

# 查看状态概览
openclaw status

# 完整诊断
openclaw status --all

# 健康检查
openclaw health
openclaw status --deep  # 深度健康检查

10.2 Gateway 管理

# 启动 Gateway
openclaw gateway start

# 停止 Gateway
openclaw gateway stop

# 重启 Gateway
openclaw gateway restart

# 查看状态
openclaw gateway status

# 手动前台运行（调试）
openclaw gateway --port 18789 --verbose

# 绑定模式
openclaw gateway --bind loopback    # 本地回环（默认）
openclaw gateway --bind lan         # 局域网
openclaw gateway --bind tailnet     # Tailscale 网络

10.3 配置管理

# 交互式配置
openclaw configure

# 查看完整配置
openclaw config get

# 查看特定配置
openclaw config get agents.defaults
openclaw config get models
openclaw config get channels.telegram

# 设置单个值
openclaw config set gateway.port 18789
openclaw config set agents.defaults.workspace ~/.openclaw/workspace

# 删除配置项
openclaw config unset gateway.port

# 配置文件位置
# ~/.openclaw/openclaw.json

10.4 模型管理

# 查看可用模型
openclaw models list

# 查看模型状态
openclaw models status

# 扫描可用模型
openclaw models scan

# 设置默认模型
openclaw models set anthropic/claude-sonnet-4-0

# 测试模型连接
openclaw models probe <model-name>

10.5 频道管理

# WhatsApp 登录（QR 扫描）
openclaw channels login

# 退出登录
openclaw channels logout

# 查看频道状态
openclaw channels status

# 探测频道
openclaw channels status --probe

10.6 配对管理

# 查看待处理配对
openclaw pairing list whatsapp
openclaw pairing list telegram

# 批准配对
openclaw pairing approve whatsapp <CODE>

# 拒绝配对
openclaw pairing deny whatsapp <CODE>

10.7 消息发送

# 发送文本消息
openclaw message send --target +15555550123 --message "Hello from OpenClaw"

# 发送文件
openclaw message send --target +15555550123 --file /path/to/file.txt

10.8 代理 (Agents)

# 查看代理列表
openclaw agents list

# 添加新代理
openclaw agents add work --workspace ~/.openclaw/work

# 查看代理状态
openclaw agents status work

10.9 会话管理

# 查看活跃会话
openclaw sessions list

# 查看会话历史
openclaw sessions history <session-key>

# 重置会话
openclaw sessions reset <session-key>

10.10 技能管理

# 列出已安装技能
openclaw skills list

# 安装技能
openclaw skills install skill-name

# 查看技能配置
openclaw skills config skill-name

# 更新技能
openclaw skills update skill-name

10.11 日志和诊断

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

# 查看最近 N 行
openclaw logs --limit 100

# 健康检查
openclaw health

# 诊断和修复
openclaw doctor
openclaw doctor --fix  # 自动修复

10.12 目录和工作区

# 查看工作区目录
openclaw directory

# 查看文件
ls -la ~/.openclaw/workspace/

10.13 更新和升级

# 检查更新
openclaw --version

# 更新 CLI（安装脚本）
curl -fsSL https://openclaw.ai/install.sh | bash

# 从源码更新
git pull origin main
pnpm install
pnpm build
openclaw doctor
openclaw gateway restart

10.14 安全相关

# 安全审计
openclaw security audit

# 深度审计
openclaw security audit --deep

十一、日常维护

11.1 定期检查

# 每日检查
openclaw status
openclaw health

# 每周检查
openclaw status --all
openclaw logs --limit 500 | grep -i error
openclaw doctor

11.2 日志管理

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

# 查找错误
openclaw logs --limit 1000 | grep -i "error\|failed"

# 按日期查看
ls -lt /tmp/openclaw/openclaw-*.log | head -5
tail -f /tmp/openclaw/openclaw-$(date +%Y-%m-%d).log

# 清理旧日志（保留最近7天）
find /tmp/openclaw -name "openclaw-*.log" -mtime +7 -delete

11.3 备份配置

# 备份配置文件
cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.backup.$(date +%Y%m%d)

# 备份认证文件
cp ~/.openclaw/agents/main/agent/auth-profiles.json ~/backups/auth-profiles.json.$(date +%Y%m%d)

# 备份工作区
tar -czvf ~/backups/openclaw-workspace-backup.$(date +%Y%m%d).tar.gz ~/.openclaw/workspace/

11.4 更新流程

# 1. 检查当前版本
openclaw --version

# 2. 停止 Gateway
openclaw gateway stop

# 3. 更新 CLI
curl -fsSL https://openclaw.ai/install.sh | bash

# 4. 运行健康检查
openclaw doctor

# 5. 重新启动
openclaw gateway start

# 6. 验证状态
openclaw status

11.5 监控告警（可选）

创建监控脚本：

cat > ~/.openclaw/monitor.sh << 'EOF'
#!/bin/bash
echo "=== $(date) ==="
openclaw status
openclaw health

# 检查 Gateway 是否运行
if ! openclaw gateway status | grep -q "running"; then
    echo "⚠️ Gateway 未运行，尝试重启..."
    openclaw gateway restart
fi
EOF

chmod +x ~/.openclaw/monitor.sh

添加 cron 任务：

# 每小时运行监控
crontab -e

# 添加：
0 * * * * ~/.openclaw/monitor.sh >> ~/.openclaw/monitor.log 2>&1

11.6 清理和维护

# 清理旧日志
find /tmp/openclaw -name "openclaw-*.log" -mtime +7 -delete

# 清理临时文件
rm -rf ~/.openclaw/tmp/*

# 清理会话缓存
openclaw sessions list | awk '{print $1}' | xargs -I {} openclaw sessions reset {}

十二、故障排除

12.1 快速诊断流程

# 1. 运行完整诊断
openclaw status --all

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

# 3. 运行医生检查
openclaw doctor
openclaw doctor --fix

12.2 常见问题

问题 1：命令找不到

# 检查是否安装
npm list -g --depth=0 | grep openclaw

# 查找安装位置
find /usr -name openclaw -type f 2>/dev/null
find ~/.npm -name openclaw -type f 2>/dev/null

# 手动添加 PATH
echo 'export PATH="$PATH:/usr/local/bin"' >> ~/.zshrc
source ~/.zshrc

问题 2：Gateway 无法启动

# 查看详细错误
openclaw gateway --verbose

# 检查端口占用
lsof -i :18789

# 检查配置
openclaw doctor

# 查看日志
openclaw logs --follow | tail -50

问题 3：无 API Key

# 重新配置
openclaw configure

# 或手动设置
export ANTHROPIC_API_KEY="sk-ant-api03-..."
echo 'export ANTHROPIC_API_KEY="sk-ant-api03-..."' >> ~/.openclaw/.env

# 验证
openclaw models status

问题 4：频道无响应

# 1. 检查频道状态
openclaw channels status --probe

# 2. 检查配对状态
openclaw pairing list <channel>

# 3. 查看日志
openclaw logs --follow | grep -i "channel\|pairing"

# 4. 如果是 WhatsApp，尝试重新登录
openclaw channels logout
openclaw channels login

问题 5：OAuth 失败

# 切换到 API key
openclaw configure
# 选择 Anthropic API key

# 或使用 setup-token
openclaw models auth setup-token --provider anthropic

# 手动复制 OAuth 凭证
# 从其他机器复制 ~/.openclaw/credentials/oauth.json

问题 6：模型不可用

# 查看可用模型
openclaw models list

# 设置已知模型
openclaw models set anthropic/claude-sonnet-4-0

# 扫描新模型
openclaw models scan

问题 7：内存不足

# 检查内存使用
top -o memory

# 限制历史记录
openclaw config set 'session.historyLimit' 50

# 重启 Gateway 释放内存
openclaw gateway restart

问题 8：国内网络问题

# 设置代理
export HTTPS_PROXY="http://127.0.0.1:7890"
export HTTP_PROXY="http://127.0.0.1:7890"

# 或在配置中设置
openclaw config set gateway.proxy.url "http://127.0.0.1:7890"

12.3 Bun 警告

⚠️ Bun + WhatsApp/Telegram：Bun 与这些频道存在已知问题。如果使用 WhatsApp 或 Telegram，请使用 Node 运行 Gateway。

# 确保使用 Node
which node
node --version

# 重启 Gateway
openclaw gateway restart

12.4 紧急恢复

# 1. 停止 Gateway
openclaw gateway stop

# 2. 备份当前配置
cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.emergency

# 3. 重置配置（保留工作区）
openclaw setup --reset config

# 4. 重新配置
openclaw onboard

# 5. 如果仍有问题，恢复配置
cp ~/.openclaw/openclaw.json.emergency ~/.openclaw/openclaw.json
openclaw gateway start

十三、安全加固

⚠️ 重要警告：OpenClaw Gateway 默认配置为本地使用，从未考虑过暴露在公网场景。错误配置可能导致：API Key 泄露、跨平台聊天记录泄露、主机系统完整访问权限泄露

13.1 安全检查

# 安全审计
openclaw security audit

# 深度审计
openclaw security audit --deep

13.2 必要的安全措施

1. 绑定本地回环地址

# 确保 Gateway 只监听本地
openclaw config set gateway.bind loopback
openclaw gateway restart

2. 启用认证

# 使用 Token 认证
openclaw config set gateway.auth.mode token
openclaw config set gateway.auth.token "your-strong-random-token"

3. 文件权限加固

# 限制配置文件权限
chmod 600 ~/.openclaw/openclaw.json

# 限制工作区权限
chmod 700 ~/.openclaw/workspace/

4. 防火墙配置

# 只允许本地访问
sudo ufw allow from 127.0.0.1 to any port 18789
sudo ufw deny 18789

13.3 沙箱配置

OpenClaw 支持沙箱隔离，限制代理的访问范围：

{
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "non-main",  // 主会话在主机，其他在沙箱
        "scope": "agent",
        "workspaceAccess": "rw"
      }
    }
  }
}

如果想让主代理始终在主机运行：

{
  "routing": {
    "agents": {
      "main": {
        "workspace": "~/.openclaw/workspace",
        "sandbox": { "mode": "off" }
      }
    }
  }
}

13.4 远程访问安全

如果需要远程访问，使用 Tailscale 或 SSH 隧道：

Tailscale（推荐）

# 安装 Tailscale
curl -fsSL https://tailscale.com/install.sh | bash

# 启动
sudo systemctl start tailscaled

# 连接你的 Tailscale 网络
sudo tailscale up

# 配置 OpenClaw 通过 Tailscale 暴露
openclaw gateway --bind tailnet --token "your-token"

SSH 隧道

# 从本地机器
ssh -L 18789:127.0.0.1:18789 user@gateway-host

13.5 云服务器安全组

端口	来源	用途
22	你的 IP	SSH
18789	Tailscale IP / VPN	OpenClaw Gateway

十四、从源码安装（开发模式）

如果你想为 OpenClaw 本身做贡献：

# 克隆仓库
git clone https://github.com/openclaw/openclaw.git
cd openclaw

# 安装依赖
pnpm install

# 构建 UI
pnpm ui:build  # 首次运行自动安装 UI 依赖

# 构建项目
pnpm build

# 运行向导并安装服务
openclaw onboard --install-daemon

如果还没有全局安装，可以通过 pnpm 运行：

pnpm openclaw onboard --install-daemon

Gateway（从源码运行）

node openclaw.mjs gateway --port 18789 --verbose

十五、常见问题

Q1: 需要多少内存？

A: 最低 2GB，推荐 4GB+。如果运行多个代理或大量