OpenClaw如何安装配置？2026年AI助手网关完全指南：原理解析、实操步骤、常见问题与优化建议

重要说明

OpenClaw 是 Moltbot/Clawdbot 的最新正式名称。项目经历了多次更名：

Clawdbot → Moltbot → OpenClaw（当前名称）

本教程基于官方中文社区文档 https://www.moltcn.com/start/getting-started.html 编写。

一、OpenClaw 是什么？
二、核心特性
三、系统要求
四、安装前准备
五、安装 OpenClaw
六、首次配置向导
七、启动 Gateway
八、连接即时通讯平台
九、DM 安全配对
十、常用命令大全
Pre-installation Preparation
Installing OpenClaw
First-Time Configuration Wizard
Starting the Gateway
Connecting to Instant Messaging Platforms
DM Security Pairing
Common Commands Reference

一、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），让你通过熟悉的聊天工具直接控制你的电脑。

支持的平台


平台 / Platform	类型 / Type	说明 / Description
WhatsApp	原生集成 / Native Integration	通过 Baileys 使用 WhatsApp Web 协议 / Uses WhatsApp Web protocol via Baileys
Telegram	Bot API	DMs + 群组 via grammY
Discord	Bot API	DMs + 频道 via discord.js
iMessage	本地集成 / Local Integration	macOS 本地 imsg CLI / macOS native imsg CLI
Mattermost	插件 / Plugin	Bot Token + WebSocket 事件 / Bot Token + WebSocket events

二、核心特性

主要功能

🤖 AI 代理桥接 — 连接 Pi 代理（RPC 模式），支持工具流式传输 / AI Agent Bridging — Connects to Pi agent (RPC mode), supports tool streaming.
💬 流式响应 — 块流式传输 + Telegram 草稿流式传输 / Streaming Responses — Chunk streaming + Telegram draft streaming.
🧠 多代理路由 — 将不同提供者/用户路由到隔离的代理 / Multi-Agent Routing — Routes different providers/users to isolated agents.
🔐 订阅认证 — Anthropic (Claude Pro/Max) + OpenAI (ChatGPT/Codex) via OAuth / Subscription Authentication — Anthropic (Claude Pro/Max) + OpenAI (ChatGPT/Codex) via OAuth.
💬 会话管理 — 私聊合并为共享的 main 会话；群聊隔离 / Conversation Management — Private chats merged into a shared main session; group chats isolated.
👥 群聊支持 — @提及触发（可配置为始终响应） / Group Chat Support — @mention triggers (configurable to always respond).
📎 媒体支持 — 发送和接收图片、音频、文档 / Media Support — Send and receive images, audio, documents.
🎤 语音笔记 — 可选的转录钩子 / Voice Notes — Optional transcription hooks.
🖥️ WebChat + macOS 应用 — 本地 UI + 菜单栏辅助 / WebChat + macOS App — Local UI + menu bar assistant.
📱 iOS/Android 节点 — 配对后暴露 Canvas + 聊天 + 摄像头 / iOS/Android Node — Exposes Canvas + chat + camera after pairing.

架构图

WhatsApp / Telegram / Discord / iMessage (+ plugins)
        │
        ▼
  ┌───────────────────────────┐
  │          Gateway          │  ws://127.0.0.1:18789 (loopback-only)
  │     (single source)       │
  │                           │  http://<gateway-host>: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

三、系统要求

基础要求


项目 / Item	要求 / Requirement	说明 / Description
Node.js	≥ 22.x	必需，运行时要求 / Required, runtime requirement
pnpm	可选但推荐 / Optional but recommended	从源码构建时推荐 / Recommended when building from source
内存 / Memory	最低 2GB，推荐 4GB+ / Minimum 2GB, recommended 4GB+
磁盘空间 / Disk Space	最低 1GB，推荐 5GB+ / Minimum 1GB, recommended 5GB+

各平台要求

macOS

如果要构建应用：安装 Xcode / Command Line Tools / If building the app: Install Xcode / Command Line Tools.
仅 CLI + Gateway：Node.js 足够 / CLI + Gateway only: Node.js is sufficient.

Windows

强烈推荐使用 WSL2（推荐 Ubuntu） / Strongly recommended to use WSL2 (Ubuntu recommended).
原生 Windows 未测试，问题更多，工具兼容性较差 / Native Windows is untested, has more issues, and poorer tool compatibility.
必须先安装 WSL2，然后在 WSL 内运行 Linux 步骤 / Must install WSL2 first, then run Linux steps inside WSL.

Linux

无额外要求 / No additional requirements.

网络要求

需要访问互联网（API 调用） / Requires internet access (for API calls).
国内用户：必须使用代理，否则 Gateway 无法启动 / Users in Mainland China: Must use a proxy, otherwise the Gateway cannot start.

四、安装前准备

4.1 获取 API Key

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

Anthropic Claude（推荐）

访问 Anthropic Console / Visit Anthropic Console.
注册账号并获取 API Key / Register an account and obtain an API Key.
或使用 claude setup-token 复用 Claude Code 凭证 / Or use claude setup-token to reuse Claude Code credentials.

OpenAI（ChatGPT/Codex）

访问 OpenAI Platform / Visit OpenAI Platform.
创建 API Key / Create an API Key.

其他选项

MiniMax（国内推荐） / MiniMax (Recommended in China)
GLM（智谱AI） / GLM (Zhipu AI)
本地 Ollama 模型 / Local Ollama models

活动福利1：

🎁 MiniMax 跨年福利来袭！邀好友享 Coding Plan 双重好礼，助力开发体验！

好友立享 9折专属优惠 + Builder 权益，你赢返利 + 社区特权！

👉 立即参与：MiniMax-与用户共创智能

可以使用这个链接https://platform.minimaxi.com/subscribe/coding-plan?code=KTtgSMiAnw&source=link

活动福利2：

🚀 速来拼好模，智谱 GLM Coding 超值订阅，邀你一起薅羊毛！Claude Code、Cline 等 20+ 大编程工具无缝支持，“码力”全开，越拼越爽！立即开拼，享限时惊喜价

链接：https://www.bigmodel.cn/glm-coding?ic=N0UXBDM2TD

4.2 安装 Node.js

使用 nvm 安装（推荐）

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

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

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

# 验证 / Verify
node --version  # 应显示 v22.x.x / Should show v22.x.x
npm --version

直接安装（macOS）

# 使用 Homebrew / Using 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 / Using npm
npm install -g openclaw@latest

# 或使用 pnpm / Or using pnpm
pnpm add -g openclaw@latest

5.3 验证安装

# 查看版本 / Check version
openclaw --version

# 查看帮助 / View help
openclaw --help

5.4 Windows WSL2 安装

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

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

# 重启电脑 / Restart computer

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

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

# 在 Microsoft Store 安装 Ubuntu 22.04 / Install Ubuntu 22.04 from Microsoft Store

然后在 WSL2 终端中：

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

# 安装 OpenClaw / Install 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    # 本地运行（推荐） / Run locally (Recommended)
  Remote   # 连接到远程 Gateway / Connect to a remote Gateway

步骤 2：认证方式

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

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

步骤 3：选择模型

? Default model: (Use arrow keys)
❯ claude-sonnet-4-0           # 推荐，速度和智能平衡 / Recommended, balanced speed and intelligence
  claude-opus-4-5             # 更强智能，但更慢 / Stronger intelligence, but slower
  claude-haiku-3-5            # 快速响应 / Fast response

步骤 4：频道配置

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

步骤 5：配对安全设置

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

步骤 6：工作区设置

? Workspace directory: (Use arrow keys)
❯ ~/.openclaw

AIAI Summary (BLUF)