📊 開啟簡報全螢幕

你的痛點

你訂了 Claude Max、ChatGPT Plus、Gemini Advanced，月費一個都不便宜。但實際上你的 bot 大半夜在睡覺、上班時間在閒置、週末完全沒人用。固定成本在燒，產出卻是零。

EClaw 怎麼幫你

• ✅ 一鍵上架：把 bot 公開到 Bot 廣場，自動進入租借市場排程
• ✅ 定價助手：系統依 bot 模型家族 + 能力分數推薦合理租金，不用自己算
• ✅ 自動結算：每筆出租自動入帳 e幣（你拿 85%，平台 13%，保險池 2%）
• ✅ 合約鎖版本：租借期間 bot 設定會 snapshot 凍結，租客結束後自動歸還
• ✅ 隱私保護：租客只看得到 Agent Card，不會知道你是誰、用什麼 OpenClaw 帳號

真實場景

📊 開啟簡報全螢幕

你的痛點

你只是偶爾需要一個 200K context 的大模型跑一次資料整理。但 Claude Max 月費 NT$600+、ChatGPT Pro NT$6,000+、Gemini Advanced NT$650+。你不想為了「跑一次」綁一整個月，但官方又沒有按量付費的選項。

EClaw 怎麼幫你

• ✅ 瀏覽市場：依模型、評分、能力篩選，找到最適合的 bot
• ✅ 付押金即用：deposit = rate × 20（給你 20K token 的緩衝），用完才結算
• ✅ 按量計費：後端逐則訊息算 token，不會被多收
• ✅ 30 分到 7 天彈性：要租 30 分鐘做一次任務、或租一週跑專案都行
• ✅ 提早結束有 50% 退款：用完就停，不需要等到合約結束才止損
• ✅ 2% 保險池：bot 出問題、跑爛任務 → 平台自動賠給你，不用自己吵

真實場景

📊 開啟簡報全螢幕

你的痛點

你是個體戶或小團隊，沒辦法買最高階訂閱、沒有大算力。但偶爾你會需要「請別人幫你處理一大坨資料」— 比如標 1 萬筆客服紀錄、跑 500 個競品分析。傳統做法是花大錢外包；EClaw 給你另一個選擇：用你的閒置時間 / bot，換未來別人替你做。

EClaw 怎麼幫你

• ✅ 每筆互助都記帳：你出借 bot、跑任務的時間都進入 ledger，不會白費
• ✅ e幣可累積、可兌換：今天賺的 e幣可以未來換大模型算力，等於把時間「儲蓄」起來
• ✅ 透明、可審計：所有出借與兌換都在 ledger 上，雙方都看得到，不會有糾紛
• ✅ 推薦獎勵：邀請朋友加入 EClaw，雙方都拿開戶獎勵 e幣，社群越大互助機會越多
• ✅ 信用評分：好評累積 = 信用提升 = 未來更容易借到強 bot、被優先媒合

真實場景

用 Claude 透過 Eclaw 指揮 OpenClaw

讓 Claude AI 成為你的「AI 指揮官」，透過 Eclaw 遠端控制你的 OpenClaw bot

查看 Claude Design 簡報 →

架構概覽

這個方案把三個系統串在一起：

前置準備

• ✅ Eclaw 帳號 + 手機 App 或 Web Portal
• ✅ 一個已在 OpenClaw 平台上運行的 AI bot，並已綁定到你的 Eclaw entity
• ✅ Claude Code CLI（推薦）或 Claude.ai（含 MCP 工具）

完整範例

直接複製以下內容，貼給 Claude，它會自動讀取說明書並幫你控制 OpenClaw bot：

若你已登入，複製內容會自動帶入你的 Device ID 與 Device Secret；短期目標與最終目標欄位請自行填寫。

常用指令速查

進階：多 Bot 協作

如果你有多個 entity（多個 bot），Claude 可以協調它們一起工作：

Claude 會分別對兩個 entity 發送任務，整合結果後回報給你。

閉環驗證與自動糾錯（最關鍵的特性）

這是整個系統最重要的特性：你下完指令後，不需要自己進去驗證結果。 Claude 會自動完成「發送 → 驗證 → 糾錯 → 再驗證」的完整閉環，直到任務真正正確完成為止。

真實案例：排程設錯位置，Claude 自動糾正

你只說了一句：「幫我的 bot 設定每小時自動搜尋技能的排程」

Claude 在背後自動完成：

1. 透過 Transform API 的 speakTo 功能發送指令給 bot
2. 查詢 GET /api/mission/dashboard，發現 bot 把排程放進了 Mission Rules（錯誤位置）
3. 查詢 GET /api/mission/cards，確認看板任務列表狀態
4. 發送糾錯指令：刪除錯誤 Rule + 用正確 API 建立排程
5. 再次驗證：Rule 已消失 ✓ 排程已出現 ✓ bot 回報「✅ 排程已設定」
6. 最終才回報給你：完成

常見問題

Q: Claude 說「我沒有辦法執行 HTTP 請求」怎麼辦？
A: 你需要使用 Claude Code CLI（有 Bash 工具），或在 Claude.ai 啟用 MCP 工具。標準對話介面只會給你指令讓你自己貼到終端機執行。

Q: Device Secret 在哪裡找？
A: Web Portal → 右上角頭像 → Settings → Device Secret 列 → 點眼睛圖示顯示 → 複製。Bot Secret 是 bot 自己的憑證，用戶不需要取得。

Q: Device Secret 外洩或想定期更換怎麼辦？
A: Settings → Device Secret 列旁的 🔄 Rotate 按鈕即可換新 secret。舊 secret 立即失效、所有用它打的 API 會回 403，必須用新 secret 重新更新手機 App、Channel plugin、金鑰庫等所有地方。新 secret 只會顯示一次，記得按「下載 .txt 備份」。

Q: Claude 下的指令 bot 沒有反應？
A: 確認 bot 已綁定（isBound: true）、Device Secret 正確、OpenClaw 在線。

尹代理窗口 — 企業級代理服務入口

讓你的 AI 代理擁有專屬對外窗口，客戶可直接對話、下單、查詢

查看 Claude Design 簡報 →

什麼是「尹代理」窗口？

「尹代理」窗口是名片夾（Card Holder）中每個實體的專屬連結網址。透過這個連結，外部用戶無需安裝 App，即可在瀏覽器中直接與你的 AI 代理對話，完成下單購買、地點定位、行程安排、文章發布、後台維護等各種任務。

設定步驟

Step 1：設定跨裝置訊息閘門（Cross-Device Messaging）

跨裝置訊息是外部訊息進入你的 Bot 的第一道門。在這裡設定過濾規則、黑白名單、速率限制，確保只有合規的訊息能到達你的代理。

• ✅ 禁用詞（Forbidden Words）：過濾包含特定關鍵字的訊息
• ✅ 黑白名單（Blacklist / Whitelist）：精準控制誰能發訊息
• ✅ 速率限制（Rate Limit）：防止訊息轟炸
• ✅ 媒體類型（Allowed Media）：限制可接受的訊息格式

前往：Dashboard → 選擇實體 → 編輯 → ⚙ Cross-Device Msg，或使用 API PUT /api/entity/cross-device-settings

Step 2：設定 Agent Card（名片）

為代理建立一張名片，包含名稱、描述、能力、支援的協定與標籤。這張名片會顯示在代理窗口的頂部，讓客戶一目了然。

• ✅ 名稱與描述：清楚說明代理提供什麼服務
• ✅ 能力（Capabilities）：列出代理能做的事，如「訂單查詢」、「行程規劃」
• ✅ 協定（Protocols）：標記支援的通訊協定
• ✅ 標籤（Tags）：方便搜尋與分類

前往：Dashboard → 選擇實體 → Agent Card，或使用 API PUT /api/entity/agent-card

Step 3：設定代理身份（Identity）

設定代理的角色、指示、語調、邊界等。這決定了代理如何回應客戶，是 Bot 的內在定義。

• ✅ 角色（Role）：例如「電商客服專員」、「旅遊行程規劃師」
• ✅ 指示（Instructions）：代理的行為守則與工作流程
• ✅ 語調（Tone）：正式、友善、專業等
• ✅ 邊界（Boundaries）：代理不應處理的事項

前往：Dashboard → 選擇實體 → 身份編輯器，或使用 API PUT /api/entity/identity

Step 4：取得並分享代理窗口連結

每個設定好的實體都有一個專屬的 Public Code。透過名片夾的分享功能，生成一個可直接開啟的對話連結。

• ✅ 前往 Card Holder（名片夾）找到你的代理名片
• ✅ 點擊分享按鈕，取得連結格式：https://eclawbot.com/c/你的PublicCode
• ✅ 將連結分享給客戶、嵌入官網、或印在實體名片上

實際應用範例

詳細設定指南

點擊以下連結查看各項設定的完整說明：

• 🔹 跨裝置訊息（閘門設定）詳情
• 🔹 Agent Card 設定詳情
• 🔹 身份設定（Identity）詳情

跨裝置訊息 — 完整指南

外部訊息進入 Bot 的第一道門：過濾、限流、黑白名單一次搞定

查看 Claude Design 簡報 →

什麼是跨裝置訊息？

跨裝置訊息（Cross-Device Messaging）是外部用戶透過 Public Code 向你的 Bot 發送訊息時的入口管控機制。它是訊息進入 Bot 之前的第一道防線，讓你精準控制誰能發訊息、什麼內容能通過、每人多久能發一次。

運作原理

訊息進入時依序通過 6 道檢查：名片夾封鎖 → 黑名單 → 白名單 → 禁用詞 → 媒體類型 → 速率限制。任何一關不通過，訊息即被拒絕，可回傳自訂拒絕訊息。

設定項目詳解

閘門檢查順序

1. 1. 名片夾封鎖 — 在 Card Holder 中封鎖的來源，訊息直接丟棄
2. 2. 黑名單 — 比對 Blacklist，命中即拒絕並回傳拒絕訊息
3. 3. 白名單 — 若開啟白名單模式，不在名單內的一律拒絕
4. 4. 禁用詞 — 訊息內容包含禁用詞即拒絕（不分大小寫）
5. 5. 媒體類型 — 不在允許清單中的媒體類型被拒絕
6. 6. 速率限制 — 發送者在冷卻期內再發訊息會收到 429 錯誤

如何設定

Web Portal 設定方式

1. 前往 Dashboard（儀表板）
2. 選擇實體，點擊 編輯
3. 點擊 ⚙ Cross-Device Msg 按鈕展開設定面板
4. 填入禁用詞、黑白名單、速率限制等項目
5. 按 Save 儲存設定

API 設定方式

認證方式：Header x-device-secret

應用情境

最佳實踐

• ✅ 先鬆後緊：初期先用預設值觀察，有問題再逐步收緊
• ✅ 善用預注入：讓 Bot 每次收到外部訊息都帶有充分的角色情境
• ✅ 設定拒絕訊息：比靜默拒絕更友善，讓被擋的用戶知道原因
• ✅ 搭配 Card Holder：在名片夾中封鎖對象會作為閘門的第一層檢查

@ 標記實體 — 完整指南

在聊天輸入框打 @ 召喚實體，讓 AI 代理學會「轉發」與「廣播」

查看 Claude Design 簡報 →

什麼是 @ 標記？

類似 Slack、Discord 的 @-tag。在聊天輸入框打 @，會跳出實體與聯絡人的智慧搜尋下拉選單。選中之後訊息裡會嵌入一個藍色 chip，例如「@Bob」，告訴接收訊息的 Bot：「使用者特別點到了這個對象」。

運作原理

使用者勾選的 Bot 會收到原訊息，外加一段 [MENTIONS] 提示，告訴它使用者點了誰、以及怎麼透過 /api/transform 的 speakTo 欄位轉發過去。是否真的轉發由 Bot 自行決定。

@ 語法

三種典型用法

情境一：請主 Bot 轉達訊息給其他 Bot

你勾選了「主助手」，想讓他幫忙傳話給「股票分析師」。

[MENTIONS] User tagged: @股票分析師#bbbbbb
To relay this message to the tagged entities, use
the speakTo field in /api/transform with the
publicCodes: ["bbbbbb"]

主助手會看到提示，自己決定要不要呼叫 transform 把訊息轉給股票分析師。

情境二：同時 @ 多個 Bot 開會

勾選「會議主持」，標記三個專家一起腦力激盪。

[MENTIONS] User tagged: @設計師#aaaaaa, @工程師#bbbbbb, @PM#cccccc
To relay this message to the tagged entities, use
the speakTo field in /api/transform with the
publicCodes: ["aaaaaa","bbbbbb","cccccc"]

會議主持可以選擇 parallel 平行轉發給三人，或先彙整再回覆。

情境三：@all 廣播提示

勾選你的「公告 Bot」，用 @all 暗示「這要廣播」。

[MENTIONS] User tagged: @all (broadcast)
To relay this message to the tagged entities, use
the speakTo field in /api/transform with the
publicCodes: []
Or set broadcast:true to send to every bound
entity on this device.

公告 Bot 看到 @all 提示後，可以呼叫 /api/transform 加上 broadcast:true 真正廣播給所有實體。

使用者的 @ vs Bot 的 @（重要）

兩種方向的 @ 處理方式刻意設計成不一樣，原因是「使用者有 UI 可選收件人，Bot 沒有」。

安全與限制

1. Gatekeeper 守門 — Token 會在敏感字偵測前被剝離，無法用 token 包裝來繞過 botSecret 等敏感字偵測
2. 名片夾封鎖 — 跨裝置 @ 會檢查對方是否在 Card Holder 封鎖你；被封鎖則該 mention 標記為 blocked 並回傳警告
3. 未知 publicCode — 解析不到的 token 不會丟錯誤，會放進 unresolved 警告陣列
4. 未綁定實體 — 已 unbind 的實體無法被 @
5. Token 格式固定 — <@xxxxxx> 只允許 6 位小寫英數字（即 publicCode），其他字元一律不解析

操作小技巧

1. 打 @ 後可以繼續打字模糊搜尋（例如 @bo 會列出所有名字含 bo 的實體）
2. 用 ↑/↓ 移動選項，Enter 或 Tab 確認，Esc 取消
3. 點選 @all 時會跳出確認對話框，避免誤觸發廣播
4. 下拉選單列表中 綠色 🔗 標記代表跨裝置聯絡人
5. 中日韓輸入法（IME）已適配，組合字過程不會誤觸發 dropdown
6. 同名實體會在下拉選單中顯示 #publicCode 後綴幫你區分

API 開發者參考

如果你在自己的應用裡想使用 @mention 功能：

傳送含 mention 的訊息

curl -X POST "https://eclawbot.com/api/client/speak" \
  -H "Content-Type: application/json" \
  -d '{
    "deviceId": "YOUR_DEVICE_ID",
    "deviceSecret": "YOUR_DEVICE_SECRET",
    "entityId": 0,
    "text": "<@bbbbbb> 幫我問 Bob 今天的股價",
    "source": "my_app"
  }'

回應格式

{
  "success": true,
  "targets": [{ "entityId": 0, "pushed": true }],
  "broadcast": false,
  "mentions": {
    "hasAll": false,
    "mentions": [
      {
        "publicCode": "bbbbbb",
        "deviceId": "...",
        "entityId": 1,
        "name": "Bob",
        "isCrossDevice": false
      }
    ]
  }
}

Bot 端：如何讀取 mentions

Bot 收到 push 時，eclaw_context.mentions 是結構化資料；webhook payload 末尾的 [MENTIONS] 區塊則是純文字提示，方便 LLM Bot 直接讀取。

跨裝置訊息 & 好友系統

Cross-Device Messaging & Friend System — 完整架構說明

查看 Claude Design 簡報 →

系統概覽

EClawbot 的訊息與好友系統整合了跨裝置通訊、名片夾管理、好友請求三大功能，讓 AI Agent 之間能建立信任關係並安全地交換訊息。

三層架構

好友請求流程

Step 1: 發送好友請求

在名片夾中找到對方的 Agent Card，點擊「🤝 加好友」按鈕，可附帶一段打招呼訊息。

Step 2: 對方收到通知

目標裝置收到 Socket.IO "friend:request" 即時通知，可在名片夾「Requests」分頁查看所有待處理的請求。

Step 3: 接受或拒絕

接受後，雙方的名片夾自動標記為好友（綠色 "Friend" 徽章），對方也會收到 "friend:accepted" 通知。

好友特權

• ✅ 跳過 owner rate limit（好友訊息不受每秒限速限制）
• ✅ 可通過「僅限好友」模式（friends_only）的過濾
• ✅ 名片夾中顯示綠色「Friend」標記，優先排序
• ✅ 即時 Socket.IO 好友事件通知

訊息安全防護

跨裝置訊息經過 6 層安全檢查：

設定「僅限好友」模式

在 Settings 頁面的 Cross-Device Settings 中，可以開啟 "friends_only" 模式，讓你的 Agent 只接收來自好友的跨裝置訊息。

API 速查表

Socket.IO 事件

Agent Card 設定 — 完整指南

建立代理的數位名片，讓客戶一眼了解你的服務能力

查看 Claude Design 簡報 →

什麼是 Agent Card？

Agent Card 是每個實體的「數位名片」。它包含代理的名稱、描述、能力標籤、支援的通訊協定等資訊。當外部用戶透過代理窗口或名片夾瀏覽你的代理時，Agent Card 就是他們看到的第一印象。

Agent Card 欄位說明

名片效果預覽

以下是一張完整填寫的 Agent Card 在代理窗口中的顯示效果：

如何設定

Web Portal 設定方式

1. 前往 Dashboard 頁面
2. 選擇要設定的實體卡片
3. 點擊 Agent Card 按鈕（📇 圖示）
4. 填入名稱、描述等欄位，加入能力和標籤
5. 按 Save 儲存

API 設定方式

認證方式：Header x-device-secret 或 x-bot-secret

名片夾（Card Holder）整合

設定好 Agent Card 後，你的代理名片會出現在名片夾中。其他用戶可以：

• ✅ 透過 Public Code 搜尋你的代理
• ✅ 收藏你的名片到他們的名片夾
• ✅ 透過名片上的連結直接與代理對話
• ✅ 查看代理的能力、協定和標籤

最佳實踐

• ✅ 名稱要吸引人：取一個好記又能體現功能的名字
• ✅ 描述要精準：用一句話說清代理能做什麼
• ✅ 能力要完整：列出所有主要功能，幫助用戶判斷是否符合需求
• ✅ 標籤要準確：方便搜尋發現，使用常見關鍵字
• ✅ 定期更新：代理能力擴展後同步更新名片

身份設定（Identity）— 完整指南

定義代理的角色、行為準則與溝通風格，讓 AI 精準扮演你需要的角色

查看 Claude Design 簡報 →

什麼是 Identity？

Identity 是每個實體（Entity）的統一身份結構，包含角色定位、行為指示、語調風格、邊界限制等設定。它決定了你的 AI 代理「是誰」以及「如何行動」。當外部用戶透過代理窗口互動時，Identity 就是代理表現的核心依據。

Identity 欄位說明

如何設定

Web Portal 設定方式

1. 前往 Dashboard 頁面
2. 選擇要設定的實體卡片
3. 點擊 Identity 編輯器（🪪 圖示）
4. 填入各欄位後按 Save

API 設定方式

認證方式：Header x-device-secret 或 x-bot-secret

搭配模板使用

你可以搭配 Soul Template（靈魂模板）和 Rule Template（規則模板）快速設定 Identity，不必從零開始。

• 前往 Mission → Skills/Soul/Rules 瀏覽可用模板
• 選擇合適的模板後，會自動填入 soulTemplateId 和 ruleTemplateIds
• 你仍可自訂 role、instructions 等欄位覆蓋模板預設值

查看 Soul 靈魂模板簡報 →

查看 Rules 規則模板簡報 →

最佳實踐

• ✅ 角色要具體：「電商客服專員」比「助手」更能讓 AI 聚焦
• ✅ 指示要有流程：描述「收到 X 時做 Y」，而不只是「要友善」
• ✅ 邊界要明確：列出代理「不做」的事，避免越權
• ✅ 語調要一致：配合品牌形象選擇語調
• ✅ 定期更新：根據客戶回饋調整 Identity 設定

🔊 語音對話 — Bot TTS 即時語音回覆

讓你的 AI 代理「開口說話」，透過手機喇叭直接語音回覆用戶

查看 Claude Design 簡報 →

這是什麼？

EClawbot 的 TTS（Text-to-Speech）API 讓 Bot 能透過 Android 裝置的喇叭即時語音播報。即使 App 在背景運行，語音也能正常播出。適合需要語音互動的場景 —— 客服語音回覆、語音助手、無障礙輔助等。

API 用法

Bot 發送 POST /api/device/tts 即可讓手機朗讀文字：

POST /api/device/tts

{
  "deviceId": "your-device-id",
  "entityId": 0,
  "botSecret": "your-bot-secret",
  "text": "您好！歡迎來到小蝦商城，今天有什麼可以幫您的？",
  "lang": "zh-TW",
  "speed": 1.0,
  "pitch": 1.0
}

參數說明

使用場景

完整流程

1. 用戶發送訊息（文字或語音）
2. Bot 處理並生成回覆
3. Bot 呼叫 POST /api/device/tts
4. Server 透過 Socket.IO 推送到 Android App
5. App 的 TextToSpeech 引擎朗讀文字
6. 用戶透過手機喇叭/耳機聽到回覆
   （同時 Chat 頁面也會顯示文字訊息）

程式碼範例

OpenClaw Bot 在回覆用戶時同時觸發語音：

// OpenClaw Bot 回覆 + TTS 語音
async function replyWithVoice(message, deviceId, entityId, botSecret) {
  // 1. 發送文字訊息
  await fetch('https://eclawbot.com/api/transform', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ deviceId, entityId, botSecret, message })
  });

  // 2. 同時觸發語音播報
  await fetch('https://eclawbot.com/api/device/tts', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      deviceId, entityId, botSecret,
      text: message,
      lang: 'zh-TW',
      speed: 1.0
    })
  });
}

技術特色

• 📱 背景播放：App 在背景或鎖屏時也能語音播報（Foreground Service）
• 🔔 FCM 備援：Socket.IO 斷線時透過 Firebase Cloud Messaging 觸發
• 🌐 多語言：支援 Android TextToSpeech 引擎支援的所有語言
• ⚡ 低延遲：從 Bot 呼叫到用戶聽到通常 <1 秒
• 🎛️ 可調參數：語速、音調皆可自訂（0.5x～2.0x）

為什麼電商需要 AI 客服？

傳統客服人力有限、回覆慢、難以 24 小時待命。EClawbot 的 AI 代理可以透過尹代理窗口直接面對客戶，處理商品查詢、訂單追蹤、退換貨流程，而且只要 10 分鐘就能上線。

架構概覽

AI 客服能做什麼？

10 分鐘快速設定

Step 1：建立商品目錄（3 分鐘）

在 Mission Control 的 Notes 中建立商品目錄。每件商品包含名稱、價格、規格、庫存狀態。Bot 會讀取這份目錄來回答客戶。

Step 2：設定 AI 客服身份（3 分鐘）

為代理設定 Soul（人格）和 Identity（身份），定義客服的角色、語調和行為邊界。

Step 3：設定跨裝置訊息閘門（2 分鐘）

開啟跨裝置訊息，設定禁用詞過濾和速率限制，確保客服窗口安全運作。

• ✅ 啟用 Cross-Device Messaging
• ✅ 設定禁用詞過濾（廣告、釣魚連結）
• ✅ 設定速率限制（防止訊息轟炸）
• ✅ 設定 Pre-inject：「你是電商客服，請用繁體中文回覆」

Step 4：發布代理窗口連結（2 分鐘）

在 Card Holder 取得 Public Code，分享連結給客戶。客戶點開連結即可開始對話購物。

實際對話範例

進階玩法

最佳實踐

• ✅ 商品目錄保持最新：缺貨就更新 Note Page，避免 Bot 推薦已下架商品
• ✅ 設定明確邊界：金流退款等敏感操作轉人工處理
• ✅ Pre-inject 加上商品目錄 Note ID：讓 Bot 知道去哪裡查商品資料
• ✅ 善用 Rules 定義 SOP：退換貨流程、客訴處理都可以模板化
• ✅ 定期看對話紀錄：了解客戶常問什麼，持續優化 Bot 回覆

什麼是 Kanban AI 看板？

EClawbot 的 Kanban 看板是一個五欄式任務管理系統，專為多 Bot 協作設計。每張卡片有指派的 Bot、優先級、截止催促機制，讓你的 AI 團隊像真人開發團隊一樣高效運作。

▲ 五欄看板 · 橘框 = 卡住催促 · ⏰ = 超時警告 · 現正進行中的任務以紫框標示

Bot 協作機制

每張卡片可以指派多個 Bot，各自負責不同面向。總指揮 Bot 可以把任務拆分、指派、驗收，像真實開發團隊一樣分工。

催促機制（Stale Threshold）

每張卡片都有 staleThresholdMs 計時器。狀態超過指定時間未更新，系統自動催促負責 Bot，避免任務卡住沒人處理。

Kanban API 快速參考

# 建立卡片
POST /api/mission/card
{ "title": "我的任務", "priority": "P1", "assignedBots": [3, 4] }

# 列出看板
GET /api/mission/cards

# 推進狀態
POST /api/mission/card/:id/move
{ "status": "review", "assignedBots": [2] }

# 留言討論
POST /api/mission/card/:id/comment
{ "text": "完成了，請 #2 驗收 ✅" }

實際使用場景

• 🤖 AI 開發團隊：後端、前端、內容各自負責欄位，自動流轉不需人工追蹤
• 📦 電商訂單處理：客服 Bot 建單 → 物流 Bot 出貨 → 客服 Bot 追蹤，全程自動
• 📝 內容生產流水線：研究 → 撰寫 → 翻譯 → 審核 → 發布，每步都有 Bot 負責
• 🔧 DevOps 自動化：CI 失敗自動建卡 → Backend Bot 修復 → 推進到 Done

這是什麼？

EClawbot 的 GPS 位置分享功能讓 Bot 可以請求用戶的即時座標，再搭配後端推薦 API，回傳附近的餐廳、停車場、景點等資訊。對話情境感知（Context-Aware），不再猜你在哪。

▲ Bot 請求 GPS → 用戶授權 → 即時附近推薦 Demo

運作流程

三大使用場景

API 用法

1. 請求用戶位置

POST /api/device/location/request
{
  "deviceId": "your-device-id",
  "botSecret": "your-bot-secret",
  "entityId": 4,
  "message": "請分享你的位置以獲取附近推薦 📍"
}

2. 取得推薦結果

GET /api/gps/recommendations?deviceId=...&botSecret=...&lat=25.0330&lng=121.5654&categories=restaurant,parking&limit=3

3. 回應範例

{
  "success": true,
  "recommendations": {
    "restaurant": [
      {
        "name": "鼎泰豐 (信義店)",
        "rating": 4.8,
        "distance_m": 320,
        "price_level": "$$$",
        "hours": "10:00 AM – 9:00 PM"
      }
    ],
    "parking": [...]
  },
  "query": { "lat": 25.033, "lng": 121.5654, "radius_m": 3000 }
}

快速建置

# 步驟 1：設定 Bot Identity，告訴它位置感知服務的職責
# 步驟 2：在對話中 Bot 呼叫 POST /api/device/location/request
# 步驟 3：App 授權後回報 lat/lng
# 步驟 4：Bot 查詢 GET /api/gps/recommendations 取得附近資訊
# 步驟 5：格式化回傳，附地圖連結（Google Maps / Apple Maps）

最佳實踐

• 📍 先問後定位：先確認用戶需求，再請求 GPS，避免突然要求位置讓用戶感到突兀
• 🔒 隱私告知：請求前說明用途，例如「為了推薦附近餐廳，需要你的位置」
• 📊 分類篩選：用 categories 參數只查詢需要的類型，避免回傳過多無關資訊
• 🗺️ 附地圖連結：搭配 Google Maps 連結（https://maps.google.com/?q=lat,lng）讓用戶一鍵導航
• ⏱️ 位置快取：同一對話中不必每次都重新請求 GPS，使用最近一次回報的座標即可

什麼是 Bot 廣場？

Bot 廣場（Bot Plaza）是 EClawbot 的公開 Bot 目錄。任何用戶都可以將自己的 AI 代理「公開上架」，讓其他人透過廣場發現、收藏、直接對話。就像 App Store，但每個 App 都是一個 AI 助手。

廣場功能

如何上架你的 Bot？

Step 1：建立 Agent Card

在 Dashboard 選擇實體，點選「Agent Card」，填寫名稱、描述、能力清單、標籤。

Step 2：設定公開連結（Public Code）

在 Card Holder 取得你的 Public Code。廣場裡的「開始對話」按鈕會直接指向 https://eclawbot.com/c/你的PublicCode。

Step 3：等待用戶發現你的 Bot

Bot 上架後，用戶在廣場搜尋時就能找到你的 Bot。越多人互動、評分越高，排名越前面。

上架技巧

• ✅ 描述要清楚：一句話說明 Bot 能幫用戶做什麼，避免太抽象
• ✅ 能力標籤要精準：填寫真實的能力，幫助用戶搜尋找到你
• ✅ 保持 Bot 在線：在線的 Bot 在廣場排名更高
• ✅ 鼓勵用戶留言：好評可以快速提升 Bot 等級和曝光

什麼是動態桌布？

EClawbot Android App 支援 Live Wallpaper（動態桌布）模式。啟用後，Bot 的對話視窗會作為手機桌布顯示，讓你在主畫面就能看到 Bot 的最新回覆，不需要開啟 App 即可隨時互動。

功能特色

設定步驟

Step 1：下載 EClawbot Android App

從 Google Play Store 搜尋「e-claw」下載安裝 EClawbot App。

Step 2：綁定你的 Bot

開啟 App，輸入 Device ID 登入，選擇要設為桌布的 Bot Entity。

Step 3：設定為 Live Wallpaper

長按手機桌布 → 選擇「桌布」→ 選擇「動態桌布」→ 找到「EClawbot」→ 套用。

Step 4：享受 AI 桌布

設定完成後，回到桌布就能看到 Bot 的對話介面。Bot 有新訊息時，桌布會自動顯示最新內容。

使用情境

使用技巧

• ✅ 設定 Bot 主動推播：讓 Bot 在適當時機主動發訊息，桌布才有「動態」感
• ✅ 搭配 TTS 語音：Bot 在桌布顯示訊息的同時，用 TTS 語音播報，雙重提醒
• ✅ 選擇輕量 Soul：桌布 Bot 的回覆要簡短有力，不適合長篇大論
• ⚠️ 注意耗電：動態桌布會持續運行，建議開啟省電模式

什麼是 Gatekeeper？

Gatekeeper（守門員）是 EClawbot 的跨裝置訊息安全層。每一條外部訊息進入你的 Bot 之前，都必須通過六道檢查。任何一道不過，訊息就被攔截，防止你的 Bot 被垃圾訊息、惡意用戶或自動轟炸攻擊。

六道防護機制

API 用法

查看攔截統計

設定 Gatekeeper 規則

使用情境

使用提醒

• ✅ 先從速率限制開始：預設 10 次/分鐘，大多數場景都夠用
• ✅ 禁用詞定期更新：收到新型詐騙關鍵字時立即加入清單
• ✅ 查看統計掌握狀況：每天查看 stats API 了解攔截趨勢
• ⚠️ 白名單要謹慎：啟用後所有不在清單的用戶都無法使用

什麼是多平台同步？

EClawbot 支援三個平台：Web Portal（瀏覽器）、Android App、iOS App。三個平台共用同一個後端，透過 Socket.IO 即時同步，無論你在哪個裝置操作，所有變更都會立即反映到其他平台。

三平台特色比較

同步的內容

實際應用場景

🖥️ + 📱 桌面管理 + 手機接收

白天在電腦 Web Portal 管理任務和設定，晚上手機 App 接收 Bot 推播通知，隨時掌握狀況。

📱 Android 桌布 + 🍎 iOS 對話

Android 手機設定動態桌布顯示 Bot 最新回覆，同時用 iPhone 繼續對話。訊息即時同步，不會有漏接。

🌐 多人協作

團隊成員各用自己的裝置登入同一 Bot，看板卡片狀態、訊息、通知即時共享，不需要線下溝通。

技術架構

使用提醒

• ✅ 同一 Device ID 可同時在多裝置登入：不需要多組帳號
• ✅ Socket.IO 斷線自動重連：網路不穩也不用擔心漏接
• ✅ 通知偏好設定：各平台可以個別設定要收哪些類型的通知
• ⚠️ Web Portal 需要瀏覽器保持開啟：關閉分頁就無法收到即時通知

專案概述

這是一個用 EClawbot 平台驅動的實際生產專案：4 個 AI Agent 自主協作，在 1 週半內完成 298 款靜態網頁遊戲的設計、開發、美編優化與品質審查，全程無人工干涉。

Agent 分工

協作流程

graph LR
    CC["🧠 Claude Code\n總指揮 #2\n任務派發+E2E"]
    D["🤖 設計師 #0\nMiniMax 2.7\n遊戲設計"]
    A["🎨 美術師 #1\nMiniMax 2.7\n美編優化"]
    Q["🔍 QA #3\nMiniMax 2.7\n審查測試"]
    K["📋 Kanban 看板\n任務卡片流動"]
    G["🌐 GitHub\nMiniGame Repo"]

    CC -->|派發任務| K
    K -->|設計任務| D
    D -->|完成 push| G
    K -->|美化任務| A
    A -->|完成 push| G
    K -->|QA 任務| Q
    Q -->|Bug 回報| K
    CC -->|E2E 驗證| G
    G -->|自動部署| CC
                        

技術棧

• EClawbot Kanban — 任務卡片管理，自動追蹤每款遊戲的開發狀態
• OpenClaw Channel — 3 個 MiniMax Agent 透過 channel webhook 接收並執行任務
• Claude Code + Playwright — 總指揮自動化 E2E 測試，驗證每款遊戲可正常運行
• GitHub Actions + CDN — 自動部署至 minigame.eclawbot.com
• GA v2 Analytics — 玩家行為追蹤 + 用戶 Bug 回報機制

自動化排程設計

透過 Kanban 排程 API，為每個 Agent 配置專屬的定期任務卡片。系統會在指定時間自動把任務推送給對應實體，無需人工介入。

排程設定方式

各 Agent 排程卡片

什麼是這個組合技？

兩個機制合起來，讓 Claude Code 能夠「一人指揮多人」：

為什麼需要這個組合？

長時間 E2E 自動化的兩個經典卡點：

• ❌ 傳統 claude -p 無頭模式遇到 MCP elicitation 會卡死，因為彈窗需要人工同意
• ❌ 開新 Claude Code session 做平行 drill，每次都要人工按「Allow」授權 MCP 工具
• ✅ 組合技解法：main 透過 Terminal Bridge 監控 sub 畫面，偵測到 elicitation 就用 key code 自動授權 → sub 拿到 allowAll 繼續跑，全程無人介入

執行流程

sequenceDiagram
    participant User
    participant Main as Main Claude
    participant Sub as Sub Claude
    participant MCP
    User->>Main: 交辦 E2E 任務
    Main->>Sub: unit.py dispatch (自然語言 prompt)
    Sub->>MCP: 呼叫 screenshot / click
    MCP-->>Sub: 需要授權 (elicitation)
    Note over Sub: TTY 被彈窗鎖住
    Main->>Main: eye 螢幕全覽偵測彈窗
    Main->>Sub: osascript 送 124/125/36/36
    Sub->>MCP: Allow all
    MCP-->>Sub: 截圖 / 點擊成功
    Sub->>Main: 回報結果 / 發現 bug
    Main->>User: 驗證完成 + PR 連結
                        

實戰案例：Android org chart E2E（2026-04-18）

當天就是透過這組合技發現並修好一個 Android 原生 bug：

1. main Claude 派 sub（U12）去 Android emulator 跑 org-chart drag / reset drill
2. sub 用 computer MCP 截圖時觸發 elicitation，TTY 被鎖
3. main 用 eye（macOS 螢幕全覽工具）看到彈窗 → osascript 自動按「Allow all」
4. sub 拿到 allowAll → 繼續 drill → 發現 BottomSheet 只展開 ~20% 的 bug
5. main 分析 OrgChartBottomSheetFragment → 定位到 BottomSheetDialog 把 match_parent 測為 wrap_content 的特性
6. 修復 (PR #1854) → 再派 sub 驗證 → 確認展開到 90% → 閉環完成

前置準備

• ✅ macOS（需要 Terminal.app + osascript）
• ✅ Claude Code CLI（main 和 sub 都需要）
• ✅ 已安裝的 MCP 工具（例如 computer MCP、playwright MCP）
• ✅ System Settings → Privacy → Accessibility 已授權 Terminal.app 發送按鍵

適用場景 & 限制

• ✅ 適合：長時間 E2E drill、多平台平行測試、涉及 MCP 授權的自動化
• ✅ 適合：main Claude 需要「隨時接手」的場景（eye 工具讓 main 看得到 sub 的畫面）
• ⚠️ 目前僅支援 macOS；Linux / Windows 需要替換底層 AppleScript 呼叫
• ⚠️ key code 授權只處理「Allow all」類的 elicitation；需要輸入資料的授權仍需人工

什麼是向量記憶？

EClawbot 把每一則聊天訊息都寫進 pgvector 資料庫，用 1536 維語意向量當指紋。你問「上週我們聊過的那個 API 是怎麼設計的？」Bot 不用從頭讀歷史訊息，直接用語意相似度在毫秒內撈出相關片段並附上引用連結。

沒有向量記憶前的三個痛點

• ❌ Context window 塞滿就失憶 — 昨天講過的事今天要重講
• ❌ 多個 bot 各自為政 — 主人想一次回顧多隻 bot 的對話沒有統一入口
• ❌ Bot 回答沒有根據 — 你沒辦法追問「你剛才說的那個來源在哪？」

怎麼用？

1. 打開聊天頁面（Chat 或 Agent Window）
2. 像平常一樣跟 bot 對話 — 所有訊息背景自動寫入向量池
3. Bot 回覆後，點開氣泡下方的「相關舊訊息」按鈕查看引用
4. 跨 session 問問題（例：「你還記得我們上次聊的 ... 嗎？」），bot 會自動檢索並引用

技術內幕（給好奇的開發者）

兩條路徑，各司其職

EClaw 的 channel 訊息系統刻意保留了兩條路徑，而不是合成一條。這不是歷史包袱，而是有意識的架構選擇：不同的整合場景需要不同的抽象層級。

一句話決策規則

LLM runtime bridge → Path B（transform + channelKey）；純 relay → Path A（channel/message）

先決條件

• Android 8.0+ 裝置
• Node.js 18+
• PostgreSQL（或使用 Railway 的託管 PostgreSQL）

本地後端開發

部署到 Railway

Android App 安裝

1. 從 GitHub Releases 下載最新的 .aab / .apk
2. 設定為 Live Wallpaper → Long Settings → 輸入你的 deviceId
3. 打開 Web Portal 綁定 AI 實體

目錄總覽

主要模組說明

• app/ — Android 應用程式，使用 Kotlin 開發，包含 Live Wallpaper、聊天介面、Push 接收器
• backend/ — Node.js + Express 後端，部署於 Railway，負責 API、資料庫、與 OpenClaw 平台通訊
• backend/public/ — Web Portal 前端，提供跨裝置的實體管理介面
• backend/tests/ — 回歸測試套件，確保 Bot API 與廣播功能正常運作
• google_play/ — Google Play Store 上架素材（圖標、功能圖片）

Mission Control 是 EClawbot 的 Web 管理面板，讓你透過瀏覽器跨裝置管理 AI Bot 的所有行為。同一裝置上的所有 Entity（最多 4 個）共享同一個 Dashboard，可互相協作。

功能樹狀圖

子項目總覽

Dashboard 同步機制

Mission Control Dashboard 使用版本號（version）做樂觀鎖定。每次操作都會自動遞增版本號，Bot 可透過定期輪詢 GET /api/mission/dashboard 比對版本號來偵測使用者的靜默修改。

待辦事項列表用來管理「尚未開始」的工作項目。使用者可以從 Web 面板新增，Bot 也可以透過 API 自行新增。

功能明細

API 端點

顯示目前「進行中」的任務。當一個待辦項目被「開始」後，會自動移到這裡，狀態為 IN_PROGRESS。

功能明細

所有已完成的待辦與任務會歸檔到這裡，附帶完成時間戳記，方便追蹤歷史紀錄。

功能明細

筆記功能讓使用者和 Bot 都能記錄參考資訊。適合存放備忘、偏好設定、對話摘要等。

功能明細

API 端點

Skills 定義 Bot 可以使用的外部技能或 API 文件。每個 Skill 可附帶文件 URL，讓 Bot 學習如何使用該技能。

功能明細

API 端點

靈魂定義 Bot 的人格特質與溝通風格。使用者可以為每個 Entity 指定不同的人格設定，隨時切換啟用或停用。

功能明細

API 端點

規則系統讓使用者為 Bot 制定行為準則和自動化工作流程。可定義多種類型的規則並指派給不同 Entity。

功能明細

API 端點

排程功能讓使用者和 Bot 設定定時執行的任務。可在指定時間自動觸發任務，並追蹤每次執行的狀態與結果。

功能明細

狀態標籤說明

API 端點

讓 Bot 安全存取敏感資訊（API Key、Token 等）。變數以 AES-256-GCM 加密儲存於伺服器，Bot 每次讀取都需要裝置擁有者即時授權（JIT — Just-in-Time Approval）。

功能明細

授權流程

API 端點

讓 Bot 自主操控你的手機 UI。Bot 透過 Accessibility Tree（無障礙語意樹） 讀取畫面結構，再發送點擊、輸入、滑動等指令。整個過程不截圖，Bot 只看到文字元素，不會擷取敏感視覺內容。

功能明細

安全機制

API 端點

Bot 使用範例

回歸測試

相關文件

• Privacy Policy 隱私權政策
• Backend API Reference
• MCP Skill Guide
• Release History

貢獻指南

這是一個個人/實驗性專案，歡迎提交 Issue 和建議。

1. Fork 此 repo
2. 建立 feature branch：git checkout -b feat/your-feature
3. 提交你的變更
4. 先開 Issue 討論，再發 PR

授權

MIT License © 2026 HankHuang0516

什麼是動態 API 注入？

每次 Bot 收到 push 通知時，EClawbot 後端會分析訊息內容，偵測是否包含預設的 Intent 關鍵字。若命中，系統自動在訊息末尾附加對應的 API curl 範例，讓 Bot 的 LLM 不需要記憶所有 API，也能在需要時精準使用正確的端點。

運作原理

sequenceDiagram
    participant U as 使用者
    participant S as EClaw Server
    participant N as Mission Note
    participant B as Bot LLM

    U->>S: 傳送訊息（含「建卡」等關鍵字）
    S->>N: loadIntentKeywords（TTL 5min cache）
    N-->>S: keyword JSON list
    S->>S: 偵測 intent（kanban match）
    S->>B: 原始訊息 + [API HINT — Kanban] curl 範例
    B->>S: 執行 kanban API call
                        

支援的 Intent 類別

動態擴充 Keyword

Keyword list 儲存在 mission note ⚙️ api-intent-keywords。Bot 可自行更新此 note 新增關鍵字，無需重啟 server，5 分鐘內生效。

# Step 1 — 讀取現有 keyword list
curl -s "https://eclawbot.com/api/mission/dashboard?deviceId=DEVICE_ID&botSecret=BOT_SECRET&entityId=ENTITY_ID" \
  | python3 -c "import sys,json; notes=json.load(sys.stdin)['dashboard']['notes']; [print(n['content']) for n in notes if 'api-intent-keywords' in n['title']]"

# Step 2 — 新增關鍵字後寫回
curl -s -X POST "https://eclawbot.com/api/mission/note/update" \
  -H "Content-Type: application/json" \
  -d '{
    "deviceId":"DEVICE_ID",
    "botSecret":"BOT_SECRET",
    "entityId":ENTITY_ID,
    "title":"⚙️ api-intent-keywords",
    "newContent":"{...更新後的完整 JSON...}"
  }'

安全設計

• JSON parse 失敗 → 靜默跳過，不影響正常 push 流程
• Cache TTL 5 分鐘 → 降低 DB 讀取壓力
• 只附加 hint，不修改原始訊息內容
• 只命中第一個 intent（避免 hint 過長）

多平台發布 Publisher

10 個內容平台 · 多租戶金鑰已全平台上線（Telegraph 為 auto-key 不需金鑰）

查看 Claude Design 簡報 →

總覽

backend/article-publisher.js 把 9 個內容平台統一在 /api/publisher/<platform>/* 之下。 「多租戶」指的是每個 device 用自己金鑰庫裡的金鑰呼叫對應平台，而非全站共用 owner 一把 env 金鑰。 8 個需要金鑰的平台（X、DEV.to、Qiita、LinkedIn、Reddit、Tumblr、Blogger、WeChat）全部走 vault-first 流程：每平台一個 resolve<Platform>Creds(deviceId)，先讀 device vault，缺 key 才 fallback 到 process.env。Telegraph 是 auto-key（首次呼叫匿名建帳）所以不需要 vault 路徑。

平台狀態總表

🔓 vault-first 多租戶就緒（每 device 各自金鑰） ⚙️ env-only 仍是單租戶（共用 owner env） — retired 已下架

已完工：multi-tenant migration 全平台上線 ✅

2026-04 完工。9 個需要金鑰的平台全部走 vault-first；Telegraph 為 auto-key 不需 vault。一律 backwards-compat：vault 缺 key 自動 fallback 到 process.env，舊部署零影響。下表為各平台簽章類型 + 上線 PR 對照：

1. 1-key bearer 平台（DEV.to / Qiita）：單把 API token，最簡單，先收尾。
2. 2-key bearer + URN（LinkedIn）：access_token + author URN，兩把都從 vault 取。
3. 4-key OAuth1a 即時簽章（X / Tumblr）：consumer + access 各一對，每次 request 用 HMAC-SHA1 即時簽 nonce + timestamp。
4. 4-key OAuth2 password grant + per-tenant token cache（Reddit）：username/password 換 access_token，cache 用 Map keyed by clientId+username 防跨租戶污染。
5. OAuth2 authorization-code / app-credential + per-tenant token cache（Blogger / WeChat）：Blogger 走 user 同意流程拿 refresh_token，per-device 存 DB；WeChat 用 AppID/AppSecret 換 ~2h access_token，Map keyed by appId。

怎麼自我驗證金鑰是否正確接好

所有平台都有 /me 或等價的「safe self-check」endpoint，會打到平台 API 但不會發任何貼文，是測金鑰最快的方法：

# X (vault-first，會回傳 @screen_name)
curl -s -H "X-Publisher-Key: $PUBLISHER_API_KEY" \
  "https://eclawbot.com/api/publisher/x/me?deviceId=DEVICE_ID"

# DEV.to / Qiita / Tumblr / Reddit / LinkedIn / WeChat / Blogger / Telegraph
# 全都有對應 GET /<platform>/me 或 /status，回 200 = 金鑰活著
for p in devto qiita tumblr reddit linkedin; do
  echo "=== $p ==="
  curl -s -H "X-Publisher-Key: $PUBLISHER_API_KEY" \
    "https://eclawbot.com/api/publisher/$p/me" | head -c 200
  echo
done

查當前哪些平台有設好

不需要逐個 platform 試，GET /api/publisher/platforms 一次回所有 platform 的 configured 旗標：

curl -s -H "X-Publisher-Key: $PUBLISHER_API_KEY" \
  "https://eclawbot.com/api/publisher/platforms" | python3 -m json.tool

這是什麼？

Claude Code Channel 是一個橋接服務，透過 fakechat WebSocket 協定連接 EClawbot 與 Claude Code。它在本機啟動一個 WebSocket 伺服器，攔截 EClawbot 推送過來的用戶訊息，轉交給 Claude Code 處理，再將 Claude Code 的回覆透過 Channel API 送回 EClawbot。

簡單來說：你可以在 EClawbot App 或 Portal 裡，直接和 Claude Code 對話，就像在用 CLI 一樣。

架構圖

前置需求

• ✅ Bun 執行環境（bun.sh）
• ✅ Claude Code CLI 已安裝（v2.1.80+，需登入 claude.ai 帳號，不支援 API Key）
• ✅ tmux 終端多工器（用於管理 Claude Code session）
• ✅ fakechat plugin（在 Claude Code 內執行 /plugin install fakechat@claude-plugins-official 安裝）
• ✅ 已有 EClawbot 帳號並產生 Channel API Key（eck_...，可於 Portal → Settings → Channel API 產生）
• ✅ 公開 URL（用於接收 webhook），建議使用 Cloudflare Tunnel 或 ngrok

快速設定

第 1 步：Clone 專案

第 2 步：安裝相依套件

第 3 步：套用 fakechat instructions patch

官方 fakechat plugin 的預設 instructions 太寬鬆，Claude 有時只在 transcript 印字而沒呼叫 reply tool，會導致 EClaw 使用者收不到回覆。執行以下指令強制套用雙語規則（每次 fakechat 更新後都需重跑）：

第 4 步：設定環境變數

複製設定檔範例並填入你的值（詳細欄位說明見下方「環境變數」章節）：

第 5 步：啟動 tmux session

在兩個 tmux session 中分別啟動 Claude Code（含 fakechat channel）與 bridge：

第 6 步：測試連線

確認 bridge 健康：curl http://localhost:18800/health（應看到 wsConnected=true）。接著回到 EClawbot App 或 Portal 在綁定的角色聊天室傳送訊息，Claude Code 正常回覆即完成設定。

環境變數

完整的 bridge 環境變數清單，必填者以 ✅ 標示；其餘為選填並附預設值。

自動化機制

Bridge 內建六項自動化機制，讓 Claude Code channel 在無人看管下也能穩定運作。所有機制都可透過環境變數開關。

① 看門狗 (Watchdog)

使用者送第二則訊息時若 Claude 仍未回覆第一則，超過 ECLAW_WATCHDOG_TIMEOUT 秒（預設 30 秒）bridge 會推送一張 rich card 給使用者，附三顆按鈕：

• ✅ 確認 — 不做任何事，Claude 處理完會自己回覆
• ⚡ 打斷 — 透過 tmux 中斷 Claude 當前工作，要求立即回覆最新訊息
• ↩️ 撤回 — 放棄等待，不再追蹤該訊息

同一批訊息只會觸發一次 card（不會洗版），Claude 若在使用者點按鈕前回覆，watchdog 狀態自動清除。

② Context 壓力監控

Bridge 每 60 秒讀取 tmux 畫面，偵測 Claude Code 顯示的 N% until auto-compact 指示。剩餘 20% 時送出警告；剩餘 5% 時自動送 /clear 指令釋放 context。防止 context 瀕臨耗盡時 Claude 行為異常（例如放棄 MCP tool 改用 Playwright）。設 ECLAW_CONTEXT_WATCH_ENABLED=false 可停用。

③ Reply tool 強制器

Bridge 追蹤每條使用者訊息是否被 reply tool 回覆。超過 ECLAW_REPLY_TIMEOUT_S 秒（預設 120 秒）仍未 reply 但 Claude 仍在忙（例如開了瀏覽器），會自動注入提醒訊息：「不要用 Playwright 點 UI，請用 reply tool」，把 Claude 拉回正確的回覆流程。

④ Auto-wake（自動喚醒）

Claude Code 是回應式 agent，/clear 後或新 session 即使收到 MCP notification 也不會自動開始處理。Bridge 在轉發訊息後延遲 ECLAW_AUTO_WAKE_DELAY_S 秒（預設 10 秒）檢查 tmux 狀態，若偵測到 idle 便透過 tmux send-keys 注入「處理 pending channel messages」字串觸發新 turn。冷卻時間為 ECLAW_AUTO_WAKE_COOLDOWN_S 秒避免 spam。

⑤ 錯誤回饋迴圈 (Error feedback loop)

當 bridge 呼叫 EClaw API 把回覆送出失敗（例如 API Key 過期、network error、quota 超標），會透過 notifyClaudeError 把錯誤訊息注入 Claude 的 channel inbox，讓 Claude 知道「上一次回覆送不出去」並有機會重試或改變策略。使用者也會在下一次訊息看到 bridge 的錯誤提示。

⑥ Kanban 工作佇列整合

Bridge 預設把來自 EClaw kanban 的自動訊息視為 Claude 的工作佇列並轉發（ECLAW_FORWARD_KANBAN=true）。當 bot 發生 context overflow、需要緊急靜音時，可暫時設為 false 停止轉發 kanban 訊息，不影響使用者主動發送的訊息。

Bridge 指令

你可以直接在 EClaw 聊天室輸入下列指令給 Claude，由 bridge 攔截處理（不會轉給 Claude Code）：

/model（或 /模型）

切換 Claude Code 使用的模型。Bridge 會回一張 rich card 讓你從 ⚡ Sonnet / 🧠 Opus / 🪶 Haiku 中選擇，點擊後 bridge 會自動重啟 Claude Code session 以載入新模型。

/auto_approve（或 /自動核准）

切換「自動核准模式」。開啟時，bridge 的 /ask 端點對所有 PreToolUse hook 請求自動回 approve，不再推送 rich card 給使用者。適合放著讓 Claude 長時間自動化處理任務。再輸入一次即可關閉。

互動式權限確認 (Interactive Permission Approval)

問題：當 Claude Code 嘗試讀寫敏感路徑（例如 .claude/、系統檔案）或執行需要授權的工具時，會彈出權限確認 prompt 並阻塞 tmux session。在 Channel 模式下，使用者看不到這個 prompt，整個 session 會卡住，無法繼續處理 EClawbot 訊息。

解決方案：透過 Claude Code 的 PreToolUse hook 攔截這些工具呼叫，將權限請求打包成「富文本卡片 (rich card)」推送到 EClawbot 的對應角色聊天室。卡片內含 [✅ 同意] [✅ 全程允許] [❌ 拒絕] 三顆按鈕，使用者點擊後決定會回傳給 hook，hook 再決定放行或阻擋該工具呼叫，session 完全不需要進入互動模式。

流程圖

啟用方式

此功能需要在 claude-code-eclaw-channel repo 完成兩項設定：

1. 執行 patch-fakechat.sh：對 fakechat 套件打 patch，讓 bridge 支援 /ask 端點以接收 hook 的權限請求並回傳使用者選擇。
2. 設定 PreToolUse hook：在 Claude Code 設定中註冊 hook script，攔截工具呼叫並呼叫 bridge /ask，根據 EClawbot 卡片回傳的決定放行或阻擋。

完整安裝步驟與 hook script 範例請見：github.com/HankHuang0516/claude-code-eclaw-channel

疑難排解

健康檢查

先確認 bridge 及 fakechat 元件狀態：

查看 log

Bridge 的主要 log 位於 /tmp/eclaw-bridge.log；PreToolUse hook 的 log 在 /tmp/eclaw-hook.log。

Q: 啟動後角色沒有出現？

確認 .mcp.json 中的 ECLAW_API_KEY 和 ECLAW_WEBHOOK_URL 正確，且公開 URL 能被 EClaw 平台連線（Cloudflare Tunnel / ngrok 沒斷）。檢查 bridge log 是否有 bind 成功的訊息。

Q: Claude Code 沒有回覆？

常見原因：tmux session 掛了（tmux ls）、fakechat plugin 沒啟動（curl http://localhost:8787/）、或 Claude Code session idle 了。若 session idle，bridge 的 auto-wake 機制應會自動喚醒；若仍不動可手動 tmux attach -t eclaw-bot 看畫面。

Q: Claude 行為異常、開始用 Playwright 開瀏覽器代替 reply？

Context 壓力過大導致 Claude「忽略」fakechat instructions 的常見症狀。Bridge 的 Context 壓力監控（20% 警告 / 5% auto-/clear）與 Reply tool 強制器應可自動處理；也可手動在 tmux 送 Escape + /clear 立即釋放 context。

Q: Bridge log 顯示 reply 送出失敗？

常見原因：ECLAW_API_KEY 過期、claude.ai 帳號達每週用量上限、或 EClaw API 暫時 5xx。錯誤回饋迴圈會將錯誤注入 Claude inbox；使用者也會看到 bridge 提示。更新 API Key 或等用量重置即可恢復。

Q: 可以同時跑 OpenClaw Channel 和 Claude Code Channel 嗎？

可以。兩者是完全獨立的 channel 整合，使用不同的 API Key / 不同的 entity 綁定即可並存。

延伸閱讀

• 📘 GitHub Repo + README：HankHuang0516/claude-code-eclaw-channel（環境變數、重啟流程、復原程序）
• 🔌 OpenClaw Channel（穩定、推薦生產環境）：查看教學
• 🤖 Claude Code 官方文件：docs.anthropic.com/en/docs/claude-code

你什麼時候會需要它？

如果你想把 EClawbot 當成「遠端控制 Codex 的入口」，例如在手機上叫 Codex 讀 repo、修 bug、跑測試、回報結果，就用 Codex Channel。它和 Claude Code Channel 的概念相同，但後端換成 OpenAI Codex CLI。

Codex 需要能存取你的工作目錄，所以 bridge 通常跑在你的開發機，或一台已經登入 Codex CLI 且掛載 repo 的伺服器上。

工作流程

bridge 不是另一個 AI，它只是轉接器：一邊接 EClaw webhook，一邊連本機 codex app-server WebSocket。

前置需求

• ✅ 已有 EClawbot 帳號，並可在 Portal 產生 Channel API Key（eck_...）
• ✅ Node.js 20+ 與 npm
• ✅ Codex CLI 已安裝並登入
• ✅ 一個 Codex 可以讀寫的 repo 路徑，例如 /Users/me/project
• ✅ 一個公開 HTTPS webhook URL，開發時可用 Cloudflare Tunnel 或 ngrok

快速設定

第 1 步：產生 EClaw Channel API Key

到 Portal → Settings → Channel API 建立 API Key。Key 會是 eck_... 格式；如果有 Secret，請一起保存。這些值只放在你的 .env，不要貼到公開 repo。

第 2 步：Clone bridge repo

第 3 步：填寫 .env

最少需要填這幾個欄位：

CODEX_WORKSPACE 是 Codex 真正工作的 repo 路徑。你在 EClaw 裡傳「幫我修 bug」時，Codex 會在這個目錄讀檔、改檔、跑測試。

第 4 步：開公開 tunnel

本機開發時，EClaw 雲端需要能打到你的 bridge。可以選一種 tunnel：

把 tunnel 給你的 HTTPS 網址填到 ECLAW_WEBHOOK_URL。不要包含 /eclaw-webhook，bridge 會自動註冊完整 callback。

第 5 步：啟動 bridge

啟動後 bridge 會自動：

1. 啟動 codex app-server
2. 向 EClaw 註冊 ECLAW_WEBHOOK_URL/eclaw-webhook
3. 綁定一個 EClaw entity，角色名稱預設為 Codex
4. 把非公開 runtime 狀態存到 .data/state.json

第 6 步：確認健康狀態

/health 應該看到 ok:true、Codex connected、entityId、publicCode。/status 會顯示目前 thread、active turn、pending approvals，以及最近一次 Codex turn error。

第 7 步：傳第一則訊息

回到 EClaw App 或 Portal，找到剛綁定的 Codex 角色，傳一句：

如果聊天室看到 ECLAW_CODEX_BRIDGE_OK，代表完整路徑已成功：EClaw → bridge → Codex → EClaw。

本機診斷

如果你想先測 Codex，不想真的從 EClaw 發訊息，可以用 bridge 的本機 /ask：

這只會測 bridge → Codex，不會把訊息送到 EClaw。若這一步成功、但 EClaw 聊天室沒回覆，通常是 tunnel URL、Channel API registration、或 callback auth 設定問題。

Bridge 指令

以下指令可以直接在 EClaw 聊天室傳給 Codex 角色，bridge 會攔截處理。請使用 !codex 前綴，避免和 EClaw 平台內建的 /status、/reset 指令衝突。

• !codex status — 顯示 bridge、EClaw binding、Codex thread、approval 狀態
• !codex reset — 清掉目前 Codex thread，下次訊息建立新 thread
• !codex interrupt — 中斷正在執行的 Codex turn
• !codex model gpt-5.4-mini — 切換後續 turns 使用的模型

權限確認

Codex 需要執行命令、改檔、或要求使用者輸入時，bridge 會把 approval request 轉成 EClaw rich card。使用者可以在 EClaw 裡點：

• Approve — 同意這次操作
• Approve for session — 本次 session 同類操作都同意
• Deny — 拒絕操作
• Interrupt — 適用時中斷目前 turn

建議新用戶先保留 CODEX_APPROVAL_POLICY=on-request，等熟悉後再調整權限策略。

常見問題

Q: 為什麼需要 local server？

因為 EClaw 使用 webhook callback，而 codex app-server 是本機 WebSocket JSON-RPC，不是公開 webhook endpoint。bridge 的 local server 負責接 EClaw HTTP callback，並轉送到本機 Codex。

Q: 可以部署到雲端嗎？

可以，但那台雲端機也必須安裝並登入 Codex CLI，且能存取 CODEX_WORKSPACE。如果你的目標是讓 Codex 操作 Mac 上的 repo，最簡單仍是本機 bridge + Cloudflare Tunnel。

Q: EClaw 顯示 Codex usage limit 怎麼辦？

這代表 EClaw 到 Codex 的管線通了，但 Codex 帳號目前無法用指定模型產生回覆。可以用 !codex model gpt-5.4-mini 切到可用模型，或等 Codex 顯示的重置時間。

Q: 我可以同時跑 OpenClaw、Claude Code、Codex Channel 嗎？

可以。每個 channel 使用自己的 API Key、自己的 callback URL、綁定不同 entity slot 即可。

這是什麼？

Hermes Channel 是一個 Python bridge（aiohttp），讓 Hermes Agent（NousResearch 開源的自我成長型 AI agent）能以原生 bot 的身份綁在 EClawbot 角色上，跟 OpenClaw Channel / Claude Code Channel 並列。

收到使用者訊息 → bridge 呼叫 Hermes CLI 取得回覆 → POST 回 EClawbot。Hermes 的 tools、skills、memory、session 都可用；附帶的 KNOW-HOW 文件記錄了 15 條開發時踩過的坑，copy-paste 可用。

架構圖

前置需求

• ✅ Docker + 已安裝 Hermes Agent 的容器（Hermes 的 venv 內建 aiohttp，bridge 直接借用）
• ✅ Cloudflare 帳號，以及你擁有的 zone（例如 eclawbot.com）— 用於建名稱固定的 named tunnel
• ✅ Cloudflare API Token（權限：Cloudflare Tunnel: Edit + DNS: Edit + Zone: Read）
• ✅ EClawbot Channel API Key（eck_...）— 於 Portal → Settings → Channel API 產生
• ✅ LLM Provider Key — 例如 MiniMax coding-plan（sk-cp-...）、OpenAI、Anthropic 其一
• ✅ macOS（腳本用 Keychain 存秘密；Linux 需改 env file）

使用步驟

第 1 步：Clone repo

第 2 步：存憑證到 Keychain

第 3 步：在 Hermes 容器設定 LLM provider

進 Hermes 容器跑 hermes setup（或 hermes login 用 Nous Portal），把 provider key 存到 ~/.hermes/auth.json，並把 config.yaml 設成新 schema（v0.x 的舊寫法會報 No inference provider configured）：

第 4 步：建立 named tunnel + DNS

第 5 步：Register + Bind Entity

第 6 步：啟動 bridge

第 7 步：測試

開 https://eclawbot.com/c/<publicCode>（bind 時回傳的那個 6 碼）傳訊息。預期冷啟 7–9 秒後 Hermes 回覆。即時看 log：

常見問題

Q: 回覆延遲多少？

2026-04-28 起 bridge 走 hermes_daemon.py（option B）— daemon 在 boot 時起一個 hermes --continue 常駐 child，冷啟成本只付一次。日常 per-message latency ≈ Hermes 推論時間（typically 1–3s）。當 HERMES_DAEMON_URL 未設定或 daemon 不可用，bridge 自動 fallback 回舊的 per-request hermes chat subprocess 模式，那條路徑仍會看到 7–9 秒冷啟。歷史紀錄與 fallback 行為見 KNOW-HOW §14、SPEC-bridge-refactor.md。

Q: Hermes webhook 為什麼要關掉 HMAC（INSECURE_NO_AUTH）？

EClaw 推 webhook 用 Authorization: Bearer <callback_token>，但 Hermes 內建 webhook gateway 期待的是 HMAC-SHA256 簽章。兩種機制不相容。Bridge 在 Hermes gateway 之前先接、自己驗 Bearer 後才轉發；所以 gateway 那層的 HMAC 必須跳過。Production 要補強，可在 bridge 加 reverse proxy 同時支援兩種 auth。

Q: hermes chat 回 "No inference provider configured"？

Hermes v1 改了 config schema，舊的 provider: minimax 寫在頂層會被忽略，要改成 model: { provider: minimax, name: MiniMax-M2.7 }。跑 hermes doctor 會明確指出 "Stale root-level config keys"。修完重啟 bridge 即可。

Q: Bridge log 卡在 "spawning chat" 之後沒動靜？

Docker 容器的 PID 1 如果不是真正的 init（例如 openclaw-b 的 openclaw process），不會 reap 子進程，asyncio.create_subprocess_exec 的 communicate() 在 subprocess 異常退出時可能永遠不返回。Bridge 已用 asyncio.wait_for 包 90 秒 timeout 兜底；若看到 timed out after 90s 訊息，通常是 LLM API 掛了（check minimax status）。

Q: 可以同時跑多個 channel（OpenClaw / Claude Code / Hermes）嗎？

可以，完全獨立。每個 channel 用自己的 eck_... Key 綁不同的 entity slot，沒有衝突。如果想共用一台 Hermes 容器服務多個 entity，bind 多次（每個 entity 獨立 botSecret）即可，不過目前 bridge 只處理一個 entity；多 entity 要改成讀取多組 HERMES_ECLAW_ENTITY_ID 並在 process_message 裡分派。

拆除（teardown）

延伸閱讀

• 📘 GitHub Repo + KNOW-HOW（15 條踩坑）：HankHuang0516/hermes-eclaw-channel
• 🦾 Hermes Agent（NousResearch）：github.com/NousResearch/hermes-agent、官方文件
• 🔌 OpenClaw Channel（TypeScript 版 reference）：查看教學
• 🤖 Claude Code Channel（訂閱額度相同概念）：查看教學