OpenClaw 完整实操手册

从零开始 · 安装 Node.js → 配置 API Key → 接入飞书 · 全用图文步骤
适用版本：OpenClaw v2026.3.13 · 2026年3月
出品：极拓工坊

第一部分：安装 Node.js

为什么需要 Node.js？

OpenClaw 是用 TypeScript/JavaScript 写的，必须运行在 Node.js 环境下。要求版本 ≥ 22（推荐 Node 24）。

先检查你是否已经有 Node.js

打开终端（Windows 用命令提示符或 PowerShell，macOS/Linux 用 Terminal），输入：

bash

node --version

✅ 如果看到 v24.x.x 或 v22.x.x，说明已安装，版本满足要求，跳到第二部分。
⚠️ 如果报错 "command not found" 或版本号 < v22，需要安装或升级。

Windows 安装 Node.js

推荐方案：WSL2

OpenClaw 官方强烈推荐 Windows 用户在 WSL2 里运行，原生 Windows 环境有兼容性问题。

方案 A：原生 Windows 安装（简单，适合新手）

1. 访问 Node.js 官网下载安装包

打开浏览器，访问：https://nodejs.org/zh-cn

点击 【LTS 长期支持版】（绿色大按钮），下载 .msi 安装包。

2. 运行安装包，全部默认下一步

双击下载的 .msi 文件 → 一直点"Next"→ 最后点"Install"。

注意勾选

安装过程中有一步会问"是否安装必要的工具（如 Python、构建工具）"，勾选上。

3. 验证安装

关掉所有终端窗口，重新打开 PowerShell，输入：

bash

node --version
npm --version

两个命令都有版本号输出说明安装成功。

方案 B：WSL2 安装（推荐，性能更好）

先检查是否已有 WSL2：

打开 PowerShell，运行：

bash

wsl --status

✅ 看到 Default Version: 2 → 直接跳到步骤3
⚠️ 报错或显示 Version: 1 → 继续步骤1和2

1. 以管理员身份打开 PowerShell

在 Windows 搜索栏搜"PowerShell" → 右键 → 以管理员身份运行

2. 安装 WSL2 + Ubuntu

bash

wsl --install

等待安装完成，重启电脑。重启后会自动弹出 Ubuntu 终端，按提示设置用户名和密码。

3. 在 Ubuntu 终端里安装 Node.js 22

bash

# 添加 NodeSource 源
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -

# 安装 Node.js
sudo apt-get install -y nodejs

# 验证
node --version   # 应显示 v22.x.x
npm --version

注意

不要在 Windows 的 PowerShell 或 CMD 里运行这些命令，要在 Ubuntu 终端里运行。

macOS 安装 Node.js

方案 A：官网安装包（最简单）

访问 https://nodejs.org/zh-cn → 下载 .pkg 文件 → 双击安装
安装 Xcode 命令行工具：xcode-select --install
验证：node --version

方案 B：Homebrew 安装（开发者推荐）

bash

# 如果没有 Homebrew，先安装
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 安装 Node.js
brew install node@22

node --version

Linux 安装 Node.js（Ubuntu / Debian）

bash

# NodeSource 官方源（推荐）
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs

# 验证
node --version

第二部分：安装 OpenClaw

1. 一键安装脚本

bash

# macOS / Linux / WSL2
curl -fsSL https://openclaw.ai/install.sh | bash

# Windows PowerShell（原生，不用 WSL2）
iwr -useb https://openclaw.ai/install.ps1 | iex

2. 或用 npm 手动安装

bash

npm install -g openclaw@latest

macOS 常见报错

如果提示 sharp 相关错误，改用： SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g openclaw@latest

3. 运行初始化向导

bash

openclaw onboard --install-daemon

4. 验证安装

bash

openclaw doctor       # 诊断检查
openclaw --version    # 查看版本号
openclaw dashboard    # 打开 Web UI（浏览器 http://127.0.0.1:18789）

5. ⚠️ 必办：设置 Gateway 认证

推荐写入 .env 文件（更新不会覆盖）：

bash

# 新建或编辑 ~/.openclaw/.env
OPENCLAW_GATEWAY_TOKEN=你设的强密码

或写入 openclaw.json：

json

{
  "gateway": {
    "auth": {
      "mode": "token",
      "token": "设置一个你自己的强密码"
    }
  }
}

bash

openclaw gateway restart   # 重启使配置生效

v2026.3.13 强制要求

必须显式设置 gateway.auth.mode，否则 Gateway 拒绝启动。曾有 30,000+ 实例暴露公网！

第三部分：配置 AI 模型 API Key

什么是 API Key？

AI 模型提供商通过 API Key 识别你的身份，按调用量计费。OpenClaw 需要至少配置一个模型的 API Key 才能运行。

支持的模型提供商

提供商	代表模型	价格/百万Token	获取 API Key 地址	推荐场景
GLM（智谱）	GLM Flash	免费	bigmodel.cn	心跳/实时任务
DeepSeek	DeepSeek-V3	$0.14	platform.deepseek.com	日常任务，性价比最高
通义千问	Qwen 3.5 Plus	$0.40	dashscope.aliyun.com	中文NLP
月之暗面	Kimi K2.5	$0.60	platform.moonshot.cn	中文Agent
Anthropic	Claude Sonnet 4.6	$3.00	console.anthropic.com	Agent 效果最佳
OpenAI	GPT-5.4	$2.50	platform.openai.com	通用
硅基流动	多模型聚合	按模型	siliconflow.cn	一个Key调多家
Ollama（本地）	Qwen/Llama等	完全免费	ollama.com	隐私敏感，需32GB RAM

如何获取 API Key（以 DeepSeek 为例）

访问 platform.deepseek.com 注册账号
左侧菜单 → API Keys → 点击"创建 API Key"→ 复制保存
格式示例：sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

将 API Key 配置到 OpenClaw

方式一：向导配置（最简单）

bash

openclaw onboard

方式二：直接编辑配置文件

编辑 ~/.openclaw/openclaw.json：

json

{
  "env": {
    "DEEPSEEK_API_KEY": "sk-你的DeepSeek Key",
    "ANTHROPIC_API_KEY": "sk-ant-你的Claude Key"
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "deepseek/deepseek-chat",
        "fallbacks": ["zai/glm-4.5-flash"]
      }
    }
  }
}

验证模型连通性

bash

openclaw models list            # 列出已配置的模型
openclaw models status --probe  # 实际发一条测试请求

Fallback 是什么？

当主力模型不可用（服务器超载、Key 额度用完）时，OpenClaw 自动切换到备用模型继续工作。例如主力用 DeepSeek，Fallback 设 GLM Flash（免费），即使 DeepSeek 偶尔故障，Agent 也不会中断。

第四部分：接入飞书 — 完整操作指南

飞书接入的核心优势

使用 WebSocket 长连接模式，Bot 主动连接飞书服务器，完全不需要公网 IP、不需要域名、不需要配置反向代理。

需要准备：

一个飞书账号（个人版/企业版均可）
OpenClaw 已安装并配置了 AI 模型 API Key
约 15 分钟时间

第一阶段：飞书开发者平台建立应用

1. 打开飞书开放平台

访问：https://open.feishu.cn/app，用飞书账号登录。

2. 创建企业自建应用

点击 【创建企业自建应用】，填写应用名称和描述，点击"确定"。

3. 复制 App ID 和 App Secret（重要！）

在左侧菜单 【凭证与基础信息】 中找到：

App ID：格式为 cli_xxxxxxxxxxxxxxxx
App Secret：点击"查看"按钮，复制完整字符串

安全提醒

App Secret 相当于密码，不要分享给他人，不要提交到代码仓库。

4. 配置应用权限

左侧菜单 → 【权限管理】 → 点击右上角 【批量导入】，粘贴以下 JSON：

json

{
  "scopes": {
    "tenant": [
      "im:message",
      "im:message.p2p_msg:readonly",
      "im:message.group_at_msg:readonly",
      "im:message:send_as_bot",
      "im:resource",
      "im:chat.members:bot_access",
      "im:chat.access_event.bot_p2p_chat:read",
      "application:application:self_manage",
      "application:bot.menu:write",
      "contact:user.employee_id:readonly"
    ],
    "user": [
      "im:chat.access_event.bot_p2p_chat:read"
    ]
  }
}

5. 启用机器人（Bot）能力

左侧菜单 → 【应用功能】 → 【机器人】 → 点击"启用机器人"开关。

6. 配置事件订阅

顺序重要！

必须先完成下面的 OpenClaw 配置步骤（7-12），让 Gateway 运行起来，然后再回来配置这个。

第二阶段：在 OpenClaw 里配置飞书插件

7. 安装飞书插件

bash

openclaw plugins install @openclaw/feishu

8. 添加飞书渠道

bash

openclaw channels add

选择 Feishu，按提示粘贴 App ID 和 App Secret。

9. 或手动编辑配置文件

编辑 ~/.openclaw/openclaw.json：

json

{
  "channels": {
    "feishu": {
      "enabled": true,
      "dmPolicy": "pairing",
      "accounts": {
        "main": {
          "appId": "cli_你的AppID",
          "appSecret": "你的AppSecret",
          "botName": "OpenClaw AI助手"
        }
      }
    }
  }
}

10. 重启 Gateway

bash

openclaw gateway restart
openclaw gateway status    # 确认 running

11. 查看日志，确认飞书插件已加载

bash

openclaw logs --follow

在日志里找到：

[feishu] WebSocket connected to Feishu event server
[feishu] Bot main ready, listening for messages

第三阶段：回到飞书平台完成事件订阅

12. 配置事件订阅

回到飞书开放平台 → 你的应用 → 左侧 【事件订阅】：

选择 【使用长连接接收事件】（不要选 Webhook HTTP 模式）
点击"添加事件"，搜索 im.message.receive_v1，添加

13. 保存事件订阅，确认提示"连接正常"。

14. 发布应用

左侧菜单 → 【版本管理与发布】 → 创建版本 → 保存 → 申请发布。

第四阶段：在飞书里找到机器人并开始对话

15. 在飞书 App 里搜索你的机器人名称

16. 发送第一条消息

机器人会回复一个 6位验证码。

17. 在终端里批准配对

bash

openclaw pairing approve feishu 482931

18. 开始正式对话！ 🎉

进阶：跳过配对（设置白名单）

19. 获取你的飞书 Open ID

bash

openclaw logs --follow
# 向机器人发一条消息，在日志里找 open_id（格式：ou_xxxxxxxxxx）

20. 在配置里加入白名单

json

{
  "channels": {
    "feishu": {
      "dmPolicy": "allowlist",
      "allowFrom": ["ou_你的OpenID"]
    }
  }
}

bash

openclaw gateway restart

进阶：把机器人加入群聊

21. 在飞书群里点"…"→ 添加机器人 → 搜索你的机器人

22. 群里默认需要 @机器人才会触发回复。发送 /activation always 可改为自动回复所有消息。

第五部分：常见问题排查

问题现象	原因	解决方法
发消息机器人没有任何回复	Gateway 没有运行	`openclaw gateway status` 检查状态
机器人回复了验证码但一直等	没有运行 pairing approve	`openclaw pairing approve feishu <验证码>`
事件订阅保存失败	Gateway 没运行或飞书长连接没建立	先确保 Gateway 运行且日志有 "feishu WebSocket connected"
日志报 "AppID or AppSecret missing"	配置文件里 appId/appSecret 填写有误	检查 openclaw.json 格式

通用诊断命令：

bash

openclaw doctor            # 全面检查环境
openclaw logs --follow     # 实时查看日志
openclaw channels status   # 检查渠道连接状态
openclaw config validate   # 检查配置文件语法

第六部分：完整卸载指南

卸载不只是删文件！

OpenClaw 会注册守护进程（开机自启服务），并持有 Google、Slack、GitHub 等平台的 OAuth Token。单纯删文件或 npm uninstall 会留下残余。

一键卸载

bash

openclaw uninstall --all --yes --non-interactive

手动清理

macOS：

bash

launchctl unload ~/Library/LaunchAgents/com.openclaw.gateway.plist 2>/dev/null
launchctl unload ~/Library/LaunchAgents/ai.openclaw.gateway.plist 2>/dev/null
rm -f ~/Library/LaunchAgents/*openclaw*
rm -rf ~/.openclaw ~/.clawdbot ~/.moltbot
npm uninstall -g openclaw

Linux / WSL2：

bash

systemctl --user stop openclaw-gateway.service 2>/dev/null
systemctl --user disable openclaw-gateway.service 2>/dev/null
rm -f ~/.config/systemd/user/openclaw-gateway.service
rm -rf ~/.openclaw ~/.clawdbot ~/.moltbot
npm uninstall -g openclaw

Windows PowerShell：

powershell

Stop-ScheduledTask -TaskName "OpenClaw Gateway" -ErrorAction SilentlyContinue
Unregister-ScheduledTask -TaskName "OpenClaw Gateway" -Confirm:$false -ErrorAction SilentlyContinue
Remove-Item -Recurse -Force "$env:USERPROFILE\.openclaw" -ErrorAction SilentlyContinue
npm uninstall -g openclaw

⚠️ 最后一步：撤销 OAuth Token

平台	撤销地址
Google	myaccount.google.com/permissions
GitHub	github.com/settings/applications
Slack	slack.com/apps/manage
Discord	discord.com/developers/applications
飞书	open.feishu.cn → 你的应用 → 停用或删除

建议同时去 AI 模型平台禁用或更换用过的 API Key。

第七部分：Skill Vetter 使用指南

什么是 skill-vetter？

一个专门在你安装任何第三方 Skill 之前做安全审查的工具。输入 SKILL.md 内容，几秒钟给出 SAFE / CAUTION / DANGEROUS 评级。

安装

bash

# 在 Ubuntu 终端里运行
npx clawhub@latest install openclaw-skill-vetter

# 验证
openclaw skills list

# 重启 Gateway
openclaw gateway restart

使用方式

对话式审查（最常用）： 在飞书 / Telegram 里向 Agent 发送：

帮我审查这个 Skill 是否安全，给出评级：

[粘贴 SKILL.md 的完整内容]

扫描已安装的 Skills：

bash

openclaw skills scan ~/.openclaw/skills/

评级说明

评级	含义	建议
✅ SAFE	未发现安全问题	可以安装
⚠️ CAUTION	有需要注意的地方	仔细看 Agent 说明
🚫 DANGEROUS	发现高危模式	不要安装
❓ UNKNOWN	来源不明	不建议安装

重点检测项

危险模式	风险
网络请求 + Shell 命令组合	数据外传
eval / exec 动态执行	任意代码执行
隐蔽外部回调	C2 通信
混淆/编码代码	隐藏恶意逻辑
仿冒知名 Skill	typosquat 诈骗

OpenClaw 完整实操手册 ​

第一部分：安装 Node.js ​

先检查你是否已经有 Node.js ​

Windows 安装 Node.js ​

方案 A：原生 Windows 安装（简单，适合新手） ​

方案 B：WSL2 安装（推荐，性能更好） ​

macOS 安装 Node.js ​

方案 A：官网安装包（最简单） ​

方案 B：Homebrew 安装（开发者推荐） ​

Linux 安装 Node.js（Ubuntu / Debian） ​

第二部分：安装 OpenClaw ​

第三部分：配置 AI 模型 API Key ​

支持的模型提供商 ​

如何获取 API Key（以 DeepSeek 为例） ​

将 API Key 配置到 OpenClaw ​

第四部分：接入飞书 — 完整操作指南 ​

第一阶段：飞书开发者平台建立应用 ​

第二阶段：在 OpenClaw 里配置飞书插件 ​

第三阶段：回到飞书平台完成事件订阅 ​

第四阶段：在飞书里找到机器人并开始对话 ​

进阶：跳过配对（设置白名单） ​

进阶：把机器人加入群聊 ​

第五部分：常见问题排查 ​

第六部分：完整卸载指南 ​

一键卸载 ​

手动清理 ​

⚠️ 最后一步：撤销 OAuth Token ​

第七部分：Skill Vetter 使用指南 ​

安装 ​

使用方式 ​

评级说明 ​

重点检测项 ​

OpenClaw 完整实操手册

第一部分：安装 Node.js

先检查你是否已经有 Node.js

Windows 安装 Node.js

方案 A：原生 Windows 安装（简单，适合新手）

方案 B：WSL2 安装（推荐，性能更好）

macOS 安装 Node.js

方案 A：官网安装包（最简单）

方案 B：Homebrew 安装（开发者推荐）

Linux 安装 Node.js（Ubuntu / Debian）

第二部分：安装 OpenClaw

第三部分：配置 AI 模型 API Key

支持的模型提供商

如何获取 API Key（以 DeepSeek 为例）

将 API Key 配置到 OpenClaw

第四部分：接入飞书 — 完整操作指南

第一阶段：飞书开发者平台建立应用

第二阶段：在 OpenClaw 里配置飞书插件

第三阶段：回到飞书平台完成事件订阅

第四阶段：在飞书里找到机器人并开始对话

进阶：跳过配对（设置白名单）

进阶：把机器人加入群聊

第五部分：常见问题排查

第六部分：完整卸载指南

一键卸载

手动清理

⚠️ 最后一步：撤销 OAuth Token

第七部分：Skill Vetter 使用指南

安装

使用方式

评级说明

重点检测项