OpenClaw-Linux+飞书官方Plugin安装指南

16Miku2026-03-12 20:16

OpenClaw-Linux+飞书官方Plugin安装指南

本文详细记录了在云端 Linux 服务器上从旧版 Clawbot 更新到最新版 OpenClaw 并配置飞书机器人的完整流程。

目录

  • 前置说明
  • 第一步：检查环境
  • 第二步：解决 git SSH 访问 GitHub 问题
  • 第三步：安装 OpenClaw
  • 第四步：处理旧配置迁移
  • 第五步：运行配置向导
  • 第六步：安装飞书官方插件
  • 第七步：优化模型配置
  • 第八步：批准配对并测试
  • 第九步：远程访问 Dashboard
  • 常见问题排查
  • 总结

前置说明

使用场景

  • 环境：云端 Linux 服务器（本文基于 Ubuntu 24.04 LTS）
  • 场景：从旧版 Clawbot 更新到最新版 OpenClaw
  • 目的：保留原有配置，升级到最新版本并配置自定义模型服务商

与全新安装的区别

|------------|------|-----------|
| 场景 | 全新安装 | 更新升级 |
| 配置文件 | 需要创建 | 自动迁移 |
| 旧插件 | 无 | 需要清理兼容性问题 |
| Gateway 服务 | 新安装 | 需要替换旧服务 |

第一步：检查环境

连接服务器

使用 SSH 连接到你的 Linux 服务器：

复制代码 
ssh root@your-server-ip

检查 Node.js 版本

复制代码 
node --version

要求：Node.js v18 或更高版本。

示例输出：

复制代码 
v22.22.0

检查 npm 版本

复制代码 
npm --version

示例输出：

复制代码 
10.9.4

如果 Node.js 版本过低

如果版本不符合要求，需要升级 Node.js。对于 Ubuntu/Debian：

复制代码 
# 使用 NodeSource 仓库安装最新 LTS 版本
curl -fsSL https://deb.nodesource.com/setup_lts.x | bash -
apt-get install -y nodejs

第二步：解决 git SSH 访问 GitHub 问题

问题背景

OpenClaw 的依赖包 libsignal-node 需要通过 git 从 GitHub 拉取。在某些服务器环境中，npm 默认使用 SSH 协议访问 GitHub，但服务器可能没有配置 SSH 密钥，导致安装失败。

错误示例

复制代码 
npm error command git --no-replace-objects ls-remote ssh://git@github.com/whiskeysockets/libsignal-node.git
npm error git@github.com: Permission denied (publickey).
npm error fatal: Could not read from remote repository.

解决方案：配置 git 使用 HTTPS

1. 检查现有 git 配置
复制代码 
git config --global --list | grep url
2. 清理旧配置（如果有）
复制代码 
# 清理可能存在的旧代理配置
git config --global --unset-all url."https://ghproxy.com/https://github.com/".insteadof
git config --global --unset-all url."https://github.com/".insteadof
3. 添加 URL 重写规则
复制代码 
# 将 ssh://git@github.com/ 转换为 https://github.com/
git config --global url."https://github.com/".insteadOf "ssh://git@github.com/"

# 将 git@github.com: 转换为 https://github.com/
git config --global --add url."https://github.com/".insteadOf "git@github.com:"
4. 验证配置
复制代码 
git config --global --list | grep url

预期输出：

复制代码 
url.https://github.com/.insteadof=ssh://git@github.com/
url.https://github.com/.insteadof=git@github.com:

★ Insight ───────────────────────────────────── git 的 url.<base>.insteadOf 配置可以实现 URL 重写。当 git 遇到匹配的 URL 前缀时，会自动替换为指定的 URL。这样所有通过 SSH 协议访问 GitHub 的请求都会被转换为 HTTPS 请求，不需要 SSH 密钥就能正常工作。 ─────────────────────────────────────────────────

第三步：安装 OpenClaw

全局安装最新版

复制代码 
npm i -g openclaw

// 使用镜像安装
npm install -g openclaw@latest --registry=https://registry.npmmirror.com

安装过程

安装可能需要 5-15 分钟，取决于服务器性能和网络速度。你会看到：

复制代码 
npm warn deprecated ...（一些过时依赖的警告，可以忽略）
...
added 697 packages in 11m

验证安装

复制代码 
openclaw --version

示例输出：

复制代码 
2026.3.6

常见错误处理

错误 ：git@github.com: Permission denied (publickey)

解决：回到第二步，确认 git 配置正确。

第四步：处理旧配置迁移

配置迁移说明

OpenClaw 会自动检测并迁移旧版 Clawbot 的配置：

  • 旧路径：~/.clawdbot/
  • 新路径：~/.openclaw/
  • 旧配置：clawdbot.json
  • 新配置：openclaw.json

预期迁移输出

运行 openclaw onboard 时会看到：

复制代码 
◇  Doctor changes ─────────────────────────────────────────────────────────────╮
│                                                                              │
│  - State dir: /root/.clawdbot → /root/.openclaw (legacy path now symlinked)  │
│                                                                              │
├──────────────────────────────────────────────────────────────────────────────╯

插件兼容性问题

如果遇到插件 manifest 错误：

复制代码 
Invalid config at /root/.openclaw/openclaw.json:
- plugins: plugin manifest not found: /root/.openclaw/extensions/feishu/openclaw.plugin.json

解决方法：

  1. 删除旧的飞书插件目录：

    rm -rf ~/.openclaw/extensions/feishu

  2. 运行 doctor 修复：

    openclaw doctor --fix

第五步：运行配置向导

启动配置向导

复制代码 
openclaw onboard

配置流程详解

1. 安全提示

阅读并理解安全警告后，选择 Yes 继续。

2. 选择配置模式
  • QuickStart（快速开始）：推荐
  • Custom（自定义）：高级用户

操作 ：选择 QuickStart。

3. 检测现有配置

系统会显示已检测到的配置：

复制代码 
◇  Existing config detected ─╮
│                            │
│  workspace: ~/clawd        │
│  model: ark/glm-4.7        │
│  gateway.mode: local       │
│  gateway.port: 18789       │
│  gateway.bind: loopback    │
│                            │
├────────────────────────────┘

操作 ：选择 Update values 更新配置。

4. Gateway 设置

保持现有设置：

复制代码 
Gateway port: 18789
Gateway bind: Loopback (127.0.0.1)
Gateway auth: Token (default)
5. 配置自定义模型服务商

选项 ：选择 Custom Provider

示例配置（使用 MiraclePlus 代理）：

  1. API Base URL ：https://openai-proxy.miracleplus.com
  2. 提供 API Key 方式 ：Paste API key now
  3. API Key：输入你的密钥
  4. 兼容性 ：Anthropic-compatible
  5. 模型 ID ：claude-opus-4-6

成功后显示：Verification successful.

6. 飞书渠道配置

系统会检测已配置的飞书：

复制代码 
◇  Channel status ───────────────────────────────────────────╮
│                                                            │
│  Feishu: connected as ou_xxxxx  │
│                                                            │
├────────────────────────────────────────────────────────────┘

操作 ：选择 Feishu/Lark (飞书)，然后选择 Modify settings 更新设置。

保持现有 App Secret，选择连接模式 WebSocket (default)，选择 Feishu (feishu.cn) - China。

7. 群聊策略
  • Allowlist：只在指定群响应（需要设置白名单）
  • Open：所有群都能使用

操作 ：根据需求选择。如果选 Allowlist，需要输入群 chat_id。

8. 技能和 Hooks
  • Skills ：选择 No（后续可按需配置）
  • Hooks ：选择 Skip for now
9. Gateway 服务

系统会自动重启 Gateway 服务：

复制代码 
◇  Gateway service already installed
│  Restart
│
◒  Restarting Gateway service...
Restarted systemd service: openclaw-gateway.service
10. 完成

配置完成后显示：

复制代码 
Feishu: ok
Agents: main (default)
Gateway: reachable
Web UI: http://127.0.0.1:18789/

第六步：安装飞书官方插件

OpenClaw飞书官方插件使用指南（公开版）

为什么需要官方插件？

OpenClaw 自带的飞书插件功能有限，飞书官方提供了更完整的插件 @larksuiteoapi/feishu-openclaw-plugin，支持更多功能：

  • 日历管理
  • 任务管理
  • 多维表格
  • 文档操作
  • 云空间
  • 知识库
  • 等等

安装步骤

1. 设置 npm 源（可选）

如果国内网络访问 npm 官方源较慢，可以使用淘宝镜像：

复制代码 
npm config set registry https://registry.npmmirror.com
2. 下载飞书官方插件安装工具
复制代码 
curl -o /tmp/feishu-openclaw-plugin-onboard-cli.tgz https://sf3-cn.feishucdn.com/obj/open-platform-opendoc/195a94cb3d9a45d862d417313ff62c9c_gfW8JbxtTd.tgz
3. 安装工具
复制代码 
npm install /tmp/feishu-openclaw-plugin-onboard-cli.tgz -g
4. 清理临时文件
复制代码 
rm /tmp/feishu-openclaw-plugin-onboard-cli.tgz
5. 运行插件安装命令
复制代码 
feishu-plugin-onboard install

安装过程详解

安装过程中会：

  1. 禁用内置飞书插件：自动禁用 OpenClaw 自带的飞书插件
  2. 安装官方插件 ：从 npm 下载 @larksuiteoapi/feishu-openclaw-plugin
  3. 注册工具：注册所有飞书 API 工具（日历、任务、多维表格等）
  4. 配置渠道 ：使用现有的飞书 App ID 和 App Secret（未配置的可参考OpenClaw飞书官方插件使用指南（公开版））进行配置。

预期输出：

复制代码 
Starting installation...
Setting npm registry...
Disabling built-in Feishu plugin...
Installing official Feishu plugin...
Installing plugin @larksuiteoapi/feishu-openclaw-plugin...

Downloading @larksuiteoapi/feishu-openclaw-plugin...
Installing to /root/.openclaw/extensions/feishu-openclaw-plugin...
Installing plugin dependencies...

✅ Registered all OAPI tools (calendar, task, bitable, mail, search, drive, wiki, sheets, okr, im)
Installed plugin: feishu-openclaw-plugin
Restart the gateway to load plugins.

? Current Feishu App ID is cli_xxxxx. Do you want to use it? Yes
Installation complete! You can now run "openclaw gateway run".

安全警告说明

安装时可能会看到安全警告：

复制代码 
WARNING: Plugin "feishu-openclaw-plugin" contains dangerous code patterns:
- Environment variable access combined with network send
- Shell command execution detected

这是正常的，因为飞书插件需要：

  • 访问环境变量获取凭证
  • 执行一些系统命令

只要是从官方渠道安装的，可以放心使用。

重启 Gateway

安装完成后重启 Gateway 使插件生效：

复制代码 
openclaw gateway restart

第七步：优化模型配置

问题背景

使用自定义模型服务商时，OpenClaw 可能会使用默认的模型配置，导致：

|-----------------|-------|------------------|
| 配置项 | 默认值 | 问题 |
| contextWindow | 16000 | 上下文窗口太小，频繁触发会话压缩 |
| maxTokens | 4096 | 最大输出长度受限 |

问题表现

如果配置不当，会出现以下症状：

  1. 日志中出现警告：

    [agent/embedded] low context window: ctx=16000 (warn<32000)

  2. 会话频繁压缩： Agent 每次读完人设文档就会压缩会话，导致：

    1. 丢失上下文信息
    2. 响应变慢（压缩需要时间）
    3. 可能超时（10 分钟默认超时）

  1. 响应超时：

    [agent/embedded] embedded run timeout: timeoutMs=600000

推荐配置

对于 claude-opus-4-6 模型，推荐配置：

|-----------------|--------|----------------|
| 配置项 | 推荐值 | 说明 |
| contextWindow | 200000 | 200K 上下文窗口 |
| maxTokens | 8192 | 最大输出 8K tokens |

配置方法

方法一：命令行配置
复制代码 
# 设置上下文窗口
openclaw config set models.providers.<provider-id>.models.0.contextWindow 200000

# 设置最大输出长度
openclaw config set models.providers.<provider-id>.models.0.maxTokens 8192

示例 （provider-id 为 custom-openai-proxy-miracleplus-com）：

复制代码 
openclaw config set models.providers.custom-openai-proxy-miracleplus-com.models.0.contextWindow 200000
openclaw config set models.providers.custom-openai-proxy-miracleplus-com.models.0.maxTokens 8192
方法二：Dashboard 配置

  1. 通过 SSH 端口转发访问 Dashboard：

    ssh -N -L 18789:127.0.0.1:18789 root@your-server-ip

  2. 浏览器访问 http://localhost:18789/

  3. 进入 Settings → Models

  4. 找到对应的模型端点，修改 contextWindow 和 maxTokens

  5. 保存后重启 Gateway

验证配置

复制代码 
openclaw config get models.providers.<provider-id>.models.0

预期输出：

复制代码 
{
  "id": "claude-opus-4-6",
  "contextWindow": 200000,
  "maxTokens": 8192,
  ...
}

重启生效

配置修改后需要重启 Gateway：

复制代码 
openclaw gateway restart

★ Insight ─────────────────────────────────────``contextWindow 决定了 Agent 能"记住"多少上下文信息。设置太小会导致频繁压缩会话历史（compaction），不仅影响响应速度，还可能丢失重要信息。对于 claude-opus-4-6 这样支持 200K 上下文的模型，务必将 contextWindow 设置为 200000。maxTokens 则决定了单次回复的最大长度，8192 是比较合理的默认值。 ─────────────────────────────────────────────────

第八步：批准配对并测试

配对机制

当有人第一次给飞书机器人发消息时，会生成配对码。需要在服务器上批准。

批准配对

复制代码 
openclaw pairing approve feishu <配对码>

示例：

复制代码 
openclaw pairing approve feishu XXXXXXXX

成功输出：

复制代码 
Approved feishu sender ou_xxxxx.

测试对话

在飞书里给机器人发送消息，如：

复制代码 
你好

如果机器人正常回复，配置成功！

第九步：远程访问 Dashboard

SSH 端口转发

由于服务器没有 GUI，需要通过 SSH 端口转发在本地访问 Web 控制面板。

在本地电脑执行（Windows PowerShell）：

复制代码 
ssh -N -L 18789:127.0.0.1:18789 root@your-server-ip

访问 Dashboard

保持 SSH 连接，在浏览器中访问：

复制代码 
http://localhost:18789/

或使用带 token 的 URL（自动登录）：

复制代码 
http://localhost:18789/#token=your-token

获取 Token

复制代码 
openclaw config get gateway.auth.token

常见问题排查

问题 1：git 访问 GitHub 失败

错误 ：Permission denied (publickey)

解决：

复制代码 
git config --global url."https://github.com/".insteadOf "ssh://git@github.com/"
git config --global --add url."https://github.com/".insteadOf "git@github.com:"

问题 2：插件 manifest 错误

错误 ：plugin manifest not found

解决：

复制代码 
rm -rf ~/.openclaw/extensions/feishu
openclaw doctor --fix

问题 3：群聊不响应

检查群聊策略：

复制代码 
openclaw config get channels.feishu.groupPolicy

如果是 allowlist 但白名单为空，改为 open：

复制代码 
openclaw config set channels.feishu.groupPolicy "open"

问题 4：Gateway 服务未运行

检查状态：

复制代码 
systemctl --user status openclaw-gateway.service

重启服务：

复制代码 
systemctl --user restart openclaw-gateway.service

查看日志：

复制代码 
openclaw logs

问题 5：API 调用失败

检查模型配置：

复制代码 
openclaw config get models

重新配置模型：

复制代码 
openclaw configure --section model

问题 6：模型上下文窗口过小导致会话频繁压缩

症状：

  1. 日志中出现警告：

    [agent/embedded] low context window: ctx=16000 (warn<32000)

  2. Agent 响应缓慢，频繁进行会话压缩（compaction）

  3. 响应超时（10 分钟后仍未返回）

原因：

自定义模型服务商的 contextWindow 默认值为 16000，对于 claude-opus-4-6 等支持 200K 上下文的模型来说太小了。

解决：

复制代码 
# 查看当前配置
openclaw config get models.providers.<provider-id>.models.0

# 设置正确的上下文窗口
openclaw config set models.providers.<provider-id>.models.0.contextWindow 200000
openclaw config set models.providers.<provider-id>.models.0.maxTokens 8192

# 重启 Gateway
openclaw gateway restart

问题 7：飞书官方插件安装失败

症状：

安装过程中出现网络错误或依赖安装失败。

解决：

  1. 检查网络连接，确保能访问 npm 和飞书 CDN

  2. 尝试使用国内镜像：

    npm config set registry https://registry.npmmirror.com

  3. 清理缓存后重试：

    npm cache clean --force
    feishu-plugin-onboard install

问题 8：飞书机器人不回复消息

排查步骤：

  1. 检查 Gateway 是否运行：

    openclaw status

  2. 检查飞书连接状态：

    openclaw status

  3. 查看详细日志：

    openclaw logs

    或

    tail -100 /tmp/openclaw/openclaw-$(date +%Y-%m-%d).log

  4. 检查配对状态：

    openclaw pairing list

总结

更新流程回顾

  1. ✅ 检查 Node.js 环境
  2. ✅ 配置 git 使用 HTTPS 访问 GitHub
  3. ✅ 全局安装 OpenClaw
  4. ✅ 清理旧插件并运行 doctor
  5. ✅ 运行 onboard 更新配置
  6. ✅ 安装飞书官方插件
  7. ✅ 优化模型配置（contextWindow/maxTokens）
  8. ✅ 配置自定义模型服务商
  9. ✅ 批准配对并测试

配置路径对比

|------|----------------------------|----------------------------|
| 项目 | 旧版 | 新版 |
| 配置目录 | ~/.clawdbot/ | ~/.openclaw/ |
| 配置文件 | clawdbot.json | openclaw.json |
| 服务名 | clawdbot-gateway.service | openclaw-gateway.service |

关键命令速查

复制代码 
# 安装
npm i -g openclaw

# 检查版本
openclaw --version

# 修复配置
openclaw doctor --fix

# 配置向导
openclaw onboard

# 批准配对
openclaw pairing approve feishu <code>

# 查看状态
openclaw status

# 查看日志
openclaw logs

# 重启 Gateway
systemctl --user restart openclaw-gateway.service

# 远程 Dashboard
ssh -N -L 18789:127.0.0.1:18789 root@server-ip

相关资源

附录：systemd 服务管理

查看 Gateway 服务状态

复制代码 
systemctl --user status openclaw-gateway.service

启动/停止/重启服务

复制代码 
# 启动
systemctl --user start openclaw-gateway.service

# 停止
systemctl --user stop openclaw-gateway.service

# 重启
systemctl --user restart openclaw-gateway.service

开机自启动

复制代码 
systemctl --user enable openclaw-gateway.service

禁用自启动

复制代码 
systemctl --user disable openclaw-gateway.service
相关推荐
the sun342 小时前
打通嵌入式与 Linux：USB 转串口通信实战
linux·运维·服务器
光影少年2 小时前
open claw安装教程
ai·aigc
要开心吖ZSH2 小时前
（三）OpenClaw 云端服务器控制本地 Windows 浏览器完整配置指南（SSH方式）
运维·服务器·windows·openclaw
XMYX-02 小时前
Zabbix 7.0 自定义 Linux 监控模板（Agent Active版，支持CPU/内存/磁盘/网卡自动发现）
linux·zabbix
研究点啥好呢2 小时前
3月10日GitHub热门项目推荐|自动化的浪潮
运维·人工智能·ai·自动化·github
xier_ran3 小时前
【第一周】论文精读：Lost in the Middle: How Language Models Use Long Contexts
人工智能·语言模型·自然语言处理·agent·rag
进击切图仔3 小时前
linux 虚拟文件系统简介和详解
linux·运维·服务器
予枫的编程笔记3 小时前
【YF技术周报 Vol.03】AI全产业链爆发：模型迭代、算力升级与监管博弈
ai·大模型·java后端·ai agent·rag架构·算力基建·政策监管
皮皮哎哟3 小时前
嵌入式数据库从入门到精通
linux·数据库·sqlite3·sqlite3_open
热门推荐
01GitHub 镜像站点02OpenClaw 使用和管理 MCP 完全指南03本地部署 OpenClaw + DeepSeek-R1 完全指南04得物前端部门，没了05OpenClaw 飞书机器人不回复消息？3 小时踩坑总结06OpenClaw 连接飞书完整指南：插件安装、配置与踩坑记录07OpenClaw macOS 完整安装与本地模型配置教程（实战版）08Window 10部署openclaw报错node.exe : npm error code 12809OpenClaw 接入 QQ Bot 完整实践指南10OpenClaw-VSCode：在 VS Code 里玩转 OpenClaw，远程管理+SSH 双剑合璧