From 0865090a2ba46f7da0756d231b29d75ede0a623b Mon Sep 17 00:00:00 2001 From: yangxuan Date: Wed, 16 Sep 2026 16:36:40 +0800 Subject: [PATCH] =?UTF-8?q?fix(tools):=20=E6=B8=85=E9=99=A4=2036=20?= =?UTF-8?q?=E6=9D=A1=E6=97=A0=E6=B3=95=E6=B3=A8=E5=86=8C=E7=9A=84=E9=A3=9E?= =?UTF-8?q?=E4=B9=A6=E5=B7=A5=E5=85=B7=E5=A3=B0=E6=98=8E=EF=BC=8C=E6=9C=AA?= =?UTF-8?q?=E6=B3=A8=E5=86=8C=E5=91=8A=E8=AD=A6=2020=E2=86=920?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 根因(实测两层): - tools.alsoAllow 声明 37 个 feishu_* 工具，仅 feishu_chat 能注册 - 其余 36 个由 @larksuite/openclaw-lark 提供，而该插件无法加载: require("openclaw/plugin-sdk") 在 openclaw 2026.9.4 的 exports 中不存在 (只有 ./plugin-sdk/core 等子路径)；插件版本 2026.6.10 落后一个大版本 关键对照: @openclaw/feishu 2026.9.4 已装且 loaded，提供 14 个飞书工具 (doc/wiki/drive/perm/bitable)，能力无损失 —— 无需依赖 lark 插件 处置: - tools.alsoAllow: 37 条 -> 1 条(feishu_chat) - plugins.entries.openclaw-lark.enabled 保持 false(曾置 true 验证失败后回退) - 重启验证: 未注册告警 0、插件加载失败 0、feishu 14 工具全在、飞书渠道正常 - 文档补充"渠道层 vs 工具层"辨析：这也解释了为何手机飞书交互一直正常 --- docs/openclaw-API响应性能分析与优化.md | 70 +++++++++++++++++--------- openclaw.json | 38 +------------- 2 files changed, 48 insertions(+), 60 deletions(-) diff --git a/docs/openclaw-API响应性能分析与优化.md b/docs/openclaw-API响应性能分析与优化.md index 42383a7..22cd139 100644 --- a/docs/openclaw-API响应性能分析与优化.md +++ b/docs/openclaw-API响应性能分析与优化.md @@ -222,44 +222,66 @@ openclaw models list --provider deepseek | 手段 | 动作 | 预期 | |---|---|---| -| 收敛工具集 | 让高频 agent 少暴露「用不上」的工具（当前 `tools.profile=full`；本机 `tools.allow` 未设置，`tools.alsoAllow` 有 37 条——**其中 36 条是无效声明**，见下方告警说明） | 模型少做无效试探，轮次下降（⚠️ 需实测，见 §5） | +| 收敛工具集 | 让高频 agent 少暴露「用不上」的工具（当前 `tools.profile=full`；本机 `tools.allow` 未设置、`tools.alsoAllow` 仅剩 `feishu_chat`——**36 条无效声明已于 16:35 清除**，见下方说明） | 模型少做无效试探，轮次下降（⚠️ 需实测，见 §5） | | 提升单轮信息密度 | 在 agent 的 `AGENTS.md` 中要求「一次调用批量取证」：合并多次 `read`/`memory_search` 为一次 | 显著减少往返 | | 并行取证 | 把可并行的只读操作交给 `subagents`（当前 `subagents.maxConcurrent=4`） | 串行改并行 | | 技能不必现装现用 | 需要什么技能**提前装好**，避免在对话中触发 ClawHub 审计+安装（实测单次 13.5–14s） | 消除最大单点等待 | -> ⚠️ **有 36 个「声明了却不存在」的工具**（2026-09-16 复核，**告警仍在持续**：当天 20 次，最后一次 16:27:34）： -> `tools.profile (full) allowlist contains unknown entries` 与 `tools.allow allowlist contains unknown entries` 各 10 次，报的全是 `feishu_bitable_*` / `feishu_calendar_*` / `feishu_task_*` 等。 +> ⚠️ **曾有 36 个「声明了却不存在」的工具 → 已于 2026-09-16 16:35 修复，两条告警均清零**（详见下方"处置结果"）。 -**根因定位（实测）**：本机 `tools.alsoAllow` 声明了 **37 个** `feishu_*` 工具，但只有 **1 个真正注册成功**： +**问题的样子**：`tools.profile (full) allowlist contains unknown entries` 与 `tools.allow allowlist contains unknown entries` 各 10 次（当天累计 20 次，最后一次 16:27:34），报的全是 `feishu_bitable_*` / `feishu_calendar_*` / `feishu_task_*` 等。 + +#### 根因（实测，两层） + +**第一层**：`tools.alsoAllow` 声明了 **37 个** `feishu_*` 工具，但只有 **1 个**（`feishu_chat`，由 `@openclaw/feishu` 提供）能注册——其余 **36 个属于另一个插件** `@larksuite/openclaw-lark`。 + +**第二层（真因）**：`openclaw-lark` **根本加载不了**——它 `require("openclaw/plugin-sdk")`，而 openclaw 2026.9.4 的 `package.json#exports` 里**只有 `./plugin-sdk/core`、`./plugin-sdk/setup` 等子路径，没有裸的 `./plugin-sdk`**： ``` -alsoAllow 声明 37 个 ─┬─ ✅ 成功注册: feishu_chat （feishu 插件提供，enabled: true） - └─ ❌ 注册失败: 其余 36 个 ← openclaw-lark 插件提供 +$ openclaw-lark failed to load from ~/.openclaw/extensions/openclaw-lark/index.js: + Error: Cannot find module 'openclaw/plugin-sdk' +$ 插件版本: 2026.6.10（升级前的旧版；npm 上最新仅 2026.7.16） ``` -而 `openclaw-lark` 在配置里被**显式关闭**了： +**这不是配置问题，是版本不兼容**——该插件用了已不存在的模块路径，且其最新版仍落后主流 `openclaw` 一个大版本。 -```json5 -"plugins": { "entries": { - "feishu": { "enabled": true }, // 只提供 feishu_chat - "openclaw-lark": { "enabled": false } // 36 个 feishu_* 工具的真正提供者 → 未加载 -}} +#### 关键对照：你要的能力其实已经有了 + +`@openclaw/feishu` 已经装好并在跑（`status: loaded`、`trusted-official`），它提供 **14 个**飞书工具（`tools.profile=full` 下全部可用）： + +``` +feishu_doc feishu_wiki feishu_drive feishu_perm feishu_chat feishu_app_scopes +feishu_bitable_get_meta feishu_bitable_list_fields feishu_bitable_list_records +feishu_bitable_get_record feishu_bitable_create_record feishu_bitable_update_record +feishu_bitable_create_app feishu_bitable_create_field ``` -验证：`grep "http server listening" 日志` → 实际只加载 **6 个插件**（dingtalk-connector, feishu, memory-core, ollama, openclaw-weixin, searxng），**不含 openclaw-lark**。 - -**影响**：`alsoAllow` 里那 36 条是**无效声明**——它们不报错，但也不生效；模型可能尝试调用不存在的工具而浪费一轮往返。 - -**两个互斥的修法（需决策，不建议同时做）**： - -| 方案 | 做法 | 代价 | +| | `@larksuite/openclaw-lark`（坏） | `@openclaw/feishu`（在用） | |---|---|---| -| **A. 精简声明**（推荐，契合 P0-2） | 从 `tools.alsoAllow` 删掉用不上的 `feishu_*` 条目 | 需先确认哪些飞书能力**真的要用** | -| **B. 启用插件** | `plugins.entries.openclaw-lark.enabled = true` | 真实注册 36 个工具，**工具面大幅变大**，可能反增轮次与上下文开销；且 lark 插件需飞书应用凭据/oauth 流程 | +| 版本 | 2026.6.10（最新 2026.7.16） | **2026.9.4**，`peerDeps: openclaw>=2026.9.4` | +| 加载 | **失败**（`openclaw/plugin-sdk` 不存在） | 正常 | +| 工具 | 38 个细粒度（calendar / task / im / oauth / sheet…） | **14 个**（doc / wiki / drive / perm / bitable），用 `_create`/`_list` 动词对内部再做复合操作 | +| 适配 | 落后一个大版本 | 与 openclaw 同步 | -> 复核命令（注意：告警**不是**历史遗留，会随每次配置重载/插件加载重现）： +#### 处置结果（2026-09-16 16:35 已完成） + +| 动作 | 结果 | +|---|---| +| 从 `tools.alsoAllow` 删除 36 条 lark 专属声明（保留 `feishu_chat`） | 未注册告警 **20 次/天 → 0** | +| `plugins.entries.openclaw-lark.enabled` 保持 **false** | 消除 `failed to load` 报错（曾尝试置 true 验证：确认失败后回退） | +| 复查 `@openclaw/feishu` | `status: loaded`、**14 个工具全在**，能力无损失 | +| 复查飞书渠道 | WebSocket 正常连接，**手机 App 交互不受影响** | + +> **两个独立层次，别混淆**（这是本次排查最值得记住的一点）： +> - **渠道层**：飞书 App ⇄ gateway 的消息收发，由 `@openclaw/feishu` 的 channel 部分负责 → **一直正常**，所以手机交互没问题 +> - **工具层**：模型在对话里"动手操作飞书"的能力，由插件的 `contracts.tools` 负责 → 那 36 条声明在这里无效 +> +> `alsoAllow` 坏掉**不会**影响聊天交互，只会让"让 AI 去操作飞书文档/多维表格"这类动作落空。 + +> 复核命令（改完这两个都应为 0／不为 0 都应引起注意）： > ```bash > grep -c "allowlist contains unknown entries" /tmp/openclaw/openclaw-$(date +%F).log +> grep -c "failed to load" /tmp/openclaw/openclaw-$(date +%F).log > grep "http server listening" /tmp/openclaw/openclaw-$(date +%F).log | tail -1 # 看实际加载了哪些插件 > ``` @@ -366,6 +388,8 @@ python3 ~/.openclaw/scripts/perf-analyze.py [日志1 日志2 ...] |---|---|---| | 主配置 | 删除 `models.providers.newapi`；`modelPolicy.allow` 收敛为 `deepseek/deepseek-flash`；`sql` agent 主模型改为 deepseek | 配置热重载（日志：`config hot reload applied`） | | agent 级 `models.json` | `finances`/`main`/`resume`/`sql`/`travel` 各自残留的 new-api provider（含指向 `192.168.2.74:3000`、`100.115.195.188:3000` 的条目，含**明文 key**）全部移除 | 下次 gateway 启动生效 | -| 备份 | `~/.openclaw/openclaw.json.bak-20260916-161323-pre-newapi-removal`、`~/.openclaw/backups/agent-models-json-2026-09-16T0816/` | — | +| 工具声明清理 | `tools.alsoAllow` 由 37 条减为 1 条（删除 36 条由 `openclaw-lark` 提供、实际无法注册的声明） | 重启 gateway（16:35），告警 20→0 | +| 插件开关 | `plugins.entries.openclaw-lark.enabled` 保持 **false**（曾置 true 实测其 `require("openclaw/plugin-sdk")` 失败，遂回退） | 重启 gateway | +| 备份 | `openclaw.json.bak-20260916-161323-pre-newapi-removal`、`...-163214-pre-lark-enable`、`...-163405-pre-alsoallow-fix`、`backups/agent-models-json-2026-09-16T0816/`（均在 `~/.openclaw/` 下） | — | > `agent` 级 `models.json` 是**第二套模型定义**（被 `loadCustomModels()` 读取），与主配置 `openclaw.json` 并行生效——排查模型问题时**两处都要看**，这是本次分析的第一个教训。 diff --git a/openclaw.json b/openclaw.json index eff3bc8..22852da 100644 --- a/openclaw.json +++ b/openclaw.json @@ -323,43 +323,7 @@ } }, "alsoAllow": [ - "feishu_bitable_app", - "feishu_bitable_app_table", - "feishu_bitable_app_table_field", - "feishu_bitable_app_table_record", - "feishu_bitable_app_table_view", - "feishu_calendar_calendar", - "feishu_calendar_event", - "feishu_calendar_event_attendee", - "feishu_calendar_freebusy", - "feishu_chat", - "feishu_chat_members", - "feishu_create_doc", - "feishu_doc_comments", - "feishu_doc_media", - "feishu_drive_file", - "feishu_fetch_doc", - "feishu_get_user", - "feishu_im_bot_image", - "feishu_im_user_fetch_resource", - "feishu_im_user_get_messages", - "feishu_im_user_get_thread_messages", - "feishu_im_user_message", - "feishu_im_user_search_messages", - "feishu_oauth", - "feishu_oauth_batch_auth", - "feishu_search_doc_wiki", - "feishu_search_user", - "feishu_sheet", - "feishu_task_comment", - "feishu_task_subtask", - "feishu_task_task", - "feishu_task_agent", - "feishu_task_attachment", - "feishu_task_tasklist", - "feishu_update_doc", - "feishu_wiki_space", - "feishu_wiki_space_node" + "feishu_chat" ] }, "messages": {