折腾侠
技术教程

OpenClaw 详细搭建教程：2026 年从零部署你的 AI Agent 网关

8000+ 字详细教程，涵盖 OpenClaw 安装、配置、频道连接、高级配置和常见问题

折
折腾侠
2026/03/16 发布
141约 14 分钟2086 字 / 1939 词00

OpenClaw 详细搭建教程：2026 年从零部署你的 AI Agent 网关

本文长度： 约 8,000 字
阅读时间： 20-25 分钟
适合人群： 开发者、运维人员、AI 爱好者
最后更新： 2026-03-16
难度等级： ⭐⭐⭐ 中等（有详细步骤）

📚 目录

  1. [什么是 OpenClaw？](#1-什么是 openclaw)
  2. 前置要求
  3. 安装步骤（全平台）
  4. 配置详解
  5. 连接聊天频道
  6. 使用指南
  7. 高级配置
  8. 常见问题
  9. 总结与下一步

1. 什么是 OpenClaw？

1.1 核心概念

OpenClaw 是一个自托管的 AI Agent 网关，它将你常用的聊天应用（WhatsApp、Telegram、Discord、微信等）与 AI 编程助手连接起来。

简单来说：你可以在任何聊天软件中给 AI 发消息，它就像你的私人助理一样随时响应。

1.2 核心特性

特性说明
自托管运行在你自己的服务器上，数据完全可控
多频道一个网关同时支持 WhatsApp、Telegram、Discord 等
多 Agent 路由可以为不同用户/场景分配不同的 AI 模型
媒体支持发送/接收图片、音频、文档
Web 控制台浏览器仪表盘，无需聊天软件也能用
移动端支持可配对 iOS/Android 节点

1.3 适用场景

个人使用：

  • 在微信/Telegram 中随时问 AI 问题
  • 用手机就能让 AI 写代码、查资料
  • 私人数据不经过第三方服务

团队使用：

  • 为不同成员配置不同的 AI 模型
  • 统一的 AI 服务入口
  • 可控的访问权限和审计日志

开发者使用：

  • 快速搭建 AI 聊天机器人
  • 测试不同的 AI 模型和提示词
  • 集成自定义工具和 API

1.4 架构概览

┌─────────────────────────────────────────────────────────┐
│                    聊天应用                              │
│  WhatsApp  │  Telegram  │  Discord  │  微信  │  iMessage │
└─────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────┐
│              OpenClaw Gateway（网关）                    │
│  - 消息路由                                              │
│  - 会话管理                                              │
│  - Agent 调度                                            │
│  - 插件系统                                              │
└─────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────┐
│                    AI Agent                              │
│  - Pi (内置)                                             │
│  - Claude / GPT / Qwen 等                               │
│  - 自定义 Agent                                          │
└─────────────────────────────────────────────────────────┘

2. 前置要求

2.1 硬件要求

配置最低要求推荐配置
CPU1 核2 核+
内存512MB1GB+
存储100MB500MB+
网络可访问互联网固定 IP（可选）

2.2 软件要求

必选：

  • Node.js：版本 24 推荐（22.16+ 兼容）
  • npm：随 Node.js 一起安装

可选：

  • Docker：如果用 Docker 部署
  • PM2：如果用 PM2 管理进程
  • Git：如果从源码安装

2.3 检查环境

检查 Node.js 版本：

Bash
node --version
# 输出示例：v24.14.0

检查 npm 版本：

Bash
npm --version
# 输出示例：11.0.0

如果 Node.js 版本过低，需要升级：

Bash
# 使用 nvm（推荐）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 24
nvm use 24

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

2.4 API 密钥准备

需要准备的 API 密钥：

服务用途获取地址
AI 模型提供 AI 能力根据选择的模型而定
WhatsApp连接 WhatsAppMeta Developer
Telegram连接 TelegramTelegram BotFather
其他根据需求准备-

提示： OpenClaw 内置了 Pi Agent，初次使用可以不用配置外部 AI API。

3. 安装步骤（全平台）

3.1 macOS / Linux 安装（推荐）

步骤 1：运行安装脚本

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

安装过程：

🦞 OpenClaw Installer

Downloading OpenClaw...
Installing dependencies...
Setting up configuration...
Installing service...

✅ Installation complete!

Next steps:
1. Run 'openclaw onboard' to configure
2. Run 'openclaw gateway' to start

步骤 2：验证安装

Bash
openclaw --version
# 输出示例：openclaw/1.0.0 linux-x64 node-v24.14.0

步骤 3：查看帮助

Bash
openclaw --help

输出示例：

OpenClaw - AI Agent Gateway

USAGE:
  openclaw <command> [options]

COMMANDS:
  onboard          初始化配置向导
  gateway          启动网关服务
  dashboard        打开 Web 控制台
  channels         管理聊天频道
  message          发送消息
  sessions         管理会话
  nodes            管理移动节点
  config           查看/编辑配置
  status           查看状态

OPTIONS:
  -h, --help       显示帮助信息
  -v, --version    显示版本号

3.2 Windows 安装

步骤 1：PowerShell 安装

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

步骤 2：验证安装

PowerShell
openclaw --version

注意： Windows 需要以管理员身份运行 PowerShell。

3.3 使用 npm 安装（备选）

如果安装脚本不可用，可以用 npm 直接安装：

Bash
npm install -g openclaw@latest

验证安装：

Bash
openclaw --version

3.4 从源码安装（高级）

步骤 1：克隆仓库

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

步骤 2：安装依赖

Bash
npm install

步骤 3：构建

Bash
npm run build

步骤 4：链接到全局

Bash
npm link

步骤 5：验证

Bash
openclaw --version

3.5 安装后检查清单

  • INLINE_CODE_0 显示版本号
  • INLINE_CODE_1 显示帮助信息
  • 配置文件目录创建：INLINE_CODE_2
  • 可以执行 INLINE_CODE_3

4. 配置详解

4.1 运行配置向导（推荐）

最简单的配置方式：

Bash
openclaw onboard --install-daemon

向导会引导你完成：

  1. 选择 AI 模型提供商
  2. 输入 API 密钥
  3. 配置网关端口
  4. 选择要连接的频道
  5. 设置安全选项

向导示例：

🦞 OpenClaw Setup Wizard

Step 1/5: Choose AI Provider
  1) Pi (内置，免费)
  2) Claude (Anthropic)
  3) GPT (OpenAI)
  4) Qwen (阿里云)
  5) 自定义

选择 [1]: 1
✅ 已选择 Pi (内置)

Step 2/5: Gateway Port
默认端口：18789
端口 [18789]: 
✅ 端口：18789

Step 3/5: Install as Service?
安装为系统服务，开机自启动
是否安装？[Y/n]: Y
✅ 服务已安装

Step 4/5: Configure Channels?
配置聊天频道（可稍后配置）
是否现在配置？[y/N]: N
✅ 稍后配置

Step 5/5: Setup Complete!

配置已保存到：~/.openclaw/openclaw.json
服务已启动：openclaw gateway status
控制台：openclaw dashboard

🎉 恭喜！OpenClaw 已就绪。

4.2 配置文件位置

默认位置：

~/.openclaw/openclaw.json

查看配置：

Bash
openclaw config

编辑配置：

Bash
openclaw config --edit
# 或手动编辑
nano ~/.openclaw/openclaw.json

4.3 配置文件详解

完整配置示例：

JSON5
{
  // AI 模型配置
  "ai": {
    "provider": "pi",  // pi | claude | openai | qwen
    "model": "latest",
    "apiKey": "sk-xxx",  // 某些提供商需要
    "baseUrl": "https://api.xxx.com"  // 自定义 API 地址
  },
  
  // 网关配置
  "gateway": {
    "port": 18789,
    "host": "0.0.0.0",
    "allowOrigins": ["*"],
    "rateLimit": {
      "enabled": true,
      "maxRequests": 100,
      "windowMs": 60000
    }
  },
  
  // 频道配置
  "channels": {
    "whatsapp": {
      "enabled": false,
      "phoneNumber": "+1234567890",
      "allowFrom": ["+15555550123"],  // 允许的用户
      "groups": {
        "*": {
          "requireMention": true  // 群聊需要@才响应
        }
      }
    },
    "telegram": {
      "enabled": false,
      "botToken": "123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11",
      "allowFrom": ["@username"],
      "groups": {
        "*": {
          "requireMention": true
        }
      }
    },
    "discord": {
      "enabled": false,
      "botToken": "xxx",
      "clientId": "xxx",
      "allowFrom": ["user-id"],
      "guilds": {
        "*": {
          "requireMention": true
        }
      }
    }
  },
  
  // 消息配置
  "messages": {
    "groupChat": {
      "mentionPatterns": ["@openclaw", "@bot"]
    },
    "defaultReply": false,  // 默认不回复（需要@）
    "maxContextLength": 100  // 上下文消息数量
  },
  
  // 会话配置
  "sessions": {
    "mode": "per-sender",  // per-sender | per-channel | global
    "timeout": 3600,  // 会话超时时间（秒）
    "maxSessions": 100
  },
  
  // 日志配置
  "logging": {
    "level": "info",  // debug | info | warn | error
    "file": "~/.openclaw/openclaw.log",
    "maxSize": "10MB",
    "maxFiles": 5
  }
}

4.4 环境变量（可选）

可以用环境变量覆盖配置：

Bash
# 自定义配置目录
export OPENCLAW_HOME=/custom/path
export OPENCLAW_STATE_DIR=/custom/state
export OPENCLAW_CONFIG_PATH=/custom/config.json

# API 密钥
export OPENCLAW_AI_API_KEY=sk-xxx
export OPENCLAW_TELEGRAM_BOT_TOKEN=xxx

5. 连接聊天频道

5.1 WhatsApp 连接

步骤 1：创建 WhatsApp Business API

  1. 访问 Meta Developer
  2. 创建应用
  3. 添加 WhatsApp 产品
  4. 获取 Phone Number ID 和 Access Token

步骤 2：配置 OpenClaw

JSON
{
  "channels": {
    "whatsapp": {
      "enabled": true,
      "phoneNumber": "+1234567890",
      "accessToken": "EAAB..."
    }
  }
}

步骤 3：验证 webhook

Bash
openclaw channels whatsapp verify

步骤 4：测试

Bash
openclaw message send --target +15555550123 --message "Hello from OpenClaw"

5.2 Telegram 连接

步骤 1：创建 Bot

  1. 在 Telegram 搜索 INLINE_CODE_4
  2. 发送 INLINE_CODE_5
  3. 按提示设置 bot 名称
  4. 获取 Token

步骤 2：配置 OpenClaw

JSON
{
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11"
    }
  }
}

步骤 3：启动 Bot

Bash
openclaw channels telegram start

步骤 4：测试

在 Telegram 搜索你的 bot，发送消息测试。

5.3 Discord 连接

步骤 1：创建 Discord 应用

  1. 访问 Discord Developer Portal
  2. 创建新应用
  3. 创建 Bot
  4. 获取 Token 和 Client ID
  5. 邀请 Bot 到服务器

步骤 2：配置 OpenClaw

JSON
{
  "channels": {
    "discord": {
      "enabled": true,
      "botToken": "xxx",
      "clientId": "xxx",
      "guildId": "xxx"  // 可选，限制特定服务器
    }
  }
}

步骤 3：启动 Bot

Bash
openclaw channels discord start

5.4 微信连接（通过 WeChaty）

注意： 微信需要额外的插件支持。

步骤 1：安装 WeChaty 插件

Bash
npm install -g @openclaw/channel-wechat

步骤 2：配置

JSON
{
  "channels": {
    "wechat": {
      "enabled": true,
      "puppet": "wechaty-puppet-service",
      "token": "xxx"
    }
  }
}

5.5 频道管理命令

查看所有频道：

Bash
openclaw channels list

启用频道：

Bash
openclaw channels telegram enable

禁用频道：

Bash
openclaw channels whatsapp disable

重启频道：

Bash
openclaw channels telegram restart

6. 使用指南

6.1 启动网关

作为服务启动（推荐）：

Bash
# 检查服务状态
openclaw gateway status

# 启动服务
openclaw gateway start

# 停止服务
openclaw gateway stop

# 重启服务
openclaw gateway restart

前台运行（调试用）：

Bash
openclaw gateway --port 18789

输出示例：

🦞 OpenClaw Gateway v1.0.0

[INFO] Starting gateway...
[INFO] Loading configuration...
[INFO] AI Provider: Pi (built-in)
[INFO] Channels: WhatsApp, Telegram
[INFO] Gateway listening on http://0.0.0.0:18789
[INFO] Control UI: http://127.0.0.1:18789/
[INFO] Ready to accept messages!

Press Ctrl+C to stop.

6.2 打开 Web 控制台

最简单的方式：

Bash
openclaw dashboard

或手动访问：

控制台功能：

  • 💬 聊天界面 - 直接和 AI 对话
  • ⚙️ 配置管理 - 修改配置无需重启
  • 📊 会话查看 - 查看所有活跃会话
  • 📈 统计信息 - 消息数量、响应时间等
  • 🔧 频道管理 - 启用/禁用频道

6.3 发送消息

通过 CLI 发送：

Bash
openclaw message send \
  --target +15555550123 \
  --message "Hello from OpenClaw"

带选项发送：

Bash
openclaw message send \
  --channel whatsapp \
  --target +15555550123 \
  --message "这是一条测试消息" \
  --reply-to message-id-123

6.4 管理会话

查看所有会话：

Bash
openclaw sessions list

查看会话详情：

Bash
openclaw sessions show <session-id>

清除会话：

Bash
openclaw sessions clear <session-id>

清除所有会话：

Bash
openclaw sessions clear --all

6.5 查看日志

实时日志：

Bash
openclaw logs --follow

最近 100 行：

Bash
openclaw logs --lines 100

错误日志：

Bash
openclaw logs --level error

日志文件位置：

~/.openclaw/openclaw.log

7. 高级配置

7.1 多 Agent 路由

为不同用户分配不同的 AI 模型：

JSON
{
  "routing": {
    "rules": [
      {
        "from": "+15555550123",
        "agent": "claude",
        "model": "claude-4"
      },
      {
        "from": "+15555550124",
        "agent": "gpt",
        "model": "gpt-5"
      },
      {
        "default": true,
        "agent": "pi",
        "model": "latest"
      }
    ]
  }
}

7.2 安全配置

IP 白名单：

JSON
{
  "security": {
    "allowIPs": ["192.168.1.0/24", "10.0.0.1"],
    "denyIPs": ["1.2.3.4"]
  }
}

API 密钥认证：

JSON
{
  "security": {
    "requireAuth": true,
    "apiKeys": ["key-1", "key-2"]
  }
}

速率限制：

JSON
{
  "security": {
    "rateLimit": {
      "enabled": true,
      "maxRequests": 100,
      "windowMs": 60000,
      "message": "请求过于频繁，请稍后再试"
    }
  }
}

7.3 自定义提示词

设置系统提示词：

JSON
{
  "ai": {
    "systemPrompt": "你是一个专业的编程助手，擅长 Python、JavaScript 和 DevOps。请用简洁、实用的方式回答问题。"
  }
}

针对不同频道的提示词：

JSON
{
  "ai": {
    "channelPrompts": {
      "telegram": "你是一个 Telegram 聊天机器人，回答要简短有趣。",
      "discord": "你是一个 Discord 社区助手，语气要友好专业。",
      "whatsapp": "你是一个 WhatsApp 私人助理，回答要实用直接。"
    }
  }
}

7.4 远程访问

配置 Tailscale（推荐）：

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

# 登录
tailscale up

# 获取 Tailscale IP
tailscale ip

配置 Nginx 反向代理：

Nginx
server {
    listen 443 ssl;
    server_name openclaw.example.com;
    
    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;
    
    location / {
        proxy_pass http://127.0.0.1:18789;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
    }
}

7.5 性能优化

调整并发：

JSON
{
  "performance": {
    "maxConcurrentSessions": 50,
    "messageQueueSize": 1000,
    "workerThreads": 4
  }
}

缓存配置：

JSON
{
  "performance": {
    "cache": {
      "enabled": true,
      "type": "redis",
      "host": "localhost",
      "port": 6379,
      "ttl": 3600
    }
  }
}

8. 常见问题

8.1 安装问题

Q1: 安装脚本报错 INLINE_CODE_6

解决：

Bash
# 添加执行权限
chmod +x install.sh
./install.sh

# 或使用 sudo
sudo curl -fsSL https://openclaw.ai/install.sh | bash

Q2: INLINE_CODE_7

解决：

Bash
# 检查 npm 全局 bin 目录
npm config get prefix

# 添加到 PATH
export PATH=$(npm config get prefix)/bin:$PATH

# 永久添加（添加到 ~/.bashrc 或 ~/.zshrc）
echo 'export PATH=$(npm config get prefix)/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

Q3: Node.js 版本不兼容

解决：

Bash
# 使用 nvm 安装 Node 24
nvm install 24
nvm use 24
nvm alias default 24

8.2 启动问题

Q4: 端口已被占用

错误： INLINE_CODE_8

解决：

Bash
# 查找占用端口的进程
lsof -i :18789

# 杀死进程
kill -9 <PID>

# 或修改配置使用其他端口
openclaw gateway --port 18790

Q5: 配置文件语法错误

错误： INLINE_CODE_9

解决：

Bash
# 验证 JSON 格式
cat ~/.openclaw/openclaw.json | jq .

# 修复配置文件
nano ~/.openclaw/openclaw.json

8.3 频道连接问题

Q6: WhatsApp 无法连接

检查：

  1. Phone Number ID 是否正确
  2. Access Token 是否过期
  3. Webhook URL 是否配置正确
  4. 防火墙是否开放

解决：

Bash
# 重新验证 webhook
openclaw channels whatsapp verify

# 查看日志
openclaw logs --channel whatsapp

Q7: Telegram Bot 无响应

检查：

  1. Bot Token 是否正确
  2. Bot 是否被拉黑
  3. 隐私模式是否关闭

解决：

Bash
# 在 @BotFather 中检查设置
# 关闭 Group Privacy

# 重启频道
openclaw channels telegram restart

Q8: Discord Bot 无法加入服务器

检查：

  1. OAuth2 URL 是否正确
  2. Bot 权限是否足够
  3. 服务器是否达到 Bot 上限

解决：

Bash
# 重新生成邀请链接
# https://discord.com/developers/applications/<app-id>/oauth2

# 确保选择正确的 scopes: bot, applications.commands

8.4 性能问题

Q9: 响应速度慢

优化：

JSON
{
  "performance": {
    "cache": {
      "enabled": true
    },
    "workerThreads": 4
  }
}

检查：

  1. 网络延迟
  2. AI API 响应时间
  3. 服务器负载

Q10: 内存占用高

解决：

JSON
{
  "sessions": {
    "maxSessions": 50,
    "timeout": 1800
  },
  "messages": {
    "maxContextLength": 50
  }
}

8.5 安全问题

Q11: 如何防止滥用？

配置：

JSON
{
  "security": {
    "allowFrom": ["+15555550123"],
    "rateLimit": {
      "enabled": true,
      "maxRequests": 100,
      "windowMs": 60000
    }
  }
}

Q12: 如何审计消息？

启用详细日志：

JSON
{
  "logging": {
    "level": "debug",
    "includeMessages": true
  }
}

9. 总结与下一步

9.1 本教程总结

已完成：

  • ✅ 了解 OpenClaw 的核心概念
  • ✅ 完成环境准备和安装
  • ✅ 配置网关和 AI 提供商
  • ✅ 连接聊天频道
  • ✅ 学会基本使用和管理
  • ✅ 掌握高级配置和优化
  • ✅ 了解常见问题解决方案

9.2 推荐配置清单

个人使用推荐：

JSON
{
  "ai": {
    "provider": "pi",
    "model": "latest"
  },
  "gateway": {
    "port": 18789
  },
  "channels": {
    "telegram": {
      "enabled": true
    }
  },
  "security": {
    "allowFrom": ["你的 Telegram ID"]
  }
}

团队使用推荐：

JSON
{
  "ai": {
    "provider": "claude",
    "model": "claude-4"
  },
  "gateway": {
    "port": 18789,
    "allowOrigins": ["https://your-domain.com"]
  },
  "channels": {
    "discord": {
      "enabled": true,
      "guilds": {
        "*": {
          "requireMention": true
        }
      }
    }
  },
  "security": {
    "rateLimit": {
      "enabled": true,
      "maxRequests": 100
    }
  }
}

9.3 下一步学习

推荐阅读：

  1. OpenClaw 官方文档
  2. 多 Agent 路由配置
  3. 安全最佳实践
  4. 移动端节点配对

进阶主题：

  • 自定义 Agent 开发
  • 插件系统扩展
  • 集群部署
  • 监控和告警

9.4 获取帮助

遇到问题？

📖 更新日志

版本日期更新内容
v1.02026-03-16初始版本发布

© 2026 折腾侠博客 | 本文链接： https://blog.railx.cn/posts/openclaw-setup-guide-2026

欢迎转载，请注明出处。

本文是 OpenClaw 中文搭建教程，会持续更新。建议收藏并定期查看最新版本。

标签
#AI Agent
#大语言模型
#自动化
#开发工具
#技术教程
分享到：

如果这篇文章对你有帮助，欢迎请作者喝杯咖啡 ☕

加载评论中...