Codex 项目级配置最佳实践

在团队里用 Codex 最容易踩坑的地方，不是命令不会敲，而是每个人的模型、审批策略、上下文说明都不一样。结果同一个任务，有人能跑通，有人改出一堆无关文件。遇到这类问题，先不要急着重装，优先查三件事：当前项目有没有明确的说明文件、启动 Codex 时用了哪个配置、API 入口和密钥是否一致。

一、项目级配置该管什么

项目级配置不要什么都往仓库里塞。比较稳的做法是把配置分成三层：

• 团队共识：放在仓库里，例如代码风格、测试命令、目录约定、禁止修改的文件。
• 本机偏好：放在用户目录，例如默认模型、审批策略、沙箱策略。
• 敏感信息：只放环境变量或本机配置，例如 API Key、代理地址、企业网关凭证。

这样做的好处是明显的：新人拉代码后能知道 Codex 应该怎么理解项目，但不会把密钥、个人模型额度、临时代理写进 Git。

二、建议的目录结构

一个比较实用的项目结构如下：

### token云桥中转 0029.org ###
my-service/
├── AGENTS.md
├── README.md
├── package.json
├── src/
├── tests/
├── scripts/
│   └── codex-check.sh
└── .env.example

AGENTS.md 用来写 Codex 在当前项目里的工作约束。它比在聊天里临时补充要求更可靠，因为每次进入项目都能被复用。

# AGENTS.md

## 项目约定
- 后端使用 Node.js 20，包管理器使用 pnpm。
- 源码在 src/，测试在 tests/。
- 不要直接修改数据库迁移文件，除非任务明确要求。
- 修改业务逻辑后必须补充或更新测试。

## 常用命令
- 安装依赖：pnpm install
- 单元测试：pnpm test
- 类型检查：pnpm typecheck
- 代码格式化：pnpm lint --fix

## 输出要求
- 优先给出最小修改。
- 修改前先说明会影响哪些文件。
- 遇到不确定的业务规则，先提问，不要猜。

三、本机配置不要进仓库

模型、审批、沙箱这类选项更适合放在用户级配置里。以常见的 TOML 风格为例，可以把本机默认行为放到自己的配置文件中，团队只约定推荐值，不强行提交。

model = "gpt-4.1"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

[profiles.safe]
approval_policy = "on-request"
sandbox_mode = "read-only"

[profiles.dev]
approval_policy = "on-request"
sandbox_mode = "workspace-write"

这里要注意两点。第一，read-only 适合代码审查、问题定位，不适合让 Codex 自动改文件。第二，workspace-write 更适合日常开发，但仍建议保留审批，不要让它在不了解上下文时批量改动。

四、API 入口和密钥管理

如果团队直接使用官方接口，通常用环境变量注入密钥即可：

export OPENAI_API_KEY="sk-xxxx"
codex

如果公司网络对外访问不稳定，或者需要统一管理多个模型入口，可以考虑走 OpenAI 兼容的中转服务。实际项目里我一般会先做一个最小接口测试，再接 Codex。比如 token云桥AI中转站 0029.org 这类入口，适合先验证连通性、延迟和账单消耗，再决定是否放到团队配置建议里。

接口测试可以用 curl 先跑通，不要一上来就在 Codex 里排查：

curl -s -X POST "$OPENAI_BASE_URL/v1/chat/completions" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4.1",
    "messages": [
      {"role": "user", "content": "只回复 ok"}
    ],
    "temperature": 0
  }'

如果这里都不通，问题通常不在 Codex，而在密钥、Base URL、代理或模型名。

五、为项目准备启动脚本

团队协作时，建议准备一个轻量脚本，统一检查环境，而不是让每个人靠记忆启动。

#!/usr/bin/env bash
set -e

if [ -z "$OPENAI_API_KEY" ]; then
  echo "缺少 OPENAI_API_KEY"
  exit 1
fi

if [ ! -f "AGENTS.md" ]; then
  echo "缺少 AGENTS.md，请先补充项目级说明"
  exit 1
fi

echo "Codex 环境检查通过"
codex

把它保存为 scripts/codex-check.sh，然后赋权：

chmod +x scripts/codex-check.sh
./scripts/codex-check.sh

这个脚本不需要复杂，重点是把高频错误提前暴露出来。

六、成本控制的几个细节

Codex 在项目里最容易产生额外消耗的场景，是把无关文件、构建产物、日志、大型依赖目录都塞进上下文。建议在项目说明里明确排除范围：

• 不要读取 node_modules、dist、build、coverage。
• 排查问题时先给相关文件路径，不要让它全仓库搜索。
• 大改动拆成小任务，例如“先定位问题”，再“修改实现”，最后“补测试”。
• 能用本地命令验证的，就不要让模型反复猜测。

如果项目比较大，建议在提问时直接给范围：

请只检查 src/services/order.ts 和 tests/order.test.ts，
先说明问题原因，不要修改文件。

这比一句“帮我修复订单 bug”更省 token，也更容易得到可控结果。

七、常见问题排查顺序

1. Codex 没按项目规范执行

先看当前目录是否有 AGENTS.md，内容是否过于空泛。不要只写“请遵守最佳实践”，要写具体命令、目录、禁止事项。

2. 接口报 401 或 403

优先检查密钥是否导出到当前终端：

echo "$OPENAI_API_KEY"

如果使用了中转入口，再检查 OPENAI_BASE_URL 是否拼错，以及模型名是否被该入口支持。

3. 响应慢或经常中断

先用 curl 测接口延迟，再看是否走了公司代理。不要只换模型，网络链路不稳定时，换模型通常没有本质改善。

4. 改动范围太大

把审批策略调保守一点，并在任务里明确“先列计划，不要改文件”。必要时切到只读模式做分析，确认方案后再允许写入。

总结

Codex 的项目级配置核心不是堆参数，而是把团队约定、个人偏好和敏感信息分开管理。仓库里放清晰的 AGENTS.md，本机保留模型和审批配置，接口先用最小请求测通，再接入日常开发。这样配置下来，成本、稳定性和协作一致性都会好很多。