OpenClaw 安装部署指南

系统要求

在开始安装之前，请确保你的系统满足以下要求：

硬件要求

| 组件 | 最低要求 | 推荐配置 | |------|----------|----------| | CPU | 双核 2.0GHz | 四核 3.0GHz+ | | 内存 | 4GB RAM | 8GB+ RAM | | 磁盘 | 10GB 可用空间 | 20GB+ SSD | | 网络 | 稳定的互联网连接 | 宽带连接 |

软件要求

必需软件：

Node.js：24.x（推荐），22.14+（兼容）
npm/pnpm/bun：任选其一作为包管理器
Git：用于克隆仓库（可选）

操作系统支持：

macOS：10.15+（推荐）
Linux：Ubuntu 20.04+, Debian 11+, Fedora 35+
Windows：Windows 10/11（推荐使用 WSL2）
WSL2：Windows Subsystem for Linux 2（官方推荐）

注意事项：

macOS 和 Linux 是官方主要支持的平台
Windows 原生支持存在，但 WSL2 更稳定
WSL2 提供接近原生 Linux 的体验

安装方式

OpenClaw 提供多种安装方式，选择最适合你的方式：

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

这是官方推荐的安装方式，适用于 macOS、Linux 和 WSL2：

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

安装脚本会自动：

检测系统环境
安装必要的依赖
下载最新版本的 OpenClaw
配置环境变量
设置守护进程

安装完成后，运行初始化向导：

openclaw onboard --install-daemon

方式二：npm 全局安装

如果你更熟悉 Node.js 生态，可以使用 npm 安装：

# 使用 npm
npm install -g openclaw

# 使用 pnpm（更快）
pnpm install -g openclaw

# 使用 bun（最快）
bun install -g openclaw

安装后运行初始化：

openclaw onboard

方式三：从源码构建

适合开发者或需要自定义的用户：

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

# 安装依赖
pnpm install

# 构建 UI
pnpm ui:build

# 构建项目
pnpm build

# 运行
node dist/openclaw.mjs gateway

方式四：Docker 部署

适合服务器部署或容器化环境：

# 拉取官方镜像
docker pull openclaw/openclaw:latest

# 运行容器
docker run -d \
  --name openclaw \
  -p 18789:18789 \
  -v ~/.openclaw:/root/.openclaw \
  openclaw/openclaw:latest

使用 Docker Compose：

version: '3.8'
services:
  openclaw:
    image: openclaw/openclaw:latest
    container_name: openclaw
    ports:
      - "18789:18789"
    volumes:
      - ~/.openclaw:/root/.openclaw
    restart: unless-stopped
    environment:
      - NODE_ENV=production

初始化配置

运行 onboard 向导

openclaw onboard 是一个交互式向导，会引导你完成初始配置：

openclaw onboard --install-daemon

向导会询问：

AI 模型配置
- 选择 AI 模型提供商（OpenAI、Anthropic、Google 等）
- 输入 API Key
- 配置默认模型（推荐 Claude Opus 4.6）
消息平台配置
- 选择要连接的消息平台（Telegram、WhatsApp、Discord 等）
- 配置平台认证信息
守护进程设置
- 是否安装为系统服务
- 开机自启动配置
工作空间设置
- 工作空间目录位置（默认 ~/.openclaw/workspace）
- 记忆文件初始化

手动配置文件

配置文件位于 ~/.openclaw/openclaw.json（JSON5 格式，支持注释）：

{
  // AI 模型配置
  "models": {
    "default": "anthropic:claude-opus-4.6",
    "providers": {
      "anthropic": {
        "apiKey": "sk-ant-xxx"
      },
      "openai": {
        "apiKey": "sk-xxx"
      }
    }
  },
  
  // Gateway 配置
  "gateway": {
    "port": 18789,
    "host": "127.0.0.1"
  },
  
  // 消息平台配置
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "YOUR_BOT_TOKEN"
    },
    "whatsapp": {
      "enabled": false
    }
  },
  
  // 工作空间配置
  "workspace": {
    "path": "~/.openclaw/workspace"
  }
}

配置 AI 模型

获取 API Key

Anthropic (推荐):

访问 https://console.anthropic.com
注册账号并登录
进入 API Keys 页面
创建新的 API Key
复制 Key（格式：sk-ant-xxx）

OpenAI:

访问 https://platform.openai.com
登录账号
进入 API Keys 页面
创建新的 API Key
复制 Key（格式：sk-xxx）

Google (Gemini):

访问 https://makersuite.google.com
获取 API Key
配置到 OpenClaw

配置模型

使用 CLI 配置：

# 配置 Anthropic
openclaw config set models.providers.anthropic.apiKey "sk-ant-xxx"
openclaw config set models.default "anthropic:claude-opus-4.6"

# 配置 OpenAI
openclaw config set models.providers.openai.apiKey "sk-xxx"
openclaw config set models.default "openai:gpt-4"

# 配置本地模型（Ollama）
openclaw config set models.providers.ollama.baseUrl "http://localhost:11434"
openclaw config set models.default "ollama:llama3"

模型故障转移

配置多个模型作为备份：

{
  "models": {
    "default": "anthropic:claude-opus-4.6",
    "fallback": [
      "openai:gpt-4",
      "google:gemini-pro"
    ],
    "providers": {
      "anthropic": { "apiKey": "sk-ant-xxx" },
      "openai": { "apiKey": "sk-xxx" },
      "google": { "apiKey": "xxx" }
    }
  }
}

启动 Gateway

守护进程模式（推荐）

安装为系统服务，开机自启动：

# 安装守护进程
openclaw onboard --install-daemon

# 启动服务
# macOS
launchctl start ai.openclaw.gateway

# Linux (systemd)
systemctl --user start openclaw-gateway

# 检查状态
openclaw doctor

手动启动模式

适合调试和开发：

# 前台运行（显示日志）
openclaw gateway --port 18789 --verbose

# 后台运行
openclaw gateway --port 18789 --daemon

# 停止 Gateway
openclaw gateway stop

验证安装

运行健康检查：

openclaw doctor

输出示例：

✓ Node.js version: 24.1.0
✓ OpenClaw version: 2026.4.24
✓ Gateway running on port 18789
✓ Config file found: ~/.openclaw/openclaw.json
✓ Workspace directory: ~/.openclaw/workspace
✓ AI model configured: anthropic:claude-opus-4.6
✓ Channels configured: telegram, whatsapp

连接第一个消息平台

Telegram（最简单）

创建 Telegram Bot：
- 在 Telegram 中搜索 @BotFather
- 发送 /newbot 命令
- 按提示设置 Bot 名称和用户名
- 获取 Bot Token（格式：123456:ABC-DEF...）
配置 OpenClaw：

openclaw config set channels.telegram.enabled true
openclaw config set channels.telegram.botToken "YOUR_BOT_TOKEN"

重启 Gateway：

openclaw gateway restart

测试连接：
- 在 Telegram 中搜索你的 Bot
- 发送 /start 命令
- 发送任意消息测试

启用 WhatsApp Channel：

openclaw config set channels.whatsapp.enabled true

启动 Gateway 并扫码：

openclaw gateway --verbose

扫描二维码：
- 终端会显示二维码
- 打开 WhatsApp > 设置 > 已连接的设备
- 扫描二维码完成配对

Discord

创建 Discord Bot：
- 访问 https://discord.com/developers/applications
- 创建新应用
- 在 Bot 页面创建 Bot
- 复制 Bot Token
配置 OpenClaw：

openclaw config set channels.discord.enabled true
openclaw config set channels.discord.botToken "YOUR_BOT_TOKEN"

邀请 Bot 到服务器：
- 在 OAuth2 > URL Generator 中选择 bot 权限
- 复制生成的 URL
- 在浏览器中打开并选择服务器

访问 Control UI

Control UI 是 OpenClaw 的 Web 控制面板：

启动 Gateway：

openclaw gateway

打开浏览器：

访问 http://localhost:18789

Control UI 功能：
- 查看和管理 Agent
- 配置消息平台
- 查看会话历史
- 管理技能和插件
- 查看系统状态
- 多语言支持（12 种语言）

常见问题

安装问题

Q: Node.js 版本不兼容

# 使用 nvm 安装正确版本
nvm install 24
nvm use 24

Q: 权限错误（Permission denied）

# 使用 sudo（不推荐）
sudo npm install -g openclaw

# 或配置 npm 全局目录（推荐）
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

Q: 安装脚本失败

# 手动下载脚本
curl -fsSL https://openclaw.ai/install.sh -o install.sh
chmod +x install.sh
./install.sh

# 或使用 npm 安装
npm install -g openclaw

运行问题

Q: Gateway 无法启动

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

# 使用其他端口
openclaw gateway --port 18790

Q: AI 模型无响应

# 检查 API Key 配置
openclaw config get models.providers.anthropic.apiKey

# 测试 API 连接
openclaw agent --message "Hello" --verbose

Q: 消息平台连接失败

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

# 检查配置
openclaw config get channels

配置问题

Q: 找不到配置文件

# 查看配置文件位置
openclaw config path

# 创建默认配置
openclaw onboard

Q: 重置配置

# 备份当前配置
cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.backup

# 删除配置文件
rm ~/.openclaw/openclaw.json

# 重新初始化
openclaw onboard

更新 OpenClaw

检查更新

# 查看当前版本
openclaw version

# 检查可用更新
openclaw update --check

更新到最新版本

# 更新到 stable 版本
openclaw update --channel stable

# 更新到 beta 版本
openclaw update --channel beta

# 更新到 dev 版本
openclaw update --channel dev

版本回滚

# 安装特定版本
npm install -g openclaw@2026.4.24

# 或使用 npx
npx openclaw@2026.4.24 gateway

卸载 OpenClaw

完全卸载

# 停止 Gateway
openclaw gateway stop

# 卸载守护进程
# macOS
launchctl unload ~/Library/LaunchAgents/ai.openclaw.gateway.plist
rm ~/Library/LaunchAgents/ai.openclaw.gateway.plist

# Linux
systemctl --user stop openclaw-gateway
systemctl --user disable openclaw-gateway

# 卸载 npm 包
npm uninstall -g openclaw

# 删除配置和数据（可选）
rm -rf ~/.openclaw

保留数据卸载

# 只卸载程序，保留配置
npm uninstall -g openclaw

# 配置和数据保留在 ~/.openclaw

性能优化

减少内存占用

{
  "gateway": {
    "maxMemory": "512M",
    "workers": 1
  }
}

加速启动

从 v2026.4.22 开始，内置插件采用懒加载，启动时间已缩短 82-90%。

额外优化：

{
  "plugins": {
    "lazyLoad": true,
    "autoLoad": false
  }
}

缓存配置

{
  "cache": {
    "enabled": true,
    "ttl": 3600,
    "maxSize": "100M"
  }
}

安全建议

API Key 安全

不要在配置文件中明文存储 API Key
使用环境变量：

export ANTHROPIC_API_KEY="sk-ant-xxx"
export OPENAI_API_KEY="sk-xxx"

配置文件引用环境变量：

{
  "models": {
    "providers": {
      "anthropic": {
        "apiKey": "${ANTHROPIC_API_KEY}"
      }
    }
  }
}

网络安全

Gateway 默认只监听 127.0.0.1（本地）
如需远程访问，使用反向代理（Nginx）
启用 HTTPS 和认证

文件权限

# 限制配置文件权限
chmod 600 ~/.openclaw/openclaw.json

# 限制工作空间权限
chmod 700 ~/.openclaw/workspace

下一步

安装完成后，你可以：

配置更多消息平台：阅读消息平台接入指南
探索内置技能：阅读技能系统指南
配置记忆系统：阅读记忆系统指南
部署到服务器：阅读 Docker 部署指南
加固安全配置：阅读安全配置指南

参考资源

官方安装文档：https://docs.openclaw.ai/install/index
CLI 参考：https://docs.openclaw.ai/cli
配置参考：https://docs.openclaw.ai/config
故障排除：https://docs.openclaw.ai/troubleshooting
Discord 社区：https://discord.gg/clawd

OpenClaw 安装部署指南：从零开始搭建 AI 私人助手

分享这篇文章