如何讓 Codex CLI 把任務交給 osFoundry 的 agent、team 或 loop session

做完之後，Codex CLI 就能把不該自己做的工作，交給 osFoundry 裡的一個 session：agent session、team session 或 loop。它會送出一個目標、一段它目前已知內容的摘要，以及它希望拿回來的產出。Session 的 owner 會收到通知，按下 Accept and run（接受並執行）或 Decline（拒絕）。Run 結束後，Codex 會在同一個終端機 session 裡讀取結果，然後繼續工作。如果改給它一個 Runner 席位，它就能自己啟動一次有上限的 run，完全不需要點擊。

誰負責什麼

	Codex CLI	osFoundry
登入	你自己的 Codex 登入。osFoundry 的 OAuth token 由 Codex 保管	只核准一次連線，範圍是一個 workspace 和你勾選的 scope
能存取什麼	被邀請加入的 session，透過七個 *_session_* 工具	由席位決定：Viewer 只能讀，Contributor 可以貼 note 和提議 handoff，Runner 還能請求 run
誰來執行工作	Codex 繼續在你的 repository 裡工作	Session 在自己的 agent runtime 上執行，用它自己的 agent、工具和模型設定
誰來核准	每個寫入工具執行前，Codex 都會先問你（default_tools_approval_mode = "writes"）	Handoff 會等 session owner 按下 Accept and run。Runner 席位就是 request_session_run 的常設核准
執行多久	呼叫時指定 max_rounds 1 到 10	對 owner 顯示為「Up to N rounds on your agent runtime」
會拿回什麼	這個連線所啟動任務的狀態和結果，以及寄給它的 note	Session 內部的 agent 分析留在 osFoundry 裡

設定

1. 建立連線

在 osFoundry 裡點標頭的鑰匙圖示，打開 Connected 分頁（「Connected agents」）。在「Connect in three steps」底下，把 Assistant 設成 Other MCP client，取一個顯示名稱，例如 Codex CLI，然後點 Add assistant。Owner 在每個 handoff 上都會看到這個名稱，所以請取一個對方認得的名字。

範例：顯示 Codex CLI 連線的 Connected agents 分頁

2. 把 server 加進 Codex，並加上 run scope

codex mcp add osfoundry --url https://api.osfoundry.io/api/v1/external-mcp

接著打開 ~/.codex/config.toml，把這張 table 收斂到這個工作需要的範圍：

[mcp_servers.osfoundry]
url = "https://api.osfoundry.io/api/v1/external-mcp"
scopes = ["osfoundry:read", "osfoundry:write", "osfoundry:run"]
default_tools_approval_mode = "writes"
enabled_tools = [
  "list_granted_resources",
  "list_project_resources",
  "read_session_state",
  "read_session_task_result",
  "read_session_mail",
  "post_session_note",
  "propose_session_handoff",
  "cancel_session_handoff",
  "request_session_run",
]

osfoundry:run 就是 request_session_run 背後的 scope。如果 Codex 只需要提議，就把它拿掉。Handoff 和 note 工具需要 osfoundry:write，三個讀取工具需要 osfoundry:read。設成 "writes" 之後，Codex 會在四個沒有標成 read-only 的工具執行前詢問你，讀取工具則直接執行、不會問。

3. 登入

codex mcp login osfoundry

瀏覽器會打開 osFoundry 的「Connect an agent」頁面。用上面的 scope，「Requested capabilities」會顯示三行，第三行是「Run sessions where you grant a runner role」。選好 workspace，選擇「Use pending: Codex CLI」，勾選核准方塊，再點 Connect。

4. 把連線加到放著該 session 的專案

回到 Connected 分頁，連線會顯示「Connected.」。在 Projects 底下選擇專案，點 Add to project。這樣連線就看得到該專案裡符合條件的 session，但還不能寫入任何一個。

範例：已加入一個專案的 Projects 區塊

5. 在 session 裡給它一個席位

再往下是「Agent, Team, and Loop sessions」。說明文字已經講得很清楚：「Invite it to a session as Contributor to post notes and propose handoffs, or Runner to also request runs. A handoff still needs the session owner's approval.」

Agent, Team, and Loop sessions
  [ Team session ▾ ]  [ Release desk ▾ ]  [ Contributor ▾ ]  [ Save role ]

範例：Agent, Team, and Loop sessions 區塊，Codex CLI 在 team session 中是 Contributor

Session 清單只會列出這個連線已加入的專案裡的 session。選好類型、session 和角色，然後點 Save role。先從 Contributor 開始。之後對同一個 session 儲存 Runner，就會取代原本的角色。

實際跑一次

寫這篇文章的機器上沒有安裝 Codex，所以下面的 session 是模擬的範例。工具名稱和參數名稱都是正式 server 從 tools/list 回傳的名稱，加上 Codex 幫 MCP 工具加的 mcp__osfoundry__ 前綴。Repository、session 和所有數值都是示範內容。

Example (simulated)

> The CSV export fix is merged. Hand the customer note and the KB update
  to the osFoundry Release desk team, then tell me what they wrote.

• mcp__osfoundry__list_granted_resources {}
  ← 1 project: "Billing v2"
• mcp__osfoundry__list_project_resources {"project_id": "…", "resource_type": "team_session",
      "search": "release"}
  ← team_session "Release desk"
• mcp__osfoundry__propose_session_handoff {
      "session_type": "team_session", "session_id": "…",
      "goal": "Write the customer note for the CSV export fix and update the KB article on exports.",
      "context_summary": "Exports over 10k rows were cut at 10,000. Fixed in PR #212 (streams rows, no cap). Affects plans with scheduled exports. No data was lost; re-running an export now returns all rows.",
      "requested_output": "Draft note (<120 words) and the KB article diff, for review.",
      "max_rounds": 4, "idempotency_key": "codex-csv-212-note"}
  [Codex asks: allow this tool call? → yes]
  ← handoff pending owner review

  (in osFoundry the owner opens "Codex CLI requests a handoff" → Review handoff
   → Handoffs → Outside assistant requests → Accept and run)

• mcp__osfoundry__read_session_state {"session_type": "team_session", "session_id": "…"}
  ← running, recent task "Requested by an outside assistant"
• mcp__osfoundry__read_session_task_result {"session_type": "team_session",
      "session_id": "…", "task_id": "…"}
  ← completed: draft note + KB diff
• mcp__osfoundry__post_session_note {"session_type": "team_session", "session_id": "…",
      "subject": "Thanks, one correction",
      "body": "The fix shipped in 3.18.2, not 3.18.1.", "idempotency_key": "codex-csv-212-fix"}
  [Codex asks: allow this tool call? → yes]

The Release desk drafted a 96-word note and a KB diff that replaces the
"exports are capped at 10,000 rows" paragraph. I posted a version
correction back to the session.

Owner 這邊的操作很簡單。通知寫著「Codex CLI requests a handoff」，附上「Review the request in Release desk.」和一個 Review handoff 按鈕，點下去會打開 session 的 Handoffs 分頁。在「Outside assistant requests」底下會完整顯示目標，「Context and expected output」可以展開，而「Up to 4 rounds on your agent runtime」這一行說明這次 run 最多能做多少。Accept and run 會把它排進佇列（「Handoff accepted and run queued」），Decline 則直接結束。

範例：「Codex CLI requests a handoff」通知與 Review handoff 按鈕

範例：session 的 Handoffs 分頁中待處理的外部助理請求，附 Accept and run 與 Decline

如果 Codex 送錯了東西，只要 owner 還沒接受，用 cancel_session_handoff 帶上 handoff_id 就能撤回。

界線在哪裡

提議和執行刻意拆成兩個工具。propose_session_handoff 是去問一個人。它需要 osfoundry:write、Contributor 席位，以及人看得懂的 context_summary 和 requested_output，而且在 owner 點擊之前什麼都不會開始。request_session_run 則跳過點擊。它需要 osfoundry:run 和 owner 事先給的 Runner 席位，也就是說那次點擊早在給席位的時候就做過了。兩者都把 max_rounds 上限設為 10。提議的 goal 上限是 5,000 字元，run 則是 10,000。

Codex 看得到結果，看不到推理過程。read_session_task_result 只會回傳這個連線啟動的任務。read_session_mail 回傳寄給這個連線的 note 和它自己貼的 note，工具說明裡寫著「Internal agent analysis is excluded.」。post_session_note 會加一則署名的 note，session 裡的 agent 可以回覆，而且它「does not trigger an automatic run」。

Session 照樣在原本的地方執行。Handoff 不會把 Codex 的模型、金鑰或 repository 帶進 osFoundry，帶過去的只有文字，session 用自己的 agent 和工具來做事。只存在桌面端本機的東西，例如本機資料夾或尚未同步的項目，都碰不到。Server 的 initialize 回應也這麼寫：「Local-only data is unavailable to cloud clients.」

移除存取權只要一個點擊。在 Connected 分頁移除席位或撤銷連線，Codex 下一次呼叫 session 就會被拒絕。

第一次嘗試，很適合拿一個你現在還在手動執行的 loop 來試。把 Codex CLI 以 Contributor 身分邀請進去，在你的 repository 完成一項修改，然後請 Codex 附上這次改了什麼的摘要，提議這個 loop 的下一次 run。Handoffs 說明 osFoundry 自己的 agent 如何在步驟之間傳遞 context，agent sessions 則說明 Handoffs 分頁在哪裡。