3行でいうと

  • 入れるものは3つです。Orcaのアプリ、gitのリポジトリ（ローカルの作業用コピー）、使いたいエージェントのCLIとそのログインです。最初の手順のページは前提の一覧を載せていませんが、ローカルのgitのチェックアウトと、使うエージェントへのアクセスを前提にした流れになっています。
  • アプリは公式サイトのダウンロードページから入れます。macOSはDMGかHomebrew、WindowsはインストーラのEXE、LinuxはAppImage・.deb・.rpmから選びます。
  • 最初の起動で、ホームフォルダへのアクセスを求められ、~/.claude、~/.codex、Ghosttyの設定があれば取り込みを聞かれます。そのあと「Add Repo」でリポジトリを追加します。
  • Claude CodeとCodexは、どの端末からでも一度ログインしておけば、Orcaが ~/.claude、~/.codex を読みます。読んだ範囲では、エージェントを動かす手順にOrca自体のサインインは出てきません。
  • 公式ドキュメントの間で、設定画面の名前やCLIの登録場所に食い違いがあります。この記事は、食い違いを併記し、手元の画面と照らして確かめる前提で書いています。

この記事は、公式の資料を2026年10月25日に読んでまとめたものです。この記事は、実際に使って確かめた記録ではありません。運営者は Orca を入れていますが、使い心地はこの記事には書いていません。手順は「公式の手順を順に並べたもの」で、コマンドは公式ページの例を、取得した要約から並べたものです。システムに何かを登録する操作は、必ず公式ページの原文を見て入力してください。

先に結論

前提：用語をそろえる

たとえ話：先に道具と食材を用意する

厨房（Orca）を開く前に、食材（gitのリポジトリ）と料理人の身分証（エージェントのログイン）をそろえておく、というイメージです。厨房に入ってからでも身分証は取れますが、手順は、先にそろえておくほうが短くなります。これは僕らのたとえで、公式の表現ではありません。

手順0：入れる前に用意するもの

公式の最初の手順のページは、前提を明示していません。同じページが「前の手順」としてInstallを示し、ローカルのgitのチェックアウトと、使うエージェントにアクセスできることを前提にしている、と読めます（このページの前提の読み取りは僕らのものです）。

  1. gitのリポジトリを1つ決める。 手元にチェックアウトがあるものを使います。Orcaは、gitの代わりではなく、ふつうのgitのworktreeを使います（04）。
  2. 使うエージェントのCLIを入れて、一度ログインする。 公式のエージェント別ページの記載は、次のとおりです。
エージェント 入れ方（公式ページの記載） ログイン
Claude Code npm i -g @anthropic-ai/claude-code、またはAnthropicのドキュメントに従う どの端末からでも一度ログイン。Orcaは ~/.claude を自動で読む（「追加の設定は要らない」と書かれている）
Codex OpenAIのドキュメントに従う どの端末からでも一度ログイン。Orcaは ~/.codex を読む
Cursor CLI Cursorのドキュメント（cursor.com/cli）に従う 一度ログイン。Orcaは、PATH上のCLIを自動で見つける
  1. ほかのCLIを使う場合。 公式の「Supported agents」は、ターミナルで動くCLIなら使える、と書いています。一覧にあるものは、組み込みの選択肢（agent combobox）に最初から入っています。一覧にない独自の起動コマンドを登録する専用の欄は、そのページには書かれていません。ただし設定の「Agents」には、エージェントごとに、実行ファイルのパスや名前、コマンド、引数、環境変数を上書きする項目があります。

つまずきの目安：エージェントCLIが、Orcaの外の普通のターミナルでも動かないなら、Orcaの問題ではなく、CLIのインストールかログインの問題です（公式のTroubleshootingがこの切り分けを最初に挙げています）。

手順1：macOSに入れる

公式のInstallページに書かれている入れ方は、2通りです。

1-A：DMGから入れる

  1. 公式サイトのダウンロードページ（onorca.dev/download）を開きます。Installページには、メールでダウンロードリンクを送る「Send download link」もある、と書かれています。
  2. Apple Siliconなら orca-macos-arm64.dmg、Intelなら orca-macos-x64.dmg を選びます。
  3. DMGを開き、アプリをインストールします。ドラッグ先などの細かい画面は、公式ページに書かれていません。
  4. 初めて起動すると、macOSが確認を出すことがあります。公式は、アプリは署名と公証（notarize）が済んでいて、確認が出るのはElectronアプリでは普通のことだ、と書いています。

1-B：Homebrewで入れる

brew install --cask stablyai/orca/orca

macOSでのCLIの置き場所

トラブルシューティングのページに、macOSではCLIのシムが ~/.local/bin に入る、と書かれています。ここがシェルのPATHに入っているかを確かめます（手順5）。

手順2：Windowsに入れる

  1. 公式のダウンロードページから、インストーラ（orca-windows-setup.exe）を入れます。ダウンロードページそのものは、この記事では読み直していません（対応するWindowsの版は、公式サイトで確認してください）。
  2. インストーラを実行します。インストーラの画面の細かい手順や、SmartScreenなどの警告の扱いは、公式のInstallページには書かれていません。
  3. 公式の記載によると、同梱の orca コマンドはネイティブで、Visual C++ Redistributableは要りません。トラブルシューティングには、インストーラがネイティブの orca をPATHに追加すると書かれています。反映のため新しいターミナルを開くことは、公式の記載ではなく、一般的な話です。
  4. 既定のシェルは、アプリの「Settings → Terminal」で、PowerShellかCommand Promptに変えられます。WSLを使う場合は後述（手順6の表）。

Windows on ARMの機械で動くかどうかは、読んだページには書かれていません。入れる前に、公式のダウンロードページとリリースノートで確かめてください。

手順3：Linuxに入れる

Installページの記載は次のとおりです。

形式 公式の記載
AppImage orca-linux.AppImage。自動更新を使いたいならAppImage、と書かれている
.deb、.rpm ページは、GitHub Releasesの一般のページへリンクしている（具体的なファイル名は、そのページには書かれていない）。更新があると、パッケージマネージャーのコマンドを表示する。そのコマンドを実行する前に、Orcaを終了する、と書かれている
Arch Linux（AUR） READMEに yay -S stably-orca-bin（ソースからなら stably-orca-git）がある

手順4：最初の起動

公式のInstallページによる、初回起動の流れです。

  1. Orcaを起動します。
  2. ホームフォルダへのアクセスを求められます。リポジトリを追加するためです。許可するかどうかは、自分で決めます。
  3. ~/.claude、~/.codex、Ghosttyの端末の設定が見つかれば、取り込みを提案されます。ターミナルのページには、Ghosttyの配色・フォント・カーソルが初回起動で取り込まれ、あとから「Settings → Terminal → Import from Ghostty」で取り込み直せる、とあります。
  4. 何もない最初の画面（landing screen）が出ます。ここで、最初のリポジトリを追加します（手順6）。

メモ：画面の細かい見た目（ボタンの形、メニューの階層）は、公式のページに書かれていないものは、ここにも書きません。

手順5：Orca CLI（orca コマンド）を登録する（任意）

Orca CLIは、アプリに同梱されています。エージェントやスクリプトからOrcaを動かすときに使います（07）。最初の1回だけなら、飛ばして構いません。

  1. アプリで設定を開きます（設定ページは、macOSの Cmd-, で開き、キーワードで検索できる、と書いています）。
  2. 「General」の「Orca CLI」で、CLIを登録します。
  3. 新しいターミナルで確かめます。
command -v orca
orca status --json

command -v orca が場所を返し、orca status --json が応答すれば、アプリとCLIがつながっています。CLIは、動いているOrcaのアプリを操作するので、アプリが起動している必要があります（公式は、動いているエディタをスクリプトで操作する、と書いています。バージョンの条件は、overviewには書かれていません）。

食い違いの併記： 登録の場所は、Settings reference、CLI overview、Troubleshootingでは「Settings → General → Orca CLI」です（Installのページ自体は、CLIの登録場所を書いていません）。一方、CLI referenceのページは「Settings → Experimental → CLI」と書いています。どちらが手元の画面にあるかは、画面で確かめてください。

手順6：リポジトリを追加して、最初のworktreeを作る

ここは、公式の「Your first 3-agent session」の手順1〜3に沿っています。コマンドや例の依頼文は、そのページには書かれていません。

6-1：リポジトリを追加する

  1. サイドバーの「Add Repo」をクリックして、ローカルのチェックアウトを選びます。
  2. Orcaが、リポジトリのgitの状態を読み、既定のブランチを「base ref」にします。新しいworktreeは、これから分岐します。
  3. 結果：リポジトリがサイドバーに出ます。base refは、あとからリポジトリの設定で変えられます。

6-2：worktreeを作る

  1. サイドバーで、リポジトリ名の横の「+」をクリックします。
  2. 作業の名前を入れます（公式の例は fix-login-race）。空欄なら、Orcaが名前を作ります。設定の「General」には「Default new-worktree name」があり、接頭辞か、海の生き物の名前を選べます。
  3. ランチャーで、既定のエージェントが先に選ばれています（「Settings → Agents」で決めたもの）。空のターミナル（Blank Terminal）も選べます。
  4. 「start-from」の参照を選びます。通常は origin/main ですが、ほかのブランチやコミットも選べます。
  5. 結果：Orcaが、管理するフォルダの中にgit worktreeを作り、ブランチをチェックアウトして開きます。

worktreeのページには、さらに次の記載があります。

6-3：エージェントを選ぶ

  1. 新しいworktreeのターミナルで、「agent combobox」から、Claude Code、Codex、Cursor CLIなどを選びます。
  2. 結果：Orcaが、そのエージェントのCLIを、worktreeのフォルダで起動します。契約の認証情報は、そのまま渡されます。

Claude Codeは、公式のページによると、ステータス行のフックつきで起動され、状態の点（state dots）が出ます。CodexはOrcaが codex をworktreeのフォルダで動かし、いま選ばれているアカウントで認証します。Cursor CLIは、CLIが出す状態のイベントを読んで状態の点を出します。モデルの選択は、Orcaは上書きしません（CLIの中で設定）。

手でバイナリ名を打った場合： 公式の「Agents & sessions」によると、Orcaがそれを認識せず、状態のしるしが出ないことがあります。組み込みの選択から起動すると、状態が出ます。

手順7：初期設定の見どころ

設定の全体は、公式の「Settings reference」にあります。最初に見る価値がある項目を、公式のページにある名前で並べます。既定値は、そのページが書いているものだけを載せます。

設定の場所（公式の表記） 何の設定か 公式が書く既定値・注意
Agents → Installed agents 見つかったCLIの有効・無効。起動メニューに出すものを絞る （既定値の記載なし）
Agents → Per-agent launch defaults CLIの実行ファイルのパス・名前、コマンド、引数、環境変数の上書き 構造化チャットも同じ保存済みのコマンドと引数を使う（環境変数までは書かれていない）
Agents → Agent permissions 新しいセッションの許可の方式。Manual、Auto、Yolo 既定の方式は、そのページに書かれていない。Autoが使えるのはClaude、Claude Agent Teams、Codex。それ以外は「Other agents」の設定
Agents → Trust the folder when Orca starts an agent Orcaが起動したエージェント自身の「フォルダを信頼するか」の確認を省く オンが既定
Agents → Run each Codex terminal on its own server Codexのタブごとに裏のサーバーを分ける（Codex 0.157以降） オンが既定。新しいターミナルから効く
Agents → Agent status hooks working、waiting、doneの表示 orca agent hooks on|off|status でも操作
Terminal → Default shell 新しいローカルのタブのシェル 空なら、システムの既定。Windowsは、PowerShell、Command Prompt、WSLも選べる
Terminal → Shell arguments Unixの独自シェルの引数 既定は -l（ログインシェル）
Notifications エージェント終了の通知（System、sound、chip）、カテゴリごとの音、機械ごとの通知 （既定値の記載なし）
General → Updates 更新の確認 自動更新が既定。RCは修飾キーつきクリック（手順8-C）
Privacy（テレメトリのページの表記） 「Share anonymous usage data」 設定の一覧のページには、この節が見当たらない（食い違い）
Repository → Worktree Shared Paths gitに入れていないファイルを新しいworktreeへ複製・リンク 手順9
Experimental Activity Page、Agent hibernation、Agent Dashboard、Chat UIなど 使うときだけ有効にする（公式は「Experimental」と書く）

Agent permissionsについて（事実だけ）。 公式の「Supported agents」は、新しい起動で、各CLIの許可を省くフラグを事前入力する、と書いています（Claude Codeは --dangerously-skip-permissions、Codexは --dangerously-bypass-approvals-and-sandbox、ほかの一部は --yolo）。切り替えは「Settings → Agents → Agent Permissions」で、起動引数や環境を自分で上書きしたエージェントは、この切り替えの対象外です。同じページの「Agents & sessions」にも、既定でフルの自律のフラグを当てる、と書かれています。最初の1回を動かす前に、この設定がどうなっているかを、画面で確かめてください。Autoの扱いは、ページ同士で書き方が違います（設定の一覧はAutoを挙げ、Supported agentsはYoloとManualの切り替えだけを書き、Autoには触れていません）。また、Supported agentsは、ClaudeとCodexのネイティブチャットの既定は「Settings → Chat → Behavior」で別に決まると書いていますが、設定の一覧は、新しいセッションの許可の既定は「Agents」にあって、Chatの節にはない、と読める書き方です。どちらが手元の画面に当たるかは、画面で確かめてください。

手順7-A：Claudeの複数アカウント、Codexの複数アカウント

手順8：動作を確かめる

8-A：エージェントが動くか

  1. 手順6の worktree で、エージェントを選びます。
  2. ターミナルにエージェントのプロンプトが出ることを確かめます。
  3. 簡単な依頼を入れます。この記事の例：「README.md の先頭に、このプロジェクトの目的を1文で足して。ほかのファイルは触らないで」。（「この記事の例」で、公式の例ではありません。）
  4. 状態の点が、動作中（スピナー）から、終了（エメラルドの点）に変わるかを見ます。公式の「Agents & sessions」の説明では、スピナーが作業中、琥珀の「?」が入力待ち、エメラルドの点が完了または静かな状態、赤い点が中断や失敗、灰色の点が待機、です。
  5. 差分（diff）の画面を開き、READMEの変更が見えることを確かめます。

8-B：CLIがつながるか

orca status --json
orca worktree ps --json

2つ目は、worktreeの一覧です（CLI overviewの例）。JSONが返れば、つながっています。

8-C：更新とRC（任意）

8-D：ログとフィードバック

「Help → Open Logs」でログのフォルダが開きます。「Help → Send Feedback」では、スクリーンショットやログを添えて送れます。GitHub IssuesとDiscordも窓口として書かれています。

手順9：任意の設定：gitに入っていないファイルを持ち込む

新しいworktreeには、gitに入れていないファイル（.env、依存のフォルダなど）が入っていません。公式のworktreeのページに、3つの方法があります。

  1. Settings → Repository → Worktree Shared Paths。 主チェックアウトからファイルを持ち込みます。macOSでは、可能ならAPFSのクローンコピー、ダメならシンボリックリンクです。
  2. orca.yaml の worktree.sharedDirectories。 gitに入れていないフォルダ（node_modules、.cache など）を、コピーではなくリンクで共有します。実在するフォルダで、gitの管理外であることが条件です。
  3. リポジトリ直下の .worktreeinclude。 複製したいgit管理外のファイルやフォルダ（.env など）を、1つずつ書きます。使えるのはリテラルのパスだけで、ワイルドカードや否定は、警告つきで飛ばされます。

orca.yaml の項目は、ユーザーのShared Pathsの一覧に足されます（置き換えはしません）。.env などの秘密の値を持ち込むことになるので、何が複製されるかを、worktreeを作る前に確かめてください。

つまずきと直し方

公式のTroubleshooting & FAQにある項目に沿っています。

症状 公式が書く原因・直し方
エージェントが起動しない まず、Orcaの外の普通のターミナルで、そのCLIを動かす。そこでも失敗するなら、CLIのインストールかログインの問題。Orcaが見ているPATHにCLIがあるかを「Settings → Agents」で確かめ、タブの「Restart」チップを押す
エージェントCLIが見つからない CLIがOrcaの使うPATHにない。PATHに足して、「Settings → Agents」で確かめる
orca が「command not found」 CLIが未登録か、置き場所がPATHにない。「Settings → General → Orca CLI」で登録。macOSは ~/.local/bin をPATHに
Codexで path must be shorter than SUN_LEN Codex 0.157以降で、Orca管理のアカウントのhomeのソケットのパスが長い場合。Orca v1.4.212以降に更新すると、自動で直る。アカウントの移動や config.toml の編集は要らない
worktreeが作れない start-from refを取得していないか、そのブランチのworktreeがすでにある。リポジトリで git fetch origin を実行する。既存のworktreeを消すか、別のブランチ名にする
diffが古い、おかしい rebase、resetなどのgit操作が、更新の間に起きた可能性。diffのツールバーの更新アイコンを押す
gh が入っていないと言われるが、端末では動く PATHにある、固まる gh のランチャーが原因の可能性。Orcaは、バージョン確認を通るほうを使う。次の3つのコマンドで確かめる 
gh auth status -h github.com
gh api user
gh api rate_limit --jq '.resources.core'
症状 公式が書く原因・直し方（続き）
ブラウザで browser_no_tab 今のworktreeにタブがない。orca tab create --url ... を実行するか、ブラウザのペインを開いてアドレスを入れる
Kerberosのログインが失敗（SSH） klist で有効なチケットを確認し、OpenSSHの設定のそのHostに GSSAPIAuthentication yes があるか確かめ、「Settings → SSH」でテストし直す
状態の点が出ない Troubleshootingのページには書かれていません。手でバイナリ名を打つと、状態が出ないことがある、と「Agents & sessions」にあります

気をつけること

出典