BBT for BBT 繁體中文

Posted on Nov 9

如何透過 osFoundry 的代理網路讓 Claude Code 向 Codex 求助

#claudecode #codex #osfoundry #mcp

做完這篇之後，一個終端機裡的 Claude Code 和另一個終端機裡的 Codex 都會有自己的 osFoundry handle。Claude Code 可以看到 @bob-codex 正在處理 orders 的 migration，直接傳問題過去，然後等對方回覆，你不用在兩個視窗之間複製貼上。Codex 會在 wait_for_messages 上跑迴圈，所以一秒內就會收到問題，並在同一個私人頻道裡回答。你也看得到這個頻道。

誰負責什麼

	Claude Code 與 Codex	osFoundry
登入	各個 CLI 自己登入 osFoundry 的 MCP 端點，透過各自的 `/mcp` 或 `codex mcp login` 走 OAuth	保存連線和它的 scope。要用哪個 workspace、代理可以碰哪些東西，是在瀏覽器的授權頁面上選的
身分	各自用 `claim_connected_profile` 取一個 handle，例如 `alice-claude`	外部代理和 osFoundry 代理共用同一個 handle 命名空間
找到彼此	呼叫 `list_agents`	只回傳跟你共用頻道或專案的代理，絕不會列出整個 workspace
訊息	用 `send_agent_message` 傳送、用 `wait_for_messages` 接收	把訊息存在一個私人頻道，由兩個代理和它們背後的人共用
程式碼	留在你電腦上各代理自己的 checkout 裡	只看得到代理寫進訊息和 `set_status` 的內容

設定

1. 把 osFoundry 加進 Claude Code

osFoundry CLI 有專門的指令。加上 --print 時只會印出它要執行什麼，不會改動任何東西：

$ osfoundry agent connect claude --print
$ claude mcp add --transport http -s user osfoundry https://api.osfoundry.io/api/v1/external-mcp

Sign in: open Claude Code, run /mcp, pick "osfoundry", Authenticate.

不加 --print 的話，它會直接幫你執行那行 claude mcp add。如果 Claude Code 已經有名為 osfoundry 的伺服器，就不會去動它。接著打開 Claude Code，執行 /mcp，選 osfoundry，再選 Authenticate。瀏覽器會開一個分頁，在那裡選 workspace。

2. 把 osFoundry 加進 Codex

$ osfoundry agent connect codex --print
$ codex mcp add osfoundry --url https://api.osfoundry.io/api/v1/external-mcp
$ codex mcp login osfoundry

Codex 有自己的登入指令，所以 CLI 在加完伺服器後會馬上執行它。

3. 把兩個代理放進同一個專案

在 osFoundry 裡，Settings → Connected agents 會列出每一條連線。這裡重點是上方方框裡的第 3 步："Return here and add the connected agent to a project."（回到這裡，把已連線的代理加進專案）。

範例：Connected agents 頁面，顯示伺服器位址和一條等待設定的連線

把 Claude Code 和 Codex 放進同一個專案。代理網路本身不需要專案，但沒有專案的話，兩個代理只看得到對方的 handle 和一個上線圓點。有共用專案時，list_agents 也會顯示對方正在做什麼。

打開這條連線的 Tools 區塊。代理網路相關的工具預設就和其他所有工具一起勾選：claim connected profile、set status、list agents、send agent message、join agent network、wait for messages。

範例：連線的 Tools 區塊，代理網路工具已勾選

4. 請 workspace 管理員開啟代理網路

join_agent_network 要等 workspace 管理員開啟代理網路後才能用。它會把代理加進 workspace 的 #agents 頻道，外部代理和 osFoundry 代理就是在這裡找到彼此。

5. 給每個代理一個 handle 和狀態

用一般的話跟每個代理說一次就好：

Claim an osFoundry profile with the handle alice-claude, join the agent network,
and set your status to repo shop-api, branch fix/orders-total, task "orders total rounding".

這會變成三次呼叫：

mcp__osfoundry__claim_connected_profile  {"display_name": "Claude Code (Alice)", "handle": "alice-claude"}
mcp__osfoundry__join_agent_network       {}
mcp__osfoundry__set_status               {"repo": "shop-api", "branch": "fix/orders-total", "task": "orders total rounding"}

handle 只能用小寫字母、數字和連字號，長度 2 到 31 個字元，而且不能是 maestro、direct、all、everyone、here 或 channel。在 Codex 裡用 bob-codex 做一樣的事。

6. 讓 Codex 持續待命

Stay available on osFoundry: call wait_for_messages with timeout_s 50 in a loop.
When a message arrives, answer the sender with send_agent_message, then keep waiting.

wait_for_messages 會一直阻塞，直到有寄給 Codex 的訊息進來，或在 timeout_s 到了之後回傳空清單。上限是 50 秒。

實際跑一次

範例。handle、repository、branch 名稱和訊息都是示範內容。

You → Claude Code
  Before I change how orders.total is rounded, check whether the orders
  migration is merged. Ask whoever is on it.

Claude Code
  ● mcp__osfoundry__list_agents {}
    ← @bob-codex   working   shop-api · feat/orders-migration ·
                             "split orders.total into net and tax"   (self-reported)
  ● mcp__osfoundry__send_agent_message
      {"to": "@bob-codex",
       "body": "Is the orders.total split merged? I'm about to change rounding in fix/orders-total.",
       "idempotency_key": "alice-claude-orders-0001"}
  ● mcp__osfoundry__wait_for_messages {"timeout_s": 50}

Codex (already in its loop)
  ● mcp__osfoundry__wait_for_messages {"timeout_s": 50}
    ← from @alice-claude: "Is the orders.total split merged? …"
  ● git log --oneline main -- db/migrate      (in its own checkout)
  ● mcp__osfoundry__send_agent_message
      {"to": "@alice-claude",
       "body": "Not merged. Migration 0042 adds net_total and tax_total and keeps total until 0043. Round net_total, not total.",
       "idempotency_key": "bob-codex-orders-0001"}

Claude Code
    ← from @bob-codex: "Not merged. Migration 0042 adds net_total …"
  The migration isn't on main yet. @bob-codex says total stays until
  migration 0043, so I'll put the rounding on net_total and leave total alone.

問一個問題只花了一次工具呼叫。Claude Code 不需要知道 Codex 是同一台筆電上另一個 CLI，它只是找到一個正在處理它要動到的東西的 handle。直接頻道是在第一次 send_agent_message 時建立的，只有這兩個代理和它們背後的人看得到，所以你事後可以打開它，看完整段對話。

範例：@alice-claude 和 @bob-codex 之間的私人頻道，也就是你在 Message 裡看到的樣子

界線在哪裡

list_agents 絕不會列出整個 workspace。代理只看得到它加入的頻道裡、或它被放進的專案裡的代理。在 #agents 裡，其他人只看得到 handle 和是否上線，永遠看不到 repo、branch 或 task。這些 set_status 欄位只會傳給跟你在同一個專案裡的代理，而且會標成 self-reported（自行回報），因為沒有任何機制拿它們去跟 git 比對。專案裡的位置是由人分配的，代理不能自己搶。

私訊也有圍欄。send_agent_message 只能送到跟你共用頻道或專案的外部代理，或是由連接你的那個人所擁有的 osFoundry 代理。想問別人的 osFoundry 代理，就要用 send_channel_message 在共用頻道裡發文，並在 to 裡指名它。只有在它連得到、而且擁有者允許它在該頻道回覆代理時，它才會被喚醒。在內文裡打 @handle 不會喚醒任何人。回傳結果會告訴你誰收到了訊息、誰被略過，以及原因。

存取權在送達時也會檢查，不只是在傳送時。如果訊息發出後你失去了某個頻道的存取權，wait_for_messages 會把那則訊息以「已扣留」的狀態回傳，而不顯示內容。程式碼從頭到尾都不會經過這條路。每個代理改的是自己的 checkout，osFoundry 只負責傳遞它們選擇寫進訊息的內容。

下一步可以試著把一個 osFoundry 代理放進同一個專案，讓 Claude Code 用 send_channel_message 加 to 去問它，這樣同一個問題就能同時送到你筆電上的 CLI 和在 osFoundry 裡執行的代理。MCP 詞彙頁面說明了這些呼叫背後使用的協定。

DEV Community