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

Miku162026-03-09 15:07

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

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

目录

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

前置说明

使用场景

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

与全新安装的区别

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

第一步：检查环境

连接服务器

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

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

检查 Node.js 版本

css 复制代码 
node --version

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

示例输出：

复制代码 
v22.22.0

检查 npm 版本

css 复制代码 
npm --version

示例输出：

复制代码 
10.9.4

如果 Node.js 版本过低

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

csharp 复制代码 
# 使用 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 密钥，导致安装失败。

错误示例

lua 复制代码 
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 配置
css 复制代码 
git config --global --list | grep url
2. 清理旧配置（如果有）
php 复制代码 
# 清理可能存在的旧代理配置
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 重写规则
csharp 复制代码 
# 将 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. 验证配置
css 复制代码 
git config --global --list | grep url

预期输出：

perl 复制代码 
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

全局安装最新版

css 复制代码 
npm i -g openclaw

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

安装过程

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

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

验证安装

css 复制代码 
openclaw --version

示例输出：

yaml 复制代码 
2026.3.6

常见错误处理

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

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

第四步：处理旧配置迁移

配置迁移说明

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

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

预期迁移输出

运行 openclaw onboard 时会看到：

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

插件兼容性问题

如果遇到插件 manifest 错误：

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

解决方法：

  1. 删除旧的飞书插件目录：
bash 复制代码 
rm -rf ~/.openclaw/extensions/feishu
  1. 运行 doctor 修复：
css 复制代码 
openclaw doctor --fix

第五步：运行配置向导

启动配置向导

复制代码 
openclaw onboard

配置流程详解

1. 安全提示

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

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

操作 ：选择 QuickStart。

3. 检测现有配置

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

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

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

4. Gateway 设置

保持现有设置：

yaml 复制代码 
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. 飞书渠道配置

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

arduino 复制代码 
◇  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 服务：

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

配置完成后显示：

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

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

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

为什么需要官方插件？

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

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

安装步骤

1. 设置 npm 源（可选）

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

arduino 复制代码 
npm config set registry https://registry.npmmirror.com
2. 下载飞书官方插件安装工具
bash 复制代码 
curl -o /tmp/feishu-openclaw-plugin-onboard-cli.tgz https://sf3-cn.feishucdn.com/obj/open-platform-opendoc/195a94cb3d9a45d862d417313ff62c9c_gfW8JbxtTd.tgz
3. 安装工具
bash 复制代码 
npm install /tmp/feishu-openclaw-plugin-onboard-cli.tgz -g
4. 清理临时文件
bash 复制代码 
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飞书官方插件使用指南（公开版））进行配置。

预期输出：

erlang 复制代码 
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".

安全警告说明

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

sql 复制代码 
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. 日志中出现警告：
ini 复制代码 
[agent/embedded] low context window: ctx=16000 (warn<32000)
  1. 会话频繁压缩： Agent 每次读完人设文档就会压缩会话，导致：
    1. 丢失上下文信息
    2. 响应变慢（压缩需要时间）
    3. 可能超时（10 分钟默认超时）
  1. 响应超时：
ini 复制代码 
[agent/embedded] embedded run timeout: timeoutMs=600000

推荐配置

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

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

配置方法

方法一：命令行配置
python 复制代码 
# 设置上下文窗口
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）：

arduino 复制代码 
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：
java 复制代码 
ssh -N -L 18789:127.0.0.1:18789 root@your-server-ip
  1. 浏览器访问 http://localhost:18789/
  2. 进入 Settings → Models
  3. 找到对应的模型端点，修改 contextWindow 和 maxTokens
  4. 保存后重启 Gateway

验证配置

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

预期输出：

json 复制代码 
{
  "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 是比较合理的默认值。 ─────────────────────────────────────────────────

第八步：批准配对并测试

配对机制

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

批准配对

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

示例：

复制代码 
openclaw pairing approve feishu XXXXXXXX

成功输出：

erlang 复制代码 
Approved feishu sender ou_xxxxx.

测试对话

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

复制代码 
你好

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

第九步：远程访问 Dashboard

SSH 端口转发

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

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

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

访问 Dashboard

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

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

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

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

获取 Token

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

常见问题排查

问题 1：git 访问 GitHub 失败

错误 ：Permission denied (publickey)

解决：

csharp 复制代码 
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

解决：

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

问题 3：群聊不响应

检查群聊策略：

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

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

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

问题 4：Gateway 服务未运行

检查状态：

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

重启服务：

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

查看日志：

复制代码 
openclaw logs

问题 5：API 调用失败

检查模型配置：

arduino 复制代码 
openclaw config get models

重新配置模型：

css 复制代码 
openclaw configure --section model

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

症状：

  1. 日志中出现警告：
ini 复制代码 
[agent/embedded] low context window: ctx=16000 (warn<32000)
  1. Agent 响应缓慢，频繁进行会话压缩（compaction）
  2. 响应超时（10 分钟后仍未返回）

原因：

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

解决：

python 复制代码 
# 查看当前配置
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. 尝试使用国内镜像：
arduino 复制代码 
npm config set registry https://registry.npmmirror.com
  1. 清理缓存后重试：
css 复制代码 
npm cache clean --force
feishu-plugin-onboard install

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

排查步骤：

  1. 检查 Gateway 是否运行：
lua 复制代码 
openclaw status
  1. 检查飞书连接状态：
lua 复制代码 
openclaw status
  1. 查看详细日志：
bash 复制代码 
openclaw logs
# 或
tail -100 /tmp/openclaw/openclaw-$(date +%Y-%m-%d).log

  1. 检查配对状态：

    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

关键命令速查

perl 复制代码 
# 安装
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 服务状态

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

启动/停止/重启服务

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

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

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

开机自启动

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

禁用自启动

bash 复制代码 
systemctl --user disable openclaw-gateway.service
相关推荐
Miku162 小时前
OpenClaw 接入 QQ Bot 完整实践指南
linux·人工智能·agent
熊崽2 小时前
Claude Code CLI+英伟达免费api 教程
人工智能
Flittly2 小时前
【从零手写 ClaudeCode：learn-claude-code 项目实战笔记】（4）Subagents (子智能体)
python·agent
沸点小助手3 小时前
「AI 编程搭子真香or翻车」沸点获奖名单公示｜本周互动话题上新🎊
aigc·agent·ai编程
AI攻城狮3 小时前
OpenFang 给我的一个提醒：AI Agent 真正难的不是自主，而是治理
人工智能·云原生·aigc
带刺的坐椅3 小时前
SolonCode v0.0.20 发布 - 编程智能体（新增子代理和浏览器能力）
java·ai·agent·solon·solon-ai·claude-code·openclaw
ZhengEnCi3 小时前
10. 重排序模型实战-BGE-Rerank应用
人工智能
吾鳴6 小时前
OpenClaw最适合新手安装的11个Skills
agent
DevUI团队6 小时前
🚀 【Angular】MateChat V20.2.2版本发布，新增8+组件，欢迎体验~
前端·javascript·人工智能
热门推荐
01GitHub 镜像站点02OpenClaw 使用和管理 MCP 完全指南03OpenClaw 连接飞书完整指南：插件安装、配置与踩坑记录04Window 10部署openclaw报错node.exe : npm error code 12805本地部署 OpenClaw + DeepSeek-R1 完全指南06OpenClaw + 飞书（Feishu）环境搭建指南07npm-error code 128问题解决方法08Clawdbot部署教程：解决‘gateway token missing’授权问题的完整步骤09Claude Code + GLM4.7 避坑指南：解决 Unable to connect to Anthropic services10OpenClaw 飞书机器人不回复消息？3 小时踩坑总结