消息與通知

Minara 可將消息從 Agent 循環推送到外部平臺。 Autopilot 交易通知、定時工作流的監控告警，以及離開 REPL 時的消息觸達，均依賴這套機制。

19 個平臺開箱即用，按類別分組。每個平臺均有獨立配置頁，涵蓋憑證步驟、入站 webhook 格式、簽名方案及平臺限制。

其中 7 個通道已在產品中開放。其餘通道在「設置 → 消息」中顯示為即將推出：底層傳輸已經就緒，運維者仍可通過 CLI 或環境變量配置，因此下面的配置頁依然準確，但 Web UI 暫不提供連接表單，也無法作為通知通道選擇。

目前開放：

• Telegram，推薦入門；支持流式編輯
• Discord，bot + 頻道；支持流式編輯（限速 1 秒）
• Lark / 飛書，tenant token + 可選 AES-256 webhook
• Email，SMTP；僅發送，主題自動截斷
• Email (Gmail OAuth)，Gmail API，OAuth 鑑權；支持流式編輯與回覆
• Signal，通過本地 signal-cli 子進程；僅發送
• Home Assistant，任意 notify.* 服務；僅發送

即將推出，企業 IM：

• Slack，webhook 或 bot token（僅 bot 模式支持流式）
• 企業微信 (WeCom)，SHA1 排序 + AES 信封
• 釘釘 (DingTalk)，HMAC-SHA256 簽名 URL 機器人
• Microsoft Teams，Bot Framework，JWT 校驗入站
• Google Chat，服務賬號 (Service Account) JWT 鑑權
• Mattermost，自託管，bot token + outgoing webhook

即將推出，消費者 / 社交：

• 微信公眾號 (WeChat OA)，48 小時窗口內的客服消息
• QQ Bot，Ed25519 webhook；被動回覆（主動消息每月限 4 條）
• LINE，Messaging API 推送 + 簽名 webhook

即將推出，聯邦 / 小眾：

• Matrix，Client-Server API + 長輪詢守護進程（不支持 E2EE）
• BlueBubbles (iMessage)，通過自託管 Mac 橋接 iMessage
• WhatsApp，Meta Cloud API；僅發送，收件人須為 E.164 格式

最簡方式：直接告訴 Minara

配置消息通道最快的方式是在對話中告訴 Minara。Agent 會引導你完成憑證配置、發送測試消息，並將配置保存到 ~/.minara/credentials.json（messaging 槽）。

set up Telegram notifications — I want trade alerts

connect Slack to channel #trades using my bot token

configure email alerts — I'll give you the SMTP settings

send me a test message on Telegram to make sure it works

what notification channels are configured right now?

turn off the discord gateway, I'm not using it anymore

when ETH breaks $4000, alert me on Telegram

最後一條提示詞會讓 Minara 建立後臺工作流，使用已配置的消息通道發送告警。Agent 一步完成告警條件、通道和工具集白名單的配置。

Minara 在保存前會確認憑證寫入（修改 ~/.minara/credentials.json 屬於第三級操作），回顯時脫敏處理，並在通道配置完成後自動發送測試消息。

手動配置

以下三個入口共享同一配置存儲，均支持熱重載；任何改動無需重啟即可生效。

通過 Shell（minara auth messaging）

minara auth messaging list                     # show configured providers
minara auth messaging add                      # interactive picker, all 19 platforms
minara auth messaging add <provider>           # interactive wizard, masks tokens
minara auth messaging test <provider>          # send a test message
minara auth messaging remove <provider>        # strip credentials

不帶 provider id 運行 minara auth messaging add 會進入交互菜單，列出全部支持平臺，顯示已配置項，並引導你完成所選平臺的憑證配置。保存後可發送 ping 測試、配置其他平臺或退出。完整流程見 CLI 子命令。

在 REPL 中（/connect）

/connect                       # numbered chooser
/connect telegram              # interactive credential entry
/connect slack --test          # test ping
/connect telegram --remove     # wipe credentials

當對話進行到一半才意識到需要接入某個平臺時，斜槓命令是最合適的入口。可選字段留空時自動跳過；重新配置時每個已有字段會顯示 (currently set, blank to keep)。斜槓命令的 token 輸入當前明文顯示（CLI 子命令會脫敏）；對於敏感憑證，建議使用 CLI 或在 shell rc 中設置環境變量。

在 Web UI 中（Settings → Messaging）

Web UI 在單一面板中展示所有提供方：

• 每個提供方的狀態標籤（runtime ready / configured / not connected / coming soon）。
• 每行的 Save / Test / Disconnect 按鈕。
• 點擊 Test 按鈕會發送真實 ping；消息會出現在 IM / 郵件客戶端中，行標籤自動變為 last test ✓。
• 輸入框留空後點擊 Save 會清除該字段（與常規設置表單的 Save = 清除語義一致）。可用此方式將 Slack 從 bot-token 模式切換為 webhook-only 模式，無需執行 --remove。

憑證存儲在 ~/.minara/credentials.json（權限 0600，已加入 git ignore），重裝後仍可保留，不會洩漏到代碼倉庫。三個入口寫入後均會熱重載運行中 Agent 的網關映射，無需重啟進程。

工作流：send_message 步驟類型

工作流可將消息發送作為一等步驟類型，而不必通過 tool_call: send_message 形式：

{
  "name": "notify_team",
  "kind": "send_message",
  "provider": "slack",
  "channel": "#alerts",
  "text": "BTC crossed ${trigger.threshold}"
}

調度時的提供方解析順序：

1. step.provider（單步顯式指定）。
2. definition.delivery.provider（工作流級默認值）。
3. 恰好只有一個已連接提供方時，自動使用該提供方。
4. 否則，激活拒絕，返回結構化錯誤，提示前往 /connect <platform>（REPL）或 Settings → Messaging（Web UI）。

激活檢查獨立於 Autopilot 開關。發送通知不涉及資金操作，因此 autopilotEnabled=false 時工作流同樣可激活並正常運行。定時消息和 Autopilot 自身的成功通知也遵循同樣的獨立邏輯。

當目標平臺未連接導致激活失敗時，Web UI 會彈出模態框，提供一鍵 Connect <provider> 按鈕，跳轉到 Settings → Messaging 並展開對應行；保存後頁面自動返回工作流並重試激活。

用 workflow_test 驗證消息工作流

workflow_test 是端到端驗證新平臺配置的推薦方式。它用示例觸發器運行 DAG，並通過與生產相同的通道發送一條真實消息，讓你在啟用工作流前先確認告警能到達手機。若目標提供方未連接，測試會拒絕並返回結構化 messaging_not_configured 錯誤，提示前往 /connect <provider>（REPL）或 Settings → Messaging（Web UI）。同一工作流中涉及資金及其他破壞性操作的工具仍為模擬執行，僅消息步驟實際發送。完整流程見工作流頁的"在部署前本地測試工作流"一節。

一次性提醒

對於"滿足條件 X 後通知一次即停止"的工作流，在 send_message 後追加 deactivate 步驟。工作流發送完成後會將自身 active 置為 false，觸發器不再重複觸發。完整 JSON 模板見工作流頁的"一次性提醒"一節。

能力矩陣

所有平臺均支持純文本發送，這是基準能力，矩陣不單獨標註。下列各列描述疊加在基準之上的高級能力。

圖例：✅ 當前版本已支持，❌ 平臺本身不支持，未接入 = 尚未實現（後續 PR 跟進）。Slack 的輸入狀態列為空，因為現代 Slack Web / Events API 不提供 bot 輸入觸發接口（原 RTM API 已廢棄）。

"富文本"指超出共享文本及附件能力的平臺原生富消息發佈。目前已支持 Slack Block Kit、臨時消息（chat.postEphemeral）、定時消息（chat.scheduleMessage），以及通過 send_message 上的 provider_options.slack 通道傳入的 metadata。其他提供方或無對應能力（WhatsApp / Signal / HomeAssistant / webhook 模式 Slack），或尚未接入（Telegram 內聯鍵盤迴復標記、Discord 組件、郵件 HTML 正文）。具體 API 見 slack 頁面。

Slack 集成模式。 矩陣展示推薦的 bot-token 模式，可使用完整 Slack Web API，包括 chat.postMessage、chat.update、files.v2、reactions.add 及 Events API webhook。Minara 同時支持更簡單的 webhook-URL 模式，適用於無法安裝 Slack 應用的部署場景。該模式能力較窄（不支持流式、文件上傳、表情回應、輸入狀態、臨時消息及定時消息），但仍支持純文本、Block Kit blocks 和話題回覆。兩種配置路徑及各模式能力對比見 Slack 頁面。

Home Assistant 所有列均為 ❌，原因類似：其 notify.<service> API 在所有已調研的具體 notify 平臺上均為純文本接收器。如需附加圖片，可將其上傳至 CDN，在消息正文中附上 URL。

"流式"指 Agent 逐 token 的響應以單條消息展示，通過原地編輯持續更新。不支持流式的平臺會緩衝完整響應，在最終完成時一次性發送，通過 apps/agent/src/messaging/stream-helpers.ts 中的共享輔助函數 createStreamSink 實現。

附件

send_message({attachments: [...]}) 可附加 Agent 在沙盒內生成的圖片、文檔或語音（通過 image_generate、audio_generate、write_file、代碼執行等）。LLM 通過沙盒相對路徑引用這些文件：

send_message({
  provider: "telegram",
  text: "BTC/USD daily with key levels",
  attachments: [
    { kind: "image", sandbox_path: "images/btc-2026-04-19.png" },
    { kind: "file", sandbox_path: "files/levels.csv", caption: "CSV of levels" },
  ],
})

附件類型：

• image：圖片。路由到平臺的圖片專用接口（Telegram sendPhoto、WhatsApp image 等）。
• file：通用文檔附件，適用於 PDF、CSV、壓縮包。
• voice：短語音。Telegram 要求 OGG/Opus 格式；發送非 OGG 格式時解析器會返回明確錯誤。
• audio：音樂 / 播客 / 長音頻。Telegram 使用 sendAudio；對於無獨立語音界面的平臺，處理方式與 voice 相同。

安全策略：

• 僅接受沙盒路徑。解析器在上傳前會拒絕 .. 路徑穿越、絕對路徑和指向沙盒外的符號鏈接，攻擊者無法將 send_message 用作數據滲出通道。
• 單附件上限 50 MB（可通過 MESSAGING_MAX_ATTACHMENT_BYTES 調整）。提供方 API 會獨立執行各自的大小限制。
• 提供方支持受能力門控：若所選提供方不支持某 kind（如向 WhatsApp 發送 voice），工具邊界會返回明確錯誤，而非在 API 層返回 400。

話題

向 send_message 傳入 thread 可發送到話題對話：

send_message({
  provider: "slack",
  text: "follow-up",
  thread: "1700000000.000100",  // parent message's ts
})

各提供方語義（自動處理，調用方只需傳入 thread）：

• Telegram：message_thread_id，用於論壇話題（超級群組及私聊）。
• Discord：話題即頻道，話題 id 替換 URL 中的頻道 id，適用於活躍和歸檔話題。
• Slack：thread_ts，即父消息的時間戳。僅 bot 模式支持（webhook 模式會被拒絕）。
• Email：該值同時寫入 In-Reply-To 和 References 頭部。傳入父郵件的 Message-ID（通常帶尖括號，如 <abc@host>）。

不支持話題的提供方（whatsapp、signal、home_assistant）在傳入 thread 時，工具邊界會返回明確錯誤。

輸入狀態與表情回應

set_typing 和 add_reaction 是兩個額外工具，用於對話內的即時反饋。權限等級為第二級 CONFIRM_ONCE（裝飾性信號，不涉及數據出站），獨立於 send_message 的第三級確認。

// Let the user know the bot is thinking before a long reply.
set_typing({ provider: "telegram", on: true })

// Acknowledge an inbound message with an emoji instead of composing text.
add_reaction({
  provider: "discord",
  message_id: "1234567890",
  emoji: "👍",
})

輸入狀態持續性：Telegram 和 Discord 的指示約 5～10 秒後過期。apps/agent/src/messaging/typing-heartbeat.ts 中的 typing-heartbeat 輔助函數會自動續發，可在長輪次 LLM 響應期間保持"正在輸入……"狀態。

能力支持（見上方矩陣）：輸入狀態支持 telegram / discord / signal；表情回應支持 discord / slack（bot 模式）/ signal。其他提供方在工具邊界拒絕這兩個操作。

入站消息：雙向對話

Minara 也能接收消息並回復，因此你可以直接在聊天應用裡與 Agent 對話，而不必使用 CLI。消息抵達 Agent 有兩種方式，平臺採用哪一種，決定了在沒有公網 IP 的機器上能否進行雙向對話。

客戶端外連 daemon（默認）

對多數平臺，Agent 主動向外建立並保持一條長連接（HTTP 長輪詢或 WebSocket），消息順著這條連接推送下來。Agent 充當客戶端，因此在 NAT 之後、個人筆記本上、沒有公網地址、沒有隧道、沒有第三方的情況下都能工作。這是默認行為：當平臺的出站憑據已配置且未為其配置公網 webhook 時，對應 daemon 會自動啟動。可用 MESSAGING_<PLATFORM>_* 開關按平臺覆蓋（見 環境變量）；開關為三態（留空 = 自動，1 = 強制開啟，0 = 強制關閉）。

具備客戶端外連 daemon 的平臺：Telegram（getUpdates）、Discord（Gateway）、Slack（Socket Mode）、Mattermost（v4 WebSocket）、QQ（v2 網關）、DingTalk（Stream Mode）、Lark（長連接），以及 Matrix（/sync）和 Signal（signal-cli）。

Webhook 監聽器（平臺要求時）

部分平臺只能通過向公網 HTTPS 端點 POST 來投遞入站消息。對這些平臺，Minara 運行一個 HTTP webhook 服務器（見 apps/agent/src/messaging/inbound/server.ts），由 MESSAGING_INBOUND_ENABLED 控制。它默認綁定 127.0.0.1，因此沒有公網 IP 的主機需要一個反向代理或隧道來終止 TLS 並轉發請求。為某個平臺設置 webhook 簽名密鑰，會讓該平臺切回 webhook 入站，daemon 隨之讓位。

安全策略：

• 每個請求在分發前都經過簽名驗證（Telegram 的 X-Telegram-Bot-Api-Secret-Token、Slack 的 HMAC-SHA256（v0:{ts}:{body}）、Discord 與 QQ 的 Ed25519、Lark 的 AES 信封、Teams 與 Google Chat 的 JWT）。無法驗證的請求返回 401。
• 帶時間戳方案設有 5 分鐘重放窗口。
• 請求體大小上限（默認 4 MB），超出返回 413。

可達性：哪些平臺可完全本地運行

Google Chat（Cloud Pub/Sub 拉取）和 BlueBubbles（連接到自託管服務器的 socket）也可改為客戶端外連；目前它們仍以 webhook 入站方式發佈。

語音轉寫：配置 MESSAGING_INBOUND_TRANSCRIBE=1 且設置 OPENAI_API_KEY 後，入站語音消息會通過 OpenAI Whisper 轉寫後再分發。轉寫結果寫入 InboundMessage.text，原始音頻保留在 attachments 供回放。

Minara 如何使用消息通知

配置好提供方後，以下三種路徑可向其發送消息：

1. send_message 工具：從 Agent 內部調用

LLM 判斷需要發送通知時，會調用：

send_message({
  provider: "telegram",
  text: "BTC drawdown 5% triggered the watch",
})

Agent 在對話中途即可觸發。例如"當 ETH 突破 4000 美元時在 Telegram 提醒我"會建立定時工作流，條件觸發時調用 send_message。

2. 自主交易：交易執行報告

Autopilot 啟用後，每次執行完成會發送摘要：

🟢 Bought $100 of SOL @ $167.23
   Position: +$100 | Slippage: 0.04% | Gas: $0.12
   Reason: momentum > 3σ on 1h chart

消息發送至 ~/.minara/settings.json 中配置的默認通知目標提供方。

3. 工作流：定時告警

定時監控以只讀加消息權限在後臺運行：

you: watch the top 20 tokens by 24h volume, alert me on >5% moves every 15 min

agent: [sets up a cron workflow with tool set "read, memory, messaging"]

工作流只能觀察和通知。白名單會阻止交易操作，LLM 在運行途中改變決策也無法繞過。

覆蓋目標通道

send_message 接受 channel 覆蓋參數，一個提供方可扇出到多個目標：

send_message({
  provider: "telegram",
  channel: "-1009876543210",    // different chat from the default
  text: "Critical: position liquidation imminent",
})

適合將緊急告警路由到獨立手機或群組，同時保持常規通知在默認通道。

安全策略

• 憑證存儲在 ~/.minara/credentials.json，位於代碼倉庫和項目目錄之外
• minara auth messaging list 會脫敏顯示密鑰，格式為 12***xyz (46 chars)，不顯示原始 token
• 消息發送屬於第三級操作（ALWAYS_CONFIRM），交互式調用時每次 send_message 均會提示確認。自主輪次（cron / autopilot）僅在 safetyConfig.autopilotEnabled 已設置時才可執行第三級工具，否則該路徑下消息發送會被拒絕。通過 minara auth messaging add 寫入憑證的操作在交互向導內完成（無需單獨的工具級確認提示，嚮導本身即確認流程）
• 消息通知無法執行交易。工具集白名單將"可查看和通知"與"可交易"嚴格分離；就算 LLM 嘗試調用涉及資金的工具，消息啟用型工作流也不具備該能力

下一步

從上方選擇一個平臺，按步驟完成配置。Telegram 最為簡便，配置環節最少，流式網關經過充分驗證，完整測試流程（/newbot → 獲取 chat id → minara auth messaging test telegram）三分鐘內即可完成。