Xikapi 接入文档

连接 Telegram ​

Telegram 是 OpenClaw 最适合新手试用的通讯渠道之一。它通过 Telegram Bot API 工作，默认使用 long polling。这里推荐使用 openclaw channels add 写入配置，比手动改配置文件或临时环境变量更稳定。

注意拼写

Channel 名称必须写成 telegram，不要写成 telegrm、tg 或其他缩写。

前置条件 ​

  • 已完成 OpenClaw Gateway 初始化
  • 已有 Telegram 账号
  • 可以和 @BotFather 对话
  • 当前机器可以访问 api.telegram.org

1. 创建 Telegram Bot ​

  1. 打开 Telegram，搜索 @BotFather。
  2. 发送 /newbot。
  3. 按提示输入 Bot 名称和用户名。
  4. 保存 BotFather 返回的 bot token。

bot token 通常长这样：

text
1234567890:AAExampleExampleExampleExample

2. 添加 Telegram Channel ​

推荐使用 CLI 写入配置：

bash
openclaw channels add --channel telegram --token "your BotFather token"

示例：

bash
openclaw channels add --channel telegram --token "1234567890:AAExampleExampleExampleExample"

添加后重启 Gateway：

bash
openclaw gateway restart

然后检查状态：

bash
openclaw channels status --probe
openclaw channels logs --channel telegram

如果状态里能看到 Telegram account，并且没有 token 或网络错误，说明基础连接已经建立。

3. 私聊 Bot 并批准配对 ​

打开 Telegram，找到你刚创建的 Bot，发送一条消息，例如：

text
Hello

默认私聊策略是 pairing。首次私聊通常需要在终端批准：

bash
openclaw pairing list --channel telegram
openclaw pairing approve telegram <CODE>

如果你的 OpenClaw 版本支持简写，也可以使用：

bash
openclaw pairing list telegram
openclaw pairing approve telegram <CODE>

配对码通常 1 小时过期。过期后需要重新私聊 Bot 触发新的配对码。

4. 推荐的单人私聊配置 ​

如果只是自己使用，建议把自己的 Telegram 数字用户 ID 固定进 allowlist，比每次依赖 pairing 更稳定。

先私聊 Bot，然后查看日志：

bash
openclaw logs --follow

在日志中找 from.id，它是你的 Telegram 数字用户 ID。

也可以用 Bot API 查看：

bash
curl "https://api.telegram.org/bot<bot_token>/getUpdates"

配置思路：

js
{
  channels: {
    telegram: {
      enabled: true,
      dmPolicy: "allowlist",
      allowFrom: ["123456789"]
    }
  }
}

allowFrom 放用户 ID，不是 Bot token，也不是 Telegram 用户名。

5. 添加到群组 ​

把 Bot 添加到 Telegram 群组后，默认建议要求 @ 机器人才回复。

常见配置：

js
{
  channels: {
    telegram: {
      groupPolicy: "allowlist",
      groups: {
        "*": {
          requireMention: true
        }
      }
    }
  }
}

如果要指定某个群，先让群里发一条消息，再看日志：

bash
openclaw logs --follow

找到 chat.id。超级群 ID 通常是负数，例如：

text
-1001234567890

指定群配置：

js
{
  channels: {
    telegram: {
      groups: {
        "-1001234567890": {
          requireMention: true
        }
      }
    }
  }
}

6. 群里不 @ 也想回复 ​

Telegram Bot 默认 Privacy Mode 会限制机器人读取普通群消息。如果你希望机器人不需要 @ 也能看见群消息，需要二选一：

  1. 在 BotFather 中执行 /setprivacy，选择 Disable。
  2. 或者把 Bot 设置为群管理员。

修改 Privacy Mode 后，建议把 Bot 移出群再重新加入。

同时配置：

js
{
  channels: {
    telegram: {
      groups: {
        "-1001234567890": {
          requireMention: false
        }
      }
    }
  }
}

7. 不推荐的临时环境变量方式 ​

也可以使用环境变量：

bash
export TELEGRAM_BOT_TOKEN="123:abc"

Windows PowerShell：

powershell
$env:TELEGRAM_BOT_TOKEN="123:abc"

但这种方式只对当前终端会话可靠。如果 Gateway 是 daemon / service，可能读不到你当前 PowerShell 里的临时环境变量。因此新手建议优先使用：

bash
openclaw channels add --channel telegram --token "your BotFather token"

常见问题 ​

Bot 私聊不回复 ​

按顺序检查：

bash
openclaw gateway status
openclaw channels status --probe
openclaw channels logs --channel telegram
openclaw pairing list --channel telegram

常见原因：

  • telegram 拼写错误
  • Bot token 填错
  • Gateway 没有重启
  • 私聊 pairing 没有批准
  • 当前机器无法访问 api.telegram.org
  • Xikapi 模型没有配置成功，Telegram 收到消息但模型无法回复

群里不回复 ​

常见原因：

  • 没有 @ 机器人
  • 群 ID 没有加入 groups
  • groupPolicy 仍是 allowlist，但没有放行对应群
  • BotFather Privacy Mode 仍然开启
  • Bot 没有被重新加入群

status 里看不到 Telegram ​

重新添加：

bash
openclaw channels add --channel telegram --token "your BotFather token"
openclaw gateway restart
openclaw channels status --probe

日志里出现 getUpdates / fetch failed ​

通常是当前机器无法访问 Telegram API，或者网络代理配置不对。

可以先测试：

bash
curl "https://api.telegram.org/bot<bot_token>/getMe"

如果这个请求失败，需要先解决网络或代理问题。

参考链接 ​