OpenClaw 入门指南：从零到一的完整安装配置教程
想拥有一个 24 小时待命的个人 AI 助手吗？OpenClaw 让你能够在 WhatsApp、Telegram、Discord 等常用聊天工具中随时随地与 AI 对话。本文将从零开始，带你完成 OpenClaw 的完整安装和配置，让你在最短时间内拥有属于自己的 AI 助手。
一、什么是 OpenClaw？为什么你需要它？
1.1 OpenClaw 的核心价值
OpenClaw 不是一个简单的”ChatGPT 包装器”，而是一个本地优先的控制平面，让你能够在自己的硬件上运行一个功能强大的 AI 助手，并通过你日常使用的聊天应用（WhatsApp、Telegram、Discord、iMessage 等）随时随地访问它。
核心价值主张：
| 特性 | 传统 AI 服务 | OpenClaw |
|---|---|---|
| 数据隐私 |
| 数据完全本地控制 | 可用性 | 依赖网络连接和服务状态 | 24/7 本地运行，不受外部影响 | 定制化 | 有限的自定义选项 | 完全可配置，支持多代理、多模型 | 集成成本 | 需要单独访问每个平台 | 统一接口，多通道支持 | 成本 | 按使用量计费 | 一次性硬件投入，长期使用 |
1.2 适用场景OpenClaw 适合以下场景：
1.3 系统要求最低配置：
推荐配置：
二、安装前的准备工作2.1 检查系统环境在开始安装之前，我们需要确认系统满足基本要求。 检查 Node.js 版本： 如果版本低于 22，需要升级： | sudo -E bash -
sudo apt-get install -y nodejs
Windows (下载官方安装包)# https://nodejs.org/检查 pnpm（推荐）： 如果没有安装 pnpm： 2.2 选择安装方式OpenClaw 提供两种安装方式： | 安装方式 | 适用场景 | 优点 | 缺点 |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| npm 安装 |
| 简单快捷，自动更新 | 无法修改源代码 | Git 安装 | 开发者，需要定制 | 可修改源码，参与贡献 | 需要手动更新 | 推荐：新手用户选择 npm 安装，开发者选择 Git 安装。
三、完整安装步骤3.1 方法一：npm 安装（推荐新手）步骤 1：安装 OpenClaw 步骤 2：运行引导向导 这个命令会：
步骤 3：检查 Gateway 状态 如果看到 步骤 4：打开控制面板 这会在浏览器中打开 OpenClaw 的 Web 控制面板，你可以在这里：
3.2 方法二：Git 安装（开发者）步骤 1：克隆仓库 步骤 2：安装依赖 步骤 3：运行引导向导 步骤 4：开发模式运行（可选） 四、模型认证配置OpenClaw 支持多种 AI 模型提供商，以下是主流配置方法。 4.1 Anthropic（Claude）配置方式一：使用 Setup Token（订阅用户） 如果你使用 Claude Pro/Max 订阅： 复制生成的 token，然后在 OpenClaw 中配置： 方式二：使用 API Key（推荐生产环境） 1. 登录 [Anthropic Console](https://console.anthropic.com/) 4.2 OpenAI（Codex/GPT）配置使用 OAuth（订阅用户）： 这会打开浏览器完成 OAuth 认证流程。 使用 API Key： 4.3 本地模型配置（完全离线）如果你希望数据完全本地化，可以使用本地模型： 使用 LM Studio： 1. 下载并安装 [LM Studio](https://lmstudio.ai/) 4.4 模型选择建议 |
使用场景 | 推荐模型 | 理由 |
|---|---|---|---|---|---|---|---|---|---|
| 日常对话 |
| 代码开发 | Claude Opus / Codex | 代码理解能力强 |
| 长文档处理 | Claude 200K / GPT-4 Turbo | 上下文窗口大 |
| 完全离线 | Llama 3 70B / Qwen 72B | 本地运行，隐私保护 |
五、通道配置详解
5.1 WhatsApp 配置
步骤 1：启用 WhatsApp
在引导向导中选择 WhatsApp，或手动配置：
openclaw channels login whatsapp
步骤 2：扫描二维码
系统会显示一个二维码，用 WhatsApp 手机应用扫描。
步骤 3：配置访问控制
编辑配置文件 ~/.openclaw/openclaw.json：
{
channels: {
whatsapp: {
dmPolicy: "pairing", // pairing | allowlist | open | disabled
allowFrom: ["+8613800138000"], // 允许的用户号码
groups: {
"": { requireMention: true } // 群组中需要@提及才响应
}
}
}
}
步骤 4：重启 Gateway
openclaw gateway restart
5.2 Telegram 配置
步骤 1：创建 Bot
1. 在 Telegram 中搜索 @BotFather
2. 发送 /newbot创建新机器人
3. 复制 Bot Token
步骤 2：配置 OpenClaw
{
channels: {
telegram: {
botToken: "YOUR_BOT_TOKEN",
dmPolicy: "pairing",
allowFrom: ["tg:123456789"], // 用户 ID 或 @username
groups: {
"": { requireMention: true }
}
}
}
}
步骤 3：获取用户 ID
方法一：查看日志
openclaw logs --follow
发送消息给 bot，查看 from.id
方法二：使用官方 API
curl "https://api.telegram.org/botYOUR_BOT_TOKEN/getUpdates"
5.3 Discord 配置
步骤 1：创建 Discord 应用
1. 访问 [Discord Developer Portal](https://discord.com/developers/applications)
2. 创建新应用
3. 进入 "Bot" 页面，创建机器人
4. 复制 Bot Token
步骤 2：邀请机器人到服务器
生成邀请链接：
https://discord.com/api/oauth2/authorize?client_id=YOUR_CLIENT_ID&permissions=0&scope=bot
步骤 3：配置 OpenClaw
{
channels: {
discord: {
token: "YOUR_BOT_TOKEN",
guilds: {
"YOUR_GUILD_ID": {
requireMention: false,
channels: {
"general": { allow: true }
}
}
}
}
}
}
六、配置文件详解
6.1 配置文件位置
~/.openclaw/openclaw.json
6.2 最小可用配置
{
agents: {
defaults: {
workspace: "~/.openclaw/workspace"
}
},
channels: {
whatsapp: {
allowFrom: ["+8613800138000"]
}
}
}
6.3 常用配置项
代理配置：
{
agents: {
list: [
{
id: "main",
workspace: "~/.openclaw/workspace",
model: "anthropic/claude-sonnet-4-5-20260514"
},
{
id: "coding",
workspace: "~/.openclaw/workspace-coding",
model: "anthropic/claude-opus-4-5-20260514"
}
]
}
}
消息配置：
{
messages: {
responsePrefix: "🦞", // 回复前缀
ackReaction: "👀", // 确认表情
queue: {
mode: "collect", // 消息队列模式
debounceMs: 1000 // 防抖时间
}
}
}
安全配置：
{
gateway: {
bind: "127.0.0.1", // 绑定地址
port: 18789, // 端口
auth: {
token: "YOUR_GATEWAY_TOKEN"
}
},
channels: {
whatsapp: {
dmPolicy: "allowlist", // 只允许白名单用户
allowFrom: ["+8613800138000"]
}
}
}
七、常见问题与解决方案
7.1 安装问题
问题 1：Node.js 版本过低
使用 nvm 管理 Node 版本
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 22
nvm use 22
问题 2：权限错误
npm 全局安装权限问题
npm config set prefix ~/.npm-global
export PATH=~/.npm-global/bin:$PATH
7.2 Gateway 启动问题
问题：Gateway 无法启动
查看详细日志
openclaw logs --follow
检查配置
openclaw doctor
重置配置
openclaw doctor --fix
问题：端口被占用
查找占用端口的进程
lsof -i :18789
修改配置使用其他端口
# 编辑 ~/.openclaw/openclaw.json
{
gateway: { port: 18790 }
}
7.3 通道连接问题
WhatsApp 无法连接：
1. 检查网络连通性
2. 重新扫描二维码
3. 清除认证缓存：
rm -rf ~/.openclaw/credentials/whatsapp/*