学习笔记
OpenClaw 完整安装教程
2026-02-19
AI
0

目录

OpenClaw 完整安装教程
📋 目录
一、系统要求
1.1 基础要求
1.2 检查 Node.js 版本
二、安装方式
2.1 npm 安装（推荐）⭐
2.2 pnpm 安装
2.3 bun 安装
2.4 从源码安装（开发版）
2.5 Docker 安装
2.6 命令行安装
三、首次配置
3.1 运行引导向导（强烈推荐）
3.2 配置文件详解
最小配置示例
完整配置示例
3.3 AI 模型配置
Anthropic Claude（强烈推荐）
OpenAI GPT
其他模型
3.4 通讯频道配置
Telegram 配置
WhatsApp 配置
Slack 配置
Discord 配置
四、启动与使用
4.1 启动 Gateway
4.2 检查状态
4.3 基本命令
4.4 聊天命令
五、卸载方法
5.1 npm 卸载
5.2 停止并移除守护进程
5.3 Docker 卸载
5.4 完全清理
六、常见问题与解决方案
6.1 安装问题
Q1: 安装时出现权限错误
Q2: Node.js 版本不兼容
Q3: 安装后命令找不到
6.2 启动问题
Q4: Gateway 启动失败 - 端口被占用
Q5: 配置文件格式错误
Q6: 守护进程无法启动
6.3 AI 模型问题
Q7: API Key 无效
Q8: 模型响应缓慢或超时
Q9: 模型切换不生效
6.4 通讯频道问题
Q10: Telegram Bot 不响应
Q11: WhatsApp 断开连接
Q12: Discord DM 无法接收
6.5 工具使用问题
Q13: 浏览器控制无法使用
Q14: Web 搜索返回错误
6.6 性能问题
Q15: 内存占用过高
Q16: 响应速度慢
七、高级配置
7.1 多模型故障转移
7.2 Tailscale 远程访问
7.3 沙盒安全配置
7.4 自定义 Skills
7.5 Cron 定时任务
八、更新 OpenClaw
九、获取帮助
9.1 官方资源
9.2 诊断工具
9.3 调试模式
十、安全建议

OpenClaw 完整安装教程

版本说明: 本教程基于 OpenClaw 最新版本（2025年2月）

官方资源:

📋 目录

  1. 系统要求
  2. 安装方式
    • npm 安装（推荐）
    • pnpm 安装
    • bun 安装
    • 源码安装
    • Docker 安装
    • 命令行安装
  3. 首次配置
    • 运行引导向导
    • 配置文件详解
    • AI 模型配置
    • 通讯频道配置
  4. 启动与使用
  5. 卸载方法
  6. 常见问题与解决方案
  7. 高级配置

一、系统要求

1.1 基础要求

项目要求
Node.js≥ 22 （必须）
操作系统macOS / Linux / Windows (WSL2)
包管理器npm / pnpm / bun
内存建议 4GB+
磁盘空间至少 2GB 可用空间

1.2 检查 Node.js 版本

bash
node --version
# 输出应该 >= v22.0.0

如果版本过低，请先升级 Node.js：

bash
# 使用 nvm 升级（推荐）
nvm install 22
nvm use 22

# 或使用官方安装包
# https://nodejs.org/

二、安装方式

2.1 npm 安装（推荐）⭐

这是最简单、最推荐的安装方式：

bash
# 全局安装 OpenClaw
npm install -g openclaw@latest

# 验证安装
openclaw --version

2.2 pnpm 安装

bash
# 使用 pnpm 安装
pnpm add -g openclaw@latest

# 验证安装
openclaw --version

2.3 bun 安装

bash
# 使用 bun 安装
bun add -g openclaw@latest

# 验证安装
openclaw --version

2.4 从源码安装（开发版）

适合想参与开发或使用最新功能的用户：

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

# 安装依赖（推荐使用 pnpm）
pnpm install

# 构建 UI
pnpm ui:build

# 构建项目
pnpm build

# 运行引导向导
pnpm openclaw onboard --install-daemon

# 开发模式（自动重载）
pnpm gateway:watch

2.5 Docker 安装

bash
# 拉取镜像
docker pull openclaw/openclaw:latest

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

2.6 命令行安装

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

详细 Docker 配置请参考：https://docs.openclaw.ai/install/docker

三、首次配置

3.1 运行引导向导（强烈推荐）

OpenClaw 提供了一个交互式向导，会一步步引导你完成配置：

bash
# 运行向导并安装守护进程
openclaw onboard --install-daemon

向导会帮助你配置：

  • ✅ Gateway 服务
  • ✅ 工作目录
  • ✅ 通讯频道（WhatsApp、Telegram、Slack 等）
  • ✅ AI 模型
  • ✅ Skills 技能

3.2 配置文件详解

配置文件位于：~/.openclaw/openclaw.json

最小配置示例

json5
{
  "agent": {
    "model": "anthropic/claude-opus-4-6"
  }
}

完整配置示例

json5
{
  // === AI 模型配置 ===
  "agent": {
    // 默认使用的 AI 模型
    "model": "anthropic/claude-opus-4-6",
    
    // 思考级别: off | minimal | low | medium | high | xhigh
    "thinking": "medium",
    
    // 工作空间路径
    "workspace": "~/.openclaw/workspace",
    
    // 默认行为
    "defaults": {
      // 沙盒模式: off | non-main | all
      "sandbox": {
        "mode": "non-main"
      }
    }
  },
  
  // === Gateway 配置 ===
  "gateway": {
    // 监听地址
    "bind": "loopback",
    
    // 端口号
    "port": 18789,
    
    // 详细日志
    "verbose": false,
    
    // 身份验证
    "auth": {
      "mode": "tailscale",  // none | password | tailscale
      "password": "your-secure-password"
    },
    
    // Tailscale 配置（可选）
    "tailscale": {
      "mode": "off",  // off | serve | funnel
      "resetOnExit": false
    }
  },
  
  // === 通讯频道配置 ===
  "channels": {
    // Telegram 配置
    "telegram": {
      "botToken": "123456:ABCDEF",
      "allowFrom": ["your_telegram_id"],
      "groups": {
        "*": {
          "requireMention": true
        }
      }
    },
    
    // WhatsApp 配置
    "whatsapp": {
      "allowFrom": ["+86138xxxxxxxx"],
      "groups": ["*"]
    },
    
    // Slack 配置
    "slack": {
      "botToken": "xoxb-xxx",
      "appToken": "xapp-xxx",
      "allowFrom": ["U123456"]
    },
    
    // Discord 配置
    "discord": {
      "token": "MTIx...",
      "allowFrom": ["123456789"],
      "dmPolicy": "pairing"  // pairing | open
    },
    
    // Signal 配置
    "signal": {
      "account": "+86138xxxxxxxx",
      "allowFrom": ["+86138xxxxxxxx"]
    }
  },
  
  // === 模型提供商配置 ===
  "models": {
    "anthropic": {
      "apiKey": "sk-ant-api...",
      "maxTokens": 8192
    },
    "openai": {
      "apiKey": "sk-...",
      "maxTokens": 4096
    }
  },
  
  // === 工具配置 ===
  "tools": {
    // 浏览器配置
    "browser": {
      "enabled": true,
      "color": "#FF4500"
    },
    
    // Web 搜索配置
    "web": {
      "braveApiKey": "your-brave-api-key"
    }
  }
}

3.3 AI 模型配置

OpenClaw 支持多种 AI 模型，推荐配置如下：

Anthropic Claude（强烈推荐）

json5
{
  "agent": {
    "model": "anthropic/claude-opus-4-6"
  },
  "models": {
    "anthropic": {
      "apiKey": "sk-ant-api03-..."
    }
  }
}

获取 API Key: https://console.anthropic.com/

OpenAI GPT

json5
{
  "agent": {
    "model": "openai/gpt-4o"
  },
  "models": {
    "openai": {
      "apiKey": "sk-..."
    }
  }
}

其他模型

json5
// Moonshot / 月之暗面
"agent": { "model": "moonshot/kimi-k2.5" }

// Google Gemini
"agent": { "model": "google/gemini-2.0-flash" }

// DeepSeek
"agent": { "model": "deepseek/deepseek-chat" }

3.4 通讯频道配置

Telegram 配置

  1. 创建 Bot：

    • 与 @BotFather 对话
    • 发送 /newbot
    • 获取 Bot Token

  2. 获取你的 Chat ID：

  3. 配置：

json5
{
  "channels": {
    "telegram": {
      "botToken": "123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11",
      "allowFrom": ["123456789"]
    }
  }
}

WhatsApp 配置

bash
# 登录 WhatsApp
openclaw channels login

按提示扫描二维码即可。

Slack 配置

  1. 创建 Slack App: https://api.slack.com/apps
  2. 获取 Bot Token 和 App Token
  3. 配置：
json5
{
  "channels": {
    "slack": {
      "botToken": "xoxb-xxx",
      "appToken": "xapp-xxx",
      "allowFrom": ["U12345678"]
    }
  }
}

Discord 配置

  1. 创建 Bot: https://discord.com/developers/applications
  2. 获取 Bot Token
  3. 配置：
json5
{
  "channels": {
    "discord": {
      "token": "MTIx...",
      "allowFrom": ["123456789"],
      "dmPolicy": "pairing"
    }
  }
}

四、启动与使用

4.1 启动 Gateway

bash
# 前台启动（查看日志）
openclaw gateway --verbose

# 指定端口启动
openclaw gateway --port 18789 --verbose

# 后台启动（通过守护进程）
openclaw gateway start

4.2 检查状态

bash
# 查看 Gateway 状态
openclaw gateway status

# 运行诊断
openclaw doctor

4.3 基本命令

bash
# 发送消息
openclaw message send --to +1234567890 --message "Hello from OpenClaw"

# 与 AI 对话
openclaw agent --message "你好，介绍一下自己"

# 查看帮助
openclaw --help
openclaw gateway --help

4.4 聊天命令

在与 AI 对话时可以使用以下命令：

命令说明
/status查看当前会话状态
/new 或 /reset重置会话
/compact压缩会话上下文
/think <级别>设置思考级别
/verbose on/off开启/关闭详细模式
/usage查看使用量
/restart重启 Gateway（仅限拥有者）

五、卸载方法

5.1 npm 卸载

bash
# 卸载全局包
npm uninstall -g openclaw

# 清理配置文件（可选）
rm -rf ~/.openclaw

5.2 停止并移除守护进程

bash
# macOS (launchd)
launchctl unload ~/Library/LaunchAgents/com.openclaw.gateway.plist
rm ~/Library/LaunchAgents/com.openclaw.gateway.plist

# Linux (systemd)
systemctl --user stop openclaw-gateway
systemctl --user disable openclaw-gateway
rm ~/.config/systemd/user/openclaw-gateway.service

5.3 Docker 卸载

bash
# 停止并删除容器
docker stop openclaw
docker rm openclaw

# 删除镜像
docker rmi openclaw/openclaw:latest

# 清理数据卷（谨慎操作）
rm -rf ~/.openclaw

5.4 完全清理

bash
# 删除所有 OpenClaw 相关数据
rm -rf ~/.openclaw
rm -rf ~/Library/Logs/openclaw        # macOS 日志
rm -rf ~/.cache/openclaw              # 缓存

六、常见问题与解决方案

6.1 安装问题

Q1: 安装时出现权限错误

错误信息:

npm ERR! code EACCES
npm ERR! syscall access

解决方案:

bash
# 方法1：修改 npm 默认目录
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc
npm install -g openclaw@latest

# 方法2：使用 npx（无需全局安装）
npx openclaw@latest ...

# 方法3：使用 sudo（不推荐）
sudo npm install -g openclaw@latest

Q2: Node.js 版本不兼容

错误信息:

error openclaw@x.x.x: The engine "node" is incompatible with this module

解决方案:

bash
# 使用 nvm 安装 Node.js 22
nvm install 22
nvm use 22
nvm alias default 22

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

Q3: 安装后命令找不到

解决方案:

bash
# 检查全局安装路径
npm config get prefix

# 添加到 PATH
echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# 验证
which openclaw

6.2 启动问题

Q4: Gateway 启动失败 - 端口被占用

错误信息:

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

解决方案:

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

# 杀死进程
kill -9 <PID>

# 或使用其他端口
openclaw gateway --port 18790

Q5: 配置文件格式错误

错误信息:

SyntaxError: Unexpected token } in JSON at position ...

解决方案:

bash
# 验证 JSON 格式
openclaw doctor

# 或使用在线工具验证 ~/.openclaw/openclaw.json
# 注意：JSON5 允许注释，但必须是有效的 JSON5 格式

Q6: 守护进程无法启动

解决方案:

bash
# macOS
launchctl list | grep openclaw
launchctl start com.openclaw.gateway

# Linux
systemctl --user status openclaw-gateway
systemctl --user restart openclaw-gateway
journalctl --user -u openclaw-gateway -f

6.3 AI 模型问题

Q7: API Key 无效

错误信息:

401 Unauthorized - Invalid API key

解决方案:

  1. 检查 API Key 是否正确
  2. 确认 API Key 有可用额度
  3. 检查配置文件中的 Key 是否被正确转义
bash
# 测试 API Key
curl https://api.anthropic.com/v1/models \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01"

Q8: 模型响应缓慢或超时

解决方案:

json5
// 在配置中添加超时设置
{
  "agent": {
    "model": "anthropic/claude-opus-4-6",
    "timeout": 120000  // 120秒
  }
}

Q9: 模型切换不生效

解决方案:

bash
# 重启 Gateway
openclaw gateway restart

# 或使用命令行指定模型
openclaw agent --model openai/gpt-4o --message "Hello"

6.4 通讯频道问题

Q10: Telegram Bot 不响应

排查步骤:

  1. 检查 Bot Token 是否正确
  2. 确认已向 Bot 发送 /start
  3. 检查 allowFrom 是否包含你的 Chat ID
  4. 查看 Gateway 日志
bash
openclaw gateway --verbose

Q11: WhatsApp 断开连接

解决方案:

bash
# 重新登录
openclaw channels login

# 检查 creds 文件
ls ~/.openclaw/credentials/whatsapp/

Q12: Discord DM 无法接收

解决方案:

json5
{
  "channels": {
    "discord": {
      "dmPolicy": "pairing",  // 改为 "open" 允许所有人
      "allowFrom": ["*"]      // 允许所有用户
    }
  }
}

6.5 工具使用问题

Q13: 浏览器控制无法使用

解决方案:

bash
# 确保已安装 Chrome/Chromium
# macOS
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --version

# Linux
google-chrome --version

# 在配置中启用浏览器
{
  "browser": {
    "enabled": true
  }
}

Q14: Web 搜索返回错误

错误信息:

missing_brave_api_key

解决方案:

  1. 获取 Brave API Key: https://brave.com/search/api/
  2. 配置 Key：
bash
openclaw configure --section web
# 或手动编辑配置文件
{
  "tools": {
    "web": {
      "braveApiKey": "your-api-key"
    }
  }
}

6.6 性能问题

Q15: 内存占用过高

解决方案:

json5
{
  "agent": {
    // 启用会话修剪
    "pruneSessions": true,
    "maxSessionAge": 3600000  // 1小时
  }
}

Q16: 响应速度慢

优化建议:

  1. 使用更快的模型（如 Claude Haiku 或 GPT-3.5）
  2. 启用流式响应
  3. 减少上下文长度
json5
{
  "agent": {
    "model": "anthropic/claude-haiku",
    "streaming": true,
    "contextWindow": 4000
  }
}

七、高级配置

7.1 多模型故障转移

json5
{
  "agent": {
    "model": "anthropic/claude-opus-4-6",
    "fallbackModels": [
      "openai/gpt-4o",
      "moonshot/kimi-k2.5"
    ]
  }
}

7.2 Tailscale 远程访问

json5
{
  "gateway": {
    "bind": "loopback",
    "auth": {
      "mode": "tailscale"
    },
    "tailscale": {
      "mode": "serve",  // serve 或 funnel
      "resetOnExit": false
    }
  }
}

7.3 沙盒安全配置

json5
{
  "agent": {
    "defaults": {
      "sandbox": {
        "mode": "non-main",  // 非主会话使用 Docker 沙盒
        "allowlist": ["bash", "read", "write", "edit"],
        "denylist": ["browser", "cron", "gateway"]
      }
    }
  }
}

7.4 自定义 Skills

bash
# 安装技能
openclaw skills install weather
openclaw skills install 1password

# 查看已安装技能
openclaw skills list

# 更新技能
openclaw skills update

7.5 Cron 定时任务

bash
# 添加定时任务
openclaw cron add --name "daily-summary" \
  --schedule "0 9 * * *" \
  --message "总结今天的日程"

# 列出定时任务
openclaw cron list

# 删除定时任务
openclaw cron remove --name "daily-summary"

八、更新 OpenClaw

bash
# 检查更新
openclaw --version

# 更新到最新版本
npm update -g openclaw@latest

# 或重新安装
npm install -g openclaw@latest

# 运行迁移
openclaw doctor

九、获取帮助

9.1 官方资源

9.2 诊断工具

bash
# 运行完整诊断
openclaw doctor

# 查看日志
openclaw logs

# 检查配置
openclaw config get

9.3 调试模式

bash
# 开启详细日志
openclaw gateway --verbose

# 调试特定频道
DEBUG=telegram:* openclaw gateway

十、安全建议

  1. 保护 API Keys: 不要将 API Keys 提交到 Git
  2. 使用 allowlist: 配置 allowFrom 限制谁可以与 Bot 交互
  3. 启用 DM 配对: 默认使用 dmPolicy: "pairing"
  4. 定期更新: 保持 OpenClaw 和依赖项更新
  5. 审查权限: 定期运行 openclaw doctor 检查配置

恭喜！ 你已经完成了 OpenClaw 的完整安装配置。现在可以开始与你的个人 AI 助手对话了！

如果遇到问题，记得查看第六部分的常见问题，或加入 Discord 社区寻求帮助。

本文作者:JACK WEI

本文链接:

版权声明:本博客所有文章除特别声明外，均采用 BY-NC-SA 许可协议。转载请注明出处！