Channel 配置（远程接入）

这一页解决什么

怎么让 Agent 在 Telegram / Slack / 飞书 / 钉钉 / 邮件 / Web 这些通道里被远程调用？
各 channel 怎么配（最小可用配置）？
怎么控制谁可以使唤 Agent（白名单 / 群组策略）？

全部内置 Channel

Channel	key	鉴权	群组策略	流式输出
桌面/浏览器 UI	`ui`	CORS 控制浏览器来源；不是用户鉴权	—	✅
Telegram	`telegram`	Bot Token	`open` / `mention`	✅
WhatsApp	`whatsapp`	Bridge URL + Token	`open` / `mention`	—
Discord	`discord`	Bot Token（OAuth 流）	—	—
飞书 Lark	`feishu`	App ID/Secret + 验证 token	`open` / `mention`	✅
钉钉	`dingtalk`	Client ID/Secret	—	—
Slack	`slack`	Bot/App Token	`open` / `mention` / `allowlist`	—
微信社群（Mochat）	`mochat`	—	—	—
QQ	`qq`	App ID + Secret	—	—
Matrix	`matrix`	homeserver + 账号或 token	`open` / `mention` / `allowlist`	—
邮件（IMAP+SMTP）	`email`	IMAP/SMTP 凭据	—	—
企业微信 AI Bot	`wecom`	Bot ID/Secret，可选 SDK	—	依实现
个人微信	`weixin`	扫码获取 token	—	依实现

当前源码可发现 13 个内置 Channel 模块。企微需要其可选 SDK；微信 weixin 是个人微信的扫码/长轮询接入，不是公众号回调。能否启用还取决于依赖、凭据与实际平台服务。

全局开关

{
  "channels": {
    "sendProgress": true,
    "sendToolHints": false,
    "sendMaxRetries": 3,
    "transcriptionProvider": "groq"
  }
}

字段	含义
`sendProgress`	是否把 Agent 文字进度流式推到 channel
`sendToolHints`	是否把工具调用提示（`read_file("...")`）推过去（默认关，避免打扰）
`sendMaxRetries`	投递失败重试次数（含首发）
`transcriptionProvider`	语音转写后端：`groq` 或 `openai`

UI（桌面 / 浏览器，`channels.ui`）

MiraUI 桌面应用和浏览器版前端连的就是这个 channel——通过 WebSocket 推消息、REST 拉项目数据。不开它 UI 就连不上后端，所以装完 mira 第一件事就是确认这一节配好。

{
  "channels": {
    "ui": {
      "enabled": true,
      "allowFrom": ["*"],
      "corsOrigins": ["*"]
    }
  }
}

字段	默认	说明
`enabled`	`false`	总开关。启动 gateway 会按 UI 启动逻辑处理启用状态；使用 `--no-ui` 可明确禁用，检查实际配置
`allowFrom`	`[]`	允许连接的客户端 ID / 来源白名单。`["*"]` 放行全部；空列表拒绝消息发送者；不会为全部 REST 接口提供用户鉴权
`corsOrigins`	`["*"]`	CORS `Access-Control-Allow-Origin` 列表。`["*"]` 放行全部 origin（适合本机自用）；要锁死的话填 `["https://your-host"]`

Host / port 怎么定？

UI channel 不绑自己的端口——它复用 gateway 监听的 host:port（默认 0.0.0.0:18790）。所以你看到的 UI 连接地址其实就是 gateway 地址：

mira gateway                              # 0.0.0.0:18790
mira gateway --host 127.0.0.1 -p 28790    # 改 gateway，UI channel 跟着走

UI 连远程后端的话，gateway 必须监听 0.0.0.0（不能只 127.0.0.1），且对应端口的防火墙要开。详见 troubleshooting §1。

场景	`allowFrom`	`corsOrigins`
个人本机 / 只跑桌面 app	`["*"]`	`["*"]`
团队远程共享一台 mira（受信内网）	`["*"]`	`["https://mira.team.lan"]`
公网暴露（不推荐，请优先走 Tailscale / VPN）	具体 client ID 列表	具体 origin 列表

验收检查

# 后端起来
mira gateway -v

# 另开一个终端
curl http://127.0.0.1:18790/api/health     # 应返回 200

UI 客户端里把 API 地址填成 http://<host>:18790/api，WebSocket 地址填成 ws://<host>:18790/ws，连接指示灯转绿就 OK。

Telegram（最简单）

找 @BotFather 新建 bot，记下 token。
写到 ~/.mira/config.json：

{
  "channels": {
    "telegram": {
      "enabled": true,
      "token": "1234567:ABC...",
      "groupPolicy": "mention",
      "reactEmoji": "👀",
      "streaming": true,
      "streamEditInterval": 0.6,
      "allowFrom": ["your_username", "123456789"]
    }
  }
}

启动：

mira gateway        # gateway 起来后 telegram 自动连
mira channels status

在私聊里 @bot 帮我查一下最新的 RSNA 综述；群里 @ 一下 bot。

groupPolicy：

open：群里任何消息都响应（聊天群少用）。
mention：必须 @ bot 才响应（推荐）。

allowFrom：使用 numeric user ID，或平台传入的 username 字符串（不加 @）。空数组拒绝访问；明确开放所有发送者才用 ["*"]。

飞书

{
  "channels": {
    "feishu": {
      "enabled": true,
      "appId": "cli_...",
      "appSecret": "...",
      "encryptKey": "...",
      "verificationToken": "...",
      "groupPolicy": "mention",
      "reactEmoji": "THUMBSUP",
      "streaming": true,
      "allowFrom": ["ou_xxx", "ou_yyy"]
    }
  }
}

需要在飞书开放平台后台：

创建企业自建应用，记下 appId / appSecret。
启用机器人能力，订阅 im.message.receive_v1。
事件接收方式使用长连接；当前代码由 Lark WebSocket 客户端接收，不提供旧文档的 /feishu/events HTTP 回调。
加密 key / 验证 token 在“事件订阅”页拷贝。

Slack

{
  "channels": {
    "slack": {
      "enabled": true,
      "botToken": "xoxb-...",
      "appToken": "xapp-...",
      "mode": "socket",
      "groupPolicy": "mention",
      "groupAllowFrom": ["C01234567"],
      "replyInThread": true,
      "allowFrom": ["U01234567"],
      "dm": { "enabled": true, "policy": "open" }
    }
  }
}

当前仅实现 mode: "socket"，需要 Bot Token 和 App Token；不支持把 mode 改成 Events API。

邮件（适合后台跑长任务，让 Agent 把结果发回邮箱）

{
  "channels": {
    "email": {
      "enabled": true,
      "consentGranted": true,
      "allowFrom": ["researcher@example.com"],
      "pollIntervalSeconds": 30,

      "imapHost": "imap.example.com",
      "imapPort": 993,
      "imapUsername": "agent@example.com",
      "imapPassword": "...",
      "imapUseSsl": true,
      "imapMailbox": "INBOX",

      "smtpHost": "smtp.example.com",
      "smtpPort": 587,
      "smtpUsername": "agent@example.com",
      "smtpPassword": "...",
      "smtpUseTls": true,

      "fromAddress": "agent@example.com",
      "subjectPrefix": "Re: ",
      "autoReplyEnabled": true,
      "maxBodyChars": 12000,
      "maxAttachmentSize": 10485760,
      "maxAttachmentsPerEmail": 5,
      "allowedAttachmentTypes": ["pdf", "csv", "png", "jpg"]
    }
  }
}

consentGranted: true 是显式授权，避免误把 Mira 接到生产邮箱。

Matrix（端到端加密的去中心化群聊）

{
  "channels": {
    "matrix": {
      "enabled": true,
      "homeserver": "https://matrix.org",
      "userId": "@agent:matrix.org",
      "password": "...",
      "e2eeEnabled": true,
      "allowFrom": ["@researcher:matrix.org"],
      "groupPolicy": "mention",
      "groupAllowFrom": ["!roomid:matrix.org"]
    }
  }
}

发送者与群组限制

通用 allowFrom 中，空列表拒绝全部发送者，["*"] 明确开放全部；具体 ID 列表只允许匹配的发送者。Telegram 还支持当前实现的 ID/username 匹配。

Slack 与 Matrix 等通道还会检查 DM/群组策略、房间/频道名单和是否提及机器人。满足群策略不等于绕过通用发送者名单；按具体通道配置并分别验证允许与拒绝的账号。

CORS 和客户端自报 ID 不是 REST 用户鉴权。团队共享后端应使用实际部署的访问控制，不能把这套消息过滤当作项目级权限隔离。

排障 checklist

配完没反应？先看 mira channels status，再看 ~/.mira/logs/agent-service.log 中对应 channel 的报错。
Telegram 收不到消息？多半是 allowFrom 没把你自己加进去。
飞书无法接收？检查应用 ID/Secret、长连接事件订阅、权限和允许的用户 open_id。
长消息被截断？看 channels.<name>.maxBodyChars（邮件）或对应平台限制。

详见 FAQ §7。

验收检查

mira channels status 显示对应 channel 已启用；实际连接以 gateway 日志与收发消息为准。
在被允许的对话里说一句话，Agent 能返回实际回复（不接 streaming 时为整段，接了 streaming 时为流式）。
切到不被允许的账号说话，Agent 不响应（不要把白名单测试当成 bug）。

这一页解决什么​

全部内置 Channel​

全局开关​

UI（桌面 / 浏览器，channels.ui）​

Host / port 怎么定？​

推荐配置​

验收检查​

Telegram（最简单）​

飞书​

Slack​

邮件（适合后台跑长任务，让 Agent 把结果发回邮箱）​

Matrix（端到端加密的去中心化群聊）​

发送者与群组限制​

排障 checklist​

验收检查​

这一页解决什么

全部内置 Channel

全局开关

UI（桌面 / 浏览器，`channels.ui`）

Host / port 怎么定？

推荐配置

验收检查

Telegram（最简单）

飞书

Slack

邮件（适合后台跑长任务，让 Agent 把结果发回邮箱）

Matrix（端到端加密的去中心化群聊）

发送者与群组限制

排障 checklist

验收检查