配置本地執行環境
Local environments 用來為 worktrees 配置 setup steps，也可以為 project 配置常用 actions。
這一篇用 8 分鐘換什麼：把 Codex App 的 local environment 拆成兩條獨立配置——setup scripts（每次新 worktree 自動跑）+ actions（top bar 一鍵執行的常用任務）。讀完後你能寫出一份可以提交到儲存庫給團隊複用的 .codex/，而不是每次 setup 都靠口頭交接。
Local environments 用來為 worktrees 配置 setup steps，也可以為 project 配置常用 actions。
配置入口在 Codex App settings pane。生成的配置檔案可以提交到專案的 Git repository，方便團隊共享。
flowchart LR
Repo["📁 repo/.codex/"]
Setup["setup scripts<br/>（自動）"]
Actions["actions<br/>（手動 / top bar）"]
WT["new worktree<br/>每次 thread 啟動"]
UseDev["💻 dev / build / test<br/>integrated terminal"]
Repo --> Setup --> WT
Repo --> Actions --> UseDev
WT -.->|依賴就緒| UseDevCodex 會把這份配置存放在 project root 的 .codex folder 中。如果你的 repository 包含多個 projects，開啟那個包含 shared .codex folder 的 project directory。
Local environments 的重點是讓 worktree 和 team members 擁有可重複的本地專案啟動方式。它不是 secret 管理器，也不是 CI 配置替代品，而是 Codex App 裡給 setup scripts 和 actions 提供的專案級配置。
Setup scripts
worktrees 和 local tasks 執行在不同目錄裡，所以新 worktree 可能還沒完成 setup，也可能缺少 dependencies，或者缺少未提交到 repository 的檔案。
當 Codex 在新 thread 開始時建立 new worktree，setup scripts 會自動執行。
setup script 用來執行配置環境所需的命令，例如：
- 安裝 dependencies。
- 執行 build process。
- 生成專案執行需要的本地檔案。
TypeScript project 示例：
npm install
npm run build如果 setup 和平臺相關，可以分別為 macOS、Windows 或 Linux 定義 setup scripts，用它們覆蓋 default。
setup script 寫什麼
適合寫進 setup script：
- 安裝依賴。
- 生成本地需要但可復現的檔案。
- 執行初始 build。
- 初始化子模組或 workspace。
- 檢查必要工具版本。
不適合寫進 setup script：
- 寫入長期 secret。
- 修改全域性系統設定。
- 刪除使用者檔案。
- 啟動長駐服務。
- 做需要人工確認的釋出操作。
setup script 會在 Codex 建立新 worktree 時自動執行，所以必須可重複、可失敗、可排查。
多平臺策略
如果專案跨 macOS、Windows、Linux，優先把公共步驟寫成預設 setup，再為平臺差異單獨覆蓋。
常見差異包括：
- shell 語法。
- package manager。
- 本地路徑。
- simulator 或 browser 可用性。
- native dependency installation。
不要在一個指令碼里堆大量平臺判斷。如果平臺差異明顯，拆成 platform-specific scripts 更清晰。
Actions
Actions 用來定義專案常用任務，例如啟動 app development server，或執行 test suite。
這些 actions 會顯示在 Codex App top bar，方便快速啟動。它們會在 App 的 integrated terminal 中執行。
Actions 的價值是減少重複輸入。常見例子：
- 觸發專案 build。
- 啟動 development server。
- 跑 test suite。
一次性 quick debugging 可以直接使用 integrated terminal。
官方截圖：
- light：https://developers.openai.com/images/codex/app/actions-light.webp
- dark：https://developers.openai.com/images/codex/app/actions-dark.webp
Node.js project 可以建立一個名為 "Run" 的 action，指令碼如下：
npm start如果 action 的 commands 和平臺相關，可以分別為 macOS、Windows 和 Linux 定義 platform-specific scripts。
為了方便識別 actions，可以為每個 action 選擇一個相關 icon。
常用 actions 設計
建議至少配置這幾類：
| Action | 示例命令 | 用途 |
|---|---|---|
| Install | pnpm install | 依賴初始化 |
| Build | pnpm run build | 驗證生產構建 |
| Dev | pnpm run dev | 啟動開發伺服器 |
| Test | pnpm test | 跑測試 |
| Lint | pnpm run lint | 靜態檢查 |
| Typecheck | pnpm run types:check | 型別檢查 |
專案不一定全都需要，但每個 action 都應該對應團隊真實使用的命令。不要為了“看起來完整”配置不會跑的命令。
Monorepo 注意事項
官方文件說明：local environment configuration 必須位於 project root 的 .codex folder 中。
monorepo 常見問題是開啟錯目錄：
repo/
.codex/
apps/web/
packages/ui/如果 .codex 在 repo/，就從 repo/ 開啟專案；如果某個 app 有自己的 .codex，就從 app directory 開啟。Codex App 只會在當前 project 對應目錄查詢共享配置。
和 worktrees 的關係
worktree 是新的 checkout，通常只包含 Git 跟蹤檔案。沒有提交到儲存庫的依賴、快取、生成檔案、本地 .env 都不會自然出現。
local environment 的 setup scripts 用來彌補這個差異：
- Codex 建立 worktree。
- setup script 自動執行。
- 依賴和構建產物準備好。
- thread 開始執行任務。
如果 worktree 裡程式碼跑不起來，優先檢查 setup scripts，而不是直接 handoff 回 Local。
安全邊界
local environment 配置可以 check into Git repo 共享，但不要把 secret 寫進去。
推薦：
- 用環境變數名佔位。
- 在憑據系統、Keychain、CI secret 或本機環境裡儲存真實值。
- setup script 只檢查變數是否存在，不列印變數值。
- logs 裡不輸出 token、賬號、私有路徑。
示例：
if [ -z "${OPENAI_API_KEY:-}" ]; then
echo "OPENAI_API_KEY is not set"
exit 1
fi排障
| 現象 | 可能原因 | 處理 |
|---|---|---|
| teammate 的配置沒有生效 | .codex 不在當前 project root | 重新從包含 .codex 的目錄開啟專案 |
| worktree 缺依賴 | setup script 沒安裝依賴 | 補 install/build 步驟 |
| action 跑錯目錄 | monorepo 開啟層級不對 | 確認 project root 和 package path |
| setup 每次都很慢 | 指令碼做了過多工作 | 拆成必要 setup 和手動 action |
| secret 洩露到日誌 | 指令碼 echo 了敏感值 | 只檢查存在性，不列印值 |
完成標準
.codex位於正確 project root。- setup script 可重複執行。
- worktree 新建後能安裝依賴並完成最小 build。
- 常用 actions 覆蓋 build、dev、test 或專案真實等價命令。
- 平臺差異已拆分或明確說明。
- 配置中沒有 hard-coded secret。