OpenClaw 安装配置完全指南

版本：v1.0
更新时间：2026年3月17日
适用系统：Windows / macOS / Linux

目录

  1. OpenClaw 简介
  2. 系统要求
  3. 安装方法
  4. 初始配置
  5. 启动 Gateway
  6. 配置通信频道
  7. 使用 Web 控制面板
  8. 常见问题排查
  9. 进阶配置

一、OpenClaw 简介

OpenClaw 是一个自托管的多通道 AI 网关，可将你的 AI 助手连接到 WhatsApp、Telegram、Discord、iMessage 等多种聊天应用。

核心特性

特性 说明
自托管 在你自己的设备上运行，完全掌控数据
多通道 同时支持 WhatsApp、Telegram、Discord、飞书等
AI 原生 专为编码助手设计，支持工具调用、会话管理和多智能体路由
开源 MIT 协议，社区驱动

工作原理

┌─────────────────┐     ┌─────────────┐     ┌─────────────────┐
│   聊天应用       │────▶│   Gateway   │────▶│   AI 智能体      │
│ (WhatsApp等)    │     │   (OpenClaw)│     │  (Claude等)     │
└─────────────────┘     └─────────────┘     └─────────────────┘
                               │
                               ▼
                        ┌─────────────┐
                        │  Web 控制面板 │
                        │  移动端节点   │
                        └─────────────┘

二、系统要求

必备条件

项目 要求
Node.js 推荐 v24，最低 v22.16+ LTS
操作系统 Windows 10/11、macOS 12+、Linux
内存 建议 4GB+
存储 至少 1GB 可用空间
网络 可访问 AI 服务商 API

检查 Node.js 版本

# 查看当前 Node 版本
node --version

# 如果版本过低，请先升级
# 推荐使用 nvm 管理 Node 版本

三、安装方法

方法一：官方安装脚本（推荐）

macOS / Linux
curl -fsSL https://openclaw.ai/install.sh | bash
Windows (PowerShell)

以管理员身份打开 PowerShell，执行：

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

方法二：通过 npm 安装

如果你已安装 Node.js，可以直接使用 npm：

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

# 验证安装
openclaw --version

方法三：从源码安装（开发者）

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

# 安装依赖
pnpm install

# 构建项目
pnpm build

# 运行 Gateway
pnpm gateway:watch

验证安装

# 检查 OpenClaw 是否安装成功
openclaw --help

# 查看版本信息
openclaw version

四、初始配置

4.1 运行配置向导

OpenClaw 提供交互式配置向导，帮助你完成初始设置：

# 运行向导并安装系统服务
openclaw onboard --install-daemon

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

  1. AI 服务商配置 - 输入 API Key（支持 OpenAI、Anthropic、Google 等）
  2. Gateway 设置 - 配置监听端口（默认 18789）
  3. 系统服务安装 - 将 Gateway 设为开机启动
  4. 通信频道配置 - 可选配置 WhatsApp、Telegram 等

4.2 配置文件详解

配置文件位于：

  • Windows: %USERPROFILE%\.openclaw\openclaw.json
  • macOS/Linux: ~/.openclaw/openclaw.json
基础配置示例
{
  "gateway": {
    "port": 18789,
    "host": "127.0.0.1",
    "auth": {
      "token": "your-secure-token-here"
    }
  },
  "agents": {
    "defaults": {
      "provider": "anthropic",
      "model": "claude-sonnet-4-20250514"
    }
  },
  "channels": {
    "whatsapp": {
      "enabled": true
    },
    "telegram": {
      "enabled": true
    }
  }
}
关键配置项说明
配置项 说明 示例
gateway.port Gateway 监听端口 18789
gateway.host 绑定地址 127.0.0.1 或 0.0.0.0
agents.defaults.provider 默认 AI 服务商 anthropic、openai
agents.defaults.model 默认模型 claude-sonnet-4-20250514

4.3 环境变量

可通过环境变量自定义配置路径：

# 自定义配置目录
export OPENCLAW_HOME=/path/to/openclaw

# 自定义状态目录
export OPENCLAW_STATE_DIR=/path/to/state

# 自定义配置文件路径
export OPENCLAW_CONFIG_PATH=/path/to/openclaw.json

五、启动 Gateway

5.1 作为系统服务运行（推荐）

安装向导会自动创建系统服务：

# 检查 Gateway 状态
openclaw gateway status

# 启动 Gateway
openclaw gateway start

# 停止 Gateway
openclaw gateway stop

# 重启 Gateway
openclaw gateway restart

5.2 前台运行（调试用）

# 前台运行，便于查看日志
openclaw gateway --port 18789 --verbose

5.3 Linux systemd 用户服务

Linux 默认使用 systemd 用户服务：

# 启用用户服务（防止注销后停止）
sudo loginctl enable-linger $USER

# 查看服务状态
systemctl --user status openclaw

# 手动编辑服务配置
sudo systemctl edit openclaw

建议添加以下优化配置：

[Service]
Environment=OPENCLAW_NO_RESPAWN=1
Environment=NODE_COMPILE_CACHE=/var/tmp/openclaw-compile-cache
Restart=always
RestartSec=2
TimeoutStartSec=90

六、配置通信频道

6.1 WhatsApp 配置

# 登录 WhatsApp（扫描二维码）
openclaw channels login whatsapp

# 查看 WhatsApp 状态
openclaw channels status whatsapp

# 登出
openclaw channels logout whatsapp

6.2 Telegram 配置

  1. 通过 @BotFather 创建 Bot
  2. 获取 Bot Token
  3. 配置 Token：
# 方式一：命令行设置
openclaw channels login telegram --token YOUR_BOT_TOKEN

# 方式二：配置文件
```json
{
  "channels": {
    "telegram": {
      "token": "YOUR_BOT_TOKEN"
    }
  }
}

6.3 Discord 配置

  1. 在 Discord Developer Portal 创建应用
  2. 获取 Bot Token
  3. 配置并邀请 Bot 加入服务器
{
  "channels": {
    "discord": {
      "token": "YOUR_DISCORD_BOT_TOKEN"
    }
  }
}

6.4 飞书 (Feishu) 配置

# 登录飞书
openclaw channels login feishu

# 或者使用配置码
openclaw channels login feishu --code YOUR_CODE

6.5 发送测试消息

# 向指定号码发送测试消息
openclaw message send --target +8613800138000 --message "Hello from OpenClaw!"

七、使用 Web 控制面板

7.1 启动控制面板

# 在浏览器中打开控制面板
openclaw dashboard

# 或者直接访问
# http://127.0.0.1:18789/

7.2 控制面板功能

功能 说明
聊天界面 直接与 AI 助手对话
会话管理 查看和管理所有会话
节点管理 配对的 iOS/Android 设备
配置管理 可视化编辑配置文件
系统状态 查看 Gateway 运行状态

7.3 远程访问

如需远程访问控制面板：

  1. SSH 隧道方式（推荐）

    ssh -L 18789:localhost:18789 user@your-server

  2. Tailscale 方式

    • 安装 Tailscale
    • 启用 Tailscale Serve
    • 通过 Tailscale IP 访问

  3. VPS 部署

八、常见问题排查

8.1 安装问题

Q: npm 安装失败
# 尝试使用管理员权限
sudo npm install -g openclaw@latest

# 或者使用 npx 临时运行
npx openclaw@latest
Q: Node.js 版本不兼容
# 使用 nvm 切换版本
nvm install 24
nvm use 24

# 或安装 LTS 版本
nvm install --lts

8.2 Gateway 启动问题

Q: 端口被占用
# 查找占用 18789 端口的进程
# macOS/Linux:
lsof -i :18789

# Windows:
netstat -ano | findstr :18789

# 使用其他端口启动
openclaw gateway --port 8080
Q: 权限不足
# Linux/macOS: 检查目录权限
ls -la ~/.openclaw/

# 修复权限
chmod -R 755 ~/.openclaw/

8.3 频道连接问题

Q: WhatsApp 无法登录
  1. 确保手机网络正常
  2. 检查二维码是否过期（2分钟内有效）
  3. 重新尝试登录： 
    openclaw channels logout whatsapp
openclaw channels login whatsapp
Q: Telegram Bot 无响应
  1. 检查 Bot Token 是否正确
  2. 确保已向 Bot 发送 /start
  3. 查看日志：openclaw gateway --verbose

8.4 调试命令

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

# 健康检查
openclaw health

# 查看配置
openclaw config show

# 查看版本信息
openclaw version --full

九、进阶配置

9.1 安全配置

访问控制
{
  "channels": {
    "whatsapp": {
      "allowFrom": ["+8613800000000"],
      "groups": {
        "*": { "requireMention": true }
      }
    }
  },
  "messages": {
    "groupChat": {
      "mentionPatterns": ["@openclaw"]
    }
  }
}
Token 认证
{
  "gateway": {
    "auth": {
      "token": "your-secure-random-token"
    }
  }
}

9.2 多模型配置

{
  "agents": {
    "profiles": {
      "coding": {
        "provider": "anthropic",
        "model": "claude-sonnet-4-20250514"
      },
      "fast": {
        "provider": "openai",
        "model": "gpt-4o-mini"
      }
    }
  }
}

9.3 备份与恢复

需要备份的目录
# 配置文件
~/.openclaw/openclaw.json

# 会话数据
~/.openclaw/agents/

# 凭证信息
~/.openclaw/credentials/

# 工作空间
~/.openclaw/workspace/
自动备份脚本
#!/bin/bash
BACKUP_DIR="/path/to/backups"
DATE=$(date +%Y%m%d_%H%M%S)

tar -czf "$BACKUP_DIR/openclaw_backup_$DATE.tar.gz" \
  ~/.openclaw/openclaw.json \
  ~/.openclaw/agents/ \
  ~/.openclaw/credentials/ \
  ~/.openclaw/workspace/

echo "Backup completed: openclaw_backup_$DATE.tar.gz"

9.4 VPS 部署优化

对于低配置 VPS（Oracle Free Tier 等），建议启用编译缓存：

# 添加到 ~/.bashrc
echo 'export NODE_COMPILE_CACHE=/var/tmp/openclaw-compile-cache' >> ~/.bashrc
echo 'export OPENCLAW_NO_RESPAWN=1' >> ~/.bashrc
mkdir -p /var/tmp/openclaw-compile-cache
source ~/.bashrc

附录：常用命令速查

命令 说明
openclaw --help 查看帮助
openclaw version 查看版本
openclaw onboard 运行配置向导
openclaw gateway start 启动 Gateway
openclaw gateway stop 停止 Gateway
openclaw gateway status 查看状态
openclaw dashboard 打开控制面板
openclaw channels login <channel> 登录频道
openclaw channels logout <channel> 登出频道
openclaw channels status 查看频道状态
openclaw health 健康检查
openclaw config show 显示配置

相关资源

  • 官方文档: https://docs.openclaw.ai
  • GitHub: https://github.com/openclaw/openclaw
  • Discord 社区: https://discord.com/invite/clawd
  • ClawHub 技能市场: https://clawhub.com
# 人工智能
Logo
龙虾开发者社区

小龙虾开发者社区是 CSDN 旗下专注 OpenClaw 生态的官方阵地，聚焦技能开发、插件实践与部署教程，为开发者提供可直接落地的方案、工具与交流平台，助力高效构建与落地 AI 应用

更多推荐

OpenClaw+GLM-4.7-Flash语音交互：对接Whisper实现语音控制

本文介绍了如何在星图GPU平台上自动化部署【ollama】GLM-4.7-Flash镜像，构建语音交互系统。该系统结合Whisper语音识别与GLM-4.7-Flash的指令理解能力，实现智能家居控制等场景的语音操作，提升日常任务执行效率。

avatar 龙虾开发者社区

学生党福音：OpenClaw+nanobot搭建学习监督助手

本文介绍了如何在星图GPU平台上自动化部署🐈 nanobot：超轻量级OpenClaw镜像，构建智能学习监督助手。该方案利用轻量级模型实现网课进度跟踪、自动生成练习题和错题整理功能，特别适合学生群体通过QQ机器人实现移动端学习管理，显著提升学习效率。

avatar 龙虾开发者社区

OpenClaw创意工坊：用nanobot镜像生成技术海报文案

本文介绍了如何在星图GPU平台上自动化部署🐈 nanobot：超轻量级OpenClaw镜像，快速生成技术海报文案。该镜像基于Qwen3-4B模型，能将复杂技术术语转化为通俗表达，适用于技术活动宣传、社交媒体推广等场景，显著提升内容创作效率。

avatar 龙虾开发者社区