本文へスキップ本文へスキップ
開発環境

Orcaを導入したら最初に何を設定する?AI開発環境の初期設定と使い方

~7 min

Orcaを導入したら最初に何を設定する?AI開発環境の初期設定と使い方
目次

Orcaを入れたものの、リポジトリ、worktree、AIエージェントの設定が並んでいて、何から始めるか迷う。最初に目指したいのは、一つの作業場所でAIが起動し、小さな変更を差分で確認できる状態です。

自分は複数の個人開発を行き来する中でOrcaを使うようになりました。ただ、この記事は初回セットアップを新しくやり直した実録ではありません。2026年10月29日時点のOrca公式Docsをもとに、初めて使う人が確認する順番を整理しています。画面名は更新で変わる場合があります。

対象はonorca.devのOrca⁠(外部サイト)です。同名の別ツールと混同しないよう、ダウンロード元から確認してください。

最初に切り分けたい三つの役割

Orcaそのものと、そこから動かすAI、開くプロジェクトを分けると理解しやすくなります。

要素

担当すること

最初の確認

Orca

作業場所、エージェント、ターミナル、差分などをまとめる

公式版を起動できるか

Claude Codeなどのエージェント

コードを調べたり変更したりする

対象CLIの起動とログインができるか

Gitリポジトリ

アプリのソースコードと履歴を持つ

開くフォルダと基準ブランチが正しいか

Orcaを起動できても、エージェント側の認証や契約が整っていなければAI作業は始まりません。逆に、外のターミナルで使えているエージェントがOrcaで動かないなら、作業ディレクトリやシェル環境から調べられます。

1. まずは安定版を入れ、必要なアクセスだけ確認する

公式InstallページからOSに合う版を選びます。macOSはApple SiliconとIntelの配布が分かれています。新機能を追うためのRC版もありますが、初回の基準を作るなら安定版の方が調査対象を増やさずに済みます。公式Install⁠(外部サイト)

初回起動ではホームディレクトリへのアクセスや、既存のClaude Code・Codex・ターミナル設定の取り込みが案内されています。何を読み込むのかを確認して進めます。認証ファイルの中身をAIへ貼り付ける必要はありません。

テーマや分割レイアウトは後でも変えられます。最初は、自分が使うシェルと文字が読める表示になっているかを確認すれば十分です。

2. AIエージェントは、先に単体で使える状態にする

Claude Codeを使う場合、公式DocsはCLIのインストールとログインを先に済ませる流れを案内しています。Orcaは既存の設定を認識してエージェントを起動します。Claude Code in Orca⁠(外部サイト)

ターミナルで確認するなら、例えば次のようにバージョンと起動可否を見ます。

claude --version
claude

これはClaude Codeを選ぶ場合の確認例です。未導入なら、リンク先から現在の公式インストール手順へ進んでください。プロジェクトのパッケージマネージャを変える作業とは別です。

ここでログインできないなら、まずエージェント側の問題を解消します。Orcaの表示設定を変えても認証の問題は解決しません。エラー画面を共有するときも、メールアドレス、トークン、パスなどは伏せます。

3. Add Repoで、実際のGitリポジトリを開く

公式の初回手順は、サイドバーのAdd Repoからローカルのcheckoutを追加する流れです。ダウンロードしたZIPのフォルダと、Gitで管理されているリポジトリを混同しないようにします。初回セッションの手順⁠(外部サイト)

追加前には、対象フォルダで次を確認すると事故を減らせます。

git status --short --branch
git branch --show-current

一つ目は未コミット変更とブランチの確認、二つ目は現在のブランチ名の確認です。どちらも変更を加えないコマンドです。

既存の変更があるときは、誰の何の変更かを把握してから作業を始めます。「最初だから一度きれいにする」と、内容を見ずにリセットする必要はありません。

4. worktreeは「別の作業用フォルダ」と考える

worktreeは、一つのリポジトリに対して別の作業フォルダを持つGitの仕組みです。Orcaでは、タスクごとに作業を分ける中心になります。worktreeの公式説明⁠(外部サイト)

公式手順ではリポジトリ名の横の+から作業を作り、名前と開始元のrefを選びます。ここで大事なのは「何を基準にした作業か」です。古い基準から始めると、最新の修正が入っていない状態でAIへ依頼してしまいます。

また、元フォルダの未コミット変更やGit管理外の.envが、新しい作業場所へ必ず引き継がれるとは考えない方が安全です。作成後に実際のファイルと設定を確認してください。

worktreeで分かれるのはソースコードの作業場所です。共有DB、外部API、同じポートで動く開発サーバーまで自動で分離されるわけではありません。初回は並列化せず、一つの作業場所を確実に動かす方が状況を追えます。

5. プロジェクトのルールを読み、依存関係を整える

開いたら、README、AGENTS.mdやCLAUDE.mdなど、そのプロジェクトで管理している指示を確認します。インストールや起動のコマンドは、リポジトリの指定に従います。

例えばpnpmのプロジェクトへ、慣れているからとnpmで別のlockfileを作ると、初期設定のつもりが環境変更になります。必要なNode.jsなどのバージョンも確認します。

環境変数は、実際の秘密値ではなく.env.exampleなどの項目名を出発点にします。開発用の接続先を使い、起動しただけで本番データへ書き込まない構成になっているかを見ます。

最初のAIへの依頼も、変更より調査から始められます。

まずREADMEとプロジェクトの指示ファイルを読んでください。
この作業場所、現在のブランチ、起動方法、必要な環境変数の名前を確認してください。
秘密値は表示せず、まだコードや依存関係は変更しないでください。

これは開始時の指示例です。AIが報告した内容を、ターミナルやファイルでも確かめます。

6. 小さな変更で、差分確認まで一周する

最初の成功条件は「エージェントが起動した」だけではありません。説明文の一部など、影響が小さい変更を依頼し、変更ファイルと差分を確認するところまで進めます。

予想外の設定変更、依存関係の追加、秘密情報の出力がないかを見ます。必要な確認が通るまでは、commitやpushへ進めなくてもかまいません。

見た目を直す作業なら、開発サーバーを起動してブラウザでも確認します。差分が正しくても、表示や操作が正しいとは限らないからです。

起動できないときは、何を比べる?

状況

先に確認すること

外のターミナルでもAIが起動しない

CLIの導入、認証、契約条件

外では起動するがOrcaでは失敗

使用シェル、PATH、エージェントの起動設定

AIは起動するがコードが見つからない

選択中のworktreeと作業ディレクトリ

元フォルダではアプリが動くがworktreeでは動かない

依存関係、Git管理外の設定、接続先

開発サーバーが起動しない

使っているポート、必要なランタイム、起動ログ

変更が別の場所へ入ったように見える

現在のフォルダ、ブランチ、差分の比較先

設定画面にはエージェント、ターミナル、通知などの項目があります。困っている対象に合わせて確認する方が、設定を一度に変えるより原因を追えます。Settings reference⁠(外部サイト)

最初に増やしたいのは、エージェント数より確認できる範囲

Orcaの魅力は複数の作業をまとめられることですが、初日から全部の機能を使う必要はありません。

一つのリポジトリ、一つのworktree、一つのエージェントで、起動・変更・差分確認まで進める。この流れをつかんでから並列作業やOrchestrationへ広げると、何が便利になり、どこで管理が増えるかを判断しやすくなります。

Orca自体の概要と使い始めた背景は、Orcaの基本紹介に書いています。本記事は、その次の「最初の作業を始めるまで」に絞りました。

過去の記事から 1 本

全 36 本のうち 3 本目の記事

related

関連記事

about

このブログについて

Web 開発・インフラ・AI を手を動かして試した記録が中心です。うまくいった話もハマった話も、仕事や日々のこともそのまま書きます。