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

解决方法：

bash 复制代码

rm -rf ~/.openclaw/extensions/feishu

运行 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 代理）：

API Base URL ：https://openai-proxy.miracleplus.com
提供 API Key 方式 ：Paste API key now
API Key：输入你的密钥
兼容性 ：Anthropic-compatible
模型 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

安装过程详解

安装过程中会：

禁用内置飞书插件：自动禁用 OpenClaw 自带的飞书插件
安装官方插件 ：从 npm 下载 @larksuiteoapi/feishu-openclaw-plugin
注册工具：注册所有飞书 API 工具（日历、任务、多维表格等）
配置渠道 ：使用现有的飞书 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	最大输出长度受限

问题表现

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

日志中出现警告：

ini 复制代码

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

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

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

响应超时：

ini 复制代码

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

配置项	推荐值	说明
`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 配置

通过 SSH 端口转发访问 Dashboard：

java 复制代码

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

浏览器访问 http://localhost:18789/
进入 Settings → Models
找到对应的模型端点，修改 contextWindow 和 maxTokens
保存后重启 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：模型上下文窗口过小导致会话频繁压缩

症状：

日志中出现警告：

ini 复制代码

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

Agent 响应缓慢，频繁进行会话压缩（compaction）
响应超时（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：飞书官方插件安装失败

症状：

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

解决：

检查网络连接，确保能访问 npm 和飞书 CDN
尝试使用国内镜像：

arduino 复制代码

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

清理缓存后重试：

css 复制代码

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

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

排查步骤：

检查 Gateway 是否运行：

lua 复制代码

openclaw status

检查飞书连接状态：

lua 复制代码

openclaw status

查看详细日志：

bash 复制代码

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

检查配对状态：

openclaw pairing list

总结

更新流程回顾

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

配置路径对比

项目	旧版	新版
配置目录	`~/.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

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