ZeroClaw Telegram 通道配置教程

博主： admin
发布时间：2026 年 03 月 02 日
1 次浏览
暂无评论
4671字数
分类： Docker 技术文档

# ZeroClaw Telegram 通道配置教程

# 一、概述

## 1. 简介
### A. 是什么
ZeroClaw Gateway 是一个基于 Rust 的 AI Agent Gateway，支持多通道接入，包括 CLI、Telegram 等方式。Telegram 通道允许用户通过群组或私聊与 AI Agent 交互。

### B. 为什么学
- 控制机器人响应行为，避免群组消息泛滥
- 优化资源使用，仅在需要时触发 AI 处理
- 提升用户体验，减少无关打扰

### C. 学完能做什么
- 配置 Telegram bot 的响应模式
- 启用提及-only 模式，让 bot 仅响应 @提及
- 灵活切换响应策略，适应不同场景

## 2. 前置知识
### A. 必备技能
- Docker 基本操作
- Linux 命令行操作
- 了解 TOML 配置文件格式

### B. 推荐知识
- ZeroClaw Gateway 基本架构
- Telegram Bot API 基础

# 二、ZeroClaw 架构简介

## 1. 系统组成
ZeroClaw Gateway 与 MCPorter（Node.js MCP CLI 客户端）集成，运行在 Docker 容器中：

```mermaid
graph TB
 Container[Docker 容器 zeroclaw-gateway]
 Gateway[ZeroClaw Gateway Rust 二进制]
 MCPorter[MCPorter CLI Node.js]
 MCP[Remote MCP Services context7, shadcn, vipmanager]

Container --> Gateway
    Gateway -.exec 子进程.-> MCPorter
    MCPorter -.HTTPS 请求.-> MCP

Container --> Volume[数据卷 ./data:/data]
 Volume --> Config[config.toml 主配置]
 Volume --> Workspace[workspace/ 技能、记忆、MCP 配置]
```

![mermaid](https://static.op123.ren/static/5a/5acc08010ff39ff2.svg)

## 2. 配置文件结构
项目使用单卷挂载实现数据持久化：

- config.toml：ZeroClaw 主配置文件，包含通道、模型、安全等设置
- mcporter.json：MCP 服务配置，定义外部服务端点和认证信息
- skills/：技能定义目录，存放 Markdown 格式的技能文件

# 三、配置 Telegram 通道

## 1. Telegram 配置项说明
config.toml 中的 channels_config.telegram 部分包含以下配置：

| 配置项 | 类型 | 默认值 | 说明 |
|-------|------|--------|------|
| bot_token | string | - | Telegram Bot API 令牌 |
| allowed_users | array | ["*"] | 允许使用 bot 的用户列表，* 表示所有用户 |
| stream_mode | string | off | 流式输出模式 |
| draft_update_interval_ms | integer | 1000 | 草稿更新间隔（毫秒） |
| interrupt_on_new_message | boolean | false | 新消息是否打断当前输出 |
| mention_only | boolean | false | 是否仅在 @提及时响应 |

## 2. mention_only 配置详解
mention_only 参数控制 bot 在群组中的响应行为：

- false：bot 会响应群组中的所有消息
- true：bot 仅在被 @提及或 @all 时才响应

启用 mention_only 后的响应逻辑：

```mermaid
flowchart TD
    A[收到 Telegram 群组消息] --> B{是否被 @提及?}
    B -->|@botname 或 @all| C[处理消息]
    B -->|无 @提及| D[忽略消息]
    C --> E[返回响应]
    D --> F[无动作]
```

![mermaid](https://static.op123.ren/static/f2/b7e4a6c8d3f9.svg)

# 四、启用提及-only 模式

## 1. 查看当前配置
使用以下命令查看当前 Telegram 配置：

```bash
sudo grep -A 7 "channels_config.telegram" /mydata/code/bots/zeroclaw_and_mcporter/data/.zeroclaw/config.toml
```

## 2. 修改配置文件
将 mention_only 参数从 false 改为 true：

```bash
sudo sed -i 's/mention_only = false/mention_only = true/g' /mydata/code/bots/zeroclaw_and_mcporter/data/.zeroclaw/config.toml
```

验证修改是否成功：

```bash
sudo grep -n "mention_only" /mydata/code/bots/zeroclaw_and_mcporter/data/.zeroclaw/config.toml
```

预期输出：
```
166:mention_only = true
```

## 3. 重启 Gateway 使配置生效
配置修改后需要重启服务：

```bash
docker restart zeroclaw-gateway
```

查看启动日志确认服务正常运行：

```bash
docker logs zeroclaw-gateway --tail 15
```

预期输出包含：
```
Listening for messages... (Ctrl+C to stop)
Telegram channel listening for messages...
```

# 五、验证配置

## 1. 测试场景
在 Telegram 群组中进行以下测试：

| 测试场景 | 预期结果 |
|---------|---------|
| 发送普通消息（无 @提及） | bot 不响应 |
| 发送 @botname 消息 | bot 响应 |
| 发送 @all 消息 | bot 响应（@all 提及所有人） |

## 2. 健康检查
确保 gateway 服务正常运行：

```bash
# 方式 1：使用 docker exec
docker compose --profile gateway exec zeroclaw-gateway zeroclaw status

# 方式 2：HTTP 请求
curl http://localhost:42617/health
```

# 六、其他常用配置

## 1. 切换响应模式
如需恢复 bot 响应所有消息，将配置改回 false：

```bash
sudo sed -i 's/mention_only = true/mention_only = false/g' /mydata/code/bots/zeroclaw_and_mcporter/data/.zeroclaw/config.toml
docker restart zeroclaw-gateway
```

## 2. 限制允许用户
修改 allowed_users 配置，仅允许特定用户使用：

```toml
allowed_users = ["user1", "user2"]
```

修改后重启服务使配置生效。

## 3. 启用流式输出
将 stream_mode 设置为 on 可实现实时流式输出：

```toml
stream_mode = "on"
```

# 七、常用管理命令

## 1. 服务管理
```bash
# 启动 gateway
docker compose --profile gateway up -d

# 停止 gateway
docker compose --profile gateway down

# 重启 gateway
docker compose --profile gateway restart

# 查看日志
docker compose --profile gateway logs -f zeroclaw-gateway
```

## 2. MCP 服务测试
```bash
# 列出配置的 MCP 服务
docker compose --profile gateway exec zeroclaw-gateway mcporter list

# 测试特定 MCP 工具
docker compose --profile gateway exec zeroclaw-gateway mcporter call vipmanager.get_statistics

# 查看工具 schema
docker compose --profile gateway exec zeroclaw-gateway mcporter list vipmanager --schema
```

# 八、常见问题

## 1. 配置修改不生效
**问题**：修改 config.toml 后 bot 行为未变化

**解决**：确认已重启 zeroclaw-gateway 容器

## 2. 文件权限拒绝
**问题**：读取或修改 config.toml 时提示权限拒绝

**解决**：使用 sudo 权限执行命令

## 3. bot 无响应
**问题**：@提及后 bot 无任何反应

**排查步骤**：
1. 检查 gateway 健康状态
2. 查看日志确认 Telegram 通道是否正常监听
3. 确认 bot_token 配置正确
4. 检查 allowed_users 配置

***

## 参考资料

1. [ZeroClaw GitHub 仓库](https://github.com/zeroclaw-labs/zeroclaw)
2. [MCPorter GitHub 仓库](https://github.com/steipete/mcporter)
3. [Telegram Bot API 文档](https://core.telegram.org/bots/api)

最后修改：2026 年 03 月 02 日

如果觉得我的文章对你有用，请随意赞赏

发表评论取消回复
使用cookie技术保留您的个人信息以便您下次快速评论，继续评论表示您已同意该条款

评论 *

私密评论

名称 *

🎲

邮箱 *

地址

ZeroClaw Telegram 通道配置教程

admin • 2026 年 03 月 02 日

# ZeroClaw Telegram 通道配置教程

# 一、概述

### B. 为什么学
- 控制机器人响应行为，避免群组消息泛滥
- 优化资源使用，仅在需要时触发 AI 处理
- 提升用户体验，减少无关打扰

### C. 学完能做什么
- 配置 Telegram bot 的响应模式
- 启用提及-only 模式，让 bot 仅响应 @提及
- 灵活切换响应策略，适应不同场景

## 2. 前置知识
### A. 必备技能
- Docker 基本操作
- Linux 命令行操作
- 了解 TOML 配置文件格式

### B. 推荐知识
- ZeroClaw Gateway 基本架构
- Telegram Bot API 基础

# 二、ZeroClaw 架构简介

## 1. 系统组成
ZeroClaw Gateway 与 MCPorter（Node.js MCP CLI 客户端）集成，运行在 Docker 容器中：

Container --> Gateway
    Gateway -.exec 子进程.-> MCPorter
    MCPorter -.HTTPS 请求.-> MCP

Container --> Volume[数据卷 ./data:/data]
 Volume --> Config[config.toml 主配置]
 Volume --> Workspace[workspace/ 技能、记忆、MCP 配置]
```

![mermaid](https://static.op123.ren/static/5a/5acc08010ff39ff2.svg)

## 2. 配置文件结构
项目使用单卷挂载实现数据持久化：

# 三、配置 Telegram 通道

## 1. Telegram 配置项说明
config.toml 中的 channels_config.telegram 部分包含以下配置：

## 2. mention_only 配置详解
mention_only 参数控制 bot 在群组中的响应行为：

- false：bot 会响应群组中的所有消息
- true：bot 仅在被 @提及或 @all 时才响应

启用 mention_only 后的响应逻辑：

![mermaid](https://static.op123.ren/static/f2/b7e4a6c8d3f9.svg)

# 四、启用提及-only 模式

## 1. 查看当前配置
使用以下命令查看当前 Telegram 配置：

```bash
sudo grep -A 7 "channels_config.telegram" /mydata/code/bots/zeroclaw_and_mcporter/data/.zeroclaw/config.toml
```

## 2. 修改配置文件
将 mention_only 参数从 false 改为 true：

```bash
sudo sed -i 's/mention_only = false/mention_only = true/g' /mydata/code/bots/zeroclaw_and_mcporter/data/.zeroclaw/config.toml
```

验证修改是否成功：

```bash
sudo grep -n "mention_only" /mydata/code/bots/zeroclaw_and_mcporter/data/.zeroclaw/config.toml
```

预期输出：
```
166:mention_only = true
```

## 3. 重启 Gateway 使配置生效
配置修改后需要重启服务：

```bash
docker restart zeroclaw-gateway
```

查看启动日志确认服务正常运行：

```bash
docker logs zeroclaw-gateway --tail 15
```

预期输出包含：
```
Listening for messages... (Ctrl+C to stop)
Telegram channel listening for messages...
```

# 五、验证配置

## 1. 测试场景
在 Telegram 群组中进行以下测试：

## 2. 健康检查
确保 gateway 服务正常运行：

```bash
# 方式 1：使用 docker exec
docker compose --profile gateway exec zeroclaw-gateway zeroclaw status

# 方式 2：HTTP 请求
curl http://localhost:42617/health
```

# 六、其他常用配置

## 1. 切换响应模式
如需恢复 bot 响应所有消息，将配置改回 false：

```bash
sudo sed -i 's/mention_only = true/mention_only = false/g' /mydata/code/bots/zeroclaw_and_mcporter/data/.zeroclaw/config.toml
docker restart zeroclaw-gateway
```

## 2. 限制允许用户
修改 allowed_users 配置，仅允许特定用户使用：

```toml
allowed_users = ["user1", "user2"]
```

修改后重启服务使配置生效。

## 3. 启用流式输出
将 stream_mode 设置为 on 可实现实时流式输出：

```toml
stream_mode = "on"
```

# 七、常用管理命令

## 1. 服务管理
```bash
# 启动 gateway
docker compose --profile gateway up -d

# 停止 gateway
docker compose --profile gateway down

# 重启 gateway
docker compose --profile gateway restart

# 查看日志
docker compose --profile gateway logs -f zeroclaw-gateway
```

## 2. MCP 服务测试
```bash
# 列出配置的 MCP 服务
docker compose --profile gateway exec zeroclaw-gateway mcporter list

# 测试特定 MCP 工具
docker compose --profile gateway exec zeroclaw-gateway mcporter call vipmanager.get_statistics

# 查看工具 schema
docker compose --profile gateway exec zeroclaw-gateway mcporter list vipmanager --schema
```

# 八、常见问题

## 1. 配置修改不生效
**问题**：修改 config.toml 后 bot 行为未变化

**解决**：确认已重启 zeroclaw-gateway 容器

## 2. 文件权限拒绝
**问题**：读取或修改 config.toml 时提示权限拒绝

**解决**：使用 sudo 权限执行命令

## 3. bot 无响应
**问题**：@提及后 bot 无任何反应

**排查步骤**：
1. 检查 gateway 健康状态
2. 查看日志确认 Telegram 通道是否正常监听
3. 确认 bot_token 配置正确
4. 检查 allowed_users 配置

***

## 参考资料

ZeroClaw Telegram 通道配置教程

发表评论取消回复
使用cookie技术保留您的个人信息以便您下次快速评论，继续评论表示您已同意该条款

搭建国内LabHub

CentOS 7.9 编译并使用rpm方式升级openssh9.6p1（包括后续更新9.8p1等）

一天从 redis 大 key 开始

安装eve-ng

重装ensp

epoll

国行 iPhone Air eSIM 限制深度技术分析

Julia Evans Django 入门学习笔记技术分析

2026.01.12. Apple Silicon PMU Counters: Analysis and Implementation Guide

互联网档案馆技术架构深度分析

ZeroClaw Telegram 通道配置教程

发表评论 取消回复 使用cookie技术保留您的个人信息以便您下次快速评论，继续评论表示您已同意该条款

ZeroClaw Telegram 通道配置教程

发表评论取消回复
使用cookie技术保留您的个人信息以便您下次快速评论，继续评论表示您已同意该条款