文档

本页内容来自 GitHub 文档的简体中文版本。

OpenAI Codex CLI 文档（简体中文）

本页为对 openai/codex 文档的中文整理与翻译，便于中国用户学习与使用。请以上游仓库为准，我们会定期同步更新。

目录

快速开始

安装与运行 Codex CLI

使用你熟悉的包管理器全局安装：

npm install -g @openai/codex  # 或使用 Homebrew：brew install codex

安装完成后，在终端运行：

codex

也可以从 最新 Release 下载对应平台的二进制包。

配合 ChatGPT 套餐使用

首次运行 codex 选择“使用 ChatGPT 登录”。需要 Plus / Pro / Team 账号。登录后可使用我们的最新模型（包含 gpt-5）。

从 API Key 用量计费迁移：

  1. 执行 codex update，确保 codex --version ≥ 0.13
  2. 确保未设置 OPENAI_API_KEY 环境变量（env | grep OPENAI_API_KEY 应为空）
  3. 重新运行 codex login

Codex CLI 登录示意

通过 VPS / 远程主机连接

若在无本地浏览器的远程主机运行，登录助手会在远程 localhost:1455 开端口。请先做端口转发，再开始登录：

# 在你的本地机器上执行
ssh -L 1455:localhost:1455 <user>@<remote-host>

用量计费替代：使用 API Key

你也可以选择使用 OpenAI API Key 进行用量计费（Usage-based）。请参考配置章节并设置环境变量或配置文件。

选择 Codex 的自治等级

  • 1. 读/写：允许 Codex 在工作区读写、更改文件与运行命令（推荐）。
  • 2. 只读：禁止写入；适合审阅与问答。
  • 3. 高级配置：在 config.toml 中按需细化（例如审批策略、允许的命令/目录白名单等）。

示例提示

  • “为登录流程增加 2FA，并补充端到端测试。”
  • “修复支付回调签名的边界条件 bug，补充回归测试。”
  • “将主题配色抽为 CSS 变量，并添加暗色模式切换。”

以提示作为输入运行

Codex 支持在非交互模式下以提示（Prompt）作为输入运行，并输出补丁和日志，便于脚本化集成到你的工具链或 CI 中。

使用开源模型

Codex 支持配置并使用部分开源或第三方模型。请参考 CLI 与配置章节，设置模型端点与凭据。

平台沙箱说明

CLI 在本地提供多种沙箱级别（只读/读写、网络开关、命令白名单等），以避免危险操作。建议在团队中启用默认防护并逐步放宽。

实验性技术声明

Codex 属于快速演进中的产品。我们在持续改进可靠性、指令遵循与可解释性。请在关键任务中保留人工复核。

系统要求

  • macOS 或 Linux（x86_64 / arm64）
  • 终端可访问 Git、常见构建工具（按你的技术栈而定）

CLI 参考

常用命令示例：

# 启动交互式会话
codex

# 更新 CLI
yes | codex update

# 查看版本
codex --version

# 登出 / 重新登录
codex logout && codex login

记忆与项目文档

Codex 会使用最小必要上下文与项目自述（如 AGENTS.md）来完成任务。你可以在仓库内提供运行与开发说明，以更好指导 Codex。

非交互 / CI 模式

支持在 CI 中运行，输出补丁与日志产物，便于自动化验证。可结合审批策略限制危险操作。

Model Context Protocol（MCP）

Codex 逐步支持 MCP，为模型提供标准化的工具与上下文接口。

追踪 / 详细日志

可开启详细日志用于故障排查或审计。日志包含命令运行记录、模型调用与补丁提案等。

DotSlash

支持通过 DotSlash 等方式对可执行工具进行声明式管理，提升跨平台一致性。

配置

在配置文件 config.toml 或环境变量中设置：

  • model / mini_model：指定默认与低延迟模型（如 gpt-5 / codex-mini-latest）
  • approvals：审批策略（如 on-request、on-failure、never 等）
  • sandbox：读写权限、网络开关、命令白名单
  • api_key：使用 OpenAI API Key 的用量计费模式

FAQ

  • 是否支持本地/私有化？ 可在本地机器运行；也可在私有环境中结合审批/沙箱策略使用。
  • 如何减少失控改动？ 使用只读模式或严格审批；在 CI 中验证补丁。
  • 如何让 Codex 更懂我的仓库？ 在仓库放置 AGENTS.md 与常见操作脚本，提供运行与测试说明。

零数据保留（ZDR）

在企业合规场景，可选择零数据保留（ZDR）模式，详见上游文档与企业方案。

Codex 开源基金

我们资助高影响力的开源项目与社区，详情请见上游仓库的说明与申请方式。

贡献指南

  • 开发流程、提 PR、评审流程与社区规范请参考上游仓库。
  • 提交贡献前需签署贡献者许可协议（CLA）。支持“Quick fixes”。

安全与负责任 AI

我们遵循安全开发流程与负责任 AI 准则，持续改进可解释性与防护。

许可

许可与版权以上游仓库为准：openai/codex。