OpenClaw 程式碼重構指南：優化插件架構並減少 600 行程式碼

寫代碼最煩人的事情之一，就是發現自己在不同的 extension 之間不斷複製貼上相似的邏輯。當你發現每個插件都要寫一遍同樣的 runtime 處理或帳號配置時，這就是該進行重構的信號了。

這份清單整理了我們積壓的重構任務，並依照預期的代碼減量（LOC reduction）、安全性和影響範圍進行了排序。

1. 頻道插件配置與安全性腳手架 (Channel plugin config and security scaffolding)

這是價值最高的重構群組。

我們在許多頻道插件中看到了重複的結構：

• config.listAccountIds
• config.resolveAccount
• config.defaultAccountId
• config.setAccountEnabled
• config.deleteAccount
• config.describeAccount
• security.resolveDmPolicy

典型的例子包括：

• extensions/telegram/src/channel.ts
• extensions/googlechat/src/channel.ts
• extensions/slack/src/channel.ts
• extensions/discord/src/channel.ts
• extensions/matrix/src/channel.ts
• extensions/irc/src/channel.ts
• extensions/signal/src/channel.ts
• extensions/mattermost/src/channel.ts

預計提取出的形狀：

• buildChannelConfigAdapter(...)
• buildMultiAccountConfigAdapter(...)
• buildDmSecurityAdapter(...)

預計節省：

• 約 250-450 LOC

風險：

• 中等。每個頻道的 isConfigured、警告訊息和標準化邏輯都有些微差異。

2. Extension Runtime 單例樣板代碼 (Extension runtime singleton boilerplate)

非常安全。

幾乎每個 extension 都有相同的 runtime 持有者：

• let runtime: PluginRuntime | null = null
• setXRuntime
• getXRuntime

典型的例子包括：

• extensions/telegram/src/runtime.ts
• extensions/matrix/src/runtime.ts
• extensions/slack/src/runtime.ts
• extensions/discord/src/runtime.ts
• extensions/whatsapp/src/runtime.ts
• extensions/imessage/src/runtime.ts
• extensions/twitch/src/runtime.ts

特殊情況變體：

• extensions/bluebubbles/src/runtime.ts
• extensions/line/src/runtime.ts
• extensions/synology-chat/src/runtime.ts

預計提取出的形狀：

• createPluginRuntimeStore<T>(errorMessage)

預計節省：

• 約 180-260 LOC

風險：

• 低

3. Onboarding 提示與配置修補步驟 (Onboarding prompt and config-patch steps)

涉及範圍廣大。

許多 onboarding 文件重複了以下操作：

• 解析帳號 ID
• 提示 allowlist 條目
• 合併 allowFrom
• 設定 DM 策略
• 提示 secrets
• 修補頂層與帳號範圍的配置

典型的例子包括：

• extensions/bluebubbles/src/onboarding.ts
• extensions/googlechat/src/onboarding.ts
• extensions/msteams/src/onboarding.ts
• extensions/zalo/src/onboarding.ts
• extensions/zalouser/src/onboarding.ts
• extensions/nextcloud-talk/src/onboarding.ts
• extensions/matrix/src/onboarding.ts
• extensions/irc/src/onboarding.ts

現有的 helper 銜接點：

• src/channels/plugins/onboarding/helpers.ts

預計提取出的形狀：

• promptAllowFromList(...)
• buildDmPolicyAdapter(...)
• applyScopedAccountPatch(...)
• promptSecretFields(...)

預計節省：

• 約 300-600 LOC

風險：

• 中等。容易過度抽象；請保持 helper 的功能單一且可組合。

4. 多帳號配置 Schema 片段 (Multi-account config-schema fragments)

跨 extension 重複的 schema 片段。

常見模式：

• const allowFromEntry = z.union([z.string(), z.number()])
• 帳號 schema 加上：
  • accounts: z.object({}).catchall(accountSchema).optional()
  • defaultAccount: z.string().optional()
• 重複的 DM/group 欄位
• 重複的 markdown/tool 策略欄位

典型的例子包括：

• extensions/bluebubbles/src/config-schema.ts
• extensions/zalo/src/config-schema.ts
• extensions/zalouser/src/config-schema.ts
• extensions/matrix/src/config-schema.ts
• extensions/nostr/src/config-schema.ts

預計提取出的形狀：

• AllowFromEntrySchema
• buildMultiAccountChannelSchema(accountSchema)
• buildCommonDmGroupFields(...)

預計節省：

• 約 120-220 LOC

風險：

• 低到中等。有些 schema 很簡單，有些則很特殊。

5. Webhook 與 Monitor 生命週期啟動 (Webhook and monitor lifecycle startup)

中等價值的重構群組。

重複的 startAccount / monitor 設定模式：

• 解析帳號
• 計算 webhook 路徑
• 記錄啟動日誌
• 啟動 monitor
• 等待中止 (abort)
• 清理
• 狀態接收器 (status sink) 更新

典型的例子包括：

• extensions/googlechat/src/channel.ts
• extensions/bluebubbles/src/channel.ts
• extensions/zalo/src/channel.ts
• extensions/telegram/src/channel.ts
• extensions/nextcloud-talk/src/channel.ts

現有的 helper 銜接點：

• src/plugin-sdk/channel-lifecycle.ts

預計提取出的形狀：

• 帳號 monitor 生命週期的 helper
• 基於 webhook 的帳號啟動 helper

預計節省：

• 約 150-300 LOC

風險：

• 中到高。傳輸層 (Transport) 的細節差異很大。

6. 小型完全重複代碼清理 (Small exact-clone cleanup)

低風險的清理桶。

例子：

• 重複的 gateway argv 檢測：
  • src/infra/gateway-lock.ts
  • src/cli/daemon-cli/lifecycle.ts
• 重複的連接埠診斷渲染：
  • src/cli/daemon-cli/restart-health.ts
• 重複的 session-key 構建：
  • src/web/auto-reply/monitor/broadcast.ts

預計節省：

• 約 30-60 LOC

風險：

• 低

測試群組 (Test clusters)

LINE webhook 事件 fixtures

典型的例子：

• src/line/bot-handlers.test.ts

預計提取：

• makeLineEvent(...)
• runLineEvent(...)
• makeLineAccount(...)

預計節省：

• 約 120-180 LOC

Telegram 原生指令權限矩陣 (Telegram native command auth matrix)

典型的例子：

• src/telegram/bot-native-commands.group-auth.test.ts
• src/telegram/bot-native-commands.plugin-auth.test.ts

預計提取：

• forum context builder
• 拒絕訊息斷言 helper
• 表格驅動的權限測試案例

預計節省：

• 約 80-140 LOC

Zalo 生命週期設定

典型的例子：

• extensions/zalo/src/monitor.lifecycle.test.ts

預計提取：

• 共享的 monitor 設定 harness

預計節省：

• 約 50-90 LOC

Brave llm-context 不支援選項測試

典型的例子：

• src/agents/tools/web-tools.enabled-defaults.test.ts

預計提取：

• it.each(...) 矩陣

預計節省：

• 約 30-50 LOC

建議執行順序 (Suggested order)

1. Runtime 單例樣板代碼
2. 小型完全重複代碼清理
3. 配置與安全性 builder 提取
4. 測試 helper 提取
5. Onboarding 步驟提取
6. Monitor 生命週期 helper 提取

如果你在重構過程中遇到任何問題，可以隨時諮詢 AI Setup Assistant。

下一步

• 了解如何開發頻道插件
• Extension 配置 Schema 指南