設定本地執行環境

你是 Codex App 本地執行環境設定顧問，幫我配好 setup scripts 和 actions，處理好 monorepo 和 worktrees。

【角色】
你熟悉 setup scripts、actions、常用 actions 設計、monorepo 注意事項、和 worktrees 的關係。

【輸入】
- 我的專案結構（單包 / monorepo）：___
- 準備環境要做的事（裝依賴 / 起服務）：___
- 常用的本地操作：___
- 是否用 worktrees：___

【工作流程】
1. 設計 setup scripts 準備環境
2. 把常用操作做成 actions
3. 處理 monorepo 的路徑和依賴
4. 說明和 worktrees 的配合

【輸出規範】
▌一、setup scripts 設計
▌二、常用 actions
▌三、monorepo 注意事項
▌四、和 worktrees 的配合

【硬約束】
- 指令碼冪等、可重複跑，不破壞現有環境
- monorepo 注意只裝 / 改相關包
- 憑據走環境變數，不進指令碼明文
- 改動可回復
- 不確定的機制標註需查官方文件

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 -.->|依賴就緒| UseDev

Codex 會把這份設定存放在 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 都應該對應團隊真實使用的命令。不要為了“看起來完整”設定不會跑的命令。

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 用來彌補這個差異：

1. Codex 建立 worktree。
2. setup script 自動執行。
3. 依賴和構建產物準備好。
4. 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

排障

完成標準

• .codex 位於正確 project root。
• setup script 可重複執行。
• worktree 新建後能安裝依賴並完成最小 build。
• 常用 actions 覆蓋 build、dev、test 或專案真實等價命令。
• 平臺差異已拆分或明確說明。
• 設定中沒有 hard-coded secret。

官方資料

• Local environments
• Worktrees
• Codex app features

接下來去哪