---
title: "配置本地執行環境"
description: "Local environments 用來為 worktrees 配置 setup steps，也可以為 project 配置常用 actions。"
verifiedAt: "2026-05-07"
---

> [!NOTE]
> **這一篇用 8 分鐘換什麼**：把 Codex App 的 local environment 拆成兩條獨立配置——**setup scripts**（每次新 worktree 自動跑）+ **actions**（top bar 一鍵執行的常用任務）。讀完後你能寫出一份可以提交到儲存庫給團隊複用的 `.codex/`，而不是每次 setup 都靠口頭交接。

Local environments 用來為 worktrees 配置 setup steps，也可以為 project 配置常用 actions。

配置入口在 [Codex App settings](codex://settings) pane。生成的配置檔案可以提交到專案的 Git repository，方便團隊共享。

```mermaid
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 示例：

```bash
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](https://developers.openai.com/codex/app/features#integrated-terminal) 中執行。

Actions 的價值是減少重複輸入。常見例子：

- 觸發專案 build。
- 啟動 development server。
- 跑 test suite。

一次性 quick debugging 可以直接使用 integrated terminal。

官方截圖：

- light：[https://developers.openai.com/images/codex/app/actions-light.webp](https://developers.openai.com/images/codex/app/actions-light.webp)
- dark：[https://developers.openai.com/images/codex/app/actions-dark.webp](https://developers.openai.com/images/codex/app/actions-dark.webp)

Node.js project 可以建立一個名為 "Run" 的 action，指令碼如下：

```bash
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 常見問題是開啟錯目錄：

```text
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、賬號、私有路徑。

示例：

```bash
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。

## 官方資料

- [Local environments](https://developers.openai.com/codex/app/local-environments)
- [Worktrees](https://developers.openai.com/codex/app/worktrees)
- [Codex app features](https://developers.openai.com/codex/app/features)

## 接下來去哪

<Cards>
  <Card title="App 核心" href="/zh-Hant/docs/codex/official/01-products/33-app-core" description="App 的整體心智模型" />
  <Card title="App 設定" href="/zh-Hant/docs/codex/official/01-products/34-app-settings" description="找到 .codex 與 environment 配置入口" />
  <Card title="App 命令" href="/zh-Hant/docs/codex/official/01-products/37-app-commands" description="actions 之外的命令面板入口" />
  <Card title="Worktrees" href="/zh-Hant/docs/codex/official/01-products/43-worktrees" description="setup scripts 服務的物件" />
  <Card title="App 排障" href="/zh-Hant/docs/codex/official/01-products/41-app-troubleshoot" description="setup / actions 跑不起來時按層定位" />
</Cards>
