通道配置

xopcbot 支持多种通信通道。当前仅实现了 Telegram。

Telegram 通道

配置

在 ~/.config/xopcbot/config.json 中添加：

{
  "channels": {
    "telegram": {
      "enabled": true,
      "token": "YOUR_BOT_TOKEN",
      "allowFrom": ["@username1", "@username2"],
      "apiRoot": "https://api.telegram.org",
      "debug": false
    }
  }
}

获取 Bot Token

1. 打开 Telegram，搜索 @BotFather
2. 发送 /newbot 创建新机器人
3. 按提示设置名称和用户名
4. 复制生成的 Token

配置字段

字段	类型	说明
enabled	boolean	是否启用通道
token	string	Bot Token
allowFrom	string[]	白名单用户 (用户名或 ID)
apiRoot	string	自定义 Telegram API 地址，默认 https://api.telegram.org
debug	boolean	是否启用调试日志

使用限制

• 仅支持群组和私聊：不支持频道
• 轮询模式：当前使用长轮询，延迟约 1-2 秒
• 媒体处理：图片等媒体会显示为 [media]

启动测试

xopcbot gateway --port 18790

然后在 Telegram 中与机器人对话。

常见问题

Q: 收不到消息？

• 检查 Token 是否正确
• 确认 enabled 设为 true
• 检查网络连接

Q: 如何添加管理员？ 修改 allowFrom 数组：

{
  "channels": {
    "telegram": {
      "token": "...",
      "allowFrom": ["@admin1", "123456789"]
    }
  }
}

反向代理配置

在某些网络环境下，可能需要使用反向代理访问 Telegram API。

1. 配置反向代理

{
  "channels": {
    "telegram": {
      "enabled": true,
      "token": "YOUR_BOT_TOKEN",
      "apiRoot": "https://your-proxy-domain.com",
      "debug": true
    }
  }
}

2. 验证连接

启动时会自动调用 getMe 验证连接：

[INFO] Telegram API connection verified: {"username":"your_bot","apiRoot":"https://your-proxy-domain.com"}

手动测试连接 (代码方式):

const result = await channel.testConnection();
if (result.success) {
  console.log('Bot info:', result.botInfo);
} else {
  console.error('Connection failed:', result.error);
}

---

消息格式

入站消息

{
  channel: 'telegram',
  sender_id: '123456789',
  chat_id: '987654321',
  content: 'Hello, bot!',
  media?: ['file_id_1', 'file_id_2'],
  metadata?: Record<string, unknown>
}

出站消息

{
  channel: 'telegram',
  chat_id: '987654321',
  content: 'Hello, user!'
}

---

发送消息

通过 CLI

# 发送消息到 Telegram
xopcbot agent -m "Hello from CLI"

通过 Gateway API

curl -X POST http://localhost:18790/api/message \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "telegram",
    "chat_id": "123456789",
    "content": "Hello via API!"
  }'

通过 Extension

api.registerHook('message_sending', async (event, ctx) => {
  // 拦截或修改消息
  return { content: event.content };
});

---

最佳实践

1. 设置白名单：生产环境建议设置 allow_from 限制用户
2. 启用日志：通过 npm run dev 查看通道状态
3. 错误处理：通道连接失败时会自动重连
4. 资源清理：停止服务时正确关闭连接