CodeBuddy CLI 接入 Telegram Channel 完全指南

简要

Telegram 是官方支持的 4 个 Channel 之一。 ⚠️ 但目前处于 Beta 阶段，功能和接口可能调整。

CodeBuddy CLI 支持 4 个 Channel：

💡 一句话理解 Channel：一种特殊的 MCP 服务器，把外部消息/告警/Webhook 推送进正在运行的 CodeBuddy Code 会话，并可通过同一 Channel 回复——相当于一个「聊天桥」。

一、Telegram Channel 接入（5 步，官方流程）

第 1 步：创建 Telegram Bot 拿 token

1. 在 Telegram 里搜索并打开 @BotFather
2. 发送 /newbot，按提示设置 bot 名称与用户名
3. 创建成功后，BotFather 会返回一串 HTTP API Token（形如 123456789:AAF-xxxx...），复制保存

第 2 步：安装官方插件

在 CodeBuddy Code 中执行：

/plugin install telegram@claude-plugins-official

第 3 步：配置 token

/telegram:configure <你的 bot token>

第 4 步：带 Channel 启动 CLI

codebuddy --channels plugin:telegram@claude-plugins-official

可以同时加载多个 Channel，逗号分隔：

codebuddy --channels plugin:telegram@claude-plugins-official,plugin:discord@claude-plugins-official

第 5 步：配对（把你的账号加入白名单）

1. 在 Telegram 里给你的 bot 发任意一条消息
2. bot 会回复一个配对码
3. 回到 CodeBuddy Code 执行：

/telegram:access pair <配对码>

1. 配对完成，你的发送者 ID 进入白名单，之后即可正常对话

二、它能干什么（能力边界）

典型场景

• 在手机 Telegram 上给 CodeBuddy 下任务，实际工作在你自己的机器和真实文件上执行
• CI / 监控告警的 Webhook 到达时，CodeBuddy 已经打开着你的文件并记得你在调试什么

三、安全机制（必读）

⚠️ 关于 Prompt 注入：未做发送者校验的 Channel 是注入攻击入口。自建 Channel 时，务必用 message.from.id（发送者）而非 message.chat.id（群组）做校验——群聊里两者不同，按群组校验等于放行群里所有人。

四、组织/企业管控

管理员在 settings.json 中设置：

{
  "channelsEnabled": true
}

设为 false 则完全禁用 Channel（MCP 服务器仍连接、工具仍可用，但 Channel 消息不会到达）。

五、自建 Telegram Channel（进阶，官方协议）

官方已有 Telegram 插件，但如果你想自己实现（比如加自定义逻辑、接企业内网），协议是开放的。

核心三要素

1. 声明 claude/channel capability
2. 发送 notifications/claude/channel 事件
3. 通过 stdio 传输连接（CodeBuddy Code 作为父进程启动它）

Server 配置选项

最小骨架（以 Webhook 接收器为例，可直接改成 Telegram 轮询）

#!/usr/bin/env bun
import { Server } from '@modelcontextprotocol/sdk/server/index.js'
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'

const mcp = new Server(
  { name: 'webhook', version: '0.0.1' },
  {
    capabilities: { experimental: { 'claude/channel': {} } },
    instructions: '来自 webhook 的事件以 <channel> 标签到达。单向通道，只需阅读并处理。',
  },
)

await mcp.connect(new StdioServerTransport())

Bun.serve({
  port: 8788,
  hostname: '127.0.0.1',
  async fetch(req) {
    const body = await req.text()
    await mcp.notification({
      method: 'notifications/claude/channel',
      params: {
        content: body,
        meta: { path: new URL(req.url).pathname, method: req.method },
      },
    })
    return new Response('ok')
  },
})

注册到 .mcp.json：

{
  "mcpServers": {
    "webhook": { "command": "bun", "args": ["./webhook.ts"] }
  }
}

通知格式

await mcp.notification({
  method: 'notifications/claude/channel',
  params: {
    content: 'build failed on main',
    meta: { severity: 'high', run_id: '1234' },
  },
})

到达 CLI 后渲染为：

<channel source="webhook" severity="high" run_id="1234">
build failed on main
</channel>

meta 的键名只允许字母、数字、下划线，含连字符等其他字符的键会被静默丢弃。

双向：暴露 reply 工具

import { ListToolsRequestSchema, CallToolRequestSchema } from '@modelcontextprotocol/sdk/types.js'

mcp.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [{
    name: 'reply',
    description: '通过此 channel 发送回复消息',
    inputSchema: {
      type: 'object',
      properties: {
        chat_id: { type: 'string', description: '要回复的对话 ID' },
        text: { type: 'string', description: '要发送的消息' },
      },
      required: ['chat_id', 'text'],
    },
  }],
}))

mcp.setRequestHandler(CallToolRequestSchema, async req => {
  if (req.params.name === 'reply') {
    const { chat_id, text } = req.params.arguments as { chat_id: string; text: string }
    await sendToPlatform(chat_id, text)   // 调用你的聊天平台 API
    return { content: [{ type: 'text', text: 'sent' }] }
  }
  throw new Error(`unknown tool: ${req.params.name}`)
})

权限中继（远程审批工具调用）

Server 构造器加一行：

capabilities: {
  experimental: {
    'claude/channel': {},
    'claude/channel/permission': {},   // 启用权限中继
  },
  tools: {},
},

• CLI 发出 notifications/claude/channel/permission_request，含 request_id（5 个小写字母，排除 l）、tool_name、description、input_preview（截断 200 字符）
• 你的 Channel 回复裁决：

await mcp.notification({
  method: 'notifications/claude/channel/permission',
  params: { request_id: '<收到的 request_id>', behavior: 'allow' },  // 或 'deny'
})

• 在 Telegram 侧识别用户回复：

// 匹配 "y abcde" / "yes abcde" / "n abcde" / "no abcde"
// [a-km-z] 为 CLI 使用的 ID 字母表（小写，跳过 'l'）
const PERMISSION_REPLY_RE = /^\s*(y|yes|n|no)\s+([a-km-z]{5})\s*$/i

本地终端与远程 Channel 的对话框同时打开，先回答的生效，另一个自动关闭。

开发调试与发布

# 开发阶段：绕过允许列表白名单
codebuddy --dangerously-load-development-channels server:my-webhook

• 该标志只绕过允许列表检查，channelsEnabled 组织策略仍然生效
• 提交到官方市场并通过安全审查后，会被加入允许列表，之后可直接用 --channels 加载
• 打包成插件后用 /plugin install 安装，再用 --channels plugin:<name>@<marketplace> 启用

六、Channel vs 其他功能（别用错）

七、上手建议（推荐路线）

1. 先玩 fakechat（零成本、无需任何 token）：

   /plugin install fakechat@claude-plugins-official
   codebuddy --channels plugin:fakechat@claude-plugins-official
   

   打开 http://localhost:8787 即可体验完整双向流程。
2. 确认流程跑通后，再按第一节 5 步接入 Telegram。
3. 需要常驻：把 codebuddy --channels plugin:telegram@... 放进 tmux / 后台进程，否则关掉终端就收不到消息。