配置本地运行环境
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。