OpenClaw安装配置完全指南

1.OpenClaw 简介

2.系统要求

3.安装方法

4.初始配置

5.启动 Gateway

6.配置通信频道

7.使用 Web 控制面板

8.常见问题排查

9.进阶配置

一、OpenClaw 简介

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

核心特性

工作原理

二、系统要求

必备条件

检查 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：

# 全局安装 OpenClawnpm install -g openclaw@latest# 验证安装openclaw --version

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

# 克隆仓库git clone https://github.com/openclaw/openclaw.gitcd openclaw# 安装依赖pnpm install# 构建项目pnpm build# 运行 Gatewaypnpm 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}}}

关键配置项说明

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# 启动 Gatewayopenclaw gateway start# 停止 Gatewayopenclaw gateway stop# 重启 Gatewayopenclaw 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=1Environment=NODE_COMPILE_CACHE=/var/tmp/openclaw-compile-cacheRestart=alwaysRestartSec=2TimeoutStartSec=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 控制面板功能

7.3 远程访问

如需远程访问控制面板：

1.SSH 隧道方式（推荐）

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

2.Tailscale 方式

o安装 Tailscale

o启用 Tailscale Serve

o通过 Tailscale IP 访问

3.VPS 部署

o参考 VPS 部署指南

八、常见问题排查

8.1 安装问题

Q: npm 安装失败

# 尝试使用管理员权限sudo npm install -g openclaw@latest# 或者使用 npx 临时运行npx openclaw@latest

Q: Node.js 版本不兼容

# 使用 nvm 切换版本nvm install 24nvm 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 whatsappopenclaw 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/bashBACKUP_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 等），建议启用编译缓存：

# 添加到 ~/.bashrcecho 'export NODE_COMPILE_CACHE=/var/tmp/openclaw-compile-cache' >> ~/.bashrcecho 'export OPENCLAW_NO_RESPAWN=1' >> ~/.bashrcmkdir -p /var/tmp/openclaw-compile-cachesource ~/.bashrc

附录：常用命令速查

相关资源

·官方文档: https://docs.openclaw.ai

·GitHub: https://github.com/openclaw/openclaw

·Discord 社区: https://discord.com/invite/clawd

·ClawHub 技能市场: https://clawhub.com