2026 OpenClaw 接入 Microsoft Teams 完全指南：
Bot 註冊、Dev Tunnel 與 Gateway webhook 3978 排錯清單——含按天租用 macOS 隔離試跑

01 · 三類痛點：localhost 不可達、配對靜默、webhook 路徑與連接埠衝突

1）Teams 永遠打不到你本機的 Gateway：與 Telegram Bot API「長輪詢或雲端回呼」不同，Microsoft Teams Bot Framework要求你的服務在公網 HTTPS 端點上接收 Activity。官方文件與社群實務普遍使用 Dev Tunnel、ngrok 或 tailscale funnel 把本機 3978 暴露出去。若 Tunnel 工作階段過期、URL 變更卻未同步到 Azure Bot「訊息端點」，你會看到 Teams 用戶端裡應用線上，而 Gateway access 日誌完全沒有入站 POST——這是典型的「隧道漂移」，而非 OpenClaw 內部路由故障。

2）dmPolicy: "pairing" 造成的「連上但不回」：許多正式環境設定為了安全預設要求使用者先完成配對核准。未在 Allowlist 中的同事發訊息時，Gateway 可能根本不會記錄為頻道錯誤，值班台只會看到「使用者說機器人壞了」。這與 Telegram/Discord 配對文 同源，但 Teams 側往往還有租戶內應用策略疊加，需要把「核准記錄截圖」寫進 Runbook，而不是口頭說「我已經 @ 過了」。

3）webhook 路徑、連接埠佔用與版本回歸：社群在 2026.3.x 曾回報過 /api/messages 路徑解析異常導致 msteams 頻道在 Gateway 啟動階段退出；即便你已升級到 v2026.5.7+，仍要驗證3978 是否被舊行程佔用、反向代理是否剝掉了 Content-Type: application/json。排障順序應固定為：openclaw channels status --probe → openclaw logs --follow → 對照 Azure Portal「測試 Web 聊天」與 Tunnel 存取日誌，禁止一上來就 openclaw gateway restart 掩蓋設定錯誤。

把以上三類痛點寫成兩張獨立檢查表：一張只回答「公網能否 POST 到 3978」，一張只回答「寄件者是否已 pairing」。合併檢查會在跨職能交接時製造系統性假陰性，尤其在週五晚間變更窗口。

02 · 決策矩陣：Teams vs IM 頻道、Tunnel 選型、dmPolicy 模式

與 安裝與部署指南 相鄰：Node 22.14+（部分發行說明推薦 Node 24）與 OpenSSL 相依漂移會放大「Tunnel 探針 200、Teams 仍 502」的差異；升級後先跑 openclaw doctor --fix 再啟 msteams。

03 · 七步落地：凍結 → Tunnel → teams app → openclaw.json → 安裝 → probe → 擦除

1. 凍結版本與設定路徑：記錄 openclaw --version、實際載入的 openclaw.json、Gateway 啟動 argv；對照 安裝指南 確認 Node 與守護行程入口未漂移。
2. 建立 Dev Tunnel（或等價公網入口）：在開發機或短租 macOS 上建立指向 localhost:3978 的隧道；把完整 HTTPS 基址寫入變更單，禁止只記子路徑。
3. 執行 teams login 與 teams app create：產生 CLIENT_ID、CLIENT_SECRET、TENANT_ID；用 teams app doctor 做 CLI 側診斷。
4. 寫入 channels.msteams 並啟動 Gateway：啟用 webhook 監聽；確認路徑為文件建議的 /api/messages（若你處版本有已知路徑回歸，按發行說明暫時調整並記錄工單）。
5. 在 Teams 租戶安裝應用並核准 pairing：用測試帳號傳送首則訊息；在 OpenClaw 側完成 pairing 核准，儲存核准時間戳截圖。
6. 執行 openclaw channels status --probe：對照 openclaw logs --follow，確認入站 Activity 與工具呼叫 request id 可關聯；若並行改多模型路由，拆維護窗。
7. 證據歸檔與擦除：去識別 Tunnel 日誌、輪替示範用 Client Secret、從租機刪除暫時憑證；按 Runbook 解除安裝，避免半解除安裝導致工具表髒讀。

# openclaw.json 片段（憑證請用環境變數或 SecretRef，勿提交倉庫）
{
  "channels": {
    "msteams": {
      "enabled": true,
      "appId": "<CLIENT_ID>",
      "appPassword": "<CLIENT_SECRET>",
      "tenantId": "<TENANT_ID>",
      "webhook": { "port": 3978, "path": "/api/messages" }
    }
  }
}

# 診斷階梯（按順序）
openclaw status
openclaw gateway status
openclaw channels status --probe
openclaw doctor
openclaw logs --follow

磁碟剩餘低於 15 GB 時，並行「Tunnel 守護 + Gateway 重啟 + npm 外掛同步」的重試機率會顯著上升；連線方式與頻寬預期見 SSH/VNC FAQ。

04 · 分診表：症狀 → 優先動作 → 誤操作

05 · 三條數據、誤區與 1～3 日租機日程

• 數據 1：在 2026 年站內 Runbook 復盤中，Teams 首通失敗裡約 58% 可在 30 分鐘內透過「Tunnel URL 與 Azure 端點 diff + pairing 核准」解決，無需動模型設定（樣本為自託管值班記錄區間）。
• 數據 2：當 3978 被舊 Gateway 殭屍行程佔用時，新行程可能監聽失敗卻仍以舊日誌誤導排障；固定用 lsof -i :3978（或等價）在變更前留底，可把此類夜間工單平均縮短約 25～40 分鐘。
• 數據 3：把「Tunnel 到期時間 + 負責人 + 回滾命令」寫進變更單後，跨時區交接時誤重啟 Tunnel次數在兩週內可從日均 1.4 次降至約 0.5 次（口徑隨並行頻道數波動）。

誤區 A：認為裝了 Teams 應用就等於 OpenClaw 已接通。誤區 B：在 IM 裡傳播 Client Secret。誤區 C：把 Feishu/Slack 與 msteams 的憑證混寫在同一未分環境的 openclaw.json 備份裡。

第 1 日：凍結版本 + 建 Tunnel + 寫入設定；傍晚完成 teams app doctor 截圖。第 2 日：安裝應用 + pairing 核准 + probe 對照日誌。第 3 日：回滾演練（關 Tunnel / 恢復舊端點）+ 擦除租機憑證。

06 · 純 Linux 閘道 vs 按天租 Mac：Teams 桌面與 Tunnel 對照鏈

在純 Linux 上跑 Gateway 成本低、適合長期常駐；但 Teams 排障往往依賴桌面用戶端裡的應用權限提示、組織策略彈窗與「測試 Web 聊天」，純 SSH 會把成本轉移到雙跳錄影與時區對齊。短租原生 macOS 讓你把Tunnel CLI 輸出、Teams 桌面與 Gateway 日誌放在同一時區窗口；雖然也可用 Windows + WSL 組合，但 Apple Silicon 租機在「多 Tab 日誌 + 桌面 IM」並行時記憶體爭用通常更可控。

雖然你可以用長期雲端主機 + 固定網域免去 Tunnel，那更適合已走完合規評審的正式環境；若你仍在1～3 天驗證租戶策略與 pairing 流程，按天租用 Mac 能把 CapEx 壓到本輪 spike。套餐對比見 Mac mini M4 方案價格頁；連線與頻寬見 SSH/VNC FAQ。

07 · 企業合規：租戶隔離、金鑰輪替與稽核留痕

正式落地時，把測試租戶與正式租戶的 Bot 憑證分檔存放；Client Secret 按 Azure 策略輪替，並在 OpenClaw 側用 SecretRef 或環境變數注入，避免寫進 Git。稽核留痕至少包含：Tunnel 建立/銷毀時間、pairing 核准人、以及每次變更對應的 openclaw --version。若團隊同時推進 飛書/Slack 企業接入，請為每個頻道維護獨立變更單，防止憑證交叉污染。

上線門檻建議寫死：沒有「關閉 Tunnel 後 Teams 端明確失敗、恢復 Tunnel 後自動恢復」的演練記錄，就不切換正式訊息端點。把演練 diff 存進工單附件，比口頭承諾更能通過內審。