HaloWebUI 内置的HaloClaw 网关，让你把 AI 大模型直接装进 Telegram、企业微信、飞书三大聊天软件：在微信里 @ 一下机器人，就能调用 HaloWebUI 中已配置的任意模型对话，支持图片理解、模型切换、思考强度调节和用量统计。本文手把手带你完成三端接入。

一、HaloClaw 是什么：一个把 AI 装进聊天软件的网关 🐱

HaloClaw 是 HaloWebUI 基于 OpenWebUI 扩展出的消息网关模块，位于 backend/open_webui/haloclaw/，它把外部平台的每条消息桥接到 HaloWebUI 的 AI 对话流水线（核心调度逻辑见 dispatcher.py），主要能力包括：

• 三平台适配：Telegram 走长轮询（无需公网地址），企业微信与飞书走 Webhook 事件回调
• 完整对话链路：多轮历史、系统提示词、图片消息（文本 + 图片混合理解）
• 智能体增强：可挂载 HaloWebUI 内置工具、调节思考强度（low/medium/high）
• 细粒度管控：白名单私聊策略、群聊 @ 触发、按用户禁用/封禁、按用户覆盖模型
• 用量留痕：每条消息记录prompt_tokens与completion_tokens，配合 HaloWebUI 的模型计费与用量统计

三个平台的适配实现分别在：

• adapters/telegram.py
• adapters/wechat_work.py
• adapters/feishu.py

二、快速启用 HaloClaw 网关（3 步上手）

第 1 步：启动服务

拉取仓库并以管理员身份启动后端（也可用 Docker Compose 部署，参考根目录 docker-compose.yaml）：

git clone https://gitcode.com/gh_mirrors/ha/HaloWebUI cd HaloWebUI/backend pip install -r requirements.txt python -m open_webui.main

第 2 步：开启 HaloClaw 开关

HaloClaw 默认关闭，可用环境变量ENABLE_HALOCLAW=true启动，或直接登录管理后台，在设置 → HaloClaw（前端页面 src/routes/(app)/settings/haloclaw/+page.svelte/settings/haloclaw/+page.svelte)）中打开总开关，并设置全局默认模型、历史轮数（HALOCLAW_MAX_HISTORY，默认 20）与限速（HALOCLAW_RATE_LIMIT，默认 10 条/分钟）。配置项定义见 config.py。

第 3 步：创建网关

在管理后台新增 Gateway，选择平台（telegram/wechat_work/feishu），填入对应凭据、指定默认模型，打开开关即生效——服务启动时会自动拉起所有已启用的网关（lifecycle.py）。

三、接入 Telegram：最简单的起步方案 ✅

Telegram 走长轮询方式，服务器不需要公网 IP，是最适合新手上手的平台。

1. 在 Telegram 中找到@BotFather，发送/newbot创建机器人，拿到bot_token
2. 在 HaloClaw 后台创建 Telegram 网关，config中只需填一项：bot_token
3. 打开开关，私聊机器人发送/start即可对话

接入后机器人自带中文命令菜单（定义见 menus/telegram.py）：

实用细节：

• 支持发送图片提问，机器人会把图片转成数据格式喂给模型做视觉理解
• 群聊中默认只在 @机器人 或回复机器人时响应（group_policy: mention），也可在网关的access_policy中设为disabled彻底关闭群聊
• 回复自动做 Markdown → Telegram HTML 转换，超长消息自动分段

四、接入企业微信：办公场景的 AI 助手 💼

企业微信走回调模式，需要服务器有公网可访问的地址（可用 Nginx 反代或内网穿透工具）。

1. 在企业微信管理后台创建自建应用，获取corp_id（企业 ID）与secret，并记下应用agent_id
2. 在应用的「接收消息」中设置回调 URL：

https://你的域名/api/v1/haloclaw/webhook/wechat_work/{gateway_id}

3. 回调设置页会要求验证，填入Token和EncodingAESKey后即可通过 URL 校验（校验逻辑见 router.py）
4. 在 HaloClaw 后台创建wechat_work网关，config填入 5 个字段：

5. 打开开关，在成员授权范围里把自己加进去，私聊应用发消息即可

技术要点：企业微信要求 5 秒内响应，HaloClaw 采用「先应答、后台异步处理」策略，access_token自动每 100 分钟刷新一次，全程无需人工干预（adapters/wechat_work.py）。

五、接入飞书：事件订阅与加密校验 📮

飞书同样走事件订阅 + 回调，步骤与企业微信类似：

1. 在飞书开放平台创建企业自建应用，获取app_id与app_secret
2. 为应用开通机器人能力，添加「接收消息」事件订阅，回调地址填：

https://你的域名/api/v1/haloclaw/webhook/feishu/{gateway_id}

3. 订阅页会发起url_verification挑战验证，HaloClaw 自动完成 token 校验并原样返回 challenge（router.py）
4. 创建feishu网关，config填入 4 个字段：

5. 打开开关，在飞书里单聊或拉机器人进群即可

群聊中 @机器人 即可触发；适配器内置事件去重机制，避免平台重推导致重复回复（adapters/feishu.py）。

六、模型选择、访问控制与用量统计 📊

在网关设置里，你可以为每个平台独立指定default_model_id；HaloWebUI 模型列表中各提供商都有专属品牌图标：

模型解析优先级为：用户级覆盖 → 网关默认模型 → 全局默认模型（dispatcher.py）。配合 HaloWebUI 的模型计费与用量统计，管理员可以在后台按网关查看每条消息的 Token 消耗。

访问控制（access_policy字段）：

• 私聊：dm_policy支持open（任何人可用）与allowlist（仅白名单用户）
• 群聊：group_policy支持mention（@ 才响应）与disabled（禁用）
• 管理后台可对单个外部用户执行封禁、绑定 Halo 账号（复用该账号的模型权限）、指定专属模型等操作（接口定义见 router.py）

用量与审计：所有收发消息都会落库到haloclaw_message_log表，记录方向、角色、内容摘要、模型 ID 和 Token 数，管理后台可按网关、按用户查看日志（models.py）。

七、常见问题与最佳实践 🔧

最佳实践：

1. 先用Telegram验证链路（无需公网），再逐步上线企业微信/飞书
2. 生产环境务必启用白名单 + 限速，避免 API Key 被滥用
3. 为网关配置系统提示词（如"你是 XX 公司的客服助手，仅回答与业务相关的问题"），行为更可控
4. 定期在管理后台清理消息日志，控制数据库体积

至此，你已经在自己常用的聊天软件里拥有了一个受控的 AI 助手入口。HaloWebUI 的 HaloClaw 网关源码全部开放在 backend/open_webui/haloclaw/，欢迎基于适配器模式（adapters/base.py）扩展更多平台。