如何讓 Claude 在你的桌機上執行 osFoundry Graph 並等待結果

完成後，Claude 的對話會啟動你已儲存的某個 osFoundry Graph，也就是那種會分支、平行展開、失敗時重試的多步驟 agent 程式，而且執行是在你自己的桌機上進行，不在 Claude 裡，也不在伺服器上。Claude 會立刻拿到一張 ticket，在桌機處理期間持續查詢狀態，最後用 Graph 的結果回答你。如果你中途改變主意，Claude 也可以取消它。

誰負責什麼

設定

這裡假設 Claude connector 已經建好（鑰匙圖示 → Connected → Add assistant，接著在 Claude 中把 https://api.osfoundry.io/api/v1/external-mcp 加成自訂 connector）。

1. 在桌機上準備一個已儲存的 Graph session

Graph 存在裝置上。你可以透過 Maestro、agent 或 osStudio 撰寫或編輯，每個儲存後的 Graph 都會拿到一個 session ID，格式是 gs_ 加上 32 個十六進位字元。桌面 app 的 Graph 畫面會列出它們。只在瀏覽器裡看過的 Graph 無法分享，因為瀏覽器沒辦法執行它。

範例：桌面應用程式的 Graph 畫面，列出已儲存的 Graph 工作階段

2. 把 Claude 連線加入一個專案

在鑰匙圖示 → Connected 中選取 Claude 連線。在 Projects 底下選一個專案，點 Add to project（加入專案）。Claude 只會在這個專案裡找 Graph。

範例：Claude 連線的 Projects 區塊，已加入一個專案

3. 把 Graph session 分享到該專案

在同一個 Connected 分頁再往下，只有桌面 app 才有一個叫 Share desktop Graph sessions（分享桌機 Graph session）的區塊。你擁有的每個專案都會列在這裡，這台裝置上儲存的 Graph session 以核取方塊呈現：

Share desktop Graph sessions
Choose the saved Graph sessions to share with each project, then enable that project.
Your desktop must be open and signed in.

Launch plan · workspace                      [ Share selected Graphs ]
  [x] Weekly KPI digest
  [ ] Release notes draft

範例：在 Share desktop Graph sessions 中為一個專案勾選一個工作階段

先勾選 session，再點 Share selected Graphs。如果什麼都沒勾，app 會用 "Choose at least one Graph session for this project first." 擋下你。分享一個專案並不會分享裝置上所有的 Graph。每個 session 都是各自獨立的決定，而且是以專案為單位。

4. 讓桌面 app 保持開啟

桌面 app 每 20 秒會檢查一次專案裡有沒有排隊中的執行，你變更分享內容時也會立刻檢查。如果 app 關著，Claude 的請求就會一直留在佇列裡，直到 app 再次開啟。

5. 請 Claude 執行

In osFoundry, run the Weekly KPI digest Graph in the Launch plan project
for week 2026-W45, and tell me the three biggest changes.

實際跑一次

下面的專案、Graph 和數字都是範例資料。工具名稱和參數名稱則是正式伺服器在 tools/list 中列出的名稱。在 Claude Code 裡，同樣的工具會以 mcp__osfoundry__run_graph_session 這類名稱出現。

範例

Claude → list_granted_resources {}
       ← projects: Launch plan
Claude → list_graph_sessions {"project_id": "<Launch plan>"}
       ← Weekly KPI digest  (gs_3f…, weekly-kpi-digest v3, ready)
         Release notes draft 沒有出現：因為從來沒被勾選
Claude → run_graph_session {"graph_session_id": "gs_3f…",
                            "arguments": {"week": "2026-W45"},
                            "idempotency_key": "kpi-2026-w45-a"}
       [Claude 請你允許這次工具呼叫 → Allow]
       ← command_id "8c1e…", status queued
Claude → get_graph_run {"command_id": "8c1e…"}
       ← queued            （桌機還沒來輪詢）
Claude → get_graph_run {"command_id": "8c1e…"}
       ← running
Claude → get_graph_run {"command_id": "8c1e…"}
       ← completed
         result: {"execution_id": "GR-0007L", "status": "completed",
                  "result": {...}, "total_tokens": 18412, "reported_cost": 0.07}

Claude：第 45 週：註冊數 +18%，試用轉付費從 9.1% 降到 7.4%，
        而週二上版之後客服工單翻倍。

第一次 get_graph_run 回傳 queued，並不是 Claude 那端在拖延。沒有任何東西會主動推送到你的桌機。是桌機自己向伺服器要工作，在它下一次檢查之前，這次執行就只是在排隊。一旦被拉取，桌機會用 Graph 畫面所用的同一個指令來執行 Graph，再把結果回傳。Claude 最後讀到的是這份回傳的結果，不是即時串流。

這次執行也會歸檔在桌機上的 Launch plan 專案底下。執行中用到的專案脈絡和聊天紀錄搜尋，範圍都只限這個專案，不會更廣。

要停止時，Claude 會用同一個 command_id 呼叫 cancel_graph_run。還在排隊的執行會被直接取消，根本不會開始。已經在跑的則會收到取消請求，桌機每 3 秒檢查一次，並把它轉給正在執行的 Graph。

界線在哪裡

Graph 不會離開裝置。list_graph_sessions 只回傳中繼資料：名稱、說明、slug、版本和狀態。Claude 永遠看不到腳本、它呼叫的 agent，或它們碰到的檔案。這也是為什麼 Claude 在看不到任何 schema 的情況下傳入 arguments。如果你希望 Claude 把參數填好，就在 Graph 的說明裡寫清楚有哪些輸入。

執行交給桌機，是因為 Graph 的 agent、本機模型、資料夾和核准設定全都在那裡。伺服器只保存佇列和最終結果。桌機離線時，排隊中的執行會等它上線。Claude 沒辦法把它們送到其他地方。

執行過程中沒有人盯著。設定成每次都要詢問的工具會被直接拒絕，而不是跳出提示，因為沒人回應的提示會讓執行卡上好幾分鐘，最後還是失敗。不需要詢問的工具則照常執行。如果某個 Graph 依賴你要手動核准的工具，請自己從 Graph 畫面執行那個 Graph。

回傳的內容有上限。結果包含執行 ID、狀態、result、token 數和回報的費用，而且只有在 JSON 不超過 100,000 字元時才會完整回傳。更大的結果只會回傳 ID 和狀態，並附上 result_truncated: true，完整紀錄則留在桌機的執行歷史裡。錯誤訊息會在 2,000 字元處截斷。

只有啟動該次執行的 agent 才能讀取或取消它。其他連線查詢同一個 command_id，會得到 "Graph run not found or access removed"，跟查詢不存在的 ID 時是同樣的回應。

在執行開始之前，你隨時都能撤回分享。如果在執行還在排隊時取消勾選 session，或點 Stop sharing（停止分享），桌機會在執行前重新確認，並以 "Graph session is no longer shared with this project" 取消它。

下一步

分享一個小型 Graph，請 Claude 執行，接著趁它還在排隊時點 Stop sharing，看看 Claude 怎麼回報取消。osFoundry 一開始如何把工作分給多個 agent，可以看 Maestro 協作編排頁面，連線清單本身則在 Connected 頁面。