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

Miku16
0 阅读11分钟

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
  1. 运行 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 可能会使用默认的模型配置，导致：

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

问题表现

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

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

推荐配置

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

配置项推荐值说明
contextWindow200000200K 上下文窗口
maxTokens8192最大输出 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
  1. 浏览器访问 http://localhost:18789/
  2. 进入 Settings → Models
  3. 找到对应的模型端点，修改 contextWindow 和 maxTokens
  4. 保存后重启 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)
  1. Agent 响应缓慢，频繁进行会话压缩（compaction）
  2. 响应超时（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
  1. 清理缓存后重试：
npm cache clean --force
feishu-plugin-onboard install

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

排查步骤：

  1. 检查 Gateway 是否运行：
openclaw status
  1. 检查飞书连接状态：
openclaw status
  1. 查看详细日志：
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.jsonopenclaw.json
服务名clawdbot-gateway.serviceopenclaw-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
avatar
文章
阅读
粉丝