Codex 教程

用 Codex 配置 GitHub 工作流

用 Codex 配置 GitHub Actions 的完整指南，覆盖 CI 目标、pull_request 检查、最小权限、Secrets、缓存、失败日志、PR 复核和 OfApp API 变量。

预计阅读: 5 分钟
最近更新: 2026/07/03
维护方式: 人工编辑

用 Codex 配置 GitHub 工作流，适合为项目补齐 CI、自动测试、构建检查、PR 说明和部署前验证。重点不是生成一份看起来完整的 YAML，而是让 Codex 读取项目脚本、识别真实检查项、设置合适的触发事件和权限，再用 GitHub Actions 日志把失败原因定位出来。

项目	说明
阅读时间	约 5 分钟
更新时间	2026-07-03
适合读者	开发者、独立项目维护者、需要把 Codex 改动纳入 PR 检查的团队
你会获得	CI 设计表、可复制 Goal Prompt、Node 示例 workflow、权限与 Secrets 清单、失败日志排查路径

使用场景

场景	输出	验证
新增 CI	`.github/workflows/*.yml`	PR checks 通过，日志可读
修复失败检查	针对失败 job 的小范围改动	重新运行失败 job 后通过
规范 PR	diff 摘要、验证命令、风险说明	Review 能看懂变化
部署前检查	build、lint、test、artifact	只在可信分支或人工批准后部署
API smoke test	mock 或小范围真实请求	Key 不泄露，失败原因可定位

CI 工作流图

可复制 Goal Prompt

Goal: 为当前项目配置 GitHub Actions，让 pull_request 时运行 lint、test 和 build。

请先读取：
- package.json / pyproject.toml / go.mod / 其他构建配置
- 现有 .github/workflows
- README 中的安装和运行方式

要求：
- 使用现有脚本，不新增重依赖。
- workflow 权限保持最小，默认只读。
- 缓存只在安全且必要时添加。
- 如果需要 Secrets，只引用变量名，不写真实值。
- 完成后解释每个 job 的作用、触发条件、失败排查方法和需要人工确认的设置。

Done when:
- 本地同类命令能运行。
- workflow YAML 语法清晰。
- 相关文章和 README 中的运行说明没有冲突。
- 给出 PR 描述和失败日志排查路径。

Codex 官方手册建议把任务写清目标、上下文、约束和完成条件。配置 CI 时，这些信息尤其重要，因为 workflow 失败通常不是“YAML 写错”这么简单，还可能是脚本不存在、运行环境不一致、权限不足、Secret 缺失或缓存污染。

执行步骤

确认项目语言、包管理器、锁文件和运行版本。
查找本地脚本：lint、test、build、check、typecheck、format。
让 Codex 先列出 CI 检查矩阵，再生成 workflow。
设置触发事件，常见选择是 pull_request 和主分支 push。
设置 permissions，只给 job 需要的 GITHUB_TOKEN 权限。
如需密钥，使用 GitHub Secrets，不写入 YAML 明文，也不在日志里打印。
提交 PR 后查看 GitHub Actions 日志，让 Codex 基于失败日志做小范围修复。

Codex 应该先读什么

文件或页面	目的	要求 Codex 输出什么
`package.json` / `pyproject.toml` / `go.mod`	确认脚本、语言和版本	实际可运行的检查命令
锁文件	确认包管理器	安装命令和缓存键依据
`.github/workflows/`	避免重复或冲突	现有 job、触发事件和权限
README / docs	复核安装与测试步骤	CI 与文档是否一致
分支保护规则	判断哪些检查必须通过	需要人工确认的仓库设置
GitHub Actions 日志	修复失败 job	失败步骤、错误摘要和最小修复

CI 设计清单

设计项	建议	常见误区
触发事件	PR 跑检查，主分支 push 做回归	所有分支所有事件都跑重任务
权限	默认 `contents: read`，需要写权限再单独说明	直接给 `write-all`
安装依赖	使用锁文件和项目包管理器	CI 和本地安装方式不同
缓存	依赖稳定后再加，缓存键包含锁文件	用缓存掩盖安装问题
Secrets	只在必要 job 注入	在日志、YAML 或 PR 输出里暴露
外部 API	优先 mock，真实请求只做 smoke test	每个 PR 都跑昂贵或不稳定请求
日志	步骤名称清楚，失败能定位命令	一个大脚本里塞所有动作

注意事项

风险	处理方式
版本不一致	workflow 使用项目声明的版本，或把版本写进 `.node-version`、`.python-version` 等文件。
权限过大	默认只给 read，需要写权限时说明理由。
密钥泄露	使用 Secrets，避免打印环境变量和完整请求头。
缓存误用	先保证正确，再优化速度。
PR 来自外部 fork	谨慎使用 Secrets 和写权限，必要时改为人工批准。
CI 只在远端失败	把本地命令、runner 系统和环境变量差异列出来。

如果 CI 需要调用 OpenAI-compatible API 做测试，优先使用 mock 或跳过真实外部调用。确实需要 smoke test 时，将 OfApp API Key 放在 GitHub Secrets，并把 Base URL 配置为 https://api.ofapp.cn/v1，不要写入仓库。模型、额度、价格和具体能力请以 OfApp.cn 控制台或官方文档为准。

示例：Node 项目 PR 检查

这只是结构示例，Node 版本、包管理器和脚本名称要以项目文件为准。让 Codex 生成时，应要求它解释每个步骤和权限。

name: CI

on:
  pull_request:
  push:
    branches: [main]

permissions:
  contents: read

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v6

      - name: Setup Node
        uses: actions/setup-node@v6
        with:
          node-version-file: .node-version
          cache: npm

      - name: Install dependencies
        run: npm ci

      - name: Lint
        run: npm run lint --if-present

      - name: Test
        run: npm test --if-present

      - name: Build
        run: npm run build --if-present

如果项目没有 .node-version，可以改成明确版本；如果使用 pnpm、yarn、Python、Go 或 Rust，需要换成对应 setup action 和安装命令。不要为了让示例通过而在真实仓库里创建无意义脚本。

容器或 API 测试的 Secret 写法

env:
  OPENAI_BASE_URL: https://api.ofapp.cn/v1
  OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}

steps:
  - name: Run API smoke test
    run: npm run test:smoke --if-present

OPENAI_API_KEY 必须在 GitHub Secrets 里配置。CI 日志只应该显示变量名、状态码、请求 ID 或脱敏摘要，不应该输出真实 Key、完整响应、客户数据或内部文档。

失败日志怎么让 Codex 处理

GitHub CLI 可以读取 workflow 日志，例如：

gh run view RUN_ID --log
gh run view --job JOB_ID --log-failed

把失败 job、失败步骤、关键错误行和相关文件发给 Codex，比直接说“CI 挂了”有效得多。一个排查 prompt 可以这样写：

Goal: 修复 GitHub Actions 中失败的 test job。

Context:
- 失败 workflow: CI
- 失败 job: test
- 失败步骤: npm test
- 失败日志摘要: [粘贴脱敏后的关键错误]

Constraints:
- 只修复导致 CI 失败的最小范围。
- 不跳过测试，不删除断言，不扩大 workflow 权限。
- 如果需要修改测试或依赖，说明理由。

Done when:
- 本地同类命令通过。
- workflow 修改范围清楚。
- 给出失败原因和验证证据。

常见错误排查

错误	表现	修复
workflow 跑了不存在脚本	CI 立即失败	对照 package.json 修改命令
把 key 写进 YAML	密钥暴露	改用 Secrets
本地没跑过	CI 失败难排查	先本地执行同样命令
权限不足	发布、评论或上传失败	按 job 添加明确权限
触发事件过宽	无关分支频繁跑 CI	收窄 branches、paths 或 job 条件
缓存污染	CI 偶发失败	暂停缓存，确认安装命令稳定
外部 API 超时	PR 检查不稳定	mock 外部服务或改成小范围 smoke test

资料来源

GitHub Actions workflow syntax：workflow 的事件、job、step、权限等语法。
GitHub Actions secrets：Secrets 用于保存敏感配置。
GitHub Actions workflow logs：可用 GitHub CLI 查看 run 和 job 日志。
OpenAI Codex 官方手册：Codex 任务应写清目标、上下文、约束、验证和完成条件。
OfApp.cn API 文档：本站示例使用 OfApp.cn 时，以官方文档和控制台为准。

常见问题

Codex 可以直接 push workflow 吗？

可以在你授权的本地仓库中创建和提交文件，但 GitHub 权限、Secrets、分支保护规则和仓库设置仍需要开发者确认。涉及写权限和部署权限时，建议让 Codex 先准备变更和说明，由人复核后再推送。

CI 应该一次做很多事吗？

不建议。先保证 lint、test、build 三类关键检查稳定，再逐步增加安全扫描、部署、通知和自动评论。CI 越复杂，越需要清楚的日志和分层 job。

测试需要真实 API Key 怎么办？

优先使用 mock、录制响应或小范围 smoke test。真实 Key 必须放在 Secrets，并控制日志、调用频率和失败重试。示例 Key 只能写成 sk-xxxx。

pull_request 和 push 都要配置吗？

看团队流程。PR 检查适合阻止问题进入主分支，主分支 push 检查适合确认合并后状态。部署任务通常还需要单独的分支、环境保护或人工批准。

Codex GitHub Action 和普通 CI 是一回事吗？

不是。普通 CI 跑 lint、test、build 等确定性命令；Codex GitHub Action 更适合在 workflow 中运行 Codex 任务、生成反馈或做辅助审查。需要 API Key、触发权限和安全边界时，应单独评估。

失败时可以直接让 Codex 跳过测试吗？

不应该。跳过测试只能作为临时隔离问题的诊断手段，不能作为修复。更好的做法是让 Codex 读取失败日志、复现命令、定位原因，再做最小修复。

Codex 教程：把目标、上下文、约束和验证写成完整工作流。
Codex Goal 提示词模板：为 CI 和 PR 任务写可验收目标。
用 Codex 排查报错：处理 CI 失败日志。
用 Codex 生成测试：为 CI 补稳定测试。
用 Codex 写 Dockerfile：把构建镜像纳入 CI。
Codex 本地项目使用指南：控制工作目录、AGENTS.md 和验证命令。
API 错误排查中心：排查外部 API 错误。
错误重试示例：为 API 调用添加重试策略。

带走什么

用 Codex 配置 GitHub 工作流的重点是读取现有脚本、设置最小权限、保留可读日志和复现失败。CI 是团队质量门槛，不应变成不可理解的自动化黑箱。涉及 OfApp.cn 或任何 API Key 时，只把变量名、Base URL 和假 Key 写进文档；真实值放在 Secrets，具体模型、额度、价格和能力以 OfApp.cn 控制台或官方文档为准。