�� OpenClaw 新手小白完全安装指南

"看完想装，但卡在第一步了"
"飞书那边要配什么权限完全搞不明白"
"我连 Node.js 是什么都不知道，能装吗？"

📦 GitHub：https://github.com/openclaw/openclaw（265k+ ⭐，MIT 开源）
📖 官方文档：https://docs.openclaw.ai

安装前的准备

▎你需要什么？

•✅ 一台电脑（macOS / Linux / Windows 需 WSL2）

•✅ Node.js 22 或更高版本（OpenClaw 运行的基础环境）

•✅ 一个 AI 模型的 API Key（比如 OpenAI 或 Anthropic 的 key）

•❌ 不需要 Python

•❌ 不需要 Docker（除非你要部署到服务器）

•❌ 不需要公网 IP（飞书用 WebSocket 长连接）

▎为什么需要 Node.js？

•Python 程序需要装 Python

•Java 程序需要装 JRE

•OpenClaw 需要装 Node.js

▎安装 Node.js（如果你还没装的话）

node --version

如果显示 v22.x.x 或更高 → ✅ 不用装了，跳到下一节
如果显示 v18.x.x 或更低 → ❌ 需要升级
如果显示 command not found → ❌ 需要安装

为什么用 nvm？因为它能让你同时安装多个 Node 版本，随时切换，不会搞乱系统。

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash

nvm install 22
nvm use 22

node --version
# 应该显示 v22.x.x ✅

⚠️ 常见坑：装完 nvm 后直接输 nvm install 报错 nvm: command not found
原因：终端的配置文件还没加载 nvm
解决：关掉终端窗口，重新打开一个新的

安装 OpenClaw

▎安装流程图

▎第 ① 步：安装

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

这个脚本做了什么？
1. 检查你的 Node 版本
2. 通过 npm 全局安装 openclaw 包
3. 把 openclaw 命令加到你的 PATH

npm install -g openclaw@latest

💡 -g 代表全局安装，安装后你可以在任何目录使用 openclaw 命令。

▎第 ② 步：运行引导向导

openclaw onboard --install-daemon

🧙 向导会一步步问你：

- Step 1/4：选择 AI 模型提供商 → 国内推荐选 通义千问 或 智谱 GLM（免翻墙、注册就送额度），海外可选 OpenAI
- Step 2/4：输入 API Key → 去对应平台拿 Key，比如通义千问在 DashScope 控制台 创建，智谱在 open.bigmodel.cn 创建
- Step 3/4：要配置聊天渠道吗？→ 先选 跳过（之后再配）
- Step 4/4：安装后台守护进程 → 选 是的，安装 daemon
- ✅ 配置完成！Gateway 已启动！

--install-daemon 是什么意思？

它会把 OpenClaw 注册为系统服务，开机自动启动。就像把它变成一个「后台常驻程序」。
- macOS 上用 launchd
- Linux 上用 systemd

▎第 ③ 步：验证安装成功

# 看 Gateway 是否在运行
openclaw gateway status

openclaw dashboard

浏览器会自动打开 http://127.0.0.1:18789/

配置飞书（重点 · 手把手教）

▎为什么要接飞书？

•不用打开额外的网页，在你每天用的飞书里直接聊

•可以在群里 @AI，团队共用

•可以给不同群分配不同的 AI 角色

▎原理：飞书是怎么跟 OpenClaw 通信的？

1.❶ 你在飞书发消息（"帮我写个周报"）

2.❷ Gateway 收到消息，调用 AI 模型

3.❸ AI 返回回复，Gateway 推送回飞书

4.❹ 飞书显示回复（"好的，这是你的周报..."）

关键点：用的是 WebSocket 长连接！

这意味着：
- ✅ 你不需要公网 IP（飞书主动连你，不是你暴露端口给飞书）
- ✅ 你不需要配域名
- ✅ 你不需要 Nginx 反向代理
- ✅ 只要你的电脑能联网就行

这跟微信公众号的「回调 URL」模式完全不同！飞书的 WebSocket 方式对小白友好得多。

▎全流程图

⚠️ 顺序很重要：Step 4（事件订阅）必须在 Step 3 之后做，因为飞书会尝试连接你的 Gateway，Gateway 没运行就会失败。

▎Step 1：安装飞书插件（1 分钟）

openclaw plugins install @openclaw/feishu

为什么是插件？
OpenClaw 把不那么主流的渠道做成了插件形式，这样核心程序更轻量。
飞书、LINE、Microsoft Teams 等都是插件。
而 WhatsApp、Telegram、Slack、Discord 是内置的（因为用户多）。

openclaw plugins install ./extensions/feishu

▎Step 2：在飞书平台创建应用（10 分钟）

这是最费时间的一步，但只做一次。按我说的一步步来就行。

▎2.1 打开飞书开放平台

如果你用的是国际版 Lark，打开这个：https://open.larksuite.com/app

▎2.2 创建应用

•应用名称：我的AI助手（随便起）

•应用描述：基于OpenClaw的AI助手

•应用图标：随便选一个

📸 参考官方文档中的截图，按上方表单填写即可。

▎2.3 复制 App ID 和 App Secret

•App ID：cli_a5xxxxxxxxxxxxx

•App Secret：点击 👁 显示后复制

📸 实际截图：

复制 App ID 和 App Secret

这两个值是什么？
- App ID = 你这个应用的「身份证号」，告诉飞书"我是谁"
- App Secret = 你这个应用的「密码」，证明"我是我"

就像你登录网站需要用户名+密码，OpenClaw 连飞书也需要这两个。

▎2.4 配置权限

为什么要配权限？
飞书出于安全考虑，应用默认什么都不能做。你必须告诉飞书「这个应用需要读消息、发消息」。

{
  "scopes": {
    "tenant": [
      "aily:file:read",
      "aily:file:write",
      "application:application.app_message_stats.overview:readonly",
      "application:application:self_manage",
      "application:bot.menu:write",
      "cardkit:card:read",
      "cardkit:card:write",
      "contact:user.employee_id:readonly",
      "corehr:file:download",
      "event:ip_list",
      "im:chat.access_event.bot_p2p_chat:read",
      "im:chat.members:bot_access",
      "im:message",
      "im:message.group_at_msg:readonly",
      "im:message.p2p_msg:readonly",
      "im:message:readonly",
      "im:message:send_as_bot",
      "im:resource"
    ],
    "user": [
      "aily:file:read",
      "aily:file:write",
      "im:chat.access_event.bot_p2p_chat:read"
    ]
  }
}

这些权限都干嘛的？

| 权限 | 白话翻译 |
|------|---------|
| im:message | 能收消息 |
| im:message:send_as_bot | 能发消息 |
| im:message.p2p_msg:readonly | 能读私聊消息 |
| im:message.group_at_msg:readonly | 能读群里 @它的消息 |
| im:resource | 能收发图片/文件 |
| im:chat.members:bot_access | 能知道群成员 |
| 其他 | 辅助功能，不给也影响不大 |

📸 实际截图：

批量导入权限

▎2.5 启用机器人能力

为什么要开启机器人能力？
因为飞书应用有很多种形态（网页应用、小程序、机器人……），
我们需要的是「机器人」形态——才能在聊天里跟它对话。

📸 实际截图：

机器人配置

▎Step 4：配置事件订阅 + 发布应用（2 分钟）

确保你已完成 Step 3，且 Gateway 处于运行状态（终端运行 openclaw gateway status 应显示 running）。

▎4.1 配置事件订阅（⚠️ 最容易出错的一步）

1.事件接收方式：选 「使用长连接接收事件（WebSocket）」（不要选 HTTP 推送）

2.添加事件：搜索 im.message.receive_v1，勾选 「接收消息」

为什么选 WebSocket 而不是 HTTP 推送？

> HTTP 推送模式（不推荐）：
> 飞书 ──POST请求──▶ 你的公网URL ──▶ OpenClaw
>                     ↑
>                 需要公网IP！需要域名！需要SSL！
>                 对小白很不友好 ❌
>
> WebSocket 长连接模式（推荐 ✅）：
> 飞书 ◀──WebSocket──▶ OpenClaw
>                       ↑
>                   你的电脑主动连飞书
>                   不需要公网IP！不需要域名！
>                   只要能上网就行 ✅
>

📸 实际截图：

事件订阅配置

⚠️ 如果保存时报错：
- 确认 Gateway 正在运行：openclaw gateway status
- 确认飞书渠道已配置：检查 ~/.openclaw/openclaw.json
- 试试重启 Gateway：openclaw gateway restart

▎4.2 发布应用

📸 实际截图：

版本管理与发布

1.点击 「+ 创建版本」，填写版本号（比如 1.0.0）

2.点击 「申请发布」

3.企业自建应用通常会自动审核通过，等 1-2 分钟即可

发布后，企业内的人才能在飞书里搜到这个机器人。

▎Step 3：在 OpenClaw 中配置飞书（3 分钟）

▎方式 A：用向导（推荐，超简单）

openclaw channels add

会出现这样的界面：

> ? 选择要添加的渠道：
>   WhatsApp
>   Telegram
>   Slack
>   Discord
> ▸ Feishu          ◀── 选这个
>   更多...
>
> ? 输入 App ID: cli_a5xxxxxxxxxxxxx
> ? 输入 App Secret: ••••••••••••••••
>
> ✅ 飞书渠道已配置！
>

openclaw gateway restart

▎方式 B：手动编辑配置文件

{
  // 你之前配的模型设置
  agent: {
    model: "gpt-4o",
  },

  // 加上飞书渠道配置 👇
  channels: {
    feishu: {
      enabled: true,
      dmPolicy: "pairing",         // 首次私聊需要配对验证
      accounts: {
        main: {
          appId: "cli_a5xxxxx",     // ← 换成你的 App ID
          appSecret: "xxxxxx",      // ← 换成你的 App Secret
          botName: "我的AI助手",
        },
      },
    },
  },
}

每个字段是什么意思？

> enabled: true          → 开启飞书渠道
> dmPolicy: "pairing"    → 陌生人私聊时需要先"配对"（安全机制）
> appId                  → 你在飞书开放平台拿到的 App ID
> appSecret              → 你在飞书开放平台拿到的 App Secret
> botName                → 机器人的名字（显示用）
>

什么是 dmPolicy: "pairing"？

这是一个安全机制。想象一下：如果任何飞书用户都能直接跟你的 AI 聊天，
那你的 API 费用可能会爆炸。

pairing 模式下：
1. 陌生人发消息 → AI 不回复，而是返回一个配对码
2. 你在终端运行 openclaw pairing approve feishu <配对码>
3. 之后这个人就可以正常聊天了

> 用户 ──"你好"──▶ AI 回复 "配对码：abc123"
>
> 你 ──终端输入──▶ openclaw pairing approve feishu abc123
>
> 用户 ──"你好"──▶ AI 回复 "你好！有什么可以帮你？" ✅
>

{
  channels: {
    feishu: {
      domain: "lark",    // ← 国际版加这行
      // ... 其他配置
    },
  },
}

▎Step 5：测试！（1 分钟）

▎5.1 确认 Gateway 在运行

openclaw gateway status
# 应显示 running

openclaw logs --follow
# 实时看日志（Ctrl+C 退出）

▎5.2 在飞书里找到机器人

你：你好

🤖 AI：配对码：x7k2m

▎5.3 批准配对

# 查看待配对列表
openclaw pairing list feishu

# 批准
openclaw pairing approve feishu x7k2m    # 换成你收到的配对码

▎5.4 再次发消息

你：帮我写一首关于春天的诗

🤖 AI：春风拂面暖阳斜，桃花三月映朝霞。燕子低飞穿柳岸，满城春色入万家。

▎飞书群聊怎么玩？

张三：@我的AI助手 帮我总结一下今天的会议纪要

🤖 我的AI助手：好的，根据今天的会议内容，以下是要点总结：1. xxx  2. xxx ...

{
  channels: {
    feishu: {
      groups: {
        "oc_xxxx": {                  // 群的 ID
          requireMention: false,       // 不需要 @
        },
      },
    },
  },
}

1.在群里 @机器人发一条消息

2.在终端运行 openclaw logs --follow

3.在日志中搜索 chat_id，格式像 oc_xxxxxxxxxxxx

配置企业微信

📌 进阶内容：企业微信接入比飞书复杂得多——需要公网服务器、域名和 HTTPS 证书。如果你只用飞书，可以跳过这整节，直接看后面的「遇到问题怎么办」。

✅ 更新 (2026.3)：社区已推出企业微信插件 @mocrane/wecom，支持 Bot + Agent 双模融合，可直接安装使用！

▎原理：企业微信双模架构

▎🤔 为什么企业微信比飞书麻烦？

很多人会问：飞书那么简单，为啥企业微信这么折腾？
答案是：两家的技术方案完全不同。

这不是 OpenClaw 的限制，是企业微信本身只提供了 Webhook 回调模式，没有 WebSocket。
微信公众号、企业微信、钉钉都是这种回调模式。飞书是少数支持 WebSocket 的。

▎前置条件清单

•✅ 一个企业微信账号 —— 需要管理员权限。注册：https://work.weixin.qq.com/

•✅ 一个公网可访问的地址（三选一）：

•方案A：有服务器 → 直接部署（最稳定，⭐ 推荐）

•方案B：没服务器 → 用 ngrok/frp 内网穿透

•方案C：有服务器 → 服务器做反向代理到本机

•✅ HTTPS 证书（企业微信强制要求）—— 有域名用 Let's Encrypt 免费证书；用 ngrok 则自带

•✅ 一个域名（推荐但非必须）—— 没域名的话 ngrok 会给临时域名

❌ 飞书不需要上面任何一项！这就是为什么飞书简单得多。

▎Step 1：安装企业微信插件（1 分钟）

# 安装社区企业微信插件
openclaw plugins install @mocrane/wecom

# 启用插件
openclaw plugins enable wecom

# 确认状态
openclaw plugins list

▎Step 2：企业微信管理后台配置（10 分钟）

💡 只用 Bot 也可以聊天，Agent 是可选的增强（发文件、主动推送等）。

▎2.1 创建 Bot（智能机器人）

1.登录 企业微信管理后台

2.进入「安全与管理」→「管理工具」→「智能机器人」

3.创建机器人，选择 API 模式

4.填写回调 URL：https://你的域名/plugins/wecom/bot/default

5.记录以下信息：

•Token

•EncodingAESKey

•aibotid（Bot ID）

▎2.2 创建 Agent（自建应用，可选但推荐）

1.登录 企业微信管理后台

2.进入「应用管理」→「自建」→ 创建应用

3.获取：

•CorpId（企业ID，在「我的企业」页面）

•AgentId（应用ID）

•Secret（应用密钥）

1.⚠️ 重要：进入「企业可信IP」→ 添加你服务器的公网 IP

2.在应用详情 →「接收消息 - 设置API接收」

3.填写回调 URL：https://你的域名/plugins/wecom/agent/default

4.记录回调 Token 和 EncodingAESKey

▎Step 3：在 OpenClaw 中配置（3 分钟）

{
  channels: {
    // ... 飞书等已有渠道 ...
    wecom: {
      enabled: true,
      defaultAccount: "default",
      accounts: {
        default: {
          enabled: true,
          name: "AI助手",
          bot: {
            aibotid: "你的BOT_ID",
            token: "你的BOT_TOKEN",
            encodingAESKey: "你的BOT_AES_KEY",
            receiveId: "",
          },
          agent: {
            corpId: "你的企业CORP_ID",
            corpSecret: "你的AGENT_SECRET",
            agentId: 1000002,  // 你的应用AgentId
            token: "你的AGENT_TOKEN",
            encodingAESKey: "你的AGENT_AES_KEY",
          },
        },
      },
    },
  },
}

如果只用 Bot 不用 Agent，可以省略 agent 部分。

▎Step 4：网络配置（重要！三种方案详解）

•有 → 方案 A：服务器直接部署（最稳定，推荐）

•没有 → 方案 B：ngrok 内网穿透（临时用/测试）

•折中 → 方案 C：服务器做反向代理（OpenClaw 跑在 Mac 上，服务器只做流量中转）

▎方案 A：服务器直接部署（⭐ 最推荐）

把 OpenClaw 部署到你的云服务器上，企微直接回调服务器。
这是最稳定、最省心的方案。

•一台云服务器（2核4G 够用）

•一个域名（如 your-domain.com），DNS 解析到服务器 IP

•HTTPS 证书（用 Let's Encrypt 免费申请）

# 1. SSH 到你的服务器
ssh root@your-server-ip

# 2. 用 Docker 部署 OpenClaw（参考下面「服务器部署」章节）

# 3. 配置 Nginx 反向代理
# 在 /etc/nginx/conf.d/openclaw.conf 写入：

server {
    listen 443 ssl;
    server_name your-domain.com;  # 换成你的域名

    ssl_certificate     /etc/letsencrypt/live/your-domain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem;

    # 企业微信回调路径
    location /plugins/wecom/ {
        proxy_pass http://127.0.0.1:18789;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

# 4. 申请 HTTPS 证书（如果还没有）
sudo apt install certbot python3-certbot-nginx
sudo certbot --nginx -d your-domain.com

# 5. 重启 Nginx
sudo nginx -t && sudo systemctl reload nginx

# 6. 在企业微信管理后台填写回调URL：
#    Bot:   https://your-domain.com/plugins/wecom/bot/default
#    Agent: https://your-domain.com/plugins/wecom/agent/default

回调 URL 怎么写？

https://你的域名/plugins/wecom/bot/default

- https:// — 企微强制要求 HTTPS
- 你的域名 — 你的服务器域名
- /plugins/wecom/ — 固定路径，由 wecom 插件提供
- default — 你配置里 accounts 下的账号名

▎方案 B：ngrok 内网穿透（本机开发/测试用）

OpenClaw 跑在你的 Mac 上，用 ngrok 把本地端口暴露到公网。
适合开发测试，不适合长期使用（ngrok 免费版域名会变）。

•安装 ngrok（brew install ngrok）

•注册 ngrok 账号（免费）：https://ngrok.com/

•你的 Mac 需要一直开机并联网

# 1. 安装 ngrok
brew install ngrok

# 2. 登录（用你的 authtoken）
ngrok config add-authtoken 你的TOKEN

# 3. 启动隧道，把本地 18789 暴露出去
ngrok http 18789

ngrok 会显示一个公网地址，类似：

> Forwarding  https://a1b2c3d4.ngrok-free.app → http://localhost:18789
>

# 4. 把这个地址填到企业微信后台的回调 URL：
#    https://a1b2c3d4.ngrok-free.app/plugins/wecom/bot/default

# 5. 确保你的 OpenClaw Gateway 在运行
openclaw gateway status

⚠️ ngrok 免费版的限制：
- 每次重启 ngrok，域名会变 → 需要重新去企微后台改回调 URL
- 付费版可以固定域名（$8/月）
- 访问时会有 ngrok 的提示页（可能影响企微验证）

如果想稳定使用，建议方案 A 或方案 C。

▎方案 C：服务器反向代理到本机（折中方案）

OpenClaw 跑在你的 Mac 上，但用你的服务器做跳板。
比 ngrok 稳定，但需要维护 SSH 隧道 / frp。

•一台云服务器 + 域名 + HTTPS（同方案A）

•你的 Mac 需要一直开机并联网

•需要维护一个 SSH隧道 或 frp 连接

# 在你的 Mac 上运行（把本地 18789 映射到服务器的 18789）
ssh -R 18789:localhost:18789 root@your-server-ip -N

# -R = 反向隧道
# 18789:localhost:18789 = 服务器的18789端口 → 本机的18789端口
# -N = 不执行远程命令，只做端口转发

⚠️ 缺点：
- SSH 隧道会断（网络波动、Mac 休眠都会断）
- 需要用 autossh 或 frp 来自动重连
- Mac 合盖就断了，不适合 7x24

结论：如果你要长期用企业微信，还是把 OpenClaw 直接部署到服务器上（方案A）最省心。

▎三种方案对比

# 如果部署在服务器上（方案A），改为局域网绑定
openclaw config set gateway.bind lan

# 如果在本机用 ngrok（方案B），保持默认的 loopback 就行

{
  channels: {
    wecom: {
      network: {
        egressProxyUrl: "http://proxy.example.com:3128",
      },
    },
  },
}

▎Step 5：重启并测试

# 重启 gateway
openclaw gateway restart

# 查看渠道状态
openclaw channels status

# 查看日志
openclaw logs --follow

▎企业微信 vs 飞书对比

▎相关链接

•企业微信管理后台：https://work.weixin.qq.com/wework_admin/

•插件 npm 页面：https://www.npmjs.com/package/@mocrane/wecom

•插件完整文档：~/.openclaw/extensions/wecom/README.md

服务器部署（Docker 方式）

如果你想让 AI 助手 7x24 小时在线，需要部署到服务器上。

▎什么时候需要 Docker？

•在自己电脑上玩玩 → 不需要 Docker，前面的方式就够了

•要 7x24 在线 → 需要一台服务器 + Docker 部署

▎部署流程图

▎操作步骤

# 1. SSH 登录你的服务器
ssh root@你的服务器IP

# 2. 确保 Docker 已安装
docker --version
docker compose version

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

# 4. 一键部署
./docker-setup.sh
# 脚本会自动：构建镜像 → 运行向导 → 启动 Gateway → 生成 Token

# 5. 打开浏览器验证
# 访问 http://你的服务器IP:18789/
# 把脚本输出的 Token 粘贴到设置里

export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"
./docker-setup.sh

遇到问题怎么办？

▎诊断三板斧

1.看 Gateway 状态：openclaw gateway status

2.看日志：openclaw logs --follow

3.跑诊断：openclaw doctor（自动检查配置问题并给出建议）

▎常见问题及原理解释

▎❌ 飞书机器人不回复

1.先看 Gateway 是否在运行：openclaw gateway status

•没运行 → 重启：openclaw gateway restart

•在运行 → 继续下一步

1.看日志里有没有收到消息：openclaw logs --follow

•没收到消息 → 飞书那边配置有问题，检查以下几项：

•应用发布了吗？

•事件订阅配了 im.message.receive_v1 吗？

•用的是 WebSocket 模式吗？

•Gateway 运行时才能保存事件配置！

•收到了消息但没回复 → 可能是配对问题：openclaw pairing list feishu

▎❌ 安装时报 Node version 错误

原理：OpenClaw 用了很多 Node.js 22 才有的新特性（如 ES modules、fetch API），
老版本的 Node 跑不起来。

# 解决：切换到 Node 22
nvm install 22
nvm use 22
node --version  # 确认 v22.x

▎❌ openclaw: command not found

原理：npm 全局安装的包放在某个目录下，但你的终端不知道去那里找。

# 查看 npm 全局安装路径
npm config get prefix

# 确保这个路径在你的 PATH 里
# 通常是 /usr/local 或 ~/.nvm/versions/node/v22.x.x

# 如果用的 nvm，确保终端加载了 nvm：
source ~/.nvm/nvm.sh

▎❌ Gateway 启动后端口被占用

原理：OpenClaw 默认用 18789 端口。如果已经有程序占了这个端口，就会冲突。

# 看谁在用这个端口
lsof -i :18789

# 换个端口启动
openclaw gateway --port 19000

▎❌ API Key 无效 / AI 不回复

原理：OpenClaw 是「壳」，真正的 AI 能力来自 OpenAI / Anthropic 等模型提供商。
如果 API Key 失效或欠费，AI 就没法回复。

# 重新设置 API Key
export OPENAI_API_KEY="sk-新的key"
# 或
export ANTHROPIC_API_KEY="sk-ant-新的key"

# 重启 Gateway 使生效
openclaw gateway restart

▎❌ 飞书事件订阅保存失败

原理：选择 WebSocket 模式时，飞书会尝试连接你的 OpenClaw。
如果此时 Gateway 没在运行，连接失败，就保存不了。

1.先在 OpenClaw 配好飞书 → openclaw channels add

2.启动 Gateway → openclaw gateway restart

3.等 Gateway 跑起来后

4.再去飞书平台配事件订阅 ← 这时候飞书才能连上

常用命令速查表

有用的链接

📝 最后更新：2026 年 3 月