初めてのOrcaマニュアル
初心者向け。Claude Code や Codex をターミナルで回したことがある人向け（複数エージェントの並行画面は初めて、でよい）。
対象: AIコーディングCLIは触ったことがある / スマホから監視・続行したい人
版: 2026-09-13（公式 onorca.dev と公開ドキュメント、公開配信の実務メモに基づく）
公式の入口:
- 概要: https://www.onorca.dev/
- ドキュメント: https://www.onorca.dev/docs
- ダウンロード: https://www.onorca.dev/download
- GitHub: https://github.com/stablyai/orca
Orca 本体は MIT のオープンソース。モデルのサブスクは別（持ち込み）。
目次
0. 30秒でわかる
いちばん伝えたいこと: 1つの仕事に、1つの worktree（作業コピー）、1つのエージェント。
ターミナル1本で Claude Code を回す感覚はあるはず。同じリポジトリを、同じフォルダのまま2体に同時に触らせると、ファイルが食い合う。Orca はその食い合いを、git の worktree で止める。
Orca は、あなたがキーを打つための IDE というより、エージェントを並べて走らせる ADE（Agent Development Environment）。Claude Code / Codex / Grok など、すでに入っている CLI を、別々の作業コピーで同時に動かす。モデルそのものではない。
手元のノートが貧弱でも、奥の Mac mini や常時起動の箱で走らせて、スマホの companion（コンパニオン）から監視と続行ができる。スマホ単体では仕事は進まない。動かす側のマシンは起きていて、Orca が起動している必要がある。
1. Orcaとは何か
公式の呼び方は ADE。IDE が「人がコードを書く場所」なら、ADE は「人とエージェントが同じ仕事を進める場所」。画面の中に worktree、ターミナル、差分、ブラウザ、CLI が揃う。
やっていることは、だいたい次の4つ。
- リポジトリを開く
- 仕事ごとに git worktree を切る
- その worktree でエージェント CLI を起動する
- 差分を見て、残すか捨てる
1エージェント＝1 worktree、が基本単位。同じバグを3体に競わせるなら、worktree も3つ作る。ファイルはディスク上で別コピーなので、stash やブランチの付け替えを人間がやらなくてよい。
Orca がやらないこと:
- モデルを売らない（Claude / Codex / Grok などの契約は今までどおり）
- git の代わりにならない（中身は本物の
git worktree。ターミナルから普通の git も使える） - クラウドの箱を貸さない（リモートで動かすなら、自分の Mac mini / VPS / SSH 先）
Cursor の置き換え、というより、Cursor CLI も含めて「すでに使っているエージェント」を並べる側。エディタとしても使えるが、初日の価値はそこではない。
2. 向いている人 / 向いていない人
向いている人:
- Claude Code / Codex / Grok などの CLI を、すでに1本は回したことがある
- 同じリポで「直す」「試す」「レビューする」を同時にやりたい
- 手元の Air や Windows ノートを食わず、別マシンで走らせたい
- 外出中にスマホで進捗を見て、「続けて」「yes」を返したい
- 差分を自分で読む気がある
向いていない人:
- ノーコードでアプリを完成させたい人（公式も、そういう道具ではないと言っている）
- ターミナルも git も見たことがない人（先に CLI 1本を単体で動かす）
- チャット1窓ですべて終わらせたい人（Orca は窓が増える）
- 差分を読まずに main へ直マージしたい人（並行のうまみが事故になる）
実務で効くパターンは、配信でもよく出る「手元を薄くする」ほう。ノートPCのファンが回り切る前に、奥のマシンへ寄せて、スマホで見る。Claude Code と Codex を同じ画面で併用できるのも、単体 CLI にはないところ。
余談だが、「社内のタスク管理アプリを自作するより、エージェントに投げて GitHub で共有する」という話がある。Orca はその投げ先を、同時に何本も走らせる側。ツールを増やす道具ではない。
3. 用語ミニ辞典
| 用語 | 意味 |
|---|---|
| workspace | 画面上の1仕事。カード1枚。中身はだいたい1つの worktree |
| worktree | git worktree の実体。リポの別コピー＋専用ブランチ。エージェントの作業机 |
| agent | Claude Code などの CLI プロセス。Orca が頭の中を持っているわけではない |
| companion | iOS / Android のモバイルアプリ。デスクトップ（またはサーバ）のリモコン |
| pairing | スマホや別PCを、動いている Orca につなぐ一度きりの紐付け |
| serve | orca serve。画面なしで Orca 実行系だけを立ち上げる（ヘッドレス） |
| Remote Orca Server | 奥のマシンで Orca を常時起動し、手元やスマホは UI 専用にする方式 |
| SSH worktree | 手元の Orca が司令塔のまま、実行だけ SSH 先で行う方式 |
| Chat UI | ターミナルの上に被せたチャット風の読み面。本体はターミナル側 |
| base ref | 新しい worktree が分岐する基準（だいたい origin/main） |
| Yolo / Manual | エージェント起動時の権限。既定は Yolo 寄り（worktree を使い捨て前提） |
混同しやすいのは workspace と worktree。会話ではどちらも「この仕事」と呼ぶ。トラブルのときは、ディスク上のコピー（worktree）と、画面のカード（workspace）を分けて考える。
companion は編集器ではない。公式の言い方は read-mostly。見る、返す、止める、小さなコミット。長い編集はデスクトップ。
4. 最短セットアップ
初日はローカル1台で足りる。Mac mini 遠隔と orca serve は、1体が動いてから。
4-1. 先に用意するもの
- git リポジトリ（実験用のコピーでよい。本番 main 直は後回し）
- 使いたいエージェント CLI が、そのマシンに入っていてログイン済み
- Orca 本体
CLI が入っていないと、Orca を開いてもランチャーが空振りする。認証エラーはだいたい CLI 側。
4-2. デスクトップ（Mac を主経路）
ダウンロードページ から。
| OS | 入れ方 |
|---|---|
| macOS Apple Silicon | DMG、または brew install --cask stablyai/orca/orca |
| macOS Intel | Intel 用 DMG（チップは「このMacについて」） |
| Windows 10/11 | x64 インストーラ |
| Linux | Universal AppImage（実行権限を付けて起動） |
起動したら、Settings → Agents で CLI が見えているか確認。見つからないときは PATH の話なので、ターミナルで which claude や which codex が通るか先に見る。
4-3. モバイル（companion）
デスクトップが動いてから。
- iOS: App Store の Orca
Android: 公式の APK（サイドロード。手順は Android APK）
- デスクトップのアカウント / ステータスメニューから pairing を開く。一度きりのコードが出る
- スマホで Pair → コードを貼る（ディープリンクでも可）
- 使えるなら Orca Relay を優先（Relay だけサインインが要る）。LAN 直は任意
ペアリングは一度。以後の正はデスクトップ側。デスクトップを閉じると、LAN 直のセッションは切れる。Relay も、ホスト側の Orca が落ちればついていけない。
4-4. 初日にやらなくてよいこと
SSH worktree、Remote Orca Server、orca serve、Cloud VM。
1体が差分を出すまで、箱を増やさない。
5. 初めての1時間
公式の「最初の3エージェント」を、1体に縮めた版。成功条件は「指示を出して、差分が見える」。
5-1. リポジトリを開く
- サイドバーの Add Repo
- ローカルの git checkout を指す
- Orca がデフォルトブランチを base ref にする（あとからリポ設定で変更可）
5-2. worktree を1つ作る
- リポ名の横の +
- 仕事の名前を入れる（空欄だと海の生き物の名前が付く）
- start-from は、初めてなら base ref（
origin/mainが多い） - エージェントを選ぶ。迷ったら、いま手元で一番慣れている CLI
Orca は管理ディレクトリの下に本物の git worktree を切って、ブランチを checkout する。作成は裏で進むので、失敗したらタブの Retry。
5-3. 指示を送る
ターミナル（または Chat UI）に、いつも CLI へ書くのと同じ密度で書く。
このリポジトリの README か、入口のファイルを読んで。
「よくあるつまずき」を3行で追記して。
既存の見出しスタイルに合わせる。
テストや依存の追加はしない。
終わったら変更ファイルを列挙して。危ない操作の前に聞いてほしいなら、その一文を足す。既定が Yolo 寄りでも、プロンプト側の禁止は効く。
5-4. 差分を見る
エージェントが落ち着いたら、その worktree の diff を開く。比較対象の初期値は start-from。
見るもの:
- 触ってほしくないファイルが混ざっていないか
- 削除が多すぎないか
- コミットするならメッセージは自分で読む
気に入らなければ worktree ごと消してよい。それが worktree を切った意味。残すなら Orca 内から commit / push できる。
1時間で3体レースまで行かなくてよい。1体が差分を出した時点で、セットアップは成功。
6. 並行の基本
2体目は、同じリポの + をもう一度。新しい worktree、新しいブランチ、新しいエージェント。同じプロンプトを貼って競わせてもいいし、仕事を分けてもいい。
衝突を避けるコツ:
- 机を分ける。 同じ worktree の中で Claude と Codex を同居させない
- 入口を揃える。 両方とも汚れた作業コピーから切らず、base ref から切る
- ファイルを分ける。 片方に UI、もう片方にテスト、のように担当を書く。同じ関数を2体に直させると、あとのマージがつらい
- 勝者だけ残す。 差分を見比べ、残すほうを PR にする。負けた worktree は消す
- 使い終わったら眠らせる。 開きっぱなしの worktree はファイル監視でメモリを食う
依存（node_modules など）は、新しい worktree では最初から入っていない。毎回インストールするか、リポ設定の共有パス（Worktree Shared Paths / orca.yaml の sharedDirectories）を使う。秘密ファイルは .worktreeinclude でコピーする、というのが公式の分け方。初日は「インストールし直す」で足りる。
タブを端にドラッグすると分割できる。監視は楽しいが、ブラウザを何枚も開くと RAM が先に死ぬ。見ないペインは閉じる。
7. モバイルコンパニオン
スマホの意味は、席を外してもエージェントを孤児にしないこと。買い物中に完了通知が来て、追加の一文を返す。公式サイトの利用者コメントにも、同じ使い方が載っている。
できること（読みと短い操作が中心）:
- 全ホストの worktree と状態（working / done / 入力待ち）
- 直近のターミナル出力、Chat UI への切り替え
continue/yes/ 短い追記、写真添付、音声入力- 小さな Source Control（stage / commit）
- アカウント切り替えと使用量
- エージェント完了のプッシュ通知
できないこと（初日の期待値）:
- デスクトップ級のエディタ
- ホストが落ちた状態での単独実行
ペアリングの考え方: スマホはクライアント。セッションの正は、ペアしたデスクトップか Remote Orca Server。コードは数分で期限切れ。失敗したら新しいコードを出す。デスクトップとスマホのバージョンが離れると、相手を拒否することがある。そのときは両方更新して、だめならホストを Remove して再ペア。
遠隔で本当に効くのは、実行マシンを分けるとき。公式の楽な経路は、奥のマシンと手元の両方に Orca を入れ、私有ネットワーク（Tailscale などが例）でつなぎ、奥を Settings → Remote Orca Servers → Advertise this app as a server にする。エージェント CLI のログインは奥のマシン側。手元でログイン済みでも、奥には自動で移らない。
画面のない Linux なら orca serve --pairing-address <届くホスト名>。デスクトップアプリですでに共有しているマシンに、二重で serve しない。ポートをインターネットへ直開放しない。公式も、私有網や SSH、認証つきトンネルを使え、と書いている。
手元のファンが回り切る前に、奥へ寄せる。これが並行の実利。
8. よくあるつまずき
| 症状 | まず疑うこと |
|---|---|
| エージェントが起動しない / 見えない | CLI 未導入、未ログイン、Orca から見た PATH。ターミナルで同じコマンドを直打ちする |
| サイドバーに worktree がいない | Sleeping フィルタ、他クライアント作成分の非表示、作成失敗のままの行 |
| worktree が汚い | 前の仕事の未コミット、gitignore の依存不足、同じブランチ名の取り合い |
| 差分がおかしい | ツールバーの refresh。外で rebase / reset した直後 |
| スマホがくるくる | デスクトップ側は idle なのにスマホだけ working、のズレ。行を強制更新。ホストが落ちていないか |
| ペアリング失敗 | 同じ Orca アカウントか、コード期限、トークン無効。Retry → だめなら再ペア |
| Chat UI と中身が違うように見える | 別セッションを見ている。本体はターミナル。Chat UI は同じ PTY の読み面 |
| リモートで CLI がない | サーバ機に入れてない。手元の PATH は使われない |
Chat UI とターミナルの違いは、初日いちばんの引っかかりやすい。
- ターミナル: エージェント CLI の生画面。矢印、確認ダイアログ、TUI。正本
- Chat UI: 読みやすい会話。スキル、モデル pill、質問カード。同じセッションの別窓
- スマホの初期はターミナル寄り。長押しで Chat UI に切り替えられる。端末の既定は Settings → Chat UI
「使い方の画面」で yes を押したつもりが、生ターミナルではまだ待ち、ということが起きる。状態が Needs You（入力待ち）なら、今見ている面がどちらかを先に確認する。
worktree が汚れてきたら、その仕事を終える。別件は新しい worktree。掃除は Resource Manager → Clean up workspaces。消しても git が未マージを理由にブランチを残すことがあり、そのときは Review branches が出る。
9. やってはいけないこと
- 1 worktree に複数エージェントを無理に載せる。 並行の単位は worktree。同じ机で2人が同じファイルを保存するのと同じになる。Claude Agent Teams のような例外は、慣れてから公式ドキュメントで。
- 権限確認を読まずに連打する。 Orca の既定は Yolo 寄り（worktree を使い捨て前提に、毎回のシェル確認を飛ばす）。だからといって、Needs You の質問、sudo、本番デプロイ、秘密情報の送信、ペアリングの承認まで Enter 連打してよい、という意味ではない。Settings → Agents → Agent Permissions で Manual にしたあと、全部 Allow するのも、切り替えた意味がない。
- 本番の main 作業コピーで走らせる。 実験は worktree。残すときだけ PR。
- デスクトップを落として、スマホだけで完走させようとする。 companion はリモコン。実行側が寝たら終わり。
- アクセスリンクや pairing を他人に渡す。ポートを公開ネットに出す。 トークンは取り消せる。渡した相手が違うなら、サーバ側の Shared Server Access から revoke。
- チャットに API キーやワンタイムコードを貼る。 CLI のログインは、そのマシンの正規手順で。
- 負けた実験 worktree をいつまでも残す。 差分の化石とファイル監視だけが残る。
10. 次の一歩
公式:
- 最初の並行: https://www.onorca.dev/docs/first-session
- worktree: https://www.onorca.dev/docs/model/worktrees
- モバイル: https://www.onorca.dev/docs/mobile
- 動かし方の地図: https://www.onorca.dev/docs/ways-to-run
- つまずき: https://www.onorca.dev/docs/troubleshooting
- Discord: https://discord.gg/fzjDKHxv8Q
日本語の解説配信もある（コミュニティ側。製品サポートそのものではない）。
自分の環境で試すチェックリスト
- [ ] デスクトップに Orca を入れた（Mac / Windows / Linux）
- [ ] 使いたい CLI が、同じマシンで単体起動できる
- [ ] 実験用リポを Add Repo した
- [ ] worktree を1つ作り、エージェントの作業ディレクトリがそのコピーになっている
- [ ] 短い指示を1回送り、diff にファイルが出た
- [ ] 気に入らなければ worktree を消せることを確認した
- [ ] （任意）2つ目の worktree で別エージェントを同時に走らせた
- [ ] （任意）スマホをペアし、入力待ちに一言返した
- [ ] （任意）奥のマシンへ実行を寄せ、手元を薄くした
ローカルで1体が差分を出す。そこまでが今日の仕事。並行も遠隔も、そのあとでよい。机を分けたまま捨てられる、というのが結論です。