OpenClaw 部署与配置指南 (2026 最新版)

OpenClaw（昵称“小龙虾”）是一款强大的本地优先 AI 智能体框架，能让 AI 真正操作您的电脑、文件和工具。本指南将带您通过两种主流方式完成部署，并配置核心功能。

---

📋 前置要求

在开始之前，请确保您的环境满足以下条件：

• 操作系统：Windows 10/11, macOS 10.15+, 或 Linux (Ubuntu 20.04+)
• 网络：能够访问 GitHub 和 npm 源（国内用户建议配置镜像）
• 账号：准备好大模型 API Key（如 DeepSeek, Qwen, Ollama 本地模型等）
• 权限：拥有管理员/root 权限以安装系统依赖

---

🚀 安装方式一：通过 Node.js 安装 (推荐开发者)

这种方式最灵活，适合需要自定义开发或跨平台部署的用户。

1. 安装 Node.js 环境

OpenClaw 基于 Node.js 开发，必须安装 Node.js v22+ (推荐 v22 LTS 或 v24)。

• Windows/macOS:

  1. 访问 Node.js 官网 下载 LTS 版本安装包。
  2. 运行安装程序，一路默认即可。
  3. 验证安装：打开终端（CMD/PowerShell/Terminal），输入：

     node -v
     # 应输出 v22.x.x 或更高
     npm -v
     

• Linux (Ubuntu/Debian):

  # 更新源
  sudo apt update
  # 安装 Node.js 22.x (2026年推荐版本)
  curl -fsSL https://deb.nodesource.com/setup_22.x | sudo bash
  sudo apt install -y nodejs git
  

2. 安装 OpenClaw

使用 npm 全局安装 OpenClaw：

# 可选：配置国内镜像加速 (中国大陆用户推荐)
npm config set registry https://registry.npmmirror.com

# 全局安装 OpenClaw
npm install -g openclaw

3. 验证安装

openclaw --version
# 应输出版本号，如 2026.3.2

---

📦 安装方式二：通过官方包 cusl 安装 (推荐新手)

cusl (Claw Universal Setup Launcher) 是官方提供的独立安装器，自动处理环境依赖，适合不想手动配置 Node.js 的用户。

1. 下载安装器

• Windows:

  1. 访问 OpenClaw 官网下载页。
  2. 下载 OpenClaw-Setup-x64.exe。
  3. 双击运行，按向导完成安装。

• macOS:
  打开终端，执行一键安装脚本：

  curl -fsSL https://openclaw.ai/install.sh | bash
  

  注：如果脚本执行失败，可尝试手动下载 .dmg 安装包进行拖拽安装。

• Linux:

  wget -qO- https://openclaw.ai/install.sh | bash
  

2. 验证安装

安装完成后，cusl 会自动将 openclaw 命令加入环境变量。

openclaw --version

如果提示命令不存在，请尝试重启终端或运行 source ~/.bashrc (Linux/macOS)。

---

⚙️ 后续配置流程

安装完成后，需要进行初始化配置才能正常使用。

1.命令流程版

# 启动配置向导 
openclaw onboard

会自动跳转到Qwen网页进行登录认证


暂时跳过，后续可配置



配置完成后，在浏览器打开即可。

# 后续重新配置
openclaw onboard

后续如上述选择需要的模型配置即可。

2.修改配置文件版

第一步：初始化配置

首次运行会自动生成配置文件。手动触发初始化或编辑配置：

# 直接编辑配置文件
# Windows: C:\Users\<你的用户名>\.openclaw\openclaw.json
# macOS/Linux: ~/.openclaw/openclaw.json

第二步：配置大模型 (LLM)

OpenClaw 本身不包含模型，需对接外部 API 或本地模型。编辑 openclaw.json 中的 models 部分。

示例：配置本地 Ollama (推荐)

"models": {
  "providers": {
    "local-ollama": {
      "baseUrl": "http://127.0.0.1:11434/v1",
      "apiKey": "ollama",
      "api": "openai-completions",
      "models": [
        {
          "id": "qwen2.5:7b",
          "name": "Qwen 2.5 7B",
          "contextWindow": 32000
        }
      ]
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "local-ollama/qwen2.5:7b"
      }
    }
  }
}

注意：需先安装并运行 Ollama 服务 (ollama serve) 并拉取模型 (ollama pull qwen2.5:7b)。

示例：配置云端 API (如 DeepSeek/通义千问)

"models": {
  "providers": {
    "deepseek": {
      "baseUrl": "https://api.deepseek.com/v1",
      "apiKey": "sk-YOUR_API_KEY_HERE",
      "api": "openai-completions",
      "models": [{"id": "deepseek-chat", "name": "DeepSeek Chat"}]
    }
  }
}

第三步：配置通道 (Channels) - 以飞书为例

如果您希望机器人能在飞书上运行，需配置 channels。重要提示：2026.3.x 版本后，飞书支持已内置，无需安装额外插件！

编辑 openclaw.json：

"channels": {
  "feishu": {
    "enabled": true,
    "appId": "cli_xxxxxxxxxxxxx",       // 填入飞书应用 App ID
    "appSecret": "xxxxxxxxxxxxxxxx",    // 填入飞书应用 App Secret
    "verificationToken": "xxxxxxxxxx",  // 填入验证 Token
    "connectionMode": "websocket",      // 推荐使用 WebSocket
    "dmPolicy": "open",                 // 允许私聊
    "groupPolicy": "open"               // 允许群聊
  }
},
"plugins": {
  // 【关键】确保此处为空，不要手动安装 feishu 插件，避免冲突！
  "entries": {},
  "installs": {}
}

第四步：启动服务

配置完成后，启动 OpenClaw Gateway：

# 前台运行 (查看实时日志)
openclaw gateway start

# 后台运行 (作为服务)
openclaw daemon

# 重启
openclaw gateway restart

# 配置
openclaw onboard

启动成功后，终端会显示类似信息：

[info] Gateway started on http://127.0.0.1:18789
[info] Control UI available at http://localhost:18789/ui
[info] Channel 'feishu' connected via WebSocket

第五步：访问控制界面 (Control UI)

打开浏览器访问 http://localhost:18789/ui (或配置的端口)。

• 在界面中查看连接状态。
• 调试 Agent 行为。
• 查看实时日志。

---

🔧 常见问题排查 (FAQ)

1. 报错 duplicate plugin id detected

• 原因：同时启用了内置飞书通道和外部飞书插件。
• 解决：编辑 openclaw.json，清空 plugins 字段（参考上文配置示例），只保留 channels.feishu。删除目录 ~/.openclaw/extensions/feishu 后重启。

2. 报错 system busy 或 PingInterval undefined

• 原因：配置冲突导致连接对象初始化失败，或服务器负载过高。
• 解决：
  1. 检查并修复上述插件冲突。
  2. 重启服务：openclaw restart。
  3. 检查服务器 CPU/内存使用情况。

3. 飞书机器人“已读不回”

• 原因：
  • appId 或 appSecret 填写错误。
  • 飞书开发者后台未配置“事件订阅”URL（如果是 HTTP 模式）。
  • 本地网络无法被飞书访问（WebSocket 模式通常不需要公网 IP，但需确保出站连接正常）。
• 解决：
  • 核对凭证。
  • 查看日志中是否有 WebSocket client started 和 ws client ready。
  • 尝试在飞书开发者后台重新发布应用版本。

4. Node.js 版本过低

• 现象：安装时报错 ERR_UNSUPPORTED_NODE_VERSION。
• 解决：OpenClaw 2026 版要求 Node.js v22+。请使用 nvm (Node Version Manager) 升级：

  nvm install 22
  nvm use 22
  

---

🎉 完成