Vibe Coding App
English

OpenClaw 完全安装指南 2026

Zane
12 min read
#OpenClaw#安装教程#阿里云#AI
OpenClaw 完全安装指南 2026

OpenClaw 是一个开源的自托管 AI 智能体，267K+ GitHub stars，支持本地运行、接入各种聊天应用，并通过 ClawHub 扩展技能。

这篇指南覆盖四种主要部署方式：本地安装、Docker、阿里云 ECS 一键部署，以及通义灵码 Coding Plan API 的接入配置。不管你是第一次上手还是迁移到生产环境，按步骤走就行。

前置条件

在开始之前，确认以下工具已安装：

本地安装必需：

  • Node.js 20 或更高版本（推荐 LTS）
  • Git 2.40+
  • npm 10+ 或 pnpm

Docker 部署必需：

  • Docker 24+ 和 Docker Compose v2

阿里云 ECS 部署必需：

  • 阿里云账号（已实名认证）
  • ECS 实例：推荐 ecs.c7.xlarge（4 核 8G），通用计算型

检查 Node.js 版本：

node --version  # 应输出 v20.x.x 或更高
npm --version   # 应输出 10.x.x 或更高

如果 Node.js 版本过低，推荐用 nvm 管理多版本：

# 安装 nvm 并切换到 Node.js 20
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
nvm install 20
nvm use 20

方式一：本地安装（npm 一行命令）

最快的上手方式。适合本地开发和测试。

1.1 一键安装

# 全局安装 OpenClaw CLI
npm install -g openclaw

# 验证安装成功
openclaw --version

1.2 初始化工作目录

# 创建专用目录
mkdir ~/openclaw-workspace && cd ~/openclaw-workspace

# 初始化配置文件
openclaw init

执行 openclaw init 后，会在当前目录生成 claw.config.json，这是核心配置文件。

1.3 中文优化分支（国内用户推荐）

国内网络环境下，官方仓库访问可能不稳定。社区维护的 jiulingyun/openclaw-cn 是针对国内网络优化的 OpenClaw 中文分支，内置境内镜像加速和访问适配，更新与官方主干同步。中文社区资源汇总可以访问 clawd.org.cn，那里也有常见安装问题的中文讨论。

如需深入学习，DataWhale 维护的 datawhalechina/hand-on-openclaw 提供了完整的上手教程，并包含阿里云 Coding Plan 的配置示例。

1.4 从 GitHub 源码安装（可选）

如果需要最新开发版本或者想参与贡献：

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

# 安装依赖
npm install

# 构建项目
npm run build

# 链接到全局命令
npm link

方式二：Docker 部署

Docker 部署的好处是环境隔离，不污染本地系统，适合生产使用或多实例管理。

2.1 拉取官方镜像

# 拉取最新稳定版
docker pull openclaw/openclaw:latest

# 确认镜像拉取成功
docker images | grep openclaw

2.2 创建 docker-compose.yml

在工作目录创建配置文件：

# docker-compose.yml
version: '3.8'

services:
  openclaw:
    image: openclaw/openclaw:latest
    container_name: openclaw-agent
    restart: unless-stopped
    ports:
      - "3000:3000"  # 网关端口，按需修改
    volumes:
      - ./config:/app/config      # 配置文件目录
      - ./data:/app/data          # 持久化数据
      - ./skills:/app/skills      # 自定义技能
    environment:
      - NODE_ENV=production
      - OPENCLAW_PORT=3000
      - OPENCLAW_CONFIG=/app/config/claw.config.json
    # 沙箱模式：限制文件系统访问范围
    security_opt:
      - no-new-privileges:true

2.3 启动容器

# 创建必要目录
mkdir -p config data skills

# 启动服务
docker-compose up -d

# 查看运行状态
docker-compose ps

# 查看实时日志
docker-compose logs -f openclaw

2.4 Docker 健康检查

# 检查容器是否正常运行
docker inspect openclaw-agent --format='{{.State.Health.Status}}'

# 进入容器调试
docker exec -it openclaw-agent sh

方式三：阿里云 ECS 一键部署

这是国内用户推荐的生产部署方式。阿里云市场提供 OpenClaw 的预配置镜像，几分钟内即可上线。阿里云官方也提供了一键部署文档，详见 在阿里云 ECS 上一键部署 OpenClaw。

3.1 通过云市场一键部署

  1. 登录 阿里云控制台
  2. 进入「云市场」，搜索「OpenClaw」
  3. 选择官方发布的 OpenClaw 镜像（注意认证标志）
  4. 点击「立即购买」，选择实例规格：
    • 推荐：ecs.c7.xlarge（4 核 8G）
    • 最低配置：ecs.c6.large（2 核 4G），仅适合轻量测试
  5. 选择可用区（推荐华东1-上海或华北2-北京，延迟更低）
  6. 配置安全组：开放 TCP 3000 端口（或你自定义的网关端口）
  7. 创建实例，等待约 3 分钟

3.2 连接到实例

# 通过 SSH 连接（替换为你的 ECS 公网 IP）
ssh root@<your-ecs-ip>

# 首次连接后，检查 OpenClaw 服务状态
systemctl status openclaw

3.3 初始化配置

# 镜像已预装 OpenClaw，进入配置目录
cd /opt/openclaw

# 编辑配置文件
vim config/claw.config.json

3.4 网络配置

如果实例需要通过代理设置访问境外 API，在配置文件中添加：

{
  "network": {
    "proxy": "http://127.0.0.1:7890",  // 代理设置，按实际填写
    "timeout": 30000,
    "retryCount": 3
  }
}

对于仅使用阿里云 Coding Plan API 的用户，无需代理设置，直接走国内节点即可。

方式四：Coding Plan API 配置

这是国内用户最省心的 LLM 接入方案。通过阿里云的通义灵码 Coding Plan，可以在无需网络配置的情况下使用高质量的代码大模型。

4.1 获取 API Key

  1. 登录 阿里云灵码控制台
  2. 进入「API Keys」，点击「创建 API Key」
  3. 为 Key 命名（如 openclaw-prod），复制保存

API Key 格式示例：sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

4.2 配置 OpenClaw 接入 Coding Plan

编辑 claw.config.json：

{
  "models": {
    "default": "qwen-coder-plus",
    "providers": {
      "coding-plan": {
        "type": "openai-compatible",
        "baseUrl": "https://coding.dashscope.aliyuncs.com/compatible-mode/v1",
        "apiKey": "${CODING_PLAN_API_KEY}",  // 从环境变量读取，不要直接写 Key
        "models": [
          "qwen-coder-plus",           // 推荐：代码能力强，性价比高
          "qwen-coder-turbo",          // 快速响应，适合简单任务
          "qwen-max",                  // 复杂推理任务
          "qwen-plus"                  // 均衡选项
        ]
      }
    }
  }
}

4.3 设置环境变量

不要把 API Key 直接写在配置文件里。用环境变量注入：

# 在 .env 文件中设置（不要提交到 Git）
echo 'CODING_PLAN_API_KEY=sk-你的密钥' >> ~/.openclaw/.env

# 或者临时导出（重启后失效）
export CODING_PLAN_API_KEY="sk-你的密钥"

Docker 部署时，在 docker-compose.yml 中引用：

environment:
  - CODING_PLAN_API_KEY=${CODING_PLAN_API_KEY}

然后在宿主机上创建 .env 文件：

# 与 docker-compose.yml 同目录
echo 'CODING_PLAN_API_KEY=sk-你的密钥' > .env

4.4 验证 API 连接

# 使用 OpenClaw CLI 测试连接
openclaw test-connection --provider coding-plan

# 或者发送一个简单请求验证
openclaw chat "你好，测试连接" --provider coding-plan

成功输出示例：

[INFO] Provider: coding-plan
[INFO] Model: qwen-coder-plus
[INFO] Status: Connected
[INFO] Latency: 342ms
你好！连接正常，OpenClaw 已就绪。

如果遇到连接问题，参考：Coding Plan 常见故障排除

通用配置：模型、代理设置与技能

5.1 完整配置文件示例

{
  "version": "2.0",
  "agent": {
    "name": "MyClaw",        // 自定义智能体名称
    "language": "zh-CN",     // 界面语言
    "timezone": "Asia/Shanghai"
  },
  "models": {
    "default": "qwen-coder-plus",
    "fallback": "qwen-plus",     // 主模型失败时的备用模型
    "providers": {
      "coding-plan": {
        "type": "openai-compatible",
        "baseUrl": "https://coding.dashscope.aliyuncs.com/compatible-mode/v1",
        "apiKey": "${CODING_PLAN_API_KEY}",
        "models": ["qwen-coder-plus", "qwen-coder-turbo", "qwen-max", "qwen-plus"]
      }
    }
  },
  "network": {
    "timeout": 30000,
    "retryCount": 3,
    "retryDelay": 1000
  },
  "skills": {
    "enabled": true,
    "directory": "./skills",
    "autoload": true
  },
  "security": {
    "sandboxMode": true,          // 生产环境建议开启
    "allowedPaths": ["./data"],   // 限制文件访问范围
    "disableSystemCommands": false
  },
  "logging": {
    "level": "info",
    "file": "./data/logs/openclaw.log"
  }
}

5.2 模型选择建议

关于如何根据任务类型选择最合适的模型，参考：OpenClaw 模型选择指南

简单原则：

  • 代码生成和调试：qwen-coder-plus
  • 快速简单问答：qwen-coder-turbo
  • 复杂分析和长文本：qwen-max

5.3 ClawHub 技能安装

# 搜索可用技能
openclaw skills search

# 安装文件管理技能
openclaw skills install file-manager

# 安装浏览器控制技能
openclaw skills install browser-control

# 列出已安装技能
openclaw skills list

安装技能前，建议先了解安全注意事项：OpenClaw 安全问题解决方案

验证和首次运行

6.1 启动 OpenClaw

# 本地安装：在工作目录下启动
cd ~/openclaw-workspace
openclaw start

# Docker：已通过 docker-compose up -d 启动，查看状态
docker-compose ps

6.2 访问 Web 界面

默认启动后，在浏览器访问：

http://localhost:3000

首次访问会进入初始化向导，按提示完成：

  1. 选择语言和时区
  2. 配置主要 LLM 提供商（选择 Coding Plan）
  3. 测试连接
  4. 可选：配置消息应用集成（微信、钉钉等）

6.3 首次对话测试

在 Web 界面或通过 CLI 发送测试消息：

# CLI 方式
openclaw chat "帮我列出当前目录的文件"

# 查看智能体是否正常响应和执行

6.4 ECS 部署的额外检查

# 检查服务开机自启
systemctl is-enabled openclaw  # 应输出 enabled

# 检查防火墙规则
iptables -L -n | grep 3000

# 阿里云安全组也需要开放对应端口
# 在 ECS 控制台: 实例 -> 安全组 -> 入方向 -> 添加规则 -> TCP 3000

常见安装问题

问题：npm install 卡在下载阶段

切换为淘宝镜像源：

npm config set registry https://registry.npmmirror.com
npm install -g openclaw

问题：Node.js 版本不兼容

# 检查当前版本
node --version

# 用 nvm 切换到 Node.js 20
nvm install 20 && nvm use 20

问题：Docker 容器启动后立即退出

# 查看容器日志找原因
docker logs openclaw-agent --tail 50

# 常见原因：配置文件格式错误，检查 JSON 语法
node -e "JSON.parse(require('fs').readFileSync('./config/claw.config.json', 'utf8'))"

问题：Coding Plan API 返回 401

确认 API Key 正确且未过期，在环境变量中检查：

echo $CODING_PLAN_API_KEY  # 确认变量已设置

更多故障排除，参考：OpenClaw Coding Plan 故障排除

下一步

安装完成后，建议按顺序了解：

  1. 安全加固：OpenClaw 安全问题解决方案 - 沙箱配置、端口安全、技能审计
  2. 模型调优：OpenClaw 模型选择指南 - 根据任务类型路由不同模型
  3. 故障排除：OpenClaw Coding Plan 故障排除 - 常见报错和修复方案

英文版完整指南（包含更多集成方案）：OpenClaw Ultimate Guide

返回中文博客