---
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="/docs/codex/official/01-products/33-app-core" description="App 的整体心智模型" />
  <Card title="App 设置" href="/docs/codex/official/01-products/34-app-settings" description="找到 .codex 与 environment 配置入口" />
  <Card title="App 命令" href="/docs/codex/official/01-products/37-app-commands" description="actions 之外的命令面板入口" />
  <Card title="Worktrees" href="/docs/codex/official/01-products/43-worktrees" description="setup scripts 服务的对象" />
  <Card title="App 排障" href="/docs/codex/official/01-products/41-app-troubleshoot" description="setup / actions 跑不起来时按层定位" />
</Cards>
