Skip to content

Search or jump to...

Search code, repositories, users, issues, pull requests...

Search Clear Search syntax tips

Provide feedback

We read every piece of feedback, and take your input very seriously. Include my email address so I can be contacted Cancel Submit feedback

Saved searches

Use saved searches to filter your results more quickly

Name Query To see all available qualifiers, see our documentation. Cancel Create saved search Sign in Sign up Reseting focus You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session. You switched accounts on another tab or window. Reload to refresh your session. Dismiss alert {{ message }} openai / **codex ** Public

Lightweight coding agent that runs in your terminal

License

Apache-2.0 license 3.6k stars 271 forks Branches Tags Activity Star Notifications You must be signed in to change notification settings

Additional navigation options

openai/codex

main BranchesTags Go to file Code

Folders and files

Name| Name| Last commit message| Last commit date
---|---|---|---

Latest commit

History

23 Commits
.github| .github
codex-cli| codex-cli
.gitignore| .gitignore
.prettierignore| .prettierignore
.prettierrc.toml| .prettierrc.toml
LICENSE| LICENSE
NOTICE| NOTICE
README.md| README.md
package-lock.json| package-lock.json
package.json| package.json
View all files

Repository files navigation

OpenAI Codex CLI

轻量级代码助手，可在您的终端中运行。 npm i -g @openai/codex Codex demo GIF using: codex "explain this codebase to me" 目录

快速入门

全局安装:

npm install -g @openai/codex

接下来，将您的 OpenAI API key 设置为环境变量:

export OPENAI_API_KEY="your-api-key-here"

注意: 此命令仅为当前终端会话设置 key。 要使其永久生效，请将 export 行添加到 shell 的配置文件中（例如，~/.zshrc）。 交互式运行:

codex

或者，使用提示作为输入运行（可以选择使用Full Auto模式）:

codex "explain this codebase to me"

codex --approval-mode full-auto "create the fanciest todo-list app"

就是这样 - Codex 将搭建一个文件，在沙箱中运行它，安装任何缺少的依赖项，并向您展示实时结果。 批准更改，它们将被提交到您的工作目录。

为什么选择 Codex?

Codex CLI 专为已经在终端中工作的开发人员构建，他们需要 ChatGPT 级别的推理能力以及实际运行代码、操作文件和迭代的能力——所有这些都在版本控制下。 简而言之，它是一种 聊天驱动的开发方式，可以理解和执行您的存储库。

它是完全开源的，因此您可以查看并贡献它的开发方式!

安全模型 & 权限

Codex 允许您通过 --approval-mode 标志（或交互式引导提示）决定代理接收多少_自主权_和自动批准策略： 模式 | 代理可以在不询问的情况下执行的操作 | 仍然需要批准 ---|---|--- Suggest (默认) | • 读取存储库中的任何文件 | • 所有 文件写入/补丁 • 所有 shell/Bash 命令 Auto Edit | • 读取 和 将补丁写入文件 | • 所有 shell/Bash 命令 Full Auto | • 读/写文件 • 执行 shell 命令 | –

在 Full Auto 模式下，为了深度防御，每个命令都在禁用网络的情况下运行，并且限制在当前工作目录（加上临时文件）中。 如果您在目录_未_被 Git 跟踪的情况下以 auto-edit 或 full-auto 模式启动，Codex 也会显示警告/确认信息，因此您始终拥有安全网。

即将推出：一旦我们对其他安全措施充满信心，您就可以将特定命令列入白名单以自动执行，并启用网络。

平台沙箱细节

Codex 使用的强化机制取决于您的操作系统：

这两种方法对于日常使用都是_透明的_ - 您仍然从存储库根目录运行 codex 并像往常一样批准/拒绝步骤。

系统要求

要求 | 细节 ---|--- 操作系统 | macOS 12+、Ubuntu 20.04+/Debian 10+ 或 Windows 11 通过 WSL2 Node.js | 22 或更高版本（推荐 LTS） Git（可选，推荐） | 2.23+ 用于内置 PR 助手 内存 | 至少 4GB（推荐 8GB）

永远不要运行 sudo npm install -g; 修复 npm 权限。

CLI 参考

命令 | 目的 | 例子 ---|---|--- codex | 交互式 REPL | codex codex "…" | 交互式 REPL 的初始提示 | codex "fix lint errors" codex -q "…" | 非交互式“安静模式” | codex -q --json "explain utils.ts" 主要标志：--model/-m、--approval-mode/-a 和 --quiet/-q。

内存 & 项目文档

Codex 按以下顺序合并 Markdown 指令：

  1. ~/.codex/instructions.md – 个人全局指导
  2. 存储库根目录下的 codex.md – 共享项目注释
  3. cwd 中的 codex.md – 子包详情

使用 --no-project-doc 或 CODEX_DISABLE_PROJECT_DOC=1 禁用。

非交互/CI 模式

在管道中以无头模式运行 Codex。 GitHub Action 步骤示例：

- name: Update changelog via Codex
 run: |
  npm install -g @openai/codex
  export OPENAI_API_KEY="${{ secrets.OPENAI_KEY }}"
  codex -a auto-edit --quiet "update CHANGELOG for next release"

设置 CODEX_QUIET_MODE=1 以消除交互式 UI 噪音。

使用示例

以下是一些您可以复制粘贴的小例子。 将引号中的文本替换为您自己的任务。 ✨ | 你输入的内容 | 发生的事情 ---|---|--- 1 | codex "Refactor the Dashboard component to React Hooks" | Codex 重写类组件，运行 npm test 并显示差异。 2 | codex "Generate SQL migrations for adding a users table" | 推断您的 ORM，创建迁移文件，并在沙箱 DB 中运行它们。 3 | codex "Write unit tests for utils/date.ts" | 生成测试，执行它们，并迭代直到它们通过。 4 | codex "Bulk‑rename *.jpeg → *.jpg with git mv" | 安全地重命名文件并更新导入/用法。 5 | codex "Explain what this regex does: ^(?=.*[A-Z]).{8,}$" | 输出逐步的人工解释。 6 | codex "Carefully review this repo, and propose 3 high impact well-scoped PRs" | 建议在当前代码库中具有影响力的 PR。 7 | codex "Look for vulnerabilities and create a security review report" | 查找并解释安全漏洞。

安装

从 npm (推荐)

npm install -g @openai/codex
# 或者
yarn global add @openai/codex

从源代码构建

# 克隆存储库并导航到 CLI 包
git clone https://github.com/openai/codex.git
cd codex/codex-cli
# 安装依赖项并构建
npm install
npm run build
# 直接运行本地构建的 CLI
node ./dist/cli.js --help
# 或为方便起见，全局链接该命令
npm link

配置

Codex 在 ~/.codex/ 中查找配置文件。

# ~/.codex/config.yaml
model: o4-mini # 默认模型
fullAutoErrorMode: ask-user # 或 ignore-and-continue

您还可以定义自定义指令：

# ~/.codex/instructions.md
- Always respond with emojis
- Only use git commands if I explicitly mention you should

常见问题解答

如何阻止 Codex 接触我的存储库？ Codex 始终首先在沙箱中运行。 如果建议的命令或文件更改看起来可疑，您只需在出现提示时回答 n，您的工作树就不会发生任何事情。 它可以在 Windows 上运行吗？ 不能直接运行。 它需要 Windows Subsystem for Linux (WSL2) – Codex 已在 macOS 和 Linux 上使用 Node ≥ 22 进行了测试。 支持哪些模型？ Responses API 提供的任何模型。 默认值为 o4-mini，但传递 --model gpt-4o 或在您的配置文件中设置 model: gpt-4o 以覆盖。

贡献

该项目正在积极开发中，代码可能会发生重大变化。 一旦完成，我们将更新此消息！

更广泛地说，我们欢迎贡献 - 无论您是第一次提交 pull request 还是经验丰富的维护人员。 同时，我们关心可靠性和长期可维护性，因此合并代码的门槛有意很高。 下面的指南阐明了“高质量”在实践中的含义，并且应该使整个过程透明和友好。

开发工作流

# Watch mode (tests rerun on change)
npm run test:watch
# Type‑check without emitting files
npm run typecheck
# Automatically fix lint + prettier issues
npm run lint:fix
npm run format:fix

编写高影响代码变更

  1. 从一个 issue 开始。 打开一个新的 issue 或评论现有的讨论，以便我们可以在编写代码之前就解决方案达成一致。
  2. 添加或更新测试。 每个新功能或错误修复都应该带有测试覆盖，该测试在更改之前失败并在更改之后通过。 不需要 100% 覆盖率，但目标是有意义的断言。
  3. 记录行为。 如果您的更改影响用户行为，请更新 README、内联帮助 (codex --help) 或相关的示例项目。
  4. 保持提交原子性。 每次提交都应该编译并且测试应该通过。 这使得审查和潜在的回滚更容易。

提交 Pull Request

审核流程

  1. 一名维护人员将被分配为主要审核人。
  2. 我们可能会要求更改 - 请不要因此而感到不快。 我们重视这项工作，我们也重视一致性和长期可维护性。
  3. 当达成共识认为 PR 符合标准时，维护人员将进行 squash 并合并。

社区价值观

获取帮助

如果您在设置项目时遇到问题，想要获得关于某个想法的反馈，或者只是想说 hi - 请打开一个讨论或跳转到相关的问题。 我们很乐意提供帮助。

我们可以一起使 Codex CLI 成为一个令人难以置信的工具。 祝您黑客愉快！ 🚀

开发者原创证明 (DCO)

所有提交必须包含 Signed‑off‑by: 页脚。 这一行自我证明告诉我们您编写了代码，并且可以根据存储库的许可证进行贡献。

如何签名（推荐流程）

# squash your work into ONE signed commit
git reset --soft origin/main     # stage all changes
git commit -s -m "Your concise message"
git push --force-with-lease      # updates the PR

我们仅强制执行 squash‑and‑merge，因此单个签名提交足以用于整个 PR。

快速修复

场景 | 命令 ---|--- 修改上次提交 | git commit --amend -s --no-edit && git push -f 仅 GitHub UI | 编辑 PR 中的提交消息 → 添加 Signed-off-by: Your Name <email@example.com> DCO 检查会阻止合并，直到 PR 中的每次提交都带有页脚（使用 squash 只是其中之一）。

安全 & 负责任的 AI

您是否发现了漏洞或对模型输出有疑虑？ 请发送电子邮件至 security@openai.com，我们将及时回复。

许可证

该存储库已获得 Apache-2.0 License 的许可。

关于

Lightweight coding agent that runs in your terminal

Resources

Readme

License

Apache-2.0 license Activity Custom properties

Stars

3.6k stars

Watchers

70 watching

Forks

271 forks Report repository

Releases

No releases published

Packages 0

No packages published

Contributors 20

+ 6 contributors

Languages

Footer

© 2025 GitHub, Inc.

Footer navigation

You can’t perform that action at this time.