Orca の初期設定ガイド。Mac で Claude・Codex を使い始める手順

本記事のポイント

• Orca の初期設定は、CLI の導入と検出、権限設定、worktree の作成、実際の編集と差分確認の順で進めます。今回は Mac の Orca 1.4.198 で、Codex に README を編集させるところまで確認しました。
• Orca を Manual に切り替えても、CLI の既存設定は残ります。今回の環境では個別の起動引数を設定し、Codex の起動後に Workspace (Ask for approval) と表示されることを確認しました。
• 作業中の修正を引き継ぐ場合は、新しい worktree の作成元に必要な変更が含まれるかを確認します。初回は、既存の仕事から独立した小さな作業で試すと確認範囲を絞れます。

Orca の初期設定を、Mac に入れたバージョン 1.4.198 で試しました。Claude Code は最初から検出されましたが、Codex は一覧に出ていませんでした。検出できるようにしたあとも、権限設定と編集時の補助プログラムで確認が必要になりました。

この記事では、通常の導入手順に沿って設定を説明し、今回の環境で起きた問題と対処も紹介します。公式情報と実機の確認日は 2026 年 9 月 9 日です。

1. 最初に確認する設定と、今回の環境

Orca をダウンロードしたあとは、使う CLI を確認し、権限を設定してから練習用の worktree を作ります。最初の到達点は、AI に小さな変更を頼み、その差分を自分で確認できる状態です。

1. Claude Code または Codex の CLI を用意し、Orca で検出されるか確認します。
2. Agent Permissions と、使う CLI の個別起動引数を確認します。
3. プロジェクトを追加し、作成元を選んで worktree を作ります。
4. エージェントを起動し、権限表示と、依頼後の差分を確認します。

今回使った環境と設定は、次のとおりです。

Orca の基本や公式アプリとの違いから知りたい場合は、Orca・IDE・Claude・Codex の比較記事で使い分けを確認できます。

2. CLI を用意し、Orca で検出されるか確認する

CLI が未導入の場合は、公式の導入手順から用意します。CLI は、文字のコマンドで操作するソフトウェアの使い方です。まずターミナルで各 CLI を起動し、作業依頼を送る前にログイン状態を確認します。

Orca は、Claude Code の ~/.claude と、Codex の ~/.codex を読み取ります。すでに CLI を使っている場合は再インストールから始めず、そのまま起動・認証できるかを確認してください。Claude Code の準備、Codex の準備

Orca で ⌘, を押して設定を開き、左側の「Agent」を選びます。使用する CLI が検出され、有効になっているかを確認してください。導入やパスを変更した場合は、「更新」で検出し直します。

PATH は、コマンドを実行するときに実行ファイルを探すフォルダの一覧です。公式のトラブルシューティングも、CLI の手動起動と PATH の確認から始めています。Orca のトラブルシューティング

今回の Mac では、Codex の検出後にも対処が必要でした

Claude Code 2.1.265 は最初から検出されました。Codex 0.153.4 は ChatGPT.app 内の Contents/Resources/codex にあり、この場所が PATH 探索外だったため、Orca では未検出でした。

最初は ~/.local/bin/codex に実体を指すシンボリックリンクを作りました。別の場所にあるファイルを参照する仕組みで、更新後は Orca に Codex が表示されました。ただし、この段階では編集まで確認できていませんでした。

失敗時は、リンクを置いたフォルダ内の codex-code-mode-host を探していました。補助プログラムの実体はアプリ本体側にあり、実行可能な状態でした。

そこで、今回作成したリンクだけを、アプリ内 CLI の実体パスを起動するランチャーに置き換えました。その後は同じ README の編集が成功し、差分も確認できました。

この対処は、アプリ内の Codex を使った今回の環境に固有の事例です。初めて導入する場合は公式 CLI の手順から進め、一覧への表示だけで完了とせず、最後に小さな編集まで試してください。

3. Manual に切り替え、各 CLI の権限を確認する

設定の「Agent」で「Agent の権限」を開き、「手動（Manual）」を選びます。そのうえで、各 CLI の既存設定と個別引数を確認します。今回の環境では、Orca の切り替え後も Codex が以前から使っていた権限設定を引き継ぎました。

Orca の既定の Yolo では、Claude Code に --dangerously-skip-permissions、Codex に --dangerously-bypass-approvals-and-sandbox といった引数が設定されます。これらは、CLI の承認確認や sandbox を回避する指定です。sandbox は、プログラムが操作できる範囲を制限する仕組みです。Orca の権限設定

図 1. Manual に切り替えた直後です。個別の起動引数を設定する前の状態です。

Manual に変えても、Codex の既存設定が残っていました

切り替え直後、Orca 側の Claude と Codex の個別引数は空でした。ところが、練習用のブランクターミナルで codex と入力すると、権限は YOLO と表示されました。

この環境の ~/.codex/config.toml には、approval_policy = "never" と sandbox_mode = "danger-full-access" が設定されていました。Orca の Manual は、各 CLI のグローバル設定を初期化する機能ではありません。

ほかの作業で使っているグローバル設定は維持し、Orca から起動する場合の引数を指定することにしました。

使うエージェントの「引数」に権限を指定します

設定画面のエージェント一覧で、Claude と Codex をそれぞれ開き、「引数」に次の値を設定しました。

この引数は、新しいタブでエージェントのメニューから起動するときに使います。ブランクターミナルに codex と直接入力する操作とは分けてください。

on-request は、すべての書き込みで人の承認を求める指定ではありません。起動時の権限確認に加え、依頼後の差分を自分で確認する工程も残します。

Claude Code 2.1.265 では、インストール済み CLI のヘルプで manual が選べることを確認しました。起動後も manual mode on の表示を確認しています。

図 2. Claude と Codex に指定した起動引数です。上部の二択表示と、個別に入力した引数を分けて確認します。

個別引数を設定すると、この版では全体の二択が Yolo 側の表示になりました。入力した引数は保持されており、Codex の起動後には Workspace (Ask for approval) と表示されることも確認しています。

全体のボタン表示だけで判断せず、個別の引数と起動後の状態を確認してください。個別設定があるエージェントは、全体の Manual 切り替えでは上書きされません。

4. 作業中だけ Mac のスリープを抑える

長い依頼を動かす場合は、Keep computer awake の Agent を選ぶ方法があります。今回は Off から Agent へ変更しました。Orca の設定一覧

設定場所は Agent です。既定エージェントの Claude は、そのまま維持しました。

表示を日本語にする場合は、Appearance の Language から「日本語」を選べます。日本語 JIS キーボードでは、必要に応じて Terminal の円記号をバックスラッシュへ変換する設定も確認できます。

長時間実行時の安定性や電池消費は測定していません。ここで確認したのは、Agent に設定できたことです。

5. 作成元を選び、練習用の worktree を作る

最初は、既存の仕事から独立したリポジトリで worktree を作ります。この手順には Git で管理されたフォルダが必要です。今回は README と AGENTS だけを含む練習用リポジトリに最初のコミットを用意し、実業務のファイルは使いませんでした。

Git はファイルの変更履歴を管理する仕組みで、リポジトリはその管理単位です。worktree は、一つのリポジトリから別の作業用フォルダを作る機能です。

日本語の画面では「新規ワークスペース」から「プロジェクトを追加」でリポジトリを登録し、登録した名前の横の「＋」で作成画面を開きます。今回は次の値を選びました。Orca の初回セッション手順

図 3. 今回用いた作成設定を、入力例として再表示した画面です。worktree を重複作成したものではありません。

指定した名前の作業フォルダが作成されました。ブランクターミナルで開き、できた場所を確認してからエージェントを起動します。

既存の仕事を引き継ぐ場合は、未コミット変更を確認します

ブランチは、変更履歴を分けて進めるための枝です。コミットは、変更を履歴に記録した単位です。新しい worktree は、選んだブランチやコミットの状態から作られます。

仕事を途中から引き継ぐ場合は、必要な修正がその作成元に含まれるかを確認します。元のフォルダに未コミットの変更が残っていても、新しい worktree に自動で入る前提にはできません。Orca の worktree 解説

今回は新規の練習用リポジトリを使ったため、ほかのエージェントの仕事の移動や、一括コミットは行っていません。

共有パスは、必要な対象を決めてから追加します

Worktree Shared Paths は、macOS では可能なら APFS の clone-copy を使い、それ以外ではシンボリックリンクを使います。共有されるパスがすべて同じ実体を指すとは限りません。

.worktreeinclude は、Git 管理外のファイルやディレクトリを独立してコピーする方式です。ただし、すでに共有・リンクされる対象は、ここに追加しても再コピーされません。

複数の仕事を分ける段階では、編集する範囲と統合する担当も決めます。Orca での並列作業と公開担当の分け方では、その運用例を説明しています。

6. 起動後の権限と、実際の変更差分を確認する

新しいタブの Codex メニューから起動し、権限を確認したあと、README に一文を追加する依頼を試しました。起動、編集、差分の順に確認すると、途中で止まる箇所も分かります。

まず /status で Permissions: Workspace (Ask for approval) と表示されることを確認しました。Orca に設定した個別引数を使うため、エージェントのメニューから起動しています。

ブランクターミナルに codex と直接入力した最初の試験では、既存のグローバル設定を引き継いでいました。同じ CLI でも、起動方法と渡された引数を確認する必要がありました。

小さな依頼を送り、変更された箇所を見ます

Codex には、README の末尾に「OrcaからCodexの起動と差分確認を試しました。」という一文を加えるよう依頼しました。第 2 章のランチャー修正後、新しいセッションで同じ依頼が完了しました。

AI の完了メッセージに加え、実際の差分でも依頼した内容だけが追加されたことを確認しました。今回の確認は、Codex の起動からファイル編集までです。

図 4. README の変更差分です。追加した一文と空行の、合計 2 行を確認しました。

起動時に追加フックを信頼するか尋ねられた場面では、Continue without trusting を選びました。今回は追加フックを信頼する設定にせず、確認を進めました。

Claude は manual モードでの読み取りを確認しました

別の新しいタブでは Claude を選び、練習用フォルダを信頼して起動しました。起動引数の --permission-mode manual と、画面下部の manual mode on を確認しました。

Claude には README だけを読み、末尾の日本語の一文を答えるよう依頼しました。Read ツールで README を読み、Codex が追加した「OrcaからCodexの起動と差分確認を試しました。」という文を正確に回答しました。

今回の検証範囲は、Codex が編集と差分確認まで、Claude が起動と読み取りまでです。Claude にファイルを書き換えさせる試験は行っていません。

まとめ

Orca の初期設定では、CLI の検出、権限設定、worktree の作成、実際の編集までを一巡させると、使い始める準備ができたかを確認できます。今回は Codex の検出後にも編集時の問題が見つかったため、一覧に名前が出た時点では完了にしませんでした。

既存の CLI 設定を使う場合は、Orca の Manual 表示だけで判断せず、起動後の権限を確認してください。最初の一件は変更範囲を小さくし、差分を確認できてから並列作業を増やすと進めやすくなります。

humbulls の Growth Partnerでは、少人数の BtoB マーケティングに合わせた AI 活用と実行体制の設計を支援しています。

参考文献

• Orca：Supported agents
• Orca：Settings reference
• Orca：Claude Code in Orca
• Orca：Codex in Orca
• Orca：Worktrees
• Orca：Your first 3-agent session
• Orca：Troubleshooting & FAQ