CLI、MCP 與 A2A 整合

Codex、WorkBuddy 等本機 Agent 可透過 MCP 或 CLI + Skill 使用 OpenFiles；兩者與 A2A 共用檔案能力及任務管理。日常接入只需完成下方安裝與 setup 步驟。A2A 適用於自行開發的用戶端，不能將 /a2a 填入 MCP 位址；呼叫程序必須與 OpenFiles 在同一台電腦上。

安裝 CLI

需要 Node.js 22 或更新版本，以及包含 resources/agent 的 OpenFiles 桌面版本。CLI 隨桌面應用程式提供，從本機目錄安裝一次即可。以下為 macOS 預設安裝位置：

npm install -g "/Applications/OpenFiles.app/Contents/Resources/agent"

Windows 請使用 PowerShell，將範例路徑替換為實際安裝目錄下的 resources\agent：

npm install -g "C:\path\to\OpenFiles\resources\agent"

從原始碼開發時，先在儲存庫執行 npm run build，再執行 npm install -g ./dist/agent。安裝後即可使用 openfiles 命令，不必記住指令碼路徑。

接入 Codex

執行以下命令。它會自動啟動或連接 OpenFiles，透過 Codex CLI 註冊 MCP，並將配套 Skill 安裝至 ~/.agents/skills/openfiles。需有可用的 codex 命令；完成後重新啟動 Codex 載入設定。

openfiles setup codex

接入 WorkBuddy

執行以下命令。它會自動啟動或連接 OpenFiles，將服務合併至 ~/.workbuddy/mcp.json，保留其他 MCP 服務並備份原有設定。完成後重新啟動 WorkBuddy；若需要 CLI + Skill，也可在技能的新增入口匯入命令輸出的 skillArchive ZIP。MCP 本身已可直接使用。

openfiles setup workbuddy

首次 setup 預設建立並授權 ~/OpenFilesAgent，輸出儲存在其 output 子目錄。放入待處理檔案後，可請 Agent 使用 OpenFiles 將 CDR 匯出為包含所有頁面 SVG 的 ZIP，等待完成並回報輸出位置。使用現有目錄時加入 --workspace DIR；--output DIR 指定輸出目錄。--dry-run 僅預覽設定路徑。

授權目錄與桌面路徑儲存在 ~/.openfiles/agent/setup.json。後續 CLI、MCP 及已安裝 Skill 會依設定啟動服務，自動讀取位址與 token；設定不包含固定連接埠或 token。變更執行中閘道的授權目錄時，先退出 OpenFiles 再重試 setup；不會強制中斷現有任務。

官方設定參考： Codex MCP · WorkBuddy MCP

檢查連線與排錯

doctor 僅檢查連線，不啟動應用程式；capabilities 會啟動已設定的桌面服務。schema 可離線查閱工具參數。MCP 顯示已連接只表示介面已啟動，仍應呼叫 capabilities 確認檔案服務可用。

openfiles doctor
openfiles capabilities
openfiles schema openfiles_convert

找不到桌面程式時，以 setup codex --app /absolute/path/to/OpenFiles 指定執行檔（WorkBuddy 請替換用戶端名稱）。Node.js 或安裝位置變更後重新安裝 CLI 並執行 setup。目錄權限問題請核對 readRoots / outputRoots；寫入結果不明時先用 tasks 查找，避免重複提交。

手動啟用閘道（選用）

使用包含 resources/agent/openfiles.cjs 的桌面版本（macOS 位於 OpenFiles.app/Contents/Resources），用戶端需要 Node.js 22 或更新版本。啟動 OpenFiles 執行檔時加入 --agent-read-root=/absolute/input --agent-output-root=/absolute/output。兩個目錄必須已存在，多個目錄可重複傳入參數。閘道預設關閉；變更授權目錄需結束並重新啟動應用程式。原始碼儲存庫提供以下用戶端命令：

npm run build-electron
npm run agent -- capabilities
npm run agent -- mcp-config
npm run agent -- skill

探索能力並執行

先讀取 capabilities：conversionFormats 列出轉換組合，metadata.formats 列出可編輯欄位。openfiles_inspect 傳回個別檔案的轉換目標。呈現接受 HTML、Markdown、SVG，輸出 PNG 或 PDF，並停用指令碼與外部資源。CDR 轉換輸出含全部頁面 SVG 的 ZIP。使用 openfiles_workflow 執行已儲存的 .ofw，sourcePaths 取代檔案輸入節點；批次目錄和遮罩也必須獲得授權。PDF/OFD 中繼資料透過 metadata.edit、metadata.remove 處理。AI 節點需要已安裝執行環境，可能下載模型權重。將以下參數儲存為 request.json 並替換路徑：

JPEG 與熱影像 JPEG 共用副檔名：若檢查結果包含 contentDetectionRequired，列出的目標為候選格式，執行時會依檔案內容確認。

{"sourcePaths":["/input/design.cdr"],"outputDir":"/output","format":"zip"}

node dist/agent/openfiles.cjs call openfiles_convert --input request.json --wait

追蹤與復原工作

寫入會保留原始檔，在 outputDir 下建立新的 openfiles-* 目錄。輪詢至 completed、failed 或 canceled，再檢查 result.paths 與個別檔案錯誤。--wait 預設等待 300 秒，可用 --timeout 調整；逾時後工作仍繼續。重新提交前先用 tasks 找回工作 ID。列表接受 --json 或 --input，可傳入 state、contextId、pageSize、pageToken；輸出產物需查詢個別工作。閘道最多保留 100 個工作，同時執行最多 8 個；重新啟動會清空紀錄。取消會保留已完成的輸出。

node dist/agent/openfiles.cjs tasks
node dist/agent/openfiles.cjs task TASK_ID --wait
node dist/agent/openfiles.cjs cancel TASK_ID

連接 MCP 與安裝 Skill

mcp-config 只列印設定，不修改用戶端；請將命令與參數加入外部用戶端。mcp 透過 stdio 使用換行分隔的 JSON-RPC，skill 輸出隨附的 OpenFiles 指南。預設連線檔為 ~/.openfiles/agent/connection.json。自訂位置時，桌面的 --agent-connection=PATH 與用戶端的 --connection PATH 應相符。請勿公開 bearer token。可將下方範例的 dist/agent/openfiles.cjs 換成安裝包內的用戶端路徑。對話設定中的對外 MCP 服務與此外部閘道獨立設定。

呼叫 A2A

從連線檔讀取本機回環網址，存取 /.well-known/agent-card.json；securityRequirements 宣告 bearer 驗證。向 /a2a POST 以下 JSON，附上 Content-Type: application/json、A2A-Version: 1.0、Authorization: Bearer <token>。網路重試時重用相同訊息 ID 與內容。以 { "id": "TASK_ID" } 呼叫 GetTask 輪詢，或使用 CancelTask。ListTasks 支援 contextId、status、statusTimestampAfter、分頁及 includeArtifacts。不提供串流、推播或自然語言規劃。路徑皆屬於目前電腦；截圖編輯與外掛安裝仍透過桌面介面操作。

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "SendMessage",
  "params": {
    "message": {
      "messageId": "unique-request-id",
      "role": "ROLE_USER",
      "parts": [{"data": {"name": "openfiles_capabilities", "arguments": {}}}]
    },
    "configuration": {"returnImmediately": true}
  }
}