CodexのLocal environmentsをチームで使う前に決めること

3行まとめ

Setup

worktree作成時。

Action

人が押すtask。

Share

.codexを共有。

Scope

sandboxとnetwork。

worktreeで同じように動く状態を先に作ります。

• Codex appのLocal environmentsは、worktree向けのsetup scriptと、projectでよく使うactionsを設定する場所です。
• setup scriptはworktree作成時の準備、actionsは人が押す共通taskとして分けると、環境が重くなりにくくなります。
• .codexをrepoで共有するなら、project root、monorepoでの置き場所、platform差分、sandbox/networkの境界まで一緒に決めます。

この記事では、OpenAI公式のLocal environments、Worktrees、Codex app features、Agent approvals & security、Automations docsを確認し、2026年6月1日時点の情報として整理しています。Codex appの画面、設定項目、platform別の挙動は更新され得るため、導入前に最新docsと手元のapp設定を再確認してください。

この記事でわかること

Install

依存関係。

Build

初期build。

Run

dev server。

Test

検証action。

Local environmentsは、毎回説明する作業を設定に寄せる場所です。

• Local environmentsで何を設定するか
• setup scriptとactionsを分ける理由
• worktreeで依存関係やbuildを再現する考え方
• .codexをrepoで共有するときの注意点
• macOS、Windows、Linuxの差分をどう扱うか
• sandboxとnetwork accessを混ぜない設計
• チーム導入初週に見るべき失敗条件

Codex appでworktreeを使うと、普段のlocal checkoutを触らずに並行作業を進められます。ただし、新しいworktreeは別directoryです。依存関係、生成file、build済みartifact、local設定が揃っていないと、Codexが作業を始めた直後にinstallやbuildで止まります。

Local environmentsは、その最初のつまずきを減らすための設定です。一方で、何でもsetup scriptに入れると、worktreeを作るたびに時間がかかり、原因も追いにくくなります。ここでは、最小限のsetupと、日常的に押すactionsを分けて考えます。

前提知識

項目	内容	見方
Local env		setupとactions。
Worktrees		別checkout。
Features		integrated terminal。
Security		sandboxとnetwork。

手元のCodex appとdocsは導入時に再確認します。

OpenAI公式のLocal environments docsでは、Local environmentsはworktree向けのsetup stepsと、projectのcommon actionsを設定するものとして説明されています。設定はCodex app settings paneから行い、生成されたfileをprojectのGit repositoryへcheck inして他の人と共有できます。

同じdocsでは、Codexがこの設定をproject rootの.codex folderへ保存すること、repositoryに複数projectがある場合は共有したい.codex folderを含むproject directoryを開くことが説明されています。

公式情報で確認する範囲

確認先	見ること
Local environments	setup scripts、actions、.codex共有、platform別script
Worktrees	LocalとWorktree、Handoff、branch、parallel work
Codex app features	integrated terminal、Git tools、modes
Agent approvals & security	sandbox、approval、network access
Automations	background worktreeとproject directoryの扱い

注意点

Local environmentsは、開発環境そのものを完全に固定する仕組みではありません。Node.js、package manager、system dependency、database、secret、外部serviceなどは、projectごとに別の管理が必要です。

この記事で扱うのは、Codex appのworktreeやapp内terminalから、よく使う準備と確認を再現しやすくするための設計です。機密情報や本番操作をsetup scriptへ入れる前提にはしません。

まずsetup scriptとactionを分ける

項目	内容	見方
Setup		worktree開始時。
Action		top barから実行。
Terminal		一回だけの確認。
Script		repoに残すcommand。

依存準備と日常操作を混ぜると、環境が重くなります。

Local environmentsで最初に分けるのは、setup scriptとactionsです。

種類	役割	例
setup script	worktree作成時に自動で準備する	npm install, npm run build
action	人がapp top barから実行する	npm test, npm start
integrated terminal	一回だけの確認に使う	git status, pnpm lint
repo script	package.jsonやMakefileに残す	test, dev, typecheck

setup scriptは、worktreeを作るたびに走るものです。ここに重いtestや長いseed処理を入れると、新しいthreadの開始が遅くなります。actionsは、必要なときに人が押す共通taskです。毎回自動で走らせる必要がないものは、actionへ逃がします。

worktree作成時に必要なもの

setup scriptに入れる候補は、worktreeが最低限作業できる状態になるためのものです。

入れる候補	理由
dependency install	code補完、build、testに必要
initial build	generated typeやartifactが必要な場合
tool install	project内toolが必要な場合
lightweight check	すぐ壊れている環境を検知する

OpenAI公式docsの例では、TypeScript projectでdependenciesをinstallし、initial buildを走らせるsetup scriptが示されています。これは、worktreeがlocal checkoutとは別directoryであるため、依存関係や生成物が揃っていないことがあるからです。

setupに入れすぎないもの

次のような処理は、最初からsetup scriptへ入れないほうが扱いやすいです。

処理	理由
長いintegration test	thread開始のたびに重くなる
本番DB接続	権限と安全性の問題が大きい
deploy	setupではなく明示的な承認が必要
大量seed	失敗時の原因が追いにくい

必要ならactionにして、人間が押す形にします。

人が押す共通task

actionsは、開発サーバー起動、test、lint、typecheck、buildのように、よく使うcommandをapp top barから実行できるようにするものです。公式docsでは、actionsがCodex appのintegrated terminal内で実行されることが説明されています。

たとえば、次のように分けます。

action	command例	使う場面
Dev	npm run dev	browserで確認する
Test	npm test	修正後の回帰確認
Typecheck	npm run typecheck	変更範囲が広いとき
Lint	npm run lint	PR前の確認

one-offのdebugなら、integrated terminalを直接使えば足ります。actionsにするのは、チームで何度も押すものだけです。

.codexをrepoで共有する

Root

project rootを揃える。

Monorepo

project単位で置く。

Review

diffを確認。

Owner

更新担当を決める。

共有設定は便利ですが、project境界を間違えると使いにくくなります。

Local environmentsの設定は、project rootの.codex folderへ保存されます。公式docsでは、生成されたfileをGit repositoryへcheck inして他の人と共有できることが説明されています。

これは便利ですが、共有する以上、差分レビューの対象にします。setup scriptが変わると、他のメンバーのworktree開始時の挙動も変わります。actionsが変わると、チームが押すcommandも変わります。

project rootを間違えない

最初に確認するのは、Codex appで開いているproject directoryです。repository rootとproject rootが一致しているなら簡単ですが、monorepoでは違うことがあります。

たとえば、次のような構成です。

repo/
  apps/
    web/
    admin/
  packages/
    ui/
    auth/

apps/web向けのsetupとactionsを共有したいなら、repo全体ではなく、どのproject directoryをCodex appで開くかを決めます。公式docsでも、repositoryに複数projectがある場合は、共有したい.codex folderを含むproject directoryを開くことが説明されています。

monorepoでの置き場所

monorepoでは、1つの巨大なLocal environmentsにしないほうがよいです。web、admin、mobile、serverで必要なsetupやactionsが違うなら、project単位で分けます。

project	setup例	action例
apps/web	pnpm install, pnpm --filter web build	pnpm --filter web dev
apps/admin	admin向けbuild	admin test
packages/ui	storybook準備	visual test
packages/auth	unit test準備	auth test

共通部分はpackage managerやrepo scriptへ寄せ、Local environmentsにはproject固有の入口を置くと保守しやすくなります。

platform差分を小さくする

項目	内容	見方
Default		共通command。
macOS		必要な差分だけ。
Windows		shell差分を見る。
Linux		CI寄せも検討。

最初からOSごとに分けすぎず、違う部分だけ分けます。

Local environments docsでは、setupがplatform-specificな場合、macOS、Windows、Linux向けのsetup scriptsでdefaultをoverrideできることが説明されています。actionsも同様に、platform-specific scriptsを定義できます。

ただし、最初からOSごとに完全に別scriptへ分けると、設定が読みにくくなります。まず共通commandへ寄せ、違う部分だけplatform別に逃がします。

OS別scriptへ逃がす

OS別scriptへ逃がす候補は、shell、path、native dependency、service起動方法が違うものです。

差分	例
shell	BashとPowerShell
path	/tmp と %TEMP%
native dependency	macOSだけ必要なtool
browser launch	OSごとのopen command

一方、npm install、pnpm test、npm run buildのようなcommandは、できるだけ共通にします。違いをLocal environmentsへ持ち込む前に、package.jsonやscript側で吸収できないかを見ます。

platform差分のレビュー観点

platform別scriptを追加するときは、次の観点でreviewします。

観点	見ること
同じ目的か	OSごとに別作業になっていないか
secretなし	tokenやpasswordを埋めていないか
失敗時	errorが分かる出力になっているか
更新担当	誰がWindows/Linux側も確認するか

platform差分は、動いた人の環境だけで判断しないほうがよいです。

共通commandへ寄せる

Local environmentsを薄く保つには、repo側のscriptを整えます。

{
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "test": "vitest run",
    "typecheck": "tsc --noEmit"
  }
}

Local environmentsには、これらを呼ぶだけのsetupやactionsを置きます。そうすると、Codex app、terminal、CI、人間のlocal作業で同じ入口を使えます。

worktreeで検証できる環境にする

1. 1Install

   依存を入れる。

2. 2Build

   初期build。

3. 3Run

   server起動。

4. 4Test

   検証する。

worktreeだけで確認できるほど、handoff前の手戻りが減ります。

Worktrees docsでは、worktreeがlocal checkoutと別のcheckoutであり、同じrepository metadataを共有しながら、複数branchを並行して扱えることが説明されています。Codex appでは、Worktreeを選んでthreadを開始し、必要ならlocal environment setup scriptを使えます。

Local environmentsの価値は、worktreeで検証できる状態を作ることです。Codexが修正したあと、worktree上でbuildやtestを動かせるなら、handoff前にかなりの問題を潰せます。

dependenciesとbuild

worktreeで最初に必要なのは、dependenciesとbuildです。依存関係がないとtestもlintも動きません。generated typeが必要なprojectでは、initial buildやcodegenも検討します。

ただし、buildが重すぎるなら、setupではなくactionへ分けます。

処理	setup向き	action向き
dependency install	はい	いいえ
short build	場合による	場合による
full e2e	いいえ	はい
dev server	いいえ	はい

setupは「worktreeを作業可能にする」ためのものです。「すべて検証する」場所ではありません。

dev serverとtest

dev serverやtest suiteはactionsにします。Codex app featuresでは、integrated terminalでpnpm testやnpm test、lint系commandを実行でき、よく使うtaskはlocal environment actionとしてshortcut buttonにできることが説明されています。

特にfrontend projectでは、Dev actionとTest actionを分けると便利です。Dev actionでserverを起動し、in-app browserや通常のbrowserで確認します。Test actionは修正後に押します。

Codexにログイン済みChromeや内蔵browserを使わせる話は、公開済み記事のCodexにログイン済みChromeを渡す前にでも扱っています。Local environments側では、まずdev serverを安定して起動できる状態を作るのが先です。

sandboxとnetworkを混ぜない

項目	内容	見方
Setup		依存取得。
Workspace		書き込み範囲。
Network		必要domain。
Approval		止める条件。

setupに必要な通信とagent作業の権限を同じ扱いにしません。

Local environmentsでsetupやactionsを整えても、Codexが何でもできるわけではありません。Agent approvals & security docsでは、Codexがsandbox modeとapproval policyの2層で動くこと、localでは通常workspaceに書き込み範囲が限定され、network accessはdefaultでoffであることが説明されています。

setupに必要な通信と、agent作業時のnetwork accessを同じ扱いにしないことが大事です。

setupに必要な通信

dependency installでは、package registryやGitHub releaseへアクセスしたいことがあります。ここで必要なdomainを確認します。

用途	例
npm package	npm registry
Git dependency	GitHub
browser binary	Playwright download先
private package	社内registry

必要な通信があるなら、広いnetwork accessではなく、目的に合うallowlistを検討します。Codexのnetwork設計は、公開済み記事のCodexにインターネットアクセスを許可する前にでも整理しています。

agent作業時の権限

agentが作業中に必要な権限は、setupとは別です。たとえば、dependenciesをinstallするためにnetworkが必要でも、code修正中に外部送信が必要とは限りません。

権限を増やす前の確認

権限を増やす前に、次を確認します。

確認	理由
path	書き込み範囲を限定する
command	実行してよい操作を決める
network	送信先を絞る
approval	人間へ戻す条件を残す

background automationやworktree作業では、気づかないうちに差分が増えることがあります。Local environmentsで便利なactionsを作るほど、権限境界も見直します。

導入初週の進め方

1. 1日目

   setupを最小化。

2. 2日目

   test action追加。

3. 3日目

   dev server追加。

4. 5日目

   platform差分確認。

5. 7日目

   team共有。

最初は軽い設定にして、失敗した作業だけ足します。

Local environmentsは、最初から完璧に作ろうとしないほうがうまくいきます。まず、worktreeで止まりやすい場所を1つずつ減らします。

日	やること	見ること
1日目	最小setup scriptを作る	worktree開始が遅すぎないか
2日目	Test actionを追加する	修正後に同じ検証を押せるか
3日目	Dev actionを追加する	serverがworktreeで起動するか
4日目	platform差分を見る	macOS/Windows/Linuxで分けすぎていないか
5日目	.codex差分をreviewする	team共有してよい内容か
7日目	不要なsetupを削る	軽く保てているか

初週に見るべきなのは、設定項目の多さではありません。新しいworktreeで、Codexが迷わず作業を始められるか、人間が同じactionで検証できるか、不要な権限や長い処理が入っていないかです。

継続判断の基準

次の4つを満たすなら、チーム共有へ進めます。

判断	継続条件
再現性	新しいworktreeで同じ準備ができる
速度	thread開始が遅すぎない
明瞭さ	actionsの名前と目的が分かる
安全性	secret、deploy、広いnetworkを含まない

満たさない場合は、setupを削るか、actionsへ分けます。Local environmentsは、重い魔法のscriptではなく、作業の入口を揃えるための設定です。

FAQ

Setup?

自動準備。

Action?

共通task。

Share?

.codexをreview。

Network?

必要時だけ。

迷ったら、worktreeで再現したい作業かを見ます。

setup scriptには何を入れればよいですか

worktreeで作業を始めるための最小限を入れます。dependency install、短いbuild、必要なtool準備が候補です。長いtest、deploy、本番接続、重いseedは避け、必要ならactionへ分けます。

actionsは何個くらい作ればよいですか

最初は2から4個で十分です。Dev、Test、Typecheck、Lintのように、チームがよく押すものだけにします。増やしすぎると、どれを使うべきか迷います。

.codexは必ずcommitしますか

チームで同じ設定を使いたいならcommit対象にします。ただし、secretや個人環境依存のpathを含めないこと、差分reviewを通すこと、project rootを間違えないことが前提です。

monorepoではどこに置きますか

project単位で考えます。web、admin、server、packageごとにsetupやactionsが違うなら、Codex appでどのdirectoryをprojectとして開くかを決め、共有したい.codexの範囲を揃えます。

network accessはsetup scriptに必要ですか

依存関係取得では必要になることがあります。ただし、agent作業時にも広いnetwork accessが必要とは限りません。setupに必要な通信と、作業時の権限は分けて考えます。

次に読むなら

参照した主な情報源

• https://developers.openai.com/codex/app/local-environments
• https://developers.openai.com/codex/app/worktrees
• https://developers.openai.com/codex/app/features
• https://developers.openai.com/codex/agent-approvals-security
• https://developers.openai.com/codex/app/automations

更新履歴

1. 2026年6月1日

   OpenAI公式Codex docsを確認して初版を作成しました。

設定前には最新docsと手元のapp設定を確認してください。

• 2026年6月1日: OpenAI公式Codex docsを確認し、Local environmentsをチームで使う前のsetup script、actions、.codex共有、platform差分、worktree、sandbox、networkの分け方として初版を作成しました。