文章目录

1. 引言

在前几篇文章里,博主已经把 Codex 的核心能力与关键概念做了系统梳理:它是什么、能做什么、以及为什么它更像“工程级 AI 编程代理”而不是普通的代码补全工具。有兴趣的童鞋可以先阅读:

如果要真正把 Codex 用“顺手”,往往不取决于你会不会写提示词,而取决于你选对了入口:有些任务适合在 IDE 里边写边改边跑;有些更适合在 CLI 里批处理、跑脚本或做审查;而当你希望它并行处理、自动跑测试、甚至直接产出可验证的 diff/PR 时,Codex 云端(Web/Cloud) 反而更高效…

因此,本文不再重复讲原理,而是聚焦一个更实用的问题:Codex 在不同端(IDE / CLI / Web / 集成平台)分别怎么用、各自适合什么场景、以及如何做选择

2. IDE 插件(IDE Extension)

2.1 概述

原文地址:https://developers.openai.com/codex/ide
视频地址:https://youtu.be/sd21Igx4HtA

CodexOpenAI 的编程智能代理,它可以读取、编辑和运行代码,帮助你更快构建项目、修复错误并理解不熟悉的代码,Codex 可以通过 VS Code 扩展 在你的 IDE 中并排工作,或将任务委托到云端执行。

Codex IDE 扩展支持 Visual Studio Code 的各类版本,包括 Visual Studio Code、Cursor、Windsurf,也可以从对应市场下载安装扩展:

注:macOS 和 Linux 上扩展支持完全;Windows 上当前为实验性支持。建议在 Windows 上使用 WSL 工作区获得最佳体验。

安装完成后:

  1. 在 IDE 左侧扩展栏中可以看到 Codex 图标;
  2. 如果没有显示,在 VS Code 中重启编辑器;
  3. 在 Cursor 等 IDE 中,可能需要固定图标以便显示。
    在这里插入图片描述

也可以将 Codex 拖动到右侧侧边栏作为一个独立的标签页查看:
在这里插入图片描述

安装扩展后,它会提示你使用 ChatGPT 帐户登录 或使用 API 密钥。下面是使用 Codex IDE 扩展一些常用的工作方式:

  • 利用编辑器上下文提示: 使用打开文件、选中的代码和文件标识符,使提示更相关;
  • 切换模型: 可以从默认模型切换到其它支持代码的模型;
  • 调整推理强度: 根据任务难度选择 “低、中、高” 推理设置,以权衡速度与深度;
  • 选择审批模式: 可在 Chat、Agent、Agent(Full Access) 之间切换 Codex 的自主权限;
  • 委托到云端: 将复杂任务发送到云端执行,然后在 IDE 中监控进度并查看结果;
  • 继续云端作业: 预览云端生成的变更、请求后续操作,并在本地测试完成它们。

2.2 扩展功能

原文地址:https://developers.openai.com/codex/ide/features

1. 使用 Codex IDE 扩展可以做什么

Codex IDE 扩展让你可以在 VS Code、Cursor、Windsurf 及其他兼容 VS Code 的编辑器中直接访问 Codex。它使用与 Codex CLI 相同的智能体,并共享相同的配置。


2. Codex 提示词

在编辑器中使用 Codex 聊天、编辑和预览更改,当 Codex 拥有来自打开文件和选中代码的上下文时,你可以写更短的提示,并获得更快、更相关的结果

可以通过在提示中引用编辑器里的文件来指定上下文,例如(将 @example.tsx 作为参考文件):

Use @example.tsx as a reference to add a new page named "Resources" to the app that contains a list of resources defined in @resources.ts

3. 切换模型(Switch between models)

可以在聊天输入框下方的切换器中切换不同的模型。

在这里插入图片描述


4. 调整推理强度(Adjust reasoning effort)

你可以调整 Codex 的推理强度,以控制 Codex 在响应前思考多久(更高的推理强度适用于更复杂的任务,但响应时间会更长,也会消耗更多令牌/配额)。


5. 选择审批模式(Choose an approval mode)

默认情况下,Codex 使用 “Agent”(代理)模式,在此模式下,Codex 可以自动读取文件、进行编辑并在工作目录中运行命令,如果 Codex 要访问工作目录以外的文件或网络,仍然需要你的批准,如果只是想聊天或先规划再修改,可以切换到 “Chat”(聊天)模式:
在这里插入图片描述

如果需要 Codex 读取文件、编辑并运行命令且无需批准,可以选择 “Agent(Full Access)”(完全访问)模式 — 但这种模式要谨慎使用。


6. 云端委派(Cloud delegation)

你可以将较大的任务委派给云端的 Codex,然后在 IDE 中跟踪进度并审查结果,而无需离开当前工作环境。

  1. 设置一个 Codex 云环境(https://chatgpt.com/codex/settings/environments
  2. 选择运行在云端

在这里插入图片描述

当你从本地对话启动云端任务时,Codex 会记住对话上下文,这样你可以在之后从相同位置继续进行。


7. 云端任务后续(Cloud task follow-up)

Codex 扩展让你轻松预览云端变更,你可以要求后续任务在云端运行,但通常你也可以将更改应用到本地以测试和完成任务,在本地继续对话时,Codex 仍会保留上下文以节省时间。
在这里插入图片描述


8. 将图片拖放到提示中

你可以将图片拖放到提示编辑器中作为上下文内容(按住 Shift 拖放图片),在 VS Code 中默认阻止扩展接收拖放,所以必须这样操作。

2.3 设置

原文地址:https://developers.openai.com/codex/ide/settings

如果要更改设置,需要按照下面步骤操作:

  1. 打开编辑器设置。
  2. 搜索 “Codex” 或具体设置名称。
  3. 修改对应的值。([OpenAI][1])

注意: 有些行为(例如默认模型、审批策略和沙箱设置)不在编辑器设置中配置,而是在共享的 ~/.codex/config.toml 文件中设置(与 Codex CLI 共用)。

以下是可以在编辑器中直接配置的设置项及其含义:

设置项 说明
chatgpt.cliExecutable 仅限开发用途:指定 Codex CLI 可执行文件的路径,一般不需要手动设置,手动设置可能会导致扩展部分功能异常
chatgpt.commentCodeLensEnabled 在待办(TODO)注释上方显示 CodeLens,让你可以用 Codex 快速完成这些待办项。
chatgpt.localeOverride Codex UI 界面的首选语言,留空表示自动检测语言。
chatgpt.openOnStartup 启动扩展时自动聚焦到 Codex 侧边栏。
chatgpt.runCodexInWindowsSubsystemForLinux 仅 Windows 平台:当 Windows Subsystem for Linux(WSL)可用时,是否在 WSL 中运行 Codex,推荐开启以提升沙箱安全性和性能,目前在 Windows 上运行 Codex Agent 模式需要 WSL。更改此项后需要重新加载 VS Code 才会生效。

2.4 命令

原文地址:https://developers.openai.com/codex/ide/commands

这是 Codex IDE 扩展VS Code(及兼容 IDE)命令面板 中可用的命令列表,可以从命令面板运行这些命令,也可以将它们绑定到快捷键。如果想为某个 Codex 命令分配或更改快捷键,按如下步骤执行:

Step 1:打开命令面板:

  • macOS 上按 Cmd + Shift + P
  • Windows/Linux 上按 Ctrl + Shift + P

Step 2:运行 Preferences: Open Keyboard Shortcuts(首选项:打开键盘快捷键)。

Step 3: 搜索 “Codex” 或命令 ID(例如 chatgpt.newChat)。

Step 4: 点击铅笔图标,然后输入你想使用的快捷键。

命令 ID 默认快捷键 说明
chatgpt.addToThread - 将选中的文本片段作为上下文添加到当前会话线程中。
chatgpt.addFileToThread - 将当前整个文件作为上下文添加到当前会话线程中。
chatgpt.newChat macOS: Cmd + N
Windows/Linux: Ctrl + N
创建一个新的对话线程。
chatgpt.implementTodo - 让 Codex 处理当前选中的 TODO 注释。
chatgpt.newCodexPanel - 打开一个新的 Codex 面板。
chatgpt.openSidebar - 打开 Codex 侧边栏面板。

这些命令可以更方便地与 Codex 交互并控制它在 IDE 中的工作方式。

2.5 斜杠命令

原文地址:https://developers.openai.com/codex/ide/slash-commands

斜杠命令是一种快速控制 Codex 的方式,在聊天输入中输入 / 然后选择或输入命令名称即可执行特定动作,具体的使用方式如下:

  1. Codex 聊天输入框 中输入 /
  2. 从出现的列表中选择一个命令,或者继续输入以筛选命令(例如 /status)。
  3. Enter 执行命令。

可用的斜杠命令 列表

斜杠命令 说明
/auto-context 开启或关闭自动上下文功能,让 Codex 自动包括最近打开的文件和 IDE 上下文。
/cloud 切换到 云端模式,让任务在远程云环境执行(需要已启用云访问权限)。
/cloud-environment 选择要使用的云环境(仅在云端模式下可用)。
/feedback 打开反馈对话框,提交反馈内容,并可附带日志。
/local 切换到 本地模式,在本地工作区运行任务。
/review 启动代码复查模式,用于查看未提交的更改或与某个基础分支比较。
/status 显示当前线程 ID、上下文使用情况和速率限制等状态信息。

3. CLI(终端)

3.1 概述

原文地址:https://developers.openai.com/codex/cli
视频地址:https://youtu.be/iqNzfK4_meQ

Codex CLI 是 OpenAI 发布的 终端编码代理工具,可以在本地的终端(Terminal / Shell)中运行它。Codex CLI 能 读取、修改和执行代码,与目录中的代码库交互,帮助你处理各种开发任务(包括编辑文件、运行命令等),它是开源的,用 Rust 语言实现,以提高速度和效率。

3.1.1 安装设置CLI

可以使用包管理器以及Homebrew的方式安装 CLI

# 使用 npm
npm install -g @openai/codex

# 使用 Homebrew 安装(macOS)
brew install --cask codex

安装完成后,在终端输入 codex 运行即可,首次运行时需要登录认证你的 ChatGPT 账户或使用 API Key。

运行:输入 codex 启动交互式会话,它会读取当前目录,生成和执行命令,并在全屏交互模式下与 Codex 进行对话。

3.1.2 主要功能

1. 交互式模式(Interactive Mode):运行 codex 不带参数时进入交互式界面,你可以在这个界面中:

  • 输入自然语言提示让 Codex 生成、修改或解释代码。
  • 审查 Codex 规划的步骤并按需批准或拒绝。

2. 恢复会话:Codex 会保存历史会话,你可以使用命令恢复之前的工作状态,这样 Codex 可以继续利用已有的上下文,而不必重新输入信息

  • codex resume —— 选择并恢复某个会话
  • codex resume --last —— 恢复最近一次的会话
  • 指定会话 ID 恢复特定 session

3.模型切换与推理设置:在 CLI 会话中,Codex 默认使用与平台匹配的模型,也可以使用 /model 命令或启动参数指定不同模型:

  • macOS / Linux 默认是 gpt-5-codex
  • Windows 默认是 gpt-5

4. 图片输入:Codex CLI 支持将图片作为输入上下文,例如屏幕截图或设计规范,也可以同时附带多张图片(用逗号分隔):

codex -i 错误截图.png "解释这个错误"

5.本地代码审查模式:在 CLI 中输入 /review 即可启动代码审查功能,这一过程不会修改你的工作区;建议在 pull request 之前使用。

  • 扫描未提交的更改
  • 对比某个分支的差异
  • 优先提出可执行的改进建议

6. 网络搜索支持(可选):可以启用 Codex 调用网络搜索来获取新上下文(需要在配置或命令中启用)。


7. 自动完成 Shell 脚本:执行如下脚本,可以输出对应 shell(bash / zsh / fish 等)的自动补全脚本,方便日常使用

codex completion bash

8. 批准模式(Approval Modes):这些模式控制 Codex 在执行编辑/命令之前是否需要你确认:

  • Auto(默认):自动读写当前目录中的文件,外部操作仍需审批
  • Read-Only:Codex 只能读代码,不会修改
  • Full Access:允许 Codex 在整个系统范围内运行命令(建议谨慎使用)([OpenAI][2])

9. 自动化脚本(Scripting):你可以使用子命令 codex exec 运行非交互任务,适合结合脚本或 CI/CD 流程自动化繁琐任务,例如:

codex exec "修复 CI 失败"

10. 与 Codex Cloud 集成:使用 codex cloud 命令可以:

  • 查看和启动云端任务
  • 在本地应用任务结果 diff

例如:

codex cloud exec --env ENV_ID "总结未解决的 bug"

这样可以在本地终端启动云端 Codex 任务,并将更改合并到项目中。


11. 斜杠命令(Slash Commands)支持:可以利用以 / 开头的命令快速调用特定工作流,如 /review/fork 或自定义的命令。


12. 模型上下文协议(MCP)支持:Codex CLI 也可以通过 Model Context Protocol(MCP) 连接到扩展工具,例如语言服务器或外部数据源,让 AI 能访问更多的上下文资源

3.2 功能

原文地址:https://developers.openai.com/codex/cli/features

下面是 Codex CLI(命令行界面) 的功能说明

交互模式(Interactive Mode)

运行命令:

codex
codex "Explain this codebase to me"

启动全屏终端 UI,你可以通过自然语言提示让 Codex 读取代码库、生成修改、执行命令 并实时互动。也可以发送提示、代码片段、甚至图像(截图)、实时查看 Codex 的计划,并批准或拒绝它要执行的步骤。


恢复会话(Resuming Conversations)

Codex 会将会话记录保存在本地,因此可以恢复之前的工作状态:

  • codex resume —— 选择并恢复某个交互式会话
  • codex resume --last —— 恢复最近的一次
  • codex resume <SESSION_ID> —— 根据 ID 直接恢复某次会话

例如:

codex exec resume --last "Fix the race conditions you found"
codex exec resume 7f9f9a2e-1b3c-4c7a-9b0e-.... "Implement the plan"

恢复会话时,Codex 会保留历史对话、计划记录和批准状态,这样能继续用已有上下文工作。


模型与推理(Models and Reasoning)

默认情况下:

  • macOS/Linux 使用 gpt-5-codex
  • Windows 使用 gpt-5

可以通过命令 /model 或 CLI 启动参数来切换模型。

codex --model gpt-5-codex

图像输入(Image Inputs)

你可以在命令行中附带一或多张图片,让 Codex 一起分析图像内容,例如设计图、错误截图等:

codex -i screenshot.png "解释这个错误"
codex --image img1.png,img2.jpg "Summarize these diagrams"

支持常见格式(如 PNG、JPEG)并可以多个文件一起输入。


本地代码审查(Local Code Review)

在 CLI 中输入 /review,启动代码审查模式。可以:

  • 审查未提交更改
  • 对比某个基础分支
  • 对某个提交历史进行审查

Codex 会输出重点反馈,而不会自动更改文件。


网络搜索(Web Search)

Codex CLI 内置可选的网络搜索功能:

  • 通过配置文件或命令参数启用网络搜索
  • 启用后,Codex 可以在需要时查询最新的网页内容来补充上下文,提高准确性。
[features]
web_search_request = true

[sandbox_workspace_write]
network_access = true

命令行提示执行(Running with an Input Prompt)

可以直接在命令行后跟提示,让 Codex 读取当前目录、规划步骤并返回结果,而不打开交互界面,并结合 --path--model 等参数进一步控制行为。

codex "解释这个代码库"

Shell 自动补全(Shell Completions)

可以生成并安装自动补全脚本(bash/zsh/fish),让终端支持,然后将补全脚本加入你的 shell 配置文件,实现按 Tab 自动补全命令和参数。

codex completion bash
codex completion zsh
codex completion fish

批准模式(Approval Modes)

批准模式控制 Codex 在执行修改/命令前是否需要你的确认:

  • Auto(默认): 自动读取、编辑和运行命令(工作目录内),网络操作或系统范围行为仍需审批
  • Read-only : 只读模式,不修改文件或执行命令(等待你批准)
  • Full Access: 允许 Codex 跨系统修改并运行命令(风险较高,需谨慎)

自动化与脚本运行(Scripting)

可以通过 codex exec 子命令让 Codex 非交互式执行任务,输出结果或计划到标准输出,方便结合脚本和自动化工作流,这对 自动化任务、CI/CD 流程非常有用。

codex exec "修复 CI 失败"

与 Codex Cloud 集成(Cloud Tasks)

可以使用:

codex cloud exec --env ENV_ID "Summarize open bugs"

在 CLI 中浏览、启动云端任务,并可以将任务生成的更改应用到本地项目,无需离开终端。


斜杠命令支持(Slash Commands)

命令行中也支持以 / 开头的快捷命令,例如:

  • /review
  • /fork
  • 以及自定义的命令

这些命令可以快速执行特定工作流。


提示编辑器(Prompt Editor)

在 CLI 会话中按 Ctrl+G 可打开系统定义的编辑器(如 Vim / VS Code),便于输入、修改大量提示文本,然后发送回 Codex 执行。


Model Context Protocol(MCP) 支持

Codex CLI 支持通过 MCP 协议连接额外工具和数据源:

  • ~/.codex/config.toml 配置 MCP 服务器
  • Codex 在会话启动时自动启动相关服务,并将工具集成到工作流中

其他实用提示(Tips & Shortcuts)

下面是提升使用体验的快捷操作:

  • 输入 @ 在当前工作区快速模糊搜索文件路径
  • 在提示行前加 ! 执行本地 shell 命令
  • 启动 Codex 时指定路径:codex --cd <目录>
  • 添加多个可写根目录:--add-dir

3.3 命令行选项

原文地址:https://developers.openai.com/codex/cli/reference

3.3.1 全局标志

类型 / 值 说明
--add-dir path 在主工作区之外,额外授予目录写权限。可重复指定多个路径。
--ask-for-approval, -a untrusted on-failure
--cd, -C path 在代理开始处理请求之前设置工作目录。
--config, -c key=value 覆盖配置值。如果可能,值会按 JSON 解析;否则使用字面字符串。
--dangerously-bypass-approvals-and-sandbox, --yolo boolean 在不请求批准且不使用沙箱的情况下运行所有命令。仅应在外部已加固的环境中使用。
--disable feature 强制禁用某个功能标志(等价于 -c features.<name>=false)。可重复。
--enable feature 强制启用某个功能标志(等价于 -c features.<name>=true)。可重复。
--full-auto boolean 低摩擦本地工作的快捷方式:设置 --ask-for-approval on-request--sandbox workspace-write
--image, -i path[,path…] 向初始提示附加一个或多个图像文件。多个路径用逗号分隔,或重复该标志。
--model, -m string 覆盖配置中的模型(例如 gpt-5-codex)。
--oss boolean 使用本地开源模型提供方(等价于 -c model_provider="oss")。会验证 Ollama 是否正在运行。
--profile, -p string ~/.codex/config.toml 中加载的配置 profile 名称。
--sandbox, -s read-only workspace-write
--search boolean 启用网络搜索。为 true 时,代理可在无需每次询问的情况下调用 web_search 工具。
PROMPT string 用于启动会话的可选文本指令。省略则直接启动 TUI,不预填消息。

这些选项适用于基础 codex 命令,并会传递给每个子命令,除非下方某个部分另有说明。
在使用子命令时,请将全局标志放在子命令之后(例如 codex exec --oss ...),以确保它们按预期生效。


3.3.2 命令概览

Maturity(成熟度)列使用诸如 Experimental(实验)Beta(测试)Stable(稳定) 等标签。

成熟度 说明
codex Stable 启动终端 UI。接受上述全局标志以及可选提示或图像附件。
codex app-server Experimental 启动 Codex 应用服务器,用于本地开发或调试。
codex apply Stable 将 Codex Cloud 任务生成的最新 diff 应用到本地工作树。别名:codex a
codex cloud Experimental 在不打开 TUI 的情况下,从终端浏览或执行 Codex Cloud 任务。别名:codex cloud-tasks
codex completion Stable 生成 Bash、Zsh、Fish 或 PowerShell 的 shell 自动补全脚本。
codex exec Stable 非交互方式运行 Codex。别名:codex e。将结果流式输出到 stdout 或 JSONL,并可恢复之前的会话。
codex execpolicy Experimental 评估 execpolicy 规则文件,查看某个命令会被允许、提示还是阻止。
codex login Stable 使用 ChatGPT OAuth、设备认证或通过 stdin 传入的 API key 进行认证。
codex logout Stable 移除已存储的认证凭据。
codex mcp Experimental 管理 Model Context Protocol 服务器(列出、添加、删除、认证)。
codex mcp-server Experimental 将 Codex 本身作为 MCP 服务器通过 stdio 运行,供其他代理使用。
codex resume Stable 通过 ID 继续先前的交互式会话,或恢复最近一次对话。
codex sandbox Experimental 在 Codex 提供的 macOS seatbelt 或 Linux landlock 沙箱中运行任意命令。

3.3.3 命令解析

3.3.3.1 codex

在没有子命令的情况下运行 codex 会启动交互式终端 UI(TUI)。代理接受上述全局标志以及图像附件。使用 --search 启用网页浏览,使用 --full-auto 允许 Codex 在大多数情况下无需提示即可运行命令。


3.3.3.2 codex app-server

在本地启动 Codex 应用服务器,主要用于开发和调试,接口和行为可能随时更改,不另行通知


3.3.3.3 codex apply

将 Codex 云任务生成的最新 diff 应用到本地仓库,必须已经认证,并且对该任务有访问权限。

类型 / 值 说明
TASK_ID string 要应用 diff 的 Codex Cloud 任务标识符。

Codex 会打印被打补丁的文件;如果 git apply 失败(例如发生冲突),将以非零状态码退出。


3.3.3.4 codex cloud

从终端与 Codex Cloud 任务交互,默认命令会打开交互式选择器,codex cloud exec 会直接提交一个任务。

类型 / 值 说明
–attempts 1–4 Codex Cloud 运行的助手尝试次数(best-of-N)。
–env ENV_ID 目标 Codex Cloud 环境标识符(必填)。使用 codex cloud 查看可选项。
QUERY string 任务提示。如果省略,Codex 会交互式询问细节。

认证方式与主 CLI 相同,若任务提交失败,Codex 会以非零状态码退出。


3.3.3.5 codex completion

生成 shell 自动补全脚本,并将输出重定向到合适的位置,例如:codex completion zsh > "${fpath[1]}/_codex"

类型 / 值 说明
SHELL bash、zsh 、 fish 、 power-shell 、 elvish 要生成补全脚本的 shell,输出打印到 stdout。

3.3.3.6 codex exec

使用 codex exec(或简写 codex e)进行脚本化或 CI 场景的运行,这类运行应当在无需人工交互的情况下完成。

类型 / 值 说明
--cd, -C path 在执行任务前设置工作区根目录。
--color always 、never 、 auto 控制 stdout 中的 ANSI 颜色。
--dangerously-bypass-approvals-and-sandbox, --yolo boolean 跳过批准提示和沙箱。危险——仅在隔离的执行环境中使用。
--full-auto boolean 应用低摩擦自动化预设(workspace-write 沙箱 + on-request 批准)。
--image, -i path[,path…] 将图像附加到第一条消息。可重复;支持逗号分隔。
--json, --experimental-json boolean 输出逐行 JSON 事件,而不是格式化文本。
--model, -m string 覆盖本次运行使用的模型。
--oss boolean 使用本地开源模型提供方(需要运行中的 Ollama 实例)。
--output-last-message, -o path 将助手的最终消息写入文件,便于后续脚本处理。
--output-schema path 描述期望最终响应结构的 JSON Schema 文件。Codex 会校验工具输出。
--profile, -p string 选择在 config.toml 中定义的配置 profile。
--sandbox, -s read-only workspace-write
--skip-git-repo-check boolean 允许在非 Git 仓库目录中运行(适用于一次性目录)。
-c, --config key=value 为非交互式运行内联覆盖配置(可重复)。
PROMPT string -(从 stdin 读取)

3.3.3.7 Resume 子命令
codex exec resume [SESSION_ID]

通过 ID 恢复一个 exec 会话,或使用 --last 继续最近一次会话,可接受一个可选的后续提示。默认情况下 Codex 会输出格式化文本,添加 --json 可获得逐行 JSON 事件(每次状态变化一条)。

类型 / 值 说明
--last boolean 跳过选择器,自动恢复最近一次对话。
PROMPT string 、 - 恢复后立即发送的可选后续指令。
SESSION_ID uuid 恢复指定会话;若省略则需使用 --last

3.3.3.8 codex execpolicy

在保存 execpolicy 规则文件前进行检查。codex execpolicy check 接受一个或多个 --rules 标志(例如 ~/.codex/rules 下的文件),并输出 JSON,展示最严格的决策结果匹配到的规则,添加 --pretty 可格式化输出,execpolicy 当前处于预览阶段。

类型 / 值 说明
--pretty boolean 美化打印 JSON 结果。
--rules, -r path(可重复) 要评估的 execpolicy 规则文件路径。可组合多个文件。
COMMAND... var-args 要根据指定策略进行检查的命令。

3.3.3.9 codex login

使用 ChatGPT 账户或 API key 对 CLI 进行认证,不带标志时,Codex 会打开浏览器进入 ChatGPT OAuth 流程。

类型 说明
--with-api-key boolean 从 stdin 读取 API key(例如 printenv OPENAI_API_KEY | codex login --with-api-key)。
status、subcommand codex login status 打印当前激活的认证方式;在已登录时以状态码 0 退出,便于自动化脚本判断。

3.3.3.10 codex logout

移除已保存的 API key 和 ChatGPT 认证凭据,该命令没有任何标志


3.3.3.11 codex mcp

管理存储在 ~/.codex/config.toml 中的 Model Context Protocol 服务器条目。

子命令 选项 说明
add <name> -- <command...> --url <value>
get <name> --json 显示指定服务器配置,--json 输出原始配置条目
list --json 列出已配置的 MCP 服务器,--json 用于机器可读输出
login <name> --scopes scope1,scope2 对支持 OAuth 的可流式 HTTP 服务器发起登录
logout <name> 移除该 HTTP 服务器的 OAuth 凭据
remove <name> 删除已存储的 MCP 服务器定义

add 子命令的额外选项:

类型 / 值 说明
--bearer-token-env-var ENV_VAR 连接可流式 HTTP 服务器时,将该环境变量的值作为 bearer token 发送。
--env KEY=VALUE 可重复 启动 stdio 服务器时设置的环境变量。
--url https://… 注册可流式 HTTP 服务器,与 COMMAND... 互斥。
COMMAND... stdio transport 启动 MCP 服务器的可执行程序及其参数,放在 -- 之后。

OAuth 操作(login、logout)仅适用于可流式 HTTP 服务器,且服务器必须支持 OAuth。


3.3.3.12 codex mcp-server

通过 stdio 将 Codex 作为 MCP 服务器运行,以供其他工具连接,该命令会继承全局配置覆盖,并在下游客户端关闭连接时退出。


3.3.3.13 codex resume

通过 ID 继续一个交互式会话,或恢复最近一次对话,codex resume 接受与 codex 相同的全局标志,包括模型和沙箱覆盖。

类型 / 值 说明
--last boolean 跳过选择器,自动恢复最近一次对话。
PROMPT string -
SESSION_ID uuid 恢复指定会话;若省略则需使用 --last

3.3.3.14 codex sandbox

使用沙箱辅助工具,在与 Codex 内部相同的策略下运行命令。

macOS Seatbelt:

类型 / 值 说明
--config, -c key=value 向沙箱运行传入配置覆盖(可重复)。
--full-auto boolean 无需批准地授予当前工作区和 /tmp 的写权限。
COMMAND... var-args 在 macOS Seatbelt 下执行的 shell 命令,-- 之后的内容会被原样转发。

Linux Landlock:

类型 / 值 说明
--config, -c key=value 在启动沙箱前应用的配置覆盖(可重复)。
--full-auto boolean 在 Landlock 沙箱内授予当前工作区和 /tmp 的写权限。
COMMAND... var-args 在 Landlock + seccomp 下执行的命令,可执行程序放在 -- 之后。

标志组合与安全建议:

  • 对于无人值守的本地工作,可设置 --full-auto,但避免--dangerously-bypass-approvals-and-sandbox 组合使用,除非你身处专用的沙箱虚拟机中。
  • 当需要授予 Codex 对更多目录的写权限时,优先使用 --add-dir,而不是强制使用 --sandbox danger-full-access
  • 在 CI 中,将 --json--output-last-message 搭配使用,可同时捕获机器可读的进度信息最终的自然语言总结

3.3 斜杠命令

原文地址:https://developers.openai.com/codex/cli/slash-commands

3.3.1 概览

斜杠命令能让你在交互式 Codex 会话中快速使用键盘进行控制。在对话输入框中输入 / 会出现斜杠命令弹窗,选择命令后,Codex 会执行对应操作,比如切换模型、调整审批设置,或在不离开终端的情况下总结长对话。下面是一些常用命令及其作用:

命令 作用
/approvals 设置 Codex 在无需再次询问的情况下可以执行哪些类型的操作(调整审批策略)。
/compact 总结当前可见对话内容,以节省上下文空间。
/diff 显示 Git 差异,包括未被 Git 跟踪的文件。
/exit/quit 退出 CLI 会话。
/feedback 发送日志和诊断信息给 Codex 维护者。
/init 在当前目录生成一个 AGENTS.md 初始文件。
/logout 登出 Codex(清除本地凭据)。
/mcp 列出当前可用的 Model Context Protocol 工具。
/mention 将某个文件附加到当前对话,让 Codex 关注它。
/model 选择当前使用的模型。
/fork 将已保存的会话分支为新线程。
/resume 恢复一个已保存的会话。
/new 在当前 CLI 会话里开始一个新的对话。
/review 请求 Codex 审查当前工作目录的更改。
/status 显示当前会话状态,例如活跃模型、审批策略、Token 使用情况等。

当然还可以创建属于自己的重复使用的提示(带参数或元数据),让它们像斜杠命令一样被调用,例如:

/prompts:<命令名>

3.3.2 斜杠命令例子

3.3.2.1 切换模型(model)

在 Composer 中输入:

/model

然后在弹出列表中选择所需的模型,例如 gpt-4.1-mini 或其他更深层次模型。
Codex 会确认模型已切换。使用 /status 可验证当前设置。([OpenAI][1])


3.3.2.2 更新审批规则(approvals)

输入:

/approvals

然后选择适合的审批预设,比如 “Auto”(自动审批)或 “Read Only”(只读模式)。未来操作将按照这个策略执行。


3.3.2.3 查看状态(status)

在任何对话中输入:

/status

Codex 会显示当前会话的主要信息,包括活跃模型、审批策略、可写根目录和当前上下文使用情况。


3.3.2.4 精简对话内容(compact)

当对话很长时,使用:

/compact

Codex 会将已有对话摘要化,压缩内容以腾出更多上下文空间。


3.3.2.5 审查修改(diff)

输入:

/diff

可以查看 Git diff 内容,包括已暂存和未暂存的变更,以及未被 Git 管理的文件,以便你决定接下来怎么处理。


3.3.2.6 附加文件到对话(mention)

输入:

/mention <路径>

可以让 Codex 将某个文件加入当前对话上下文,让后续操作更聚焦于该文件。

4. Web(Codex 云)

4.1 概览

Codex 是 OpenAI 提供的智能编码代理,它可以读取、编辑并运行代码,帮助开发者更快地构建功能、修复错误、理解不熟悉的代码库等,通过 Codex 云端(Cloud),这些任务可以在后台由 Codex 的云环境并行执行,从而提升效率和自动化程度。 ([OpenAI][1])

Codex 云端实际上是 Codex 在云上的运行模式,在这种模式下:

  • Codex 可以在自己的云容器中运行任务,不受本地机器限制;
  • 支持 后台执行、并行处理多个任务
  • 每个任务都在独立的沙盒环境中运行,隔离性好、安全性高;
  • 任务执行结果可以生成可验证的修改(例如 diff 和测试结果),供开发者审查。

Codex 云端如何设置

要在云端使用 Codex,需要:

  1. 访问 Codex(chatgpt.com/codex)
  2. 连接的 GitHub 帐户
  3. 授权之后,Codex 即可访问你仓库中的代码,自动创建修改建议并提交成 GitHub Pull Request。

Codex 云端带来的优势

  • 提高开发效率:Codex 能够自动处理重复性任务,如编写功能框架、修复 bug、生成测试文件等,让开发者专注于更高价值工作。
  • 更好的团队协作:通过 GitHub 集成,Codex 可以直接在开发流程中提出建议、解决问题并提交 PR,加快团队协作节奏。
  • 安全透明:每次任务都有日志和测试输出证明执行过程,开发者可以清晰追踪 Codex 做了什么,确保可控。

Codex 云端是一个面向未来的软件工程智能体,它在云环境中后台执行代码任务,通过与 GitHub 和 IDE 的深度集成,让开发者能够更快速地完成复杂开发流程,无论是个人开发者还是大型团队,都可以借助 Codex 云端提升开发效率和协作效果。

4.2 云环境

原文地址:https://developers.openai.com/codex/cloud/environments

使用 环境(environments) 来控制 Codex 在云端任务运行期间安装和执行的内容。
例如:

  • 添加依赖项(packages)
  • 安装代码检查工具、格式化工具等
  • 设置环境变量

这些配置可以在 Codex 设置 中完成。


Codex 云任务如何运行?

当提交一个任务时,大致会发生以下流程:

Step 1: Codex 创建一个容器(container),并在指定的分支或指定的 commit SHA 处检出你的代码仓库(checkout)。

Step 2: Codex 运行你的 setup 脚本,必要时也会运行维护脚本(maintenance script),尤其是在使用缓存容器时。

Step 3: Codex 会应用你的 Internet 设置。

  • 在 setup 阶段,网络访问可以打开
  • 在 agent 执行阶段默认 关闭 Internet 访问(除非你在设置中开启有限或无限制访问)

Step 4: Agent 会循环运行终端命令:

  • 编辑代码
  • 运行检查(比如测试、lint)
  • 尝试验证其操作是否有效
  • 如果你的仓库中有 AGENTS.md 文件,agent 会使用它来了解项目的具体命令(例如运行测试、lint)。

Step 5: 当任务完成后,结果会展示出来,并显示对文件的 diff(变更),然后你可以选择打开 Pull Request 或继续提出后续问题。


默认容器镜像(Default universal image)

Codex agent 在默认的容器镜像 universal 中运行,该镜像预装了常见语言、库和工具,在环境设置中,你可以选择固定 Python、Node.js 等运行时的版本,如果需要更多软件包,也可以通过 setup 脚本手动安装。


环境变量与密钥(Environment variables 和 secrets)

环境变量在任务全过程(setup 脚本 + agent 阶段)中有效。Secrets(密钥)在运行期间会被加密存储,仅在 setup 脚本阶段解密可用,为安全起见,在 agent 阶段会被移除。


自动与手动设置

自动设置:对于常用包管理工具(如 npm、yarn、pip、poetry 等),Codex 可以自动安装依赖和工具。

手动设置: 如果你的开发环境更复杂,也可以提供自定义 setup 脚本,例如:

# 安装类型检查器
pip install pyright

# 安装项目依赖
poetry install --with test
pnpm install

注意:setup 脚本与 agent 阶段分别在不同的 Bash 会话中运行,因此像 export 这样的命令不会带到 agent 阶段。如果希望变量在 agent 阶段持续有效,请在 ~/.bashrc 中设置,或者在环境设置中新增这些变量。


容器缓存(Container caching)

Codex 会缓存容器状态最长 12 小时,以加速后续任务和后续对话,当使用缓存容器时:

  • 会检出仓库;
  • 运行维护脚本(maintenance script);
  • 如果 setup 脚本、环境变量、密钥或维护脚本等发生更改,则缓存会失效;
  • Business 和 Enterprise 用户的缓存可以在同一 workspace 中被多个用户共享。

网络访问与代理

  • 在 setup 脚本阶段允许访问互联网,用于安装依赖。
  • agent 执行阶段默认关闭互联网访问,除非你在环境设置里启用了有限或无限制访问。
  • 所有网络访问都经过 HTTP/HTTPS 代理,以增强安全性和防止滥用。

4.3 网络访问

原文地址:https://developers.openai.com/codex/cloud/internet-access

默认情况下,在 agent 执行阶段,Codex 不允许访问互联网,但可以在环境设置中为特定环境开启访问,并精细控制访问范围。


网络访问默认行为

  • 默认关闭:在 agent 执行阶段,Codex 的互联网访问是 完全禁止的,以降低安全风险。
  • Setup 阶段允许访问:只有在 setup 脚本阶段才允许访问互联网,用于安装依赖等操作。

启用互联网访问的风险

在 agent 执行阶段开启互联网访问可能带来安全问题,包括:

  • 提示注入(Prompt Injection):代理从不可信网站读取内容并按照内容执行,可能导致信息泄露或执行不安全的操作。
  • 敏感信息泄露:代码、密钥或最后的提交信息可能被发送到受控服务器。
  • 恶意依赖或恶意资源下载:从不安全源下载代码或包可能包含恶意内容。
  • 版权/许可证问题:从外部拉取的代码可能存在版权或许可限制。建议只允许访问可信域名,并严格审查日志与输出。
    在这里插入图片描述

配置互联网访问(按环境设置)

Off(关闭):完全阻止 agent 在执行阶段访问互联网,这是默认设置。

On(开启) + 自定义控制:开启后你可以进一步控制域名允许列表(Domain Allowlist),可以选择:

  • None → 空列表:从零开始自行添加可信域名。
  • Common dependencies → 常见依赖域名列表:使用官方预设的一些常见依赖下载域名(如 npm、pypi 等)。
  • All(无限制):允许访问所有域名。

之后还能手动添加或移除特定域名。


允许的 HTTP 方法

为了安全起见,你可以限定 agent 仅允许某些 HTTP 方法,例如:GETHEADOPTIONS 等安全方法,禁止危险方法如 POSTPUTDELETE 等,减少意外行为风险。


域名允许列表示例

官方提供了一个 常见依赖域名列表(Common dependencies),包括:

alpinelinux.org
anaconda.com
apache.org
apt.llvm.org
archlinux.org
azure.com
bitbucket.org
bower.io
centos.org
cocoapods.org
continuum.io
cpan.org
crates.io
debian.org
docker.com
docker.io
dot.net
dotnet.microsoft.com
eclipse.org
fedoraproject.org
gcr.io
ghcr.io
github.com
githubusercontent.com
gitlab.com
golang.org
google.com
goproxy.io
gradle.org
hashicorp.com
haskell.org
hex.pm
java.com
java.net
jcenter.bintray.com
json-schema.org
json.schemastore.org
k8s.io
launchpad.net
maven.org
mcr.microsoft.com
metacpan.org
microsoft.com
nodejs.org
npmjs.com
npmjs.org
nuget.org
oracle.com
packagecloud.io
packages.microsoft.com
packagist.org
pkg.go.dev
ppa.launchpad.net
pub.dev
pypa.io
pypi.org
pypi.python.org
pythonhosted.org
quay.io
ruby-lang.org
rubyforge.org
rubygems.org
rubyonrails.org
rustup.rs
rvm.io
sourceforge.net
spring.io
swift.org
ubuntu.com
visualstudio.com
yarnpkg.com
…

这些域名通常用于下载包、获取源代码、构建依赖等。

5. 集成(Integrations)

5.1 Github

原文地址:https://developers.openai.com/codex/integrations/github
视频教程:https://youtu.be/HwbSWVg5Ln4

可以使用 Codex 在 GitHub 的 Pull Request(拉取请求)中执行代码审查,而无需离开 GitHub 界面。具体做法是在 Pull Request 的评论里写下@codex review,然后 Codex 会自动回复一个标准的 GitHub 代码审查

5.1.1 设置代码审查

  1. 配置 Codex Cloud
  2. 打开你的仓库设置,找到 Codex 设置 并为该仓库开启 代码审查(Code review) 功能,(界面里会有一个切换开关来启用代码审查。在这里插入图片描述

在某个 Pull Request 里发表评论,写上@codex review
在这里插入图片描述
然后等待 Codex 处理并发布审查结果,就像一个团队成员那样发表评论。
在这里插入图片描述

5.1.2 自定义 Codex 审查规则

默认情况下,Codex 会根据你的代码库中的 AGENTS.md 文件应用一些审查指南。你可以在仓库顶层添加或更新 AGENTS.md,写下自定义的审核规则。例如:

## Review guidelines

- 不要打印敏感个人信息(PII)。
- 确保每个路由都被身份验证中间件包裹。

这样,Codex 会按照这些规则执行审查,如果你在 Pull Request 评论里写类似:

@codex review for security regressions

Codex 会根据语义做更具体的审查。


5.1.3 给 Codex 指派其他任务

当你在评论里提到 @codex 并跟随其他指令(不是 review),Codex 会在云端将这个 Pull Request 作为上下文来创建一个新任务。例如:

@codex fix the CI failures

Codex 会尝试定位并修复 CI(持续集成)失败的问题。

5.2 Slack

原文地址:https://developers.openai.com/codex/integrations/slack

可以在 Slack 的频道或线程里调用 Codex 来执行编码任务。只需在消息中提及 @Codex 并附上提示,Codex 会创建一个 云任务 并回复结果。
在这里插入图片描述

5.2.1 设置 Slack 应用

  1. 配置 Codex 云任务(Codex cloud tasks):需要一个 Plus、Pro、Business、Enterprise 或 Edu 计划,还需连接一个 GitHub 帐户 并至少有一个环境(environment)。
  2. 前往 Codex 设置 并为你的工作区安装 Slack 应用:根据 Slack 的策略,可能需要管理员批准安装。
  3. 在一个频道里添加 @Codex:如果还没添加,Slack 会在你提及时提示。

5.2.2 发起任务

在 Slack 的某个频道或线程内,提及 @Codex 并写出你的提示。Codex 能引用线程内早先的消息,因此通常不需要重复背景上下文。可以在提示里指定环境或仓库,这样能明确 Codex 使用哪个环境或代码仓库,例如:

@Codex 修复上面的内容 在 openai/codex

等待 Codex 做出反应并回复一个任务链接,任务完成后,Codex 会将结果发布在该线程中(视设置而定)。

5.2.3 Codex 如何选择环境和仓库

  • Codex 会查看你有访问权限的环境,并从中选择最匹配你请求的一个。
  • 如果请求不明确,它会回退到你最近使用过的环境。
  • 任务会在该环境所列第一个仓库的默认分支上运行。你可以在 Codex 里更新仓库映射,以更改默认仓库或添加更多仓库。
  • 如果没有适合的环境或仓库,Codex 会在 Slack 中回复说明,提示你如何修复问题再重试。

5.2.3 企业数据控制

默认情况下,Codex 会在线程中发布结果,这可能包括它所运行环境的信息。如果你希望 Codex 只发送任务链接而不包含答案,企业管理员可以在 ChatGPT 工作区设置中关闭 “允许 Codex Slack 应用在任务完成时发布答案” 选项。


5.2.4 数据使用、隐私与安全

当提及 @Codex 时,Slack 的消息内容和线程历史会被发送给 Codex 以理解请求并创建任务。数据处理遵循 OpenAI 隐私政策使用条款 以及其他适用政策。

注意:Codex 使用大型语言模型生成回答,它可能会犯错。请始终自行复查结果和 diff。


5.2.5 提示与故障排查

常见问题及解决方法:

  • 连接丢失:如果 Codex 无法确认你的 Slack 或 GitHub 连接,它会回复一个重新连接的链接。
  • 环境选择错误:你可以在线程中用自然语言指出希望使用的环境(例如 请在 openai/openai 环境运行),然后再次 mention @Codex
  • 长线程或复杂上下文:把关键信息摘要写在最新消息里,以免上下文被埋没。
  • 工作区发布限制:某些企业工作区可能限制发布最终答案,这种情况下可以点击任务链接查看进度和结果。

5.3 Linear

原文地址:https://developers.openai.com/codex/integrations/linear

如果在 Linear 任务中运行 Codex,可以:

  • 使用 Linear 中的 Codex 可以 从 issue(问题/任务)中委派工作
  • 可以 将某个 issue 分配给 Codex,或者在评论中提到 @Codex,Codex 会创建一个云端任务并回复进度与结果。

5.3.1 设置 Linear

按照下面步骤配置 Linear 与 Codex 的联动:

  1. 先通过在 Codex 中连接 GitHub 并为要让 Codex 工作的仓库创建环境 来设置 Codex Cloud Tasks
  2. 进入 Codex 设置为你的工作区安装 Linear 的 Codex 集成
  3. 通过在 Linear issue 的评论线程中提到 @Codex链接你的 Linear 账户

5.3.2 如何将工作委派给 Codex?

你可以通过下面两种方式委派任务:

1) 将 issue 分配给 Codex:安装并启用集成后,你可以像将任务分配给团队成员一样,将 issue 分配给 Codex。 Codex 会开始处理任务,并在 issue 中发布进度更新。
在这里插入图片描述

2) 在评论中提及 @Codex:也可以在评论中写 @Codex 来委派任务或提问。Codex 回复后,你可以在同一个评论线程中继续提问或增加说明以延续当前会话。
在这里插入图片描述

5.3.3 环境与仓库如何被 Codex 选中

Codex 开始工作后,会根据 issue 内容选择 合适的环境和仓库,如果你想指定固定仓库,可以在评论中写清楚,例如:

@Codex fix this in openai/codex

如果建议不明确,Codex 会采用最近一次使用的环境。任务默认运行在该环境仓库列表中第一个仓库的默认分支上。如需更改默认仓库或加入更多仓库,你可以在 Codex 配置中更新环境的仓库映射。

5.3.4 查看 Codex 的进展

可以 在 issue 的 Activity(活动)视图 中查看更新,点击任务链接查看更详细的进度,当任务完成后,Codex 会发布摘要并附上完成任务的链接,你可以据此创建 Pull Request(PR)。

5.3.5 自动将 Issue 指派给 Codex

可以通过设置 triage rules(初筛规则)自动将新 issue 分派给 Codex:

  1. 在 Linear 侧边栏进入 Settings(设置)
  2. Your teams(你的团队) 下选择你想要设置的团队。
  3. 打开 Workflow(工作流) → Triage(初筛)
  4. 新建规则并设置将符合条件的 issue 委派给 Codex
  5. 新任务符合规则后将自动分配给 Codex 执行。

当使用 triage 规则自动委派时,Codex 会使用 issue 创建者的账户 来运行任务。
在这里插入图片描述


5.3.6 数据使用、隐私与安全

当你 mention 尽量写清楚你想让 Codex 做什么,因为 Codex 会读取这段内容来理解请求并生成任务。数据处理遵循 OpenAI 的隐私政策与使用条款;详见官方文档。 Codex 生成的内容可能不总是正确,你仍需手动审核其回答和 diffs(变更差异)。

5.3.7 常见提示与故障排查

连接失败:如果 Codex 无法确认链接,它会在 issue 中回复一个连接账户的链接。

环境被选错了:在评论中补充你想要的环境,这样可指导 Codex 选择正确环境执行任务,例如:

@Codex please run this in openai/codex

代码上下文不准确或不完整:提供更多上下文或明确指令,有助于 Codex 更准确完成任务。

查看更多帮助:可以查阅 OpenAI 的帮助中心获取更完整的说明。


5.3.8 在本地通过 MCC 使用 Linear

如果你想让 Codex 在本地访问 Linear issue(如通过 CLI 或 IDE 扩展),可以使用 Codex 的 MCP(Model Context Protocol)服务器,推荐方法(CLI)

codex mcp add linear --url https://mcp.linear.app/mcp

执行后系统会提示登录 Linear,完成账户连接。也可以使用手动方法,在 ~/.codex/config.toml 文件中添加:

[mcp_servers.linear]
url = "https://mcp.linear.app/mcp"

然后运行,即可手动连接 Linear:

codex mcp login linear

好,这里给你一版第一人称(博主视角)+ 精简概括型的整篇博客文末总结,偏“收束观点 + 给读者方向”,不铺细节、不啰嗦:


6. 文末

到这里,本文从 IDE、CLI、Web(Cloud),一直到 GitHub / Slack / Linear 等集成平台,系统梳理了 Codex 在不同使用端的形态与适用场景。可以看到,Codex 并不是单一形态的“写代码工具”,而是一套可以嵌入个人开发与团队工程流程的 工程级编程智能体

在博主看来,使用 Codex 的关键不在于“功能是否齐全”,而在于是否把它放在合适的位置

  • 写代码、改代码时用 IDE;
  • 自动化、批处理和审查用 CLI;
  • 复杂任务和并行执行交给 Cloud;
  • 团队协作则通过各类集成让 Codex 成为流程中的一员。

当你不再纠结 “用不用 Codex”,而是开始思考“这一类工程问题该不该交给 Codex”,它的价值才会真正体现出来。希望本文能帮助大家,感谢阅读,本文完!

Logo

有“AI”的1024 = 2048,欢迎大家加入2048 AI社区

更多推荐