LangBot 4.11 插件化：微信飞书钉钉接入 Claude Code 与 Codex

从终端到群聊：AI 编程助手的新入口

团队已经在本地机器上用 Claude Code 和 Codex 处理仓库、shell 和 MCP 服务器，但同事想从企业微信、飞书或钉钉群聊中直接调用同样的能力，却一直受限于终端环境。LangBot 4.11 版本通过 Runner 插件化解决了这个痛点，让外部 CLI 代理可以像普通插件一样安装、配置，并绑定到不同的聊天平台流水线中。

据官方文档和代码仓库分析，4.10 版本虽然已经内置了 openclaw_weixin、lark、dingtalk 等消息平台适配器，但处理侧仍是九个内置 Runner 硬编码在 src/langbot/pkg/provider/runners/ 目录下。想要接入 Claude Code，要么修改 LangBot 源码，要么在机器人外部用 HTTP 服务包装 CLI。4.11 则彻底翻转了这一设计：Runner 变成插件，平台只负责事件来源。

LangBot 插件市场中的 Runner 插件

架构变化：Runner 插件化与适配器层

内置 Runner 被移除

在 4.11.0 版本中，src/langbot/pkg/provider/runners/ 目录已经完全不存在，而 4.10.11 版本中该目录下还有十个文件。provider/ 目录仅保留 modelmgr/、session/ 和 tools/。这意味着所有 Runner 都必须通过插件形式提供，运行时通过 LIST_RUNNERS 协议上报已安装插件中的 Runner，宿主程序在 RunnerRegistry 中缓存并生成形如 plugin:author/plugin_name/runner_name 的 ID。

插件清单（manifest）是核心契约，包含 id、name、label、description、capabilities、permissions、config_schema 和 metadata 等字段。其中 capabilities 是用于 UI 和资源投影的类型化布尔模型，并非权限授予；permissions 才是访问权限的上限，并与绑定策略取交集。官方提供的 Runner ID 包括 plugin:langbot-team/ClaudeCodeAgent/default 和 plugin:langbot-team/CodexAgent/default。

适配器层独立

4.11 新增了 src/langbot/pkg/platform/adapters/ 目录，拆分为十二个包，每个包含 manifest.yaml、adapter.py 和 event_converter.py。例如飞书适配器的清单声明了 kind: MessagePlatformAdapter。不过，入站文件清单并未改变：从 4.10.11 到 4.11.0，src/langbot/pkg/platform/sources/ 下的 22 个文件全部是修改，没有新增或删除。也就是说，4.11 并没有引入新的消息平台，而是通过适配器层和事件绑定来决定平台是否可用，Runner 本身不决定平台支持范围。

实战部署：双容器与四步配置

Runner 插件在独立的插件运行时容器中执行，因此需要两个容器：核心容器和运行时容器。以下为本地演示用的 Docker 命令（生产环境需替换网络和挂载路径）：

docker network create lang7-411
docker run -d --name lang7-411-core --network lang7-411 -e BOX__ENABLED=false \
  -p 15400:5300 -v "$PWD/deploy/411/data:/app/data" rockchin/langbot:v4.11.0
docker run -d --name lang7-411-runtime --network lang7-411 --network-alias langbot_plugin_runtime \
  -v "$PWD/deploy/411/data/plugins:/app/data/plugins" \
  rockchin/langbot:v4.11.0 uv run --no-sync -m langbot_plugin.cli.__init__ rt

管理员账号初始为 admin@langbot.local，密码为本地演示值，需替换。

第一步：从市场安装插件。 在 UI 中进入扩展 → 扩展市场，或通过 CLI 调用 POST /api/v1/plugins/install/marketplace，传入 {plugin_author, plugin_name}，返回 {task_id}。安装记录会标记 install_source=marketplace。文中以 langbot-team/LocalAgent 为例，Claude Code 和 Codex 插件走同样的入口，仓库位于 langbot-plugins 的 Runner/claude-code-agent 和 Runner/codex-agent。

第二步：确认插件落位。 插件产物并不在挂载的 plugins/ 目录中，而是位于运行时容器内的 /app/data/plugin-runtime/artifacts/sha256/<digest>/code/ 下，包含 manifest.yaml、main.py、pkg/、components/ 和 CERTIFICATION.md。宿主挂载的 plugins/ 目录保持为空。可以通过 API（GET /api/v1/plugins 返回包含该插件的数组）、数据库（plugin_settings 表中的 artifact_digest、runtime_revision、install_source、enabled 字段）以及日志（Mounting plugin ... → Initializing Runner component: default → Component default initialized）三重验证。

安装后的插件列表：LocalAgent 0.2.1

第三步：在流水线中选择 Runner。 在流水线编辑器中打开 AI 能力，找到标有“运行方式”的阶段卡片，从下拉框中选择完整的 Runner ID，例如 plugin:langbot-team/ClaudeCodeAgent/default。配置会存入 ai.runner.id 和 ai.runner_config[<runner_id>]，切换 Runner 时保留之前的设置。以 LocalAgent 为例，配置中可看到 timeout: 300 和 max-tool-iterations: 100。Claude Code 和 Codex 的设置项来自各自 README：command 默认分别为 claude 和 codex，timeout 默认 300 秒和 1800 秒，另有 workspace、ssh-target、mcp-servers-json 等。

第四步：接入聊天平台作为事件源。 连接企业微信、飞书或钉钉适配器，事件到达后通过事件绑定路由到流水线，选定的 Runner 执行处理。一个机器人可以对应多个流水线，每条流水线自由选择不同的 Runner。

验证与限制：需要留意的细节

验证安装是否成功可以从三个层面入手：API 返回的插件列表包含目标插件且 enabled 为 true；数据库 plugin_settings 表持久化了摘要和修订号；运行时容器内 ls 能看到上述文件而宿主 plugins/ 为空；流水线中 ai.runner.id 必须以 plugin: 开头，且 ai.runner_config 以该 ID 为键存储对象。最后发送一条真实消息，确认回复来自已安装的 Runner。

以下是官方文档中明确列出的限制与注意事项：

平台仅是事件源。 是否支持某平台取决于适配器和事件绑定，而非 Runner。支持矩阵在 01-event-system.md 中属于初步评估。
市场安装需要网络出口。 插件包从 {space_url}/api/v1/marketplace/plugins/download/... 拉取，从 GitHub 或本地归档安装则记录为 github 或 local。
产物按内容寻址。 市场侧摘要不一定等于本地摘要，需要与 plugin_settings.artifact_digest 对比。文中观察到的两个 LocalAgent 0.2.1 摘要就不同。
外部 CLI Runner 默认权限较宽松。 ClaudeCodeAgent 的 dangerously-skip-permissions 默认为 true，设为 false 可恢复 Claude Code 自身的检查；LangBot 目前没有交互式审批流程。CodexAgent 默认 approval-policy=never 和 sandbox-mode=danger-full-access。仅建议在受信任的工作区使用。
交互不是挂起等待。 两个 CLI Runner 会将 ask_user_question 等请求转为 interaction.requested，由适配器渲染为卡片；CLI 停止，用户回答后启动新运行并恢复同一会话。
Harness 路径是 MVP。 协议文档指出外部 harness runner 目前是 MVP/开发路径，不是发布级安全边界或完整的 Docker 部署方案。
认证字段可能不一致。 文中观察到 install_info._certification 显示 verification: "invalid" 且 certificate_id: null，而市场报告 certificate_status: "issued"。不要因为插件在市场中列出就认为本地验证通过。

总结与下一步

在 4.11 中，Runner 不再随 LangBot 内置，而是从市场安装、在应用中配置、按流水线选择。平台负责传递事件，Runner 决定处理方式——可以是本地 CLI 代理（Claude Code、Codex、ACP），也可以是 Dify、Coze、n8n、Langflow、DeerFlow 等服务型 Runner。

主要参考资料包括固定版本的迁移文档 pipeline-migration-config-map.zh-CN.md（其中列出了迁移器要求的最低 Runner 插件版本）以及 v4.11.0 发布页面。如果实例是从 4.10 升级而来，旧配置如何落入新形态是另一篇文章的主题，迁移会同时触及 ai.runner.runner、ai.runner.id 和 ai.runner_config。对于托管环境，可以单独考察 Cloud 方案（https://space.langbot.app）。