返回
Openclaw-Series

02. OpenClaw 环境搭建与首次运行

本文详细介绍 OpenClaw 的安装配置流程，涵盖 npm/pnpm/bun 和 Docker 四种安装方式，配置文件详解，以及常见问题的排查方法。帮助开发者在 5 分钟内完成环境搭建，启动个人 AI 助手。

适用于 OpenClaw v2026.2 | 本文假设你有 Node.js >= 22 环境，以及一个 AI API Key（推荐 Anthropic Claude）。

TL;DR: 5 分钟完成 OpenClaw 安装。支持 npm/pnpm/bun/Docker 四种方式，推荐 npm install -g openclaw@latest && openclaw onboard。配置文件位于 ~/.openclaw/openclaw.json，通过 openclaw gateway 启动。详细覆盖 Docker 部署、配置文件结构、常见问题排查。

前置要求

必需环境

环境 版本要求 检查命令 说明
Node.js >= 22.0.0 node --version 推荐使用 LTS 版本
npm >= 10.0.0 npm --version Node.js 自带
内存 >= 4GB - 推荐 8GB+ 用于复杂任务
磁盘 >= 2GB - 包含依赖和缓存

推荐环境

环境 说明
pnpm 或 bun 比 npm 更快，磁盘占用更少
Docker 用于沙箱模式或隔离环境
Tailscale 用于远程访问（可选）

AI API Key

OpenClaw 需要连接 AI 模型才能工作。推荐使用：

提供商 模型推荐 获取方式 价格参考
Anthropic Claude Opus 4.6 / Sonnet 4 console.anthropic.com 按用量计费
OpenAI GPT-4o / GPT-4-turbo platform.openai.com 按用量计费
本地模型 Ollama + Llama 3 本地部署 免费（需硬件）

💡 推荐：Anthropic Claude Opus 4.6 提供最佳的长上下文处理和提示注入防护能力。

环境验证

# 检查 Node.js 版本
node --version
# 输出示例: v22.12.0

# 检查 npm 版本
npm --version
# 输出示例: 10.9.0

# 检查系统信息
uname -a  # Linux/macOS
# 或
systeminfo | findstr /B /C:"OS Name" /C:"OS Version"  # Windows

安装方式对比

flowchart TB
    A[选择安装方式] --> B{使用场景?}
    B -->|快速体验| C[npm 全局安装]
    B -->|日常使用| D[pnpm/bun 安装]
    B -->|生产部署| E[Docker 部署]
    B -->|开发贡献| F[源码构建]
    
    C --> G[5分钟完成]
    D --> H[更快的依赖管理]
    E --> I[环境隔离 可复现]
    F --> J[可定制 参与开发]

方式对比表

方式 安装速度 磁盘占用 更新便捷 隔离性 推荐场景
npm -g ⭐⭐⭐ 较大 简单 无 快速体验、临时测试
pnpm -g ⭐⭐⭐⭐ 小 简单 无 日常使用、多项目
bun -g ⭐⭐⭐⭐⭐ 小 简单 无 追求极致速度
Docker ⭐⭐ 中 中等 完全 生产部署、团队协作
源码 ⭐ 大 复杂 无 开发贡献、深度定制

方式一：npm 全局安装（推荐新手）

安装步骤

# 1. 安装最新稳定版
npm install -g openclaw@latest

# 2. 验证安装
openclaw --version
# 输出示例: 2026.2.26

# 3. 查看帮助
openclaw --help

安装后目录结构

/usr/local/lib/node_modules/openclaw/  # 全局安装目录
├── bin/
│   └── openclaw                        # 可执行文件
├── lib/
│   └── ...                             # 核心库文件
└── package.json

~/.openclaw/                            # 用户数据目录（首次运行创建）
├── openclaw.json                       # 主配置文件
├── credentials/                       # 渠道凭据存储
├── workspace/                          # Agent 工作区
│   ├── AGENTS.md                      # Agent 行为指导
│   ├── SOUL.md                        # Agent 人格设定
│   └── skills/                        # 自定义技能
└── logs/                              # 日志目录

运行入门向导

# 启动交互式配置向导
openclaw onboard --install-daemon

向导会引导你完成：

sequenceDiagram
    participant U as 用户
    participant W as 向导
    participant S as 系统
    
    U->>W: 启动 onboard
    W->>U: 选择模型提供商
    U->>W: 选择 Anthropic
    W->>U: 输入 API Key
    U->>W: 粘贴 Key
    W->>U: 选择 Gateway 端口
    U->>W: 18789（默认）
    W->>U: 是否安装守护进程？
    U->>W: 是
    W->>S: 创建 systemd/launchd 服务
    S-->>W: 安装成功
    W-->>U: 配置完成！

方式二：pnpm 安装（推荐日常）

安装 pnpm

# 使用 npm 安装 pnpm
npm install -g pnpm

# 或使用独立脚本
curl -fsSL https://get.pnpm.io/install.sh | sh -

安装 OpenClaw

# 使用 pnpm 安装
pnpm add -g openclaw@latest

# 验证
openclaw --version

pnpm 的优势

特性 说明
硬链接存储 全局存储，多项目共享依赖，节省磁盘
更快安装 比 npm 快 2-3 倍
严格依赖 避免幽灵依赖问题
monorepo 支持 原生支持多包管理

方式三：bun 安装（追求极致速度）

安装 bun

# macOS/Linux
curl -fsSL https://bun.sh/install | bash

# 或使用 npm
npm install -g bun

安装 OpenClaw

# 使用 bun 安装
bun add -g openclaw@latest

# 验证
openclaw --version

bun 的优势

特性 说明
极速安装 比 npm 快 20-30 倍
内置打包器 原生支持 TypeScript
内置测试 Jest 兼容的测试框架
Node.js 兼容 大部分 npm 包可直接使用

方式四：Docker 部署（推荐生产）

获取镜像

# 拉取最新镜像
docker pull openclaw/openclaw:latest

# 或指定版本
docker pull openclaw/openclaw:2026.2

基础运行

# 最小化运行
docker run -d \
  --name openclaw \
  -p 18789:18789 \
  -v ~/.openclaw:/root/.openclaw \
  -e ANTHROPIC_API_KEY=your_key_here \
  openclaw/openclaw:latest

# 查看日志
docker logs -f openclaw

Docker Compose 配置

创建 docker-compose.yml：

version: '3.8'

services:
  openclaw:
    image: openclaw/openclaw:latest
    container_name: openclaw
    restart: unless-stopped
    ports:
      - "18789:18789"
    volumes:
      - ./openclaw-data:/root/.openclaw
    environment:
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
      # 或使用配置文件
      # - OPENCLAW_CONFIG=/root/.openclaw/openclaw.json
    healthcheck:
      test: ["CMD", "openclaw", "health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

启动服务：

# 创建 .env 文件
echo "ANTHROPIC_API_KEY=your_key_here" > .env

# 启动
docker-compose up -d

# 查看状态
docker-compose ps

# 查看日志
docker-compose logs -f

Docker 网络配置

# docker-compose.yml 扩展配置
services:
  openclaw:
    # ... 其他配置
    networks:
      - openclaw-net

  # 可选：反向代理
  caddy:
    image: caddy:latest
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile
    networks:
      - openclaw-net

networks:
  openclaw-net:
    driver: bridge

方式五：源码构建（开发者）

克隆仓库

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

# 安装依赖（推荐 pnpm）
pnpm install

# 构建
pnpm build

# 运行
pnpm openclaw onboard

开发模式

# 开发模式（自动重载）
pnpm gateway:watch

# 运行测试
pnpm test

# 代码检查
pnpm lint

配置文件详解

配置优先级

CLI 参数 > 环境变量 > 配置文件 > 默认值

目录结构

~/.openclaw/
├── openclaw.json           # 主配置文件
├── openclaw.json.backup    # 自动备份
├── credentials/            # 敏感凭据（自动加密）
│   ├── telegram.json
│   ├── whatsapp.json
│   └── discord.json
├── workspace/              # Agent 工作区
│   ├── AGENTS.md          # 全局行为指导
│   ├── SOUL.md            # Agent 人格
│   ├── TOOLS.md           # 自定义工具说明
│   ├── USER.md            # 用户信息
│   └── skills/            # 技能目录
│       ├── gmail/
│       │   └── SKILL.md
│       └── calendar/
│           └── SKILL.md
├── sessions/              # 会话数据
├── logs/                  # 日志文件
│   ├── gateway.log
│   └── agent.log
└── cache/                 # 缓存数据

最小配置

~/.openclaw/openclaw.json：

{
  "agent": {
    "model": "anthropic/claude-opus-4-6"
  }
}

完整配置示例

{
  "agent": {
    "model": "anthropic/claude-opus-4-6",
    "thinkingLevel": "high",
    "verboseLevel": "normal"
  },
  "gateway": {
    "port": 18789,
    "bind": "loopback",
    "host": "127.0.0.1"
  },
  "channels": {
    "telegram": {
      "botToken": "YOUR_BOT_TOKEN",
      "dmPolicy": "pairing",
      "allowFrom": []
    },
    "whatsapp": {
      "allowFrom": ["+8613800138000"],
      "groups": {
        "*": { "requireMention": true }
      }
    },
    "discord": {
      "token": "YOUR_DISCORD_TOKEN",
      "guilds": {}
    }
  },
  "agents": {
    "defaults": {
      "workspace": "~/.openclaw/workspace",
      "sandbox": {
        "mode": "off"
      }
    }
  },
  "models": {
    "fallback": [
      {
        "model": "anthropic/claude-sonnet-4",
        "condition": "rate_limit"
      }
    ]
  },
  "webhooks": [],
  "cron": []
}

配置项说明

配置项 类型 默认值 说明
agent.model string claude-opus-4-6 使用的 AI 模型
agent.thinkingLevel string normal 思考深度：off/minimal/low/medium/high/xhigh
gateway.port number 18789 Gateway 监听端口
gateway.bind string loopback 绑定地址：loopback/all
channels.*.dmPolicy string pairing DM 策略：pairing/open
agents.defaults.sandbox.mode string off 沙箱模式：off/non-main/always

环境变量

OpenClaw 支持通过环境变量覆盖配置：

# API Keys
export ANTHROPIC_API_KEY="sk-ant-..."
export OPENAI_API_KEY="sk-..."

# 渠道配置
export TELEGRAM_BOT_TOKEN="123456:ABC..."
export DISCORD_BOT_TOKEN="..."

# Gateway 配置
export OPENCLAW_PORT=18789
export OPENCLAW_BIND="loopback"

启动与验证

启动 Gateway

# 前台运行（调试模式）
openclaw gateway --verbose

# 后台运行（守护进程）
openclaw gateway --daemon

# 指定端口
openclaw gateway --port 18790

验证运行状态

# 检查健康状态
openclaw doctor

# 输出示例：
# ✓ Node.js version: v22.12.0
# ✓ OpenClaw version: 2026.2.26
# ✓ Gateway running on port 18789
# ✓ API key configured
# ✓ Workspace directory exists

访问 Web 控制台

启动 Gateway 后，打开浏览器访问：

http://127.0.0.1:18789

你将看到 Web Control UI：

页面 功能
Chat 与 Agent 对话
Sessions 管理会话
Config 配置管理
Nodes 设备节点管理
Logs 日志查看

测试对话

# 命令行测试
openclaw agent --message "你好，请介绍一下你自己"

# 输出示例：
# 你好！我是你的 OpenClaw 助手。我可以帮你...

常见问题排查

问题 1：端口被占用

症状：

Error: EADDRINUSE: address already in use 127.0.0.1:18789

解决方案：

# 查找占用端口的进程
lsof -i :18789
# 或
netstat -tlnp | grep 18789

# 终止进程
kill -9 <PID>

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

问题 2：API Key 无效

症状：

Error: Invalid API key

解决方案：

# 验证配置
openclaw config get agent.model

# 检查环境变量
echo $ANTHROPIC_API_KEY

# 重新配置
openclaw onboard

问题 3：Node 版本过低

症状：

Error: OpenClaw requires Node.js >= 22.0.0

解决方案：

# 使用 nvm 切换版本
nvm install 22
nvm use 22
nvm alias default 22

# 验证
node --version

问题 4：权限问题

症状：

Error: EACCES: permission denied

解决方案：

# 修复 npm 权限
sudo chown -R $(whoami) ~/.npm
sudo chown -R $(whoami) ~/.openclaw

# 或使用 nvm 管理 Node.js（推荐）

问题 5：Docker 网络问题

症状：

Error: Cannot connect to Gateway from container

解决方案：

# 检查网络
docker network ls
docker network inspect bridge

# 使用 host 网络
docker run --network host ...

# 或正确映射端口
docker run -p 127.0.0.1:18789:18789 ...

问题 6：凭据丢失

症状：

Warning: Telegram credentials not found

解决方案：

# 重新登录渠道
openclaw channels login telegram

# 检查凭据文件
ls ~/.openclaw/credentials/

# 备份凭据
cp -r ~/.openclaw/credentials/ ~/.openclaw/credentials.backup/

问题 7：内存不足

症状：

Error: JavaScript heap out of memory

解决方案：

# 增加 Node.js 内存限制
export NODE_OPTIONS="--max-old-space-size=8192"
openclaw gateway

# 或在 Docker 中
docker run -e NODE_OPTIONS="--max-old-space-size=8192" ...

更新与维护

更新 OpenClaw

# npm 更新
npm update -g openclaw@latest

# pnpm 更新
pnpm update -g openclaw@latest

# Docker 更新
docker pull openclaw/openclaw:latest
docker-compose up -d

# 检查版本
openclaw --version

切换发布通道

# 稳定版（推荐）
openclaw update --channel stable

# 测试版
openclaw update --channel beta

# 开发版（最新功能，可能不稳定）
openclaw update --channel dev

备份与恢复

# 备份配置
tar -czvf openclaw-backup-$(date +%Y%m%d).tar.gz ~/.openclaw/

# 恢复配置
tar -xzvf openclaw-backup-20260226.tar.gz -C ~/

# 仅备份关键文件
cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.backup
cp -r ~/.openclaw/credentials/ ~/.openclaw/credentials.backup/

下一步

恭喜！你已经成功搭建了 OpenClaw 环境。接下来：

  1. 配置第一个渠道 → 下一篇：渠道配置入门
  2. 安装第一个 Skill → 在 Web UI 中搜索并安装
  3. 定制 Agent 人格 → 编辑 ~/.openclaw/workspace/SOUL.md

本篇小结：

  • 掌握了 5 种安装方式及其适用场景
  • 理解了配置文件结构和优先级
  • 学会了启动验证和常见问题排查
  • 了解了更新维护的基本操作

更新记录：

  • 2026-02-26：初版发布，基于 OpenClaw v2026.2

系列导航：