CLI・MCP・A2A 連携

Codex や WorkBuddy などのローカル Agent は MCP または CLI + Skill で OpenFiles を利用できます。A2A ともファイル機能とタスク管理を共有します。通常は下記のインストールと setup だけで接続できます。A2A は独自クライアント向けで、/a2a は MCP URL ではありません。呼び出し元は 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 登録、~/.agents/skills/openfiles への Skill 導入を行います。codex コマンドが必要です。完了後は Codex を再起動して設定を読み込みます。

openfiles setup codex

WorkBuddy に接続する

次のコマンドで OpenFiles を起動または接続し、~/.workbuddy/mcp.json にサーバーを追加します。他のサーバーを維持し、元の設定をバックアップします。完了後は 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 へ変換します。保存済み .ofw は openfiles_workflow で実行し、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/agent/connection.json です。独自の場所にはデスクトップの --agent-connection=PATH とクライアントの --connection PATH を合わせます。bearer token は公開しないでください。例の dist/agent/openfiles.cjs はインストール先のパスに置き換えられます。チャットの外向き MCP 設定はこのゲートウェイとは別です。

A2A の呼び出し

接続ファイルのループバック URL から /.well-known/agent-card.json を取得します。securityRequirements が bearer 認証を示します。/a2a に以下の JSON を POST し、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}
  }
}