法典 - OpenAI API --- Codex - OpenAI API

Author: openai.com

Length: • 7 mins

Annotated by Harry

Codex食品

Delegate tasks to a software engineering agent in the cloud.
将任务委派给云中的软件工程代理。

Some content could not be imported from the original document. View content ↗

Codex is a cloud-based software engineering agent. Use it to fix bugs, review code, do refactors, and fix pieces of code in response to user feedback. It's powered by a version of OpenAI o3 that's fine-tuned for real-world software development.
Codex 是一个基于云的软件工程代理。使用它来修复 bug、审查代码、执行重构和修复代码段,以响应用户反馈。它由 OpenAI o3 版本提供支持,该版本针对实际软件开发进行了微调。

Overview概述

We believe in a future where developers drive the work they want to own, delegating toilsome tasks to agents. We see early signs of this future today at OpenAI, with Codex working in its own environment and drafting pull requests in our repos.
我们相信,在未来,开发人员可以推动他们想要拥有的工作,将繁重的任务委派给代理。我们今天在 OpenAI 看到了这种未来的早期迹象,Codex 在自己的环境中工作,并在我们的存储库中起草拉取请求。

Codex vs. Codex CLICodex 与 Codex CLI
These docs cover Codex, a cloud-based agent you can find in your browser. For an open-source CLI agent you can run locally in your terminal, install Codex CLI.
这些文档涵盖了 Codex,这是一个基于云的代理,您可以在浏览器中找到。对于可以在终端中本地运行的开源 CLI 代理, 请安装 Codex CLI。

Connect your GitHub连接您的 GitHub

To grant the Codex agent access to your GitHub repos, install our GitHub app to your organization. The two permissions required are ability to clone the repo and the ability to push a pull request to it. Our app will not write to your repo without your permission.
要授予 Codex 代理访问您的 GitHub 存储库的权限,请为您的组织安装我们的 GitHub 应用程序。所需的两个权限是克隆存储库的能力和向其推送拉取请求的能力。 未经您的许可,我们的应用程序不会写入您的存储库 。

Each user in your organization must authenticate with their GitHub account before being able to use Codex. After auth, we grant access to your GitHub repos and environments at the ChatGPT workspace level—meaning if your teammate grants access to a repo, you'll also be able to run Codex tasks in that repo, as long as you share a workspace.
组织中的每个用户都必须使用其 GitHub 帐户进行身份验证,然后才能使用 Codex。身份验证后,我们会在 ChatGPT 工作区级别授予对您的 GitHub 存储库和环境的访问权限,这意味着如果您的队友授予对存储库的访问权限,只要您共享工作区 ,您也可以在该存储库中运行 Codex 任务。

How it works运作方式

At a high level, you specify a prompt, and the agent goes to work in its own environment. After about 8–10 minutes, the agent gives you back a diff.
概括地说,您指定一个提示,代理将在其自己的环境中工作。大约 8-10 分钟后,代理会返回一个差异。

You can execute prompts in either ask mode or code mode. When you select ask, Codex clones a read-only version of your repo, booting faster and giving you follow-up tasks. Code mode, however, creates a full-fledged environment that the agent can run and test against.
您可以在 ask 模式或 code 模式下执行提示。当您选择 ask 时,Codex 会克隆存储库的只读版本,从而更快地启动并为您提供后续任务。但是, 代码模式会创建一个完整的环境,代理可以针对该环境运行和测试。

Exact flow:精确流程:

  1. You navigate to chatgpt.com/codex and submit a task.
    导航到 chatgpt.com/codex 并提交任务 。
  2. We launch a new Docker container based upon our base image. We then clone your repo at the desired branch or sha and run any setup scripts you have from the specified workdir.
    我们基于基础镜像启动一个新的 Docker 容器 。然后,我们在所需的 branch 或 sha 处克隆您的存储库 ,并从指定的 workdir 运行您拥有的任何设置脚本 。
  3. We disable network access. The agent does not have the ability to install dependencies from this point forward.
    我们禁用网络访问 。从此时起,代理无法安装依赖项。
  4. The agent then runs terminal commands in a loop. It writes code, runs tests, and attempts to check its work. The agent attempts to honor any specified lint or test commands you've defined in an AGENTS.md file. The agent does not have access to any special tools outside of the terminal or CLI tools you provide.
    然后,代理程序以循环方式运行终端命令 。它编写代码、运行测试并尝试检查其工作。代理会尝试遵循您在 AGENTS.md 文件中定义的任何指定 lint 或 test 命令。代理无权访问您提供的终端或 CLI 工具之外的任何特殊工具。
  5. When the agent completes your task, it presents a a diff or a set of follow-up tasks. You can choose to open a PR or respond with follow-up comments to ask for additional changes.
    当代理完成您的任务时,它会显示一个差异或一组后续任务。您可以选择打开 PR 或使用后续评论进行回复,以请求其他更改。

Submit tasks to Codex向 Codex 提交任务

After connecting your repository, begin sending tasks using one of two modes:
连接仓库后,使用以下两种模式之一开始发送任务:

  • Ask mode for brainstorming, audits, or architecture questions
    询问模式 ,用于头脑风暴、审计或架构问题
  • Code mode for when you want automated refactors, tests, or fixes applied
    代码模式 ,用于应用自动重构、测试或修复

Below are some example tasks to get you started with Codex.
以下是一些帮助您开始使用 Codex 的示例任务。

Ask mode examplesAsk 模式示例

Use ask mode to get advice and insights on your code, no changes applied.
使用询问模式获取有关代码的建议和见解,无需应用任何更改。

  • Refactoring suggestions重构建议 Codex can help brainstorm structural improvements, such as splitting files, extracting functions, and tightening documentation.
    Codex 可以帮助集思广益进行结构改进,例如拆分文件、提取函数和收紧文档。 
    Take a look at <hairiest file in my codebase>.
    Can you suggest better ways to split it up, test it, and isolate functionality?
  • Q&A and architecture understanding
    Q&A 和架构理解     Codex can answer deep questions about your codebase and generate diagrams.
    Codex 可以回答有关您的代码库的深层问题并生成图表。 
    Document and create a mermaidjs diagram of the full request flow from the client 
    endpoint to the database.

Code mode examples代码模式示例

Use code mode when you want Codex to actively modify code and prepare a pull request.
当您希望 Codex 主动修改代码并准备拉取请求时,请使用 code mode。

  • Security vulnerabilities安全漏洞 Codex excels at auditing intricate logic and uncovering security flaws.
    Codex 擅长审计复杂的逻辑和发现安全漏洞。 
    There's a memory-safety vulnerability in <my package>. Find it and fix it.
  • Code review代码审查 Append .diff to any pull request URL and include it in your prompt. Codex loads the patch inside the container.
    将 .diff 附加到任何拉取请求 URL 并将其包含在提示中。Codex 在容器内加载修补程序。 
    Please review my code and suggest improvements. The diff is below:
    <diff>
  • Adding tests添加测试 After implementing initial changes, follow up with targeted test generation.
    实施初始更改后,请跟进目标测试生成。 
    From my branch, please add tests for the following files:
    <files>
  • Bug fixing错误修复 A stack trace is usually enough for Codex to locate and correct the problem.
    堆栈跟踪通常足以让 Codex 找到并纠正问题。 
    Find and fix a bug in <my package>.
  • Product and UI fixes产品和 UI 修复 Although Codex cannot render a browser, it can resolve minor UI regressions.
    尽管 Codex 无法呈现浏览器,但它可以解决细微的 UI 回归问题。 
    The modal on our onboarding page isn't centered. Can you fix it?

Advanced configuration高级配置

Codex works out of the box, but you can point it at a custom environment to have the agent install dependencies, compile, lint, test, or spin up services exactly the way your project needs.
Codex 开箱即用,但您可以将其指向自定义环境,让代理完全按照您的项目需要安装依赖项、编译、lint、测试或启动服务。

Create an environment创建环境

By default, the agent runs in a Docker container running our universal image. It comes pre-installed with most popular languages (Python, Go, Rust, Java, Ruby). See the base Dockerfile.
默认情况下,代理在运行通用映像的 Docker 容器中运行。它预装了大多数流行的语言(Python、Go、Rust、Java、Ruby)。请参阅基本 Dockerfile。

Add setup commands添加设置命令

After the repo is cloned to the /workspace directory, we run all the specified setup commands.
将存储库克隆到 /workspace 目录后,我们运行所有指定的安装命令。

To get the best results from the agent, make sure you install dependencies (public and private), lint frameworks, and everything required to run unit tests. Specify setup commands—either multiple commands per line or one per line—and add the setup file to your repo.
要从代理中获得最佳结果,请确保安装依赖项(公共和私有)、lint 框架以及运行单元测试所需的一切。指定设置命令(每行多个命令或每行一个命令),然后将设置文件添加到您的存储库中。

Create an AGENTS.md创建 AGENTS.md

Provide common context by adding an AGENTS.md file. This is just a standard Markdown file the agent reads to understand how to work in your repository. AGENTS.md can be nested, and the agent will by default respect whatever the most nested root that it's looking for. Some customers also prompt the agent to look for .currsorrules or CLAUDE.md explicitly. We recommend sharing any bits of organization-wide configuration in this file.
通过添加 AGENTS.md 文件来提供通用上下文。这只是一个标准的 Markdown 文件,代理会读取该文件来了解如何在存储库中工作。AGENTS.md 可以是嵌套的,默认情况下,代理将遵循它要查找的嵌套最多的根。一些客户还会提示代理显式查找 .currsorrules 或 CLAUDE.md。我们建议在此文件中共享组织范围的任何配置。

Common things you might want to include:
您可能想要包含的常见内容:

  • An overview showing which particular files and folders to work in
    显示要使用的特定文件和文件夹的概览
  • Contribution and style guidelines
    贡献和样式指南
  • Parts of the codebase being migrated
    正在迁移的代码库部分
  • How to validate changes (running lint, tests, etc.)
    如何验证更改(运行 lint、测试等)

Here's an example as one way to structure your AGENTS.md file:
下面是一个构建 AGENTS.md 文件的方法示例:

# AGENTS.md
# Contributor Guide
## Dev Environment Tips
- Use pnpm dlx turbo run where <project_name> to jump to a package instead of scanning with ls.
- Run pnpm install --filter <project_name> to add the package to your workspace so Vite, ESLint, and TypeScript can see it.
- Use pnpm create vite@latest <project_name> -- --template react-ts to spin up a new React + Vite package with TypeScript checks ready.
- Check the name field inside each package's package.json to confirm the right name—skip the top-level one.
## Testing Instructions
- Find the CI plan in the .github/workflows folder.
- Run pnpm turbo run test --filter <project_name> to run every check defined for that package.
- From the package root you can just call pnpm test. The commit should pass all tests before you merge.
- To focus on one step, add the Vitest pattern: pnpm vitest run -t "<test name>".
- Fix any test or type errors until the whole suite is green.
- After moving files or changing imports, run pnpm lint --filter <project_name> to be sure ESLint and TypeScript rules still pass.
- Add or update tests for the code you change, even if nobody asked.
## PR instructions
Title format: [<project_name>] <Title>

Prompting tips提示提示

Just like ChatGPT, Codex is only as effective as the instructions you give it. Use the following tips.
就像 ChatGPT 一样,Codex 的有效性取决于您给它的指示。请使用以下提示。

  • Use greppable names. Codex literally calls grep, so specific filenames, symbols, or unique package names help it quickly find the right spot. Internally, we use the prefix wham for Codex-related packages.
    使用 greppable 名称 。Codex 的字面意思是 grep,因此特定的文件名、符号或唯一的包名称有助于它快速找到正确的位置。在内部,我们对 Codex 相关的包使用前缀 wham。
  • Tell it where to work. Codex performs best when pointed at a single file or at most a package containing ~100 files. Broad or vague prompts can leave the agent guessing.
    告诉它在哪里工作 。Codex 在指向单个文件或最多包含 ~100 个文件的包时表现最佳。宽泛或模糊的提示可能会让代理猜测。
  • Paste the full stack trace. Exact stack traces with file paths and line numbers help Codex immediately pinpoint bugs.
    粘贴完整的堆栈跟踪 。带有文件路径和行号的精确堆栈跟踪有助于 Codex 立即查明错误。
  • Spin up multiple tasks in a row. Each task runs in its own isolated environment, so feel free to queue multiple tasks simultaneously. Many engineers at OpenAI start their day by making a quick to-do list and firing off several tasks at once.
    连续启动多个任务 。每个任务都在自己的隔离环境中运行,因此可以随意同时将多个任务排队。OpenAI 的许多工程师通过快速列出待办事项清单并同时执行多项任务来开始他们的一天。
  • Give it work with a pass/fail. Just like a human, Codex validates its changes. Since it has access to a terminal, anything verifiable with a unit test or linting lands more reliably. (Codex doesn't yet support UI tests.)
    让它通过/失败。 就像人类一样,Codex 会验证其更改。由于它可以访问终端,因此任何可通过单元测试或 linting 验证的内容都会更可靠地到达。(Codex 尚不支持 UI 测试。
  • Split large changes. Instead of giving Codex a giant PR, break work into small, focused tasks. Smaller tasks are easier for the agent to test individually and easier for you to review.
    拆分大型更改 。与其给 Codex 一个巨大的 PR,不如将工作分解成小的、重点突出的任务。较小的任务更容易让代理单独测试,也更容易让您查看。
  • Let Codex take over when you're stuck. If you get blocked, create a branch and hand the problem to Codex. You can use this strategy to explore multiple solutions in parallel.
    当你遇到困难时,让 Codex 接管 。如果你被阻止了,请创建一个分支并将问题交给 Codex。您可以使用此策略并行探索多个解决方案。
  • Kick off a few tasks before you start your day. Launch tasks before your commute or morning coffee, and come back to fresh diffs ready for review.
    在开始新的一天之前,先开始一些任务 。在通勤或早上喝咖啡之前启动任务,然后返回新的差异以供审查。