OpenClaw 完全部署指南：从零搭建你的 AI 助手

阅读时间: 20分钟 | 难度: 中级 | 基于 OpenClaw 官方文档

目录#

OpenClaw 是什么
架构理解：Gateway + Channels
系统要求与准备
安装 OpenClaw
初始配置向导
启动 Gateway
接入 Telegram
接入 Discord
使用 Control UI
常见问题与排查

OpenClaw 是什么#

OpenClaw（前身为 Moltbot/Clawdbot）是一个自托管的 AI 助手网关，让你能够在自己控制的环境中运行 AI 代理，并连接到多种消息平台。

核心特性#

特性	说明
🤖 多模型支持	GPT-4、Claude、Gemini、本地模型（Ollama）
🔄 持久化会话	长对话上下文、记忆功能
🔌 技能系统	通过插件扩展功能（GitHub、搜索、代码执行）
💬 多平台	Telegram、Discord、WhatsApp、Slack、iMessage
🔒 本地优先	数据不出本地，完全可控

与 ChatGPT 的区别#

	OpenClaw	ChatGPT
部署	自托管	云服务
数据	本地	上传 OpenAI
插件	任意安装	官方限定
成本	API 费 + 服务器	订阅费
定制	完全可定制	有限

架构理解：Gateway + Channels#

理解 OpenClaw 的架构对部署至关重要：

┌─────────────────────────────────────────────────────────────┐
│                     OpenClaw Gateway                        │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐    │
│  │   Control    │  │   Session    │  │    Skill     │    │
│  │     UI       │  │   Manager    │  │   Engine     │    │
│  └──────────────┘  └──────────────┘  └──────────────┘    │
│                                                              │
│  ┌────────────────────────────────────────────────────┐   │
│  │              Channel Adapters                       │   │
│  │  Telegram │ Discord │ WhatsApp │ Slack │ iMessage  │   │
│  └────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘

plaintext

核心组件#

组件	说明	默认端口
Gateway	核心控制平面	3000
Control UI	Web 管理界面	3000/ui
Channels	消息平台适配器	-

系统要求与准备#

硬件要求#

级别	CPU	内存	存储	适用场景
入门级	2核	4GB	20GB	个人轻量使用
推荐	4核	8GB	50GB	日常办公+多平台
高级	8核	16GB	100GB	企业/团队/高并发

软件要求#

软件	版本	说明
Node.js	22+	必需，OpenClaw 基于 Node 构建
npm/pnpm	最新	包管理器
Git	任意	克隆仓库（可选）

网络要求#

可访问外网（下载依赖、调用 AI API）
如果使用本地模型（Ollama），需要相应端口

安装 OpenClaw#

官方提供 3 种安装方式，根据你的需求选择：

方式一：一键安装脚本（推荐）#

最简单的方式，自动安装 Node.js 和 OpenClaw：

# 执行安装脚本
curl -fsSL https://openclaw.ai/install.sh | bash

# 如果不需要立即启动向导，添加 --no-onboard
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --no-onboard

bash

脚本会完成：

检查系统环境
安装/升级 Node.js 22+（如缺失）
全局安装 openclaw CLI
可选：启动 onboarding 向导

方式二：npm 安装（已有 Node.js）#

如果你已经安装了 Node.js 22+：

# 使用 npm
npm install -g openclaw@latest

# 或使用 pnpm（更快）
pnpm add -g openclaw@latest

# 或使用 yarn
yarn global add openclaw@latest

bash

方式三：从源码构建（开发者）#

适合需要修改源码或贡献代码的用户：

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

# 安装依赖
pnpm install

# 构建项目
pnpm build

# 链接到全局（可选）
pnpm link --global

# 或直接运行
./bin/openclaw

bash

验证安装#

# 检查版本
openclaw --version

# 检查环境
openclaw doctor

# 查看帮助
openclaw --help

bash

初始配置向导#

安装完成后，运行 onboarding 向导进行初始配置：

# 启动交互式配置向导
openclaw onboard

# 同时安装系统服务（推荐用于服务器）
openclaw onboard --install-daemon

bash

向导配置流程#

向导会引导你完成以下配置：

1. 模型提供商配置#

选择并配置 AI 模型：

? Select model provider: (Use arrow keys)
❯ OpenAI (GPT-4, GPT-3.5)
  Anthropic (Claude 3)
  Google (Gemini)
  Ollama (Local models)
  Custom/OpenRouter

plaintext

配置 OpenAI 示例：

# 向导会询问 API Key
Enter OpenAI API Key: sk-xxxxxxxxxx

# 选择默认模型
Select default model: GPT-4 Turbo

bash

配置 Ollama（本地模型）示例：

# 确保 Ollama 已运行
ollama serve

# 在向导中选择 Ollama
Enter Ollama URL: http://localhost:11434

# 选择模型
Select model: llama3.2

bash

2. 消息渠道配置（可选）#

可以在向导中配置，也可以稍后手动添加：

? Configure messaging channels now? (Y/n)

? Select channels to configure:
  [ ] Telegram
  [ ] Discord
  [ ] Slack
  [ ] WhatsApp

plaintext

3. 安全与认证配置#

Gateway Token（必需）：

# 生成安全令牌
? Set Gateway Token (auto-generated): xxxxxxxxxxxxxxxx

# 或者自定义
? Set Gateway Token (custom): my-secure-token-123

bash

DM 配对安全（推荐启用）：

? Enable DM pairing for security? (Y/n) Y

? Require approval for new conversations? (Y/n) Y

bash

4. 数据存储配置#

? Select database:
❯ SQLite (默认，适合个人使用)
  PostgreSQL (适合团队/生产)

plaintext

SQLite（默认）：

# 数据存储位置
Data directory: ~/.openclaw/
Config file: ~/.openclaw/config.yaml
Database: ~/.openclaw/data.db

bash

PostgreSQL（可选）：

? PostgreSQL host: localhost
? PostgreSQL port: 5432
? Database name: openclaw
? Username: openclaw
? Password: ********

bash

完成配置#

向导完成后，会显示摘要：

✅ OpenClaw 配置完成！

📝 配置摘要:
   - Gateway: http://localhost:3000
   - Model: OpenAI GPT-4 Turbo
   - Channels: Telegram (配置中)
   - Security: DM pairing enabled
   - Database: SQLite (~/.openclaw/)

🚀 下一步:
   1. 启动 Gateway: openclaw gateway
   2. 打开 Control UI: openclaw dashboard
   3. 完成 Telegram 配对

📖 文档: https://docs.openclaw.ai
💬 社区: https://discord.com/invite/clawd

plaintext

启动 Gateway#

配置完成后，启动 OpenClaw Gateway：

前台运行（调试）#

# 前台启动，查看实时日志
openclaw gateway

# 指定端口
openclaw gateway --port 8080

# 指定配置文件
openclaw gateway --config /path/to/config.yaml

bash

后台运行（生产）#

# 使用系统服务（如果安装时已启用）
systemctl start openclaw
systemctl enable openclaw

# 查看状态
systemctl status openclaw

# 查看日志
journalctl -u openclaw -f

bash

使用 Docker（可选）#

OpenClaw 也支持 Docker 部署：

# 使用官方 Docker 镜像
docker run -d \
  --name openclaw \
  -p 3000:3000 \
  -v ~/.openclaw:/data \
  openclaw/openclaw:latest

# 或使用 Docker Compose
wget https://openclaw.ai/docker-compose.yml
docker-compose up -d

bash

验证启动#

# 检查 Gateway 状态
openclaw status

# 健康检查
openclaw health

# 测试 API
curl http://localhost:3000/api/health

# 查看日志
openclaw logs

bash

接入 Telegram#

Telegram 是 OpenClaw 最常用的接入平台，以下是详细配置步骤。

1. 创建 Telegram Bot#

在 Telegram 中搜索 @BotFather
发送 /newbot 命令
输入 Bot 名称（如 “MyAIAssistant”）
输入 Bot 用户名（必须以 bot 结尾，如 myai_bot）
保存获得的 Bot Token（格式：123456789:ABCdefGHIjklMNOpqrsTUVwxyz）

常用 BotFather 命令：

/setname - 修改 Bot 名称
/setdescription - 设置描述
/setabouttext - 设置关于文本
/setuserpic - 设置头像
/setcommands - 设置命令菜单

plaintext

2. 配置 OpenClaw 连接 Telegram#

# 添加 Telegram 渠道
openclaw channels add telegram --token YOUR_BOT_TOKEN

# 或者使用交互式配置
openclaw channels configure telegram

bash

手动编辑配置文件：

nano ~/.openclaw/config.yaml

bash

添加 Telegram 配置：

channels:
  telegram:
    enabled: true
    token: "123456789:ABCdefGHIjklMNOpqrSTUvwxYz"
    # 可选：设置 webhook（生产环境）
    webhook:
      enabled: false
      url: "https://your-domain.com/webhook"
    # 可选：限制特定用户访问
    allowedUsers:
      - 123456789  # 你的 Telegram User ID

yaml

3. 获取你的 Telegram User ID#

配对需要你的 Telegram User ID：

在 Telegram 中搜索 @userinfobot
发送任意消息
机器人会回复你的 Id（如 123456789）

4. 完成配对#

Telegram 配置完成后，需要安全配对：

# 在 Telegram 中向你的 Bot 发送 /start

# 然后在服务器上批准配对
openclaw pairing approve telegram

# 或者批准特定用户
openclaw pairing approve telegram --user 123456789

bash

配对流程：

你在 Telegram 发送 /start
Gateway 收到配对请求
你运行 openclaw pairing approve
配对完成，可以开始对话

5. 测试对话#

配对完成后，在 Telegram 中测试：

[你] /start
[Bot] 👋 Hello! I'm your AI assistant. How can I help you today?

[你] 你能做什么？
[Bot] I can help you with:
- 💬 General conversation
- 📝 Writing and editing
- 💻 Coding assistance
- 🔍 Web search
- 📅 Task management
- And more!

plaintext

Telegram 高级配置#

命令菜单设置（通过 @BotFather）：

/setcommands

start - Start the bot
help - Show help
status - Check system status
reset - Reset conversation

plaintext

隐私模式（通过 @BotFather）：

/setprivacy - 开启/关闭隐私模式
关闭后 Bot 可以读取群聊中的所有消息

接入 Discord#

Discord 适合团队协作场景，以下是详细配置。

1. 创建 Discord Bot#

访问 Discord Developer Portal ↗
点击 New Application，输入名称（如 “OpenClaw Bot”）
进入左侧 Bot 选项卡
点击 Add Bot → Yes, do it!
在 Token 部分点击 Reset Token，保存新的 Token

重要设置：

在 Bot 选项卡中开启以下权限：
- ✅ MESSAGE CONTENT INTENT（必须）
- ✅ SERVER MEMBERS INTENT
- ✅ PRESENCE INTENT

2. 邀请 Bot 加入服务器#

在 OAuth2 → URL Generator 中：
- SCOPES: 选择 bot 和 applications.commands
- BOT PERMISSIONS: 选择：
  - ✅ Send Messages
  - ✅ Read Message History
  - ✅ Use Slash Commands
  - ✅ Embed Links
  - ✅ Attach Files
复制生成的 URL，在浏览器中打开
选择要加入的服务器，点击 Authorize

3. 配置 OpenClaw 连接 Discord#

# 添加 Discord 渠道
openclaw channels add discord --token YOUR_BOT_TOKEN

# 交互式配置
openclaw channels configure discord

bash

手动编辑配置：

channels:
  discord:
    enabled: true
    token: "YOUR_BOT_TOKEN_HERE"
    # 可选：限制特定服务器
    allowedGuilds:
      - "123456789012345678"
    # 可选：限制特定频道
    allowedChannels:
      - "987654321098765432"
    # 命令前缀
    commandPrefix: "!"

yaml

4. 完成配对#

# 在 Discord 中向 Bot 发送消息

# 批准配对
openclaw pairing approve discord

# 或者批准特定服务器
openclaw pairing approve discord --guild 123456789012345678

bash

Discord 使用示例#

配对完成后，在 Discord 中：

[你] !help
[Bot] 🤖 Available commands:
      !help - Show this message
      !status - Check system status
      !reset - Reset conversation

[你] 你好，能帮我写一段 Python 代码吗？
[Bot] 当然可以！你需要实现什么功能？

plaintext

使用 Control UI#

OpenClaw 提供 Web 管理界面，方便管理和监控。

启动 Control UI#

# 启动并自动打开浏览器
openclaw dashboard

# 启动但不自动打开（服务器环境）
openclaw dashboard --no-open

# 指定端口
openclaw dashboard --port 8080

bash

访问地址: http://localhost:3000

Control UI 功能概览#

功能模块	说明
📊 Dashboard	系统状态、运行指标
💬 Sessions	查看和管理对话会话
🔌 Channels	管理消息平台连接
🛠️ Skills	安装和配置技能插件
⚙️ Settings	系统配置管理
📜 Logs	实时日志查看

通过 Control UI 配置 Channel#

打开 Control UI → Channels 标签
点击 Add Channel
选择渠道类型（Telegram/Discord/Slack）
输入配置信息（Token 等）
点击 Save 并 Connect

常见问题与排查#

问题 1: `openclaw: command not found`#

原因: PATH 环境变量未包含 npm 全局安装路径

解决:

# 查找 npm 全局路径
npm prefix -g

# 添加到 PATH（临时）
export PATH="$(npm prefix -g)/bin:$PATH"

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

bash

问题 2: Gateway 启动失败#

排查步骤:

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

# 检查配置语法
openclaw doctor

# 查看详细日志
openclaw logs --verbose

# 重置配置（谨慎操作）
mv ~/.openclaw/config.yaml ~/.openclaw/config.yaml.bak
openclaw onboard

bash

问题 3: Telegram Bot 无响应#

排查清单:

✅ 检查 Bot Token 是否正确
✅ 是否已向 @BotFather 发送 /setprivacy 并禁用隐私模式（如需读取群消息）
✅ 是否在 Telegram 向 Bot 发送了 /start
✅ 是否运行了 openclaw pairing approve telegram
✅ 检查 Gateway 日志：openclaw logs | grep telegram

问题 4: Discord Bot 离线#

排查步骤:

✅ 检查 Discord Developer Portal 中 Bot 是否启用了以下 Intent：
- MESSAGE CONTENT INTENT（必需）
- SERVER MEMBERS INTENT
- PRESENCE INTENT
✅ 检查 Bot 是否已被邀请加入服务器
✅ 检查频道权限，确保 Bot 有发送消息权限

问题 5: API 费用过高#

优化建议:

# 在配置中限制 Token 使用
models:
  openai:
    maxTokens: 2000  # 限制单次响应长度
    temperature: 0.7  # 降低创造性，提高确定性

yaml

使用本地模型（Ollama）：

# 安装 Ollama
curl -fsSL https://ollama.com/install.sh | bash

# 下载模型
ollama pull llama3.2

# 在 OpenClaw 配置中选择 Ollama

bash

总结#

本文详细介绍了 OpenClaw 的完整部署流程：

核心要点#

安装方式：推荐使用官方一键脚本 curl -fsSL https://openclaw.ai/install.sh | bash
架构理解：Gateway（核心）+ Channels（消息平台）
配置流程：运行 openclaw onboard 向导完成初始配置
平台接入：Telegram 和 Discord 需要分别获取 Bot Token 并完成配对

下一步#

📖 阅读官方文档：https://docs.openclaw.ai ↗
🛠️ 探索技能插件：https://www.clawhub.ai ↗
💬 加入社区：https://discord.com/invite/clawd ↗
🐙 查看源码：https://github.com/openclaw/openclaw ↗

最后更新: 2026-02-09 | 基于 OpenClaw 官方文档 v2.x

目录#

OpenClaw 是什么#

核心特性#

与 ChatGPT 的区别#

架构理解：Gateway + Channels#

核心组件#

系统要求与准备#

硬件要求#

软件要求#

网络要求#

安装 OpenClaw#

方式一：一键安装脚本（推荐）#

方式二：npm 安装（已有 Node.js）#

方式三：从源码构建（开发者）#

验证安装#

初始配置向导#

向导配置流程#

1. 模型提供商配置#

2. 消息渠道配置（可选）#

3. 安全与认证配置#

4. 数据存储配置#

完成配置#

启动 Gateway#

前台运行（调试）#

后台运行（生产）#

使用 Docker（可选）#

验证启动#

接入 Telegram#

1. 创建 Telegram Bot#

2. 配置 OpenClaw 连接 Telegram#

3. 获取你的 Telegram User ID#

4. 完成配对#

5. 测试对话#

Telegram 高级配置#

接入 Discord#

1. 创建 Discord Bot#

2. 邀请 Bot 加入服务器#

3. 配置 OpenClaw 连接 Discord#

4. 完成配对#

Discord 使用示例#

使用 Control UI#

启动 Control UI#

Control UI 功能概览#

通过 Control UI 配置 Channel#

常见问题与排查#

问题 1: openclaw: command not found#

问题 2: Gateway 启动失败#

问题 3: Telegram Bot 无响应#

问题 4: Discord Bot 离线#

问题 5: API 费用过高#

总结#

核心要点#

下一步#

问题 1: `openclaw: command not found`#