インストール
Orchestrator のデスクトップアプリをダウンロードし、使っているコーディングツールと接続します。
最新の安定版デスクトップビルドは、Orchestrator の公式ダウンロードページから入手してください。ナイトリービルドとモバイルアプリもこのページにあります。デスクトップのパッケージを直接入手したい場合は、以下から選んでください。
| Platform | Download |
|---|---|
| macOS Apple silicon | |
| macOS Intel | |
| Windows x64 | |
| Linux x64 |
スマートフォンには、iPhone・iPad 用の Orchestrator Mobile または Android 用の Orchestrator Mobile をインストールします。その後、デスクトップアプリの Connect Mobile でペアリングします。
正式なインストール方法はデスクトップアプリです。デスクトップアプリはローカルのデーモンを管理し、グローバルな ao コマンドを必要とせず、起動後と実行中に更新を確認します。
macOS で Homebrew を使ってインストールする（任意）
推奨するインストール方法は、上のデスクトップ版のダウンロードです。macOS では、既存の Homebrew cask からインストールすることもできます。
brew install --cask agentwrapper/tap/agent-orchestratorデスクトップアプリは通常、自動で更新されます。Homebrew で管理しているインストールを更新するには、Homebrew を更新してから cask をアップグレードします。
brew update
brew upgrade --cask agentwrapper/tap/agent-orchestrator前提条件
| ツール | 必要になる場面 | 理由 |
|---|---|---|
| Git | リポジトリのプロジェクト | 分離されたワークツリーとブランチを作成・管理します。 |
GitHub CLI gh | GitHub のプロジェクト | 既存の認証を使って、リポジトリとプルリクエストを操作します。 |
| 外部のコーディングエージェント（Orchestrator ではハーネスと呼びます） | インストール済みの CLI を使うエージェントセッション | Claude Code、Codex、Cursor、Aider、OpenCode など、対応しているツールをインストールします。最新の一覧とインターフェースの対応状況はエージェント一覧を参照してください。Unreal Agent は、macOS と Linux の Chat 用に Orchestrator に組み込まれています。 |
| tmux | macOS の事前チェックと、旧来またはフォールバックのターミナルセッション | macOS・Linux のデスクトップパッケージに同梱されています。ソースから起動する場合は、システムの tmux が必要になることがあります。Runtime を参照してください。 |
Orchestrator は、コンピューターにすでにインストールされ、サインイン済みのコーディングエージェントを使います。Settings → Harness では、対応エージェントのセットアップと準備状況のチェックができます。エージェントによっては、Orchestrator の外でインストールやサインインが必要です。Unreal Agent は例外で、Chat 専用の組み込みエージェントです。対応プラットフォームと権限には独自の制限があります。エージェント一覧を参照してください。
Orchestrator をセットアップする
デスクトップアプリをインストールして開く
上からお使いのプラットフォーム用のダウンロードを選んでインストールし、Orchestrator を開きます。アプリはローカルの Go デーモンを自動で起動し、監視します。
GitHub で認証する
GitHub のリポジトリを使う場合は、必要に応じて GitHub CLI をインストールし、サインインします。
gh auth login
gh auth statusリポジトリを読み取れ、エージェントに任せるつもりのブランチ操作とプルリクエスト操作ができるアカウントを使ってください。
GitLab の場合は、GitLab のトークンまたは glab でサインインします。ソース管理のセットアップを参照してください。
外部エージェントをインストールしてサインインする
外部からインストールするハーネスは、インストール後に Orchestrator の外で一度実行し、サインインを済ませてください。Orchestrator は、セッションを作成するときに使えるハーネスを検出します。組み込みの Unreal Agent を使う場合は、この手順を飛ばし、対応する macOS または Linux で Chat セッションを作るときに選んでください。
Chat に対応しているかどうかは、ハーネスとそのインストール済みバージョンによって異なります。エージェントの機能一覧を参照してください。
プロジェクトを追加する
デスクトップアプリで Add project を選び、既存のローカル Git リポジトリを選択します。Orchestrator は、元のチェックアウトを移動せずにリポジトリを登録します。ワーカーセッションごとに、分離されたワークツリーが作られます。
リポジトリが不要な作業には、プロジェクトに属さないスタンドアロンのタスクを始めることもできます。任意の CLI では ao spawn --standalone --agent codex --name notes --prompt "Draft release notes" のように実行します。スタンドアロンのワーカーは PR を担当できず、Git やプロジェクトのフラグも使えません。
旧来の npm CLI
npm の CLI をすでにお使いですか？@aoagents/ao は 0.10.0 で更新を終了しており、現在は推奨していません。
0.10.0 が npm の最後のリリースです。このパッケージは既存ユーザー向けの移行用として残っており、新しい機能は追加されません。このインストールから ao start を実行すると、デスクトップビルドを取得して開きます。
npm install -g @aoagents/ao
ao start新しく使い始める場合は、デスクトップアプリを直接インストールしてください。
Orchestrator のデータの保存場所
Orchestrator のアプリケーションの状態は、既定ですべて ~/.ao に保存されます。デーモンのデータベース、実行ファイル（run file）、管理対象のワークツリー、Electron のブラウザデータ、モバイルのペアリング設定も含まれます。高度な構成では、AO_DATA_DIR と AO_RUN_FILE でデーモンのパスを変更できます。
インストール時によくある問題
使えるエージェントがない
外部のハーネスの場合は、インストールして一度実行し、認証を済ませてから Orchestrator を再起動してください。デスクトップから起動したデーモンが、更新されたログインシェルの環境を受け取ります。Unreal Agent は、対応する macOS と Linux の Chat 用に Orchestrator に組み込まれています。CLI をインストールせずに、そのまま選んでください。
GitHub のデータが表示されない
gh auth status を実行してください。有効なアカウントが、リポジトリとそのプルリクエストにアクセスできることを確認します。
macOS や Linux で Terminal UI が起動しない
パッケージ版のビルドには tmux が同梱されています。新しいセッションは通常ネイティブの PTY ホストを使いますが、macOS では tmux が使えるかどうかを引き続き確認し、古いセッションでは tmux が必要になることがあります。ソースからのインストールとフォールバックの動作については、ランタイムの診断を参照してください。
旧来の `ao` コマンドが見つからない
デスクトップアプリにこのコマンドは必要ありません。更新を終了した旧来の CLI を意図して使う場合にだけ、パッケージマネージャーのグローバルな bin パスを調べてください。
macOS で「開発元を検証できません」と表示される
Finder で Orchestrator を右クリックして「開く」を選び、確認ダイアログでもう一度「開く」を選びます。それでも macOS がアプリをブロックする場合は、次の診断コマンドを実行し、Issue を作成するときに出力を添えてください。
sw_vers
codesign -dvvv "/Applications/Agent Orchestrator.app"
spctl -a -t exec -vvv --ignore-cache --no-cache "/Applications/Agent Orchestrator.app"
log show --last 10m --predicate 'subsystem == "com.apple.syspolicy"'