open-computer-use

Open Computer Use

概要

Open Computer Use は、Computer Use をローカル CLI および stdio MCP サーバーとして提供します。Codex.app 専用ではありません。使用するエージェントの実行環境に合わせて、コマンドと MCP 設定を調整してください。

macOS ランタイムには macOS 14.0 以降が必要です。Windows と Linux では各プラットフォーム独自のランタイムを使用するため、この macOS の最小要件は適用されません。

macOS、Linux、Windows の各環境で、同じ基本ツールをサポートしています。 list_apps、get_app_state、click、perform_secondary_action、scroll、 drag、type_text、press_key、set_value。

macOS ランタイムには、テキスト要素内の指定したテキストを選択するか、その前または後にテキストカーソルを配置する select_text も実装されています（selection：text、cursor_before、 cursor_after）。アクセシビリティツリーに表示されるとおりの text を渡してください。一意に特定できない場合は prefix／ suffix も渡します。対象が曖昧な場合、最初の一致を黙って選択するのではなく、処理は失敗します。JavaScript では app.selectText(elementIndex, text, options?) を使用します。範囲の検証ができない場合や一致しない場合は、すべてのアクションの読み戻しが無効でも例外が発生します。Windows と Linux のランタイムでは、まだこのツールは実装されていません。

macOS ではさらに query が利用できます。これは、ツリーのレンダリングやスクリーンショットの撮影をせずに、テキストやロールでコントロールを検索する、対象を絞ったアクセシビリティ検索です。

基本的なワークフロー

1. macOS では、CLI を実行する前に sw_vers -productVersion を実行し、macOS 14.0 以降であることを確認します。これより古いバージョンではランタイムを起動できないことを説明してください。バイナリの非互換性に対する解決策として、doctor や権限の変更を推奨しないでください。
2. open-computer-use -h または ocu -h を実行して、CLI がインストールされていることを確認します。インストールまたはセットアップが未完了の場合は、references/installation.md を参照してください。
3. 対応する macOS バージョンでは、最初の実際の GUI タスクの前に open-computer-use doctor を実行します。権限が不足している場合は、オンボーディング UI でアクセシビリティと画面収録を許可するようユーザーに依頼してください。
4. 操作を開始する前に、利用可能なアプリを確認します：open-computer-use call list_apps。
5. open-computer-use call get_app_state --args '{"app":"TextEdit"}' を使って、現在の UI 状態を取得します。通常、既定の状態で UI の操作には十分です。
6. チャット履歴、メール本文、ドキュメントのテキスト、長文コンテンツなど、意味的に長いテキストが必要なタスクでは、text_limit: 1000 または text_limit: "max" を指定して get_app_state を呼び出します。
7. スクロールしても表示中の長いページやリストが不完全な場合は、より大きな max_tree_nodes または max_tree_depth を指定して get_app_state を呼び出します。
8. 直近の get_app_state の結果に含まれる element_index を使った、要素を対象とするアクションを優先します。
9. 複数ステップの CLI 操作では、open-computer-use call --calls '<json-array>' を使用すると、1 つのプロセス内で最新の要素インデックスのマッピングを再利用できます。
10. ローカル MCP サーバーに対応したエージェントの実行環境では、open-computer-use mcp または ocu mcp を設定し、公開されている Computer Use ツールを直接呼び出します。references/usage.md を参照してください。
11. コードを直接使ってオーケストレーションする場合は、ocu capabilities を実行し、その後、1 回限りの ocu js または永続的な ocu repl を使用します。references/usage.md を参照してください。
12. 通信、権限、またはデスクトップセッションへのアクセスに失敗する場合は、references/troubleshooting.md を参照してください。

操作ルール

• 対象のデスクトップは、ユーザーの実際のセッションとして扱ってください。ユーザーが明示的に依頼した場合を除き、パスワードマネージャー、無関係な個人コンテンツ、機密性の高いアプリを調べないでください。
• 送信、削除、購入、承認、アップロードなど、外部から見える変更を行う前に確認してください。
• Codex.app のプラグインヘルパーが利用できると想定しないでください。インストール済みの open-computer-use / ocu CLI、または明示的な MCP 設定を使用してください。
• get_app_state または macOS の query が返すインデックスは、同じネイティブセッション内で使用してください。セッションをまたいだり、UI に大きな変更があった後にインデックスを推測してはいけません。
• セマンティックアクションと、編集可能なコントロールに対する set_value を優先してください。要素ツリーに安全な対象が表示されない場合に限り、座標指定の click、scroll、drag を使用してください。
• macOS では、ユーザーが click_method: "global"、ウィンドウサーバーのドラッグセッションを必要とする drag（ウィンドウの移動、ドラッグ選択によるテキスト選択、Finder でのドラッグ＆ドロップ）、または実際のポインターを動かす可能性があるその他の診断動作を明示的に要求した場合を除き、OPEN_COMPUTER_USE_ALLOW_GLOBAL_POINTER_FALLBACKS=1 を有効にしないでください。この設定がない場合、drag は Drag delivered via app_post を報告し、これらの操作は効果がありません。代替手段については references/usage.md を参照してください。
• Windows と Linux では、GUI オートメーションを利用できると想定する前に、コマンドがログイン済みのデスクトップセッション内で実行されていることを確認してください。

よく使う CLI アクション

open-computer-use -h
ocu -h
ocu capabilities --json
ocu js 'nodeRepl.write(6 * 7)'
ocu repl
open-computer-use doctor
open-computer-use call list_apps
ocu call list_apps
open-computer-use call get_app_state --args '{"app":"TextEdit"}'
open-computer-use call get_app_state --args '{"app":"TextEdit","text_limit":1000}'
open-computer-use call get_app_state --args '{"app":"TextEdit","text_limit":"max"}'
open-computer-use call get_app_state --args '{"app":"Google Chrome","max_tree_nodes":3000,"max_tree_depth":96}'
open-computer-use call click --args '{"app":"TextEdit","element_index":"0"}'
open-computer-use call type_text --args '{"app":"TextEdit","text":"Hello from Open Computer Use"}'

1 つのプロセス内で状態を再利用する短いシーケンスの場合：

open-computer-use call --calls '[
  {"tool":"get_app_state","args":{"app":"TextEdit"}},
  {"tool":"press_key","args":{"app":"TextEdit","key":"Return"}}
]'

MCP の使用方法

stdio 経由でローカル MCP サーバーを起動できるランタイムでは、次を使用してください。

[mcp_servers.open_computer_use]
command = "open-computer-use"
args = ["mcp"]

JSON 設定の例、ツールを直接呼び出すパターン、プラットフォームに関する注意事項については、references/usage.md をお読みください。

参考資料

• references/installation.md：CLI の初回インストール、エージェント向け MCP インストールコマンド、macOS の権限設定。
• references/usage.md：MCP の設定、CLI の直接呼び出し、シーケンス処理、プラットフォームごとの動作。
• references/troubleshooting.md：権限、デスクトップセッション、アプリの検出、アクションの失敗。