从“跑任务跑到一半上下文丢了”这个痛点切入吧。以前在项目里用 Codex 处理跨文件重构时经常遇到一个尴尬问题对话稍微长一点上下文就乱了关掉终端再重开之前的思路和决策记录全部归零Agent 又要重新理解项目结构。最近 OpenAI 在测试 Codex 的持久模式正好是冲着这个问题去的。本文会先解释清楚持久模式到底解决什么问题再给出从安装到配置的完整实操流程包括常用的会话恢复方式、项目记忆沉淀方法以及高频报错的排查清单。无论你已经用过 Codex还是刚准备上手都可以直接参考。1. Codex 持久模式是什么为什么值得关注1.1 Codex 与 AI 编码代理Codex 是 OpenAI 推出的 AI 编码代理工具它不再只是“聊天框里生成代码”而是能直接读取项目代码、执行命令、修改文件像一名真实工程师一样完成端到端的开发任务。它有两种常见形态一是集成在 ChatGPT 里的 Codex 界面适合在网页端直接操作二是 Codex CLI它是一个本地命令行工具可以在终端里启动读取当前项目的代码结构并借助 OpenAI 模型完成代码修改、运行测试、排查报错等任务。在很多开发者的工作流里Codex CLI 的使用比例比网页版更高这是因为它能直接感知本地 git 仓库、文件变更和命令输出与 IDE、CI 流程的配合也更自然。1.2 持久模式要解决的问题你会发现传统 Agent 工具的一个核心痛点在于“会话易失”。终端关闭后Agent 对项目的理解会丢失一次任务如果包含多个阶段中途断线后无法从断点继续团队协作时不同成员启动的 Agent 之间没有共享记忆长时间任务中上下文窗口被无关信息塞满导致关键决策被遗忘。OpenAI 为 Codex 测试的持久模式本质上就是解决上述问题。它希望在 Agent 与项目之间建立一种“可长期保留”的工作状态让代码代理记住项目背景、已有决策、正在执行的任务并且能够在多轮会话之间恢复。需要说明的是持久模式目前仍处于测试和演进阶段不同版本的能力边界不完全一样。但从工程角度看我们可以通过会话恢复、项目记忆文件、任务日志等方式在现有 Codex CLI 上实现接近“持久”的工作流。这也是本文要重点演示的内容。1.3 持久模式的适用场景持久模式并不是所有场景都刚需。如果你只是临时写一个脚本那直接启动 Codex 对话即可。真正需要持久化的场景通常具有以下特征任务周期长一次重构、一次技术债务清理、一次跨模块改造很难在单次对话中完成上下文强依赖Agent 需要持续理解项目架构、接口约定、历史决策而不是每次从头开始多人协作不同开发者需要共享 Agent 的工作记录避免“别人不知道 Agent 改了什么”自动化批处理在 CI 或夜间任务中运行 Codex任务中断后能重新拉起并继续。如果你手上有这类项目那么给 Codex 做持久化配置远比每次重新描述一遍项目背景要高效得多。2. 环境准备与安装2.1 安装 Codex CLICodex CLI 目前主要面向 macOS 和 Linux 环境Windows 用户一般通过 WSL 使用。安装方式以官方仓库的说明为准比较常见的方式是通过 npm 全局安装。npm install -g openai/codex如果你的网络环境访问 npm 比较慢也可以配置国内 npm 镜像后安装npm config set registry https://registry.npmmirror.com npm install -g openai/codex安装完成后先确认命令是否可用codex --version如果系统提示找不到 codex 命令通常是 npm 全局 bin 目录没有加入 PATH可以执行下面命令查看全局路径npm bin -g然后把输出目录加入.bashrc或.zshrc中的 PATH。2.2 获取并配置 OpenAI API Key使用 Codex CLI 需要配置 OpenAI API Key。获取方式以 OpenAI 官方平台为准一般是登录后进入 API Keys 页面创建密钥。密钥属于敏感信息不要提交到 git 仓库也不要在公共终端明文展示。配置到 Codex 环境中有两种常见方式。方式一通过环境变量配置。export OPENAI_API_KEYsk-你的密钥方式二写入 Codex 配置文件。不同的 Codex 版本配置文件位置可能不同常见位置是~/.codex/config.toml。例如model gpt-5.6-sol api_key sk-你的密钥这里需要特别提醒不同版本的配置字段并不完全一致甚至在较新版本中API Key 放在config.toml里可能出现格式变化。建议先运行codex --help查看当前版本支持的配置方式再决定用环境变量还是配置文件。2.3 验证安装与基础配置启动一个最简单的对话来验证配置是否生效。codex如果配置正确你会进入交互式终端可以输入自然语言指令例如“帮我介绍一下当前目录的项目结构”。如果出现模型相关报错说明 API Key 或模型名称配置有问题需要回到第二步检查。如果你不希望 Codex 直接执行命令可以在启动时指定只读沙箱模式codex --sandbox read-only这种模式适合前期的代码理解与方案评审ChatGPT 版的 Codex 也类似。3. Codex 工作方式与上下文机制拆解3.1 Codex 的启动、会话与沙箱Codex 每次启动时会读取当前工作目录的文件结构包括.git信息、项目配置文件、源代码文件。它可以像开发者一样运行终端命令但出于安全考虑它默认运行在受限的沙箱中。常见沙箱模式有以下三种模式说明适用场景read-only只能读取文件和执行只读命令代码分析、方案评估workspace-write可以修改当前工作空间内文件日常代码修改dangerous-full-access可以执行任意命令、访问任意路径需要完整系统操作的场景对大多数项目管理类任务建议优先使用workspace-write既允许 Agent 修改代码又不至于给出过度权限。生产环境中的自动化任务建议先用 read-only 模式做预检。Codex 的会话机制决定了它的上下文来源命令行输入、项目文件、命令执行结果、历史对话。这些信息会共同构成一次任务的“记忆”。3.2 上下文从哪里来很多开发者以为 Codex 只有聊天记录作为上下文实际上它比想象中更依赖项目实体信息。常见的上下文来源包括启动时扫描的目录结构git 状态与最近提交记录读取过的源码文件内容执行命令后得到的输出会话历史中的用户指令和 Agent 决策项目下的AGENTS.md文件如果有。正因为上下文来源多样所以代码代理在面对大型项目时会主动选择读取哪些文件、执行哪些命令并在内部形成对项目的理解。这个理解能否跨会话保留就取决于持久化机制的完善程度。3.3 持久化相关参数在 Codex CLI 中有几类参数与会话持久化直接相关。一类是“恢复历史会话”的参数。Codex 支持把对话历史保存到本地后续用--continue或类似参数恢复。具体参数名以codex --help输出为准。例如codex --continue另一类是“项目记忆”机制。你可以在项目根目录创建AGENTS.md文件把项目背景、编码规范、常用命令、架构约定写进去Codex 在启动或任务执行过程中会读取该文件作为跨会话的项目级上下文。这种方式是典型的“低成本持久化”不需要改动 Agent 内部实现只要把每次任务需要复用的信息沉淀到文件里后续会话都能读取。这应该成为你的默认做法。4. 持久模式实战配置与运行下面用一个实际场景演示持久模式的工作流。假设你手上有一个 Python 项目需要完成一次跨多文件的代码重构并希望 Codex 在多次会话中保持对项目目标的理解。4.1 创建测试项目先创建一个简单的项目目录mkdir codex-persist-demo cd codex-persist-demo git init创建两个原始模块文件。utils.py内容def format_name(first, last): return f{last}, {first} def split_full_name(full_name): parts full_name.split( ) if len(parts) 2: return parts[0], parts[1] return , main.py内容from utils import format_name, split_full_name def process_user(full_name): first, last split_full_name(full_name) if not first or not last: raise ValueError(invalid name) return format_name(first, last) if __name__ __main__: print(process_user(Alice Zhang))现在提交一次初始版本git add . git commit -m init demo project4.2 创建 AGENTS.md 沉淀项目上下文在项目根目录创建AGENTS.md# Project Context This project processes user names. ## Goals - Refactor name handling into a dedicated class. - Keep behavior backwards compatible. - Add unit tests for all public functions. ## Conventions - Use type hints. - Do not introduce new external dependencies. - Keep functions pure and testable. ## Commands - Run tests: python -m pytest - Run project: python main.py这个文件就是你的“持久化项目记忆”。每次 Codex 启动时它都能从AGENTS.md中读取任务目标和约束不需要你重新叙述项目背景。4.3 启动持续任务会话第一次启动时明确告诉 Codex 本次任务目标codex在交互终端中发送指令Read AGENTS.md and refactor the name processing logic into a class. Keep the existing public behavior, update main.py accordingly, and add tests.Codex 会读取项目文件并开始修改。这里的关键点是不要让这个会话一次完成所有工作。你可以在中途关闭终端下次通过--continue或会话恢复功能回到任务中。codex --continue恢复后Codex 会读取历史会话和当前项目状态继续执行未完成的重构任务。4.4 会话中断、保存与恢复在长时间任务中会话中断是常态。建议按以下流程管理在任务开始前把目标写入AGENTS.md每次会话结束时让 Codex 在项目根目录更新PROGRESS.md记录已完成项和下一步计划下次启动时用codex --continue恢复对话历史同时让它重新读取PROGRESS.md。PROGRESS.md示例# Progress - [x] Read existing utils.py and main.py - [x] Design NameProcessor class API - [ ] Implement NameProcessor - [ ] Update main.py to use NameProcessor - [ ] Write pytest tests这种“文件即记忆”的方式即使终端会话完全丢失你也能通过AGENTS.md和PROGRESS.md让新的会话快速接续任务。原理很简单Codex 作为 AI 代理最稳定的持久化媒介就是项目内文件而不是终端里的历史记录。4.5 用 Codex Harness 做自动化批处理Codex Harness 是 OpenAI 开源的一个评测与运行框架它可以把 Codex 集成到自动化流水线中。你可以把一批任务拆成多个脚本任务让 Codex 在隔离环境中批量执行。社区中也有通过 Codex Harness 接入其他模型服务的思路例如利用兼容 OpenAI 协议的端点来配置 Codex 使用第三方模型。这里展示一个环境变量层面的配置思路。export OPENAI_BASE_URLhttps://your-compatible-endpoint.example.com export OPENAI_API_KEYyour-key再运行 Codex 时它会尝试将请求发送到自定义端点。这种配置方式最常见的应用场景是私有化部署或模型替换而不是修改 Codex 自身逻辑。需要提醒的是不同 Codex 版本对 base_url 的读取方式不一样配置后如果请求失败优先检查网络连通性、端点路径和模型名称。5. 常见问题排查Codex 在安装和使用过程中会遇到不少问题。下面是我在实际使用中整理的高频报错清单。问题现象常见原因解决思路启动时提示 unable to locate the codex cli binary桌面端或 IDE 插件找不到 codex 可执行文件将 codex 路径加入 PATH或在插件设置中手动指定 codex_cli_path请求失败提示 local proxy failed while handling codex endpoint本地代理配置异常或环境变量残留检查 HTTP_PROXY/HTTPS_PROXY临时取消代理后重试模型不支持报错使用了当前账号或接口不支持的模型名称更换模型名称检查 API 版本与权限codex 打不开安装不完整、权限不足或依赖缺失重新安装、检查 node 版本、确认网络连通5.1 unable to locate the codex cli binary这个报错常见的出现位置是 ChatGPT 桌面端、IDE 插件或某些可视化工具调用 Codex 时。报错含义是程序在系统路径中找不到codex可执行文件。排查步骤如下先确认命令行中codex --version是否正常如果正常运行which codex找到可执行文件位置将可执行文件所在目录加入PATH如果在 IDE 插件中报错查找插件配置项手动填写codex_cli_path。以 macOS 为例如果 codex 安装在/usr/local/bin/codex可以在~/.zshrc中添加export PATH/usr/local/bin:$PATH然后重启终端和 IDE。5.2 本地代理切换失败如果你在使用 Codex 时设置了网络代理有时会看到类似cc switch local proxy failed while handling codex endpoint /responses的报错。这通常意味着代理服务状态异常或者代理环境变量指向了不可用的地址。排查时先查看当前环境变量env | grep -i proxy如果存在如下变量可以临时清空后重试unset HTTP_PROXY unset HTTPS_PROXY unset ALL_PROXY然后再启动 Codex。如果必须使用代理请确认代理服务本身可用并将代理地址配置正确后再启动。5.3 模型不支持报错当你看到类似the gpt-5.6-sol model is not supported when using codex with a...的报错时说明请求使用的模型在当前接口或账号配置下不可用。解决方案检查config.toml中的 model 字段或环境变量中的模型名称改成当前账号可用的模型。不要盲目相信网络上的“推荐模型”以官方 API 返回的模型列表为准。5.4 codex 打不开 / 启动失败如果启动 codex 时界面无响应或直接退出常见原因有npm 安装中断导致文件缺失Node.js 版本过低本地沙箱权限受限系统缺少必要的依赖。建议先重新安装一次npm uninstall -g openai/codex npm install -g openai/codex再检查 Node.js 版本node -v如果版本过旧考虑升级到当前官方支持的主版本。6. 最佳实践与工程建议6.1 会话与项目隔离不要让多个项目共用一个 Codex 会话。每个项目都应该有独立的AGENTS.md和PROGRESS.md并且在启动 Codex 时务必先进入对应的项目根目录。否则 Codex 会把不同项目的文件混合进上下文导致修改错乱。可以在项目根目录创建一个.codex启动脚本固定使用正确的模型、沙箱模式和上下文文件。6.2 API Key 安全管理API Key 是敏感凭据常见的泄漏途径包括写入版本库、硬编码在配置文件中、在多人共享终端中明文输出。建议采用以下策略优先通过环境变量注入密钥不要把含密钥的config.toml提交到 git如果怀疑密钥泄露立即在官方平台撤销并重新生成在自动化环境中使用密钥管理服务而不是把密钥直接写进脚本。6.3 上下文精简与成本控制Codex 的上下文是有限资源。项目规模越大越要注意控制每次任务读取的文件数量。实用建议在AGENTS.md中只写最核心的架构约定不要复制大段代码对大型项目先让 Codex 输出文件清单再指定具体文件进行分析避免在一个会话中同时处理多个不相关的任务否则上下文会迅速膨胀使用 read-only 模式做前期分析确认方案后再切换到 workspace-write 模式修改代码。6.4 安全与权限边界Codex 能替开发者执行命令这既是效率优势也是安全风险。在实际项目中尤其是生产环境必须设置权限边界。默认使用 read-only 或 workspace-write 模式不要轻易使用完全访问模式在 CI 中运行 Codex 前确保仓库代码和依赖已经通过基础安全检查在执行高风险命令时先让 Codex 输出命令内容人工确认后再运行对外部来源的提示词保持谨慎防止通过恶意项目文件诱导 Agent 执行危险操作。6.5 在 CI 中使用 Codex Harness如果你希望把 Codex 的持久化能力接入自动化流程可以考虑使用 Codex Harness。它的思路是把任务定义为脚本执行流程在隔离环境中运行 Codex。你可以为每个任务准备项目快照、预期输出和执行超时时间然后把 Codex 的生成结果写回独立目录。在接入第三方模型时需要确认协议兼容性。多数情况下只需要调整 API Key、模型名称和 base_url。如果请求失败优先查看返回的 error 信息判断是鉴权失败、模型不存在还是网络不通。7. 小结与后续学习方向本文围绕 Codex 持久模式梳理了以下核心内容Codex 作为 AI 编码代理的基本工作方式持久模式解决的核心问题跨会话上下文丢失Codex CLI 的安装与 API Key 配置通过 AGENTS.md、PROGRESS.md、会话恢复等方式搭建可落地的持久化工作流Codex Harness 在自动化批处理中的使用思路高频报错与排查方法工程化落地时的安全、成本、权限建议。接下来可以深入研究的方向包括Codex Harness 的源码与任务定义格式、自定义模型端点的接入、以及如何把 Codex 集成到团队协作流程中。你在实际使用时建议先从小型项目开始建立适合自己的持久化工作流再逐步扩展到更复杂的仓库。代码代理的能力演进很快但“用文件沉淀项目记忆”这条原则在很长一段时间内都不会过时。