Codex与Claude Code记忆增强实战：结合MemoraX Code实现上下文持久化

最近在整理终端 AI 编程工具的工作流时，遇到了一个非常实际的卡点：Codex 每次开新会话都会“失忆”，项目背景、技术选型、踩坑记录全都得重新交代一遍。后来我在 Codex 基础上接入了记忆管理工具 MemoraX Code，又把 Claude Code 放进同一套工作流里互补使用，整个开发效率提升了不少。这篇文章就把这套“Codex × Claude Code × MemoraX Code”的组合完整拆开，从安装配置到记忆注入，再到常见报错排查，全部用实测过程整理出来，适合正在折腾 Codex 和 Claude Code 的开发者直接复用。

1. 为什么要给 Codex 加上记忆

1.1 终端 AI 编程助手的现状

Codex 是 OpenAI 推出的终端 AI 编程 Agent，安装之后可以直接在命令行里用自然语言描述需求，由模型自动完成代码编写、命令执行、文件修改等操作。它的使用体验很接近 Claude Code，都是把大模型从“聊天窗口”搬到“真实项目目录”里，模型能直接读取项目文件、执行 shell 命令、运行测试，而不是像传统 IDE 插件那样只能补全代码片段。

这类工具的共同特点是：每一次对话会话是独立的。Codex 启动一个新会话时，只能读取当前项目文件、AGENTS.md 等静态上下文，并不会自动记住你昨天在另一个会话里交代过的技术约束、目录规范、数据库连接方式、部署流程。对单次任务来说问题不大，但一旦进入多日迭代、多模块开发、多人协作，反复交代上下文就会浪费大量 token，也容易因为前后描述不一致导致代码风格漂移。

1.2 没有记忆的开发痛点

我在实际使用时碰到过几个非常典型的场景：

• 昨天刚告诉 Codex “后端统一使用 Java 17 + Spring Boot 3，不要引入 MyBatis”，今天开新会话之后它又给你生成了一套老版本 Spring Boot 2 的写法。
• 项目里有一个特殊的构建命令，比如npm run build:test是测试环境专用，Codex 第一次记住了，第二次会话又默认执行npm run build，导致产物完全不对。
• 团队约定提交信息必须遵循 Conventional Commits 规范，但 Codex 每次都按自己的风格写 commit message，只能手工修正。

这些问题本质上不是模型能力不够，而是“上下文没有持久化”。模型本身是知道这些通用规范的，但它不知道“你这个项目”有这些具体约定。记忆工具要解决的就是这个信息断层。

1.3 记忆工具能带来什么

MemoraX Code 这类工具做的事情其实很朴素：把跨会话的关键信息保存到本地记忆库，在 Codex 或 Claude Code 启动时自动注入到上下文中。它和 AGENTS.md、CLAUDE.md 的区别在于，前者是“自动维护的结构化记忆”，后者是“手动维护的静态说明文件”。

接入记忆能力之后，Codex 在开新会话时就能自动知道：

• 项目使用的技术栈与版本约束。
• 常用的构建、测试、部署命令。
• 代码风格、目录结构、命名规范。
• 之前踩过哪些坑，哪些方案被否决过。
• 当前迭代正在进行的任务进度。

这套机制对个人开发者和团队都适用。个人开发者可以少重复prompt，团队可以把公共规范沉淀为共享记忆文件，新成员用 Codex 时也能继承团队上下文。

2. Codex 与 Claude Code 怎么选

2.1 Codex CLI 是什么

Codex 的官方形态是命令行工具codex，可以用 npm 全局安装，也可以使用桌面版客户端。它默认对接 OpenAI 账号登录，可以调用 GPT-5 系列模型，同时也允许通过配置文件接入其他兼容 OpenAI 接口的模型服务商。对于国内开发者来说，比较常见的做法是给 Codex 配置 DeepSeek 等第三方模型 API，这样既可以使用 Codex 的终端 Agent 交互体验，又能在模型成本和可用性上做取舍。

Codex 的工作模式是“代理式（Agent）”：你给它一个任务，它会自己决定先读哪个文件、执行什么命令、如何修改代码，并且在执行关键操作前向你确认。它会把整个操作链路拆成多个步骤，每个步骤都会展示给用户。

2.2 Claude Code 是什么

Claude Code 是 Anthropic 推出的同类终端编程工具，安装方式是npm install -g @anthropic-ai/claude-code。它同样支持读取项目文件、执行命令、多文件修改，并且支持CLAUDE.md作为项目上下文文件。Claude Code 的强项在于长上下文理解、复杂重构、多文件协调修改，以及和 Claude 模型原生能力的深度绑定。

Claude Code 的授权方式比较特殊：它可以使用 Claude 订阅账号登录，也可以使用 Anthropic API Key。如果公司组织在 Anthropic 后台禁用了 Claude 订阅的 Code 访问权限，登录时会收到类似your organization has disabled claude subscription access for claude code的报错，这时需要联系组织管理员开启，或改用 API Key 方式。

2.3 两者差异对比

对比项	Codex	Claude Code
开发方	OpenAI	Anthropic
安装方式	npm i -g @openai/codex	npm i -g @anthropic-ai/claude-code
默认模型	GPT-5 系列	Claude 系列
官方上下文文件	AGENTS.md	CLAUDE.md
第三方模型接入	支持，改 config.toml	可通过 cc switch 等工具切换
桌面客户端	有 Windows/macOS 桌面版	有桌面版
擅长场景	自动化编码、命令执行、批量修改	长上下文推理、复杂重构、架构梳理

在实际项目中，我并不认为两者是“二选一”的关系。Codex 和 Claude Code 可以搭配使用：让 Claude Code 负责需求分析、技术方案设计、复杂重构，让 Codex 负责按既定方案落地业务代码、跑测试、修报错。这样既发挥各自模型优势，又能互相验证结果。而 MemoraX Code 可以作为两者共用的“记忆层”，确保切换工具时上下文不丢失。

3. MemoraX Code 记忆机制拆解

3.1 核心思路

MemoraX Code 的设计思路并不复杂：在本地维护一个记忆库目录，里面按维度拆分多个 Markdown 文件，每个文件承载一类记忆。使用记忆时，工具把相关记忆文件的内容注入到 Codex 的 AGENTS.md 或 Claude Code 的 CLAUDE.md 中，或者直接在启动命令中作为额外上下文传入。

这样做的好处是：

• 记忆是纯文本的，随时可以手工修改、版本管理。
• 注入机制不依赖某个模型的特有功能，Codex 和 Claude Code 都能用。
• 记忆文件可以按项目、按技术栈、按团队成员拆分，灵活控制范围。

很多类似工具都采用“优化层 + 文件层”的结构。文件层负责存储原始记忆，优化层负责在每次会话前挑选最相关的记忆内容，避免把所有记忆都塞进上下文导致 token 浪费。MemoraX Code 的实用价值也在于这个“挑选”过程：不是简单地把所有历史记录拼进提示词，而是按匹配度动态组织上下文。

3.2 记忆库结构

以一个典型项目为例，初始化 MemoraX Code 之后的目录结构大致如下：

.memorax/ ├── global/ │ ├── coding-style.md │ ├── tech-stack.md │ └── workflow.md ├── project/ │ ├── architecture.md │ ├── commands.md │ └── decisions.md └── sessions/ ├── 2025-06-01-refactor.md └── 2025-06-02-db-optimization.md

• global：全局记忆，适用于所有项目，比如代码风格、通用工具链。
• project：项目记忆，只对当前项目生效，比如目录结构、环境变量、构建命令。
• sessions：会话记忆，记录某一次开发任务的上下文、结论和后续计划。

其中commands.md是我个人认为收益最大的文件。只要把项目的准入命令写清楚，Codex 就不会再猜错构建方式：

# commands - dev: npm run dev - test: npm run test:unit - build: npm run build - lint: npx eslint src --fix - db migrate: cd server && npm run migrate:up

3.3 与 AGENTS.md、CLAUDE.md 的关系

Codex 官方支持AGENTS.md，放在项目根目录时会在每次会话自动加载；Claude Code 官方支持CLAUDE.md，作用完全相同。MemoraX Code 的“取巧”之处是：它把记忆库作为源数据，在启动 Codex 或 Claude Code 前自动生成或更新这两个文件，从而实现记忆注入。

流程可以理解为：

记忆库（源数据） ↓ 生成/同步 AGENTS.md 或 CLAUDE.md（官方上下文文件） ↓ 自动加载 Codex / Claude Code（AI 终端）

所以即使 MemoraX Code 的命令版本有变化，只要理解了这个“记忆库 → 官方上下文文件 → 模型”的链路，你也可以手工维护 AGENTS.md 达到类似效果。这算是这套方案最核心的原理。

4. 环境准备与安装

4.1 环境要求

本文实测环境以 macOS 为主，Windows 的差异点会在常见问题中单独说明。需要提前准备：

• Node.js 18 以上，建议 20 LTS 或 22 LTS。
• npm 全局安装权限，Windows 用户建议使用 Node.js 官方安装包。
• 一个可用的 Codex 登录账号，或第三方模型 API Key。
• 一个可用的 Claude 账号，或 Anthropic API Key。

版本需要根据你的实际环境调整，本文重点演示配置思路，命令以你安装时的最新版本为准。

4.2 安装 Codex CLI

先确认 Node.js 环境正常：

node -v npm -v

然后全局安装 Codex：

npm install -g @openai/codex

安装完成后验证：

codex --version

如果安装成功，直接运行codex会进入交互式终端界面，首次使用需要登录 OpenAI 账号。登录完成后，Codex 会提示选择模型，通常默认使用 GPT-5 系列模型。

如果你希望使用第三方模型服务商，可以在~/.codex/config.toml中添加自定义模型供应商配置。下面是一个指向兼容 OpenAI 接口服务的配置示例：

model = "deepseek-chat" model_provider = "deepseek" [model_providers.deepseek] name = "DeepSeek" base_url = "https://api.deepseek.com/v1" env_key = "DEEPSEEK_API_KEY" wire_api = "chat"

配置说明：

• model：实际调用的模型名，必须与供应商支持的模型名一致。
• base_url：API 地址，具体以供应商文档为准。
• env_key：读取环境变量的名称，Codex 会从该环境变量读取 API Key。
• wire_api：接口协议类型，支持chat与responses两种，取决于供应商实现的接口规范。

配置完成后，还需要在 shell 中设置对应的环境变量，或者写入~/.zshrc/~/.bashrc：

export DEEPSEEK_API_KEY="你的 API Key"

4.3 安装 Claude Code

Claude Code 同样通过 npm 安装：

npm install -g @anthropic-ai/claude-code

安装后检查：

claude --version

首次运行claude时，可以选择登录 Claude 账号，或者输入 Anthropic API Key。部分用户会选择通过 cc switch 切换到第三方模型提供商，这一步我们放到后面实战中详细讲。

4.4 安装 MemoraX Code 与 cc switch

MemoraX Code 的安装同样走 npm：

npm install -g memorax-code

不同版本的命令名可能有差异，安装完成后可以通过下面的命令查看帮助，以确定你当前版本支持的子命令：

memorax --help

cc switch 是一个用于切换 Claude Code / Codex 模型提供商的社区工具，安装命令：

npm install -g cc-switch

cc switch 的用途是快速生成和切换不同模型服务商的配置文件，避免每次手动编辑 config.toml 或 Claude Code 的 settings.json。后面接入第三方模型时会用到。

5. 实战：给 Codex 加上记忆

5.1 初始化记忆库

进入一个已有项目目录，执行初始化命令：

memorax init

该命令会在当前目录创建.memorax文件结构，并生成一个默认的AGENTS.md。如果项目原本没有AGENTS.md，初始化工具会自动创建；如果已经存在，会提示是否合并。

初始化完成后的目录：

.memorax/ ├── global/ │ ├── coding-style.md │ └── tech-stack.md ├── project/ │ ├── commands.md │ ├── architecture.md │ └── decisions.md ├── sessions/ └── AGENTS.md # 根据记忆库生成的 Codex 上下文文件

5.2 编写全局记忆与项目记忆

全局记忆适合放不区分项目的通用偏好。比如我个人的coding-style.md内容：

# 代码风格偏好 - 后端使用 Java 17 + Spring Boot 3，禁止引入 MyBatis。 - 前端使用 TypeScript，组件命名采用 PascalCase。 - 方法必须写 Javadoc 或 TSDoc 注释。 - commit message 遵循 Conventional Commits 规范。 - 优先使用标准库，减少不必要的外部依赖。

项目记忆则要贴近当前仓库。比如commands.md记录项目所有关键命令：

# 项目命令 - install: npm install - dev: npm run dev - build: npm run build:prod - test: npm run test:unit - lint: npm run lint - typecheck: npx tsc --noEmit

architecture.md记录模块划分和关键设计：

# 架构说明 - 后端采用模块化分层，controller / service / repository 分离。 - 数据库访问使用 Spring Data JPA，禁止直接写原生 SQL（复杂查询除外）。 - 所有外部接口调用必须走 adapter 层，禁止在 service 里直接 new RestTemplate。 - 配置中心使用 Apollo，新增配置需要同步修改 apollo 命名空间。

写完这些之后，执行同步命令，让记忆库内容重新生成 AGENTS.md：

memorax sync

5.3 让 Codex 自动加载记忆

Codex 在启动时会自动读取项目根目录的AGENTS.md，因此只要同步完成，Codex 就会自动加载记忆。可以用下面的命令快速验证：

codex "请阅读 AGENTS.md，然后告诉我这个项目的技术栈和常用命令"

正常响应应该包含你刚才写入的技术栈信息、常用命令、代码风格约束。如果 Codex 没有加载，检查根目录是否有AGENTS.md，并且确认文件名准确无误。

5.4 在会话中测试记忆

下面用一个具体例子验证记忆效果。

第一次会话，我明确告诉 Codex 一个项目约定：

codex "记住：生产环境构建命令使用 npm run build:prod，不要使用 npm run build"

会话结束后，把这条约定写入 MemoraX Code 记忆库：

memorax add "生产环境构建命令: npm run build:prod" memorax sync

第二次开启新会话：

codex "请帮我打一个生产环境包，需要执行什么命令？"

此时 Codex 因为加载了 AGENTS.md，会直接输出：

根据项目约定，生产环境构建命令是 npm run build:prod。

如果第一次会话结束时没有写入记忆，第二次会话 Codex 大概率会回答npm run build，这正是记忆机制带来的差异。

5.5 通过 cc switch 接入第三方模型

如果你打算在 Codex 中使用第三方模型服务商，cc switch 可以简化配置流程。

运行 cc switch：

cc-switch

进入交互式界面后，选择添加供应商，填写：

• 供应商名称。
• API 地址。
• 模型名称。
• API Key。

保存后，cc switch 会生成对应的 Codex 配置片段，并提示重启 Codex 生效。配置完成后，运行：

codex --version codex "你好，请确认你当前使用的模型"

如果配置正确，Codex 会返回你配置的模型名称。

6. 实战：Codex × Claude Code 联合开发

6.1 分工思路

把两个终端 AI 编程工具放在同一套工作流里，关键是要划分清楚边界。我的常用分工是：

• Claude Code 负责“想清楚”：需求拆解、技术方案、接口设计、重构方案。
• Codex 负责“写出来”：按方案实现业务代码、补充单元测试、执行构建和修复报错。
• MemoraX Code 负责“都记住”：两边的关键结论、变更记录、踩坑信息都沉淀到记忆库。

这样做的好处是：Claude Code 的强项是长上下文推理，适合做整体设计；Codex 的强项是快速执行任务，适合在确定方案后高效率落地。

6.2 使用 Claude Code 梳理需求

在项目根目录启动 Claude Code：

claude

先让它阅读项目结构和记忆文件：

请先阅读 CLAUDE.md 和 .memorax 目录下的 project 文件，理解本项目背景，然后帮我梳理一个新功能的实现方案：在订单列表中支持批量导出 Excel。

Claude Code 会结合记忆库中的架构说明，输出一个包含接口设计、文件改动清单、实现步骤的方案。如果它给出的方案和现有架构不符，可以直接指出来，它会根据 CLAUDE.md 中的约束重新调整。

6.3 使用 Codex 落地业务代码

方案确定后，切换到 Codex 执行实现：

codex "按以下方案实现批量导出功能：1. 新增导出接口 /api/orders/export；2. 使用 EasyExcel 生成文件；3. 导出的列必须包含订单号、商品名称、金额、创建时间；4. 先实现 service 层，再写 controller。开始吧。"

因为 Codex 自动加载了 AGENTS.md，它知道项目使用 Spring Boot 3、实体类命名规范、不允许直接在 service 中写原生 SQL 等约定，生成的代码会明显更贴合项目现状。

6.4 共享记忆与上下文交接

实现过程中如果发现某个坑点，比如“EasyExcel 3.3.x 版本与 POI 5.2.2 存在兼容性问题”，立刻写入记忆库：

memorax add "EasyExcel 3.3.x 与 POI 5.2.2 兼容性有问题，建议锁定 easypoi 版本" memorax sync

这样在下一次由 Claude Code 做代码 review 或继续开发时，它也能通过 CLAUDE.md 感知到这个约束。两个工具共享同一份记忆，上下文交接成本几乎为零。

7. 常见报错与排查

7.1 cc switch local proxy failed while handling codex endpoint /responses

不少反馈中都会出现类似这样的报错：cc switch local proxy failed while handling codex endpoint /responses。这个报错发生在 cc switch 启动了本地代理服务，但在处理 Codex 的/responses端点请求时失败。

问题现象	常见原因	解决思路
报错信息带 endpoint /responses	本地代理服务无法访问目标 API 地址	检查 API 地址是否可达、端口是否正确
报错信息带模型名	当前模型名不被模型服务商支持	确认 provider 支持的模型名并修改配置
报错发生在切换供应商后	cc switch 的本地代理端口被占用	重启 cc switch 或更换本地端口

排查顺序建议如下：

1. 确认cc-switch配置里的 API 地址正确，且当前网络环境下可以正常访问。
2. 用 curl 直接测试目标端点连通性。
3. 检查配置的模型名是否真实存在。
4. 确认是否是本地代理端口冲突，尝试重启 cc switch。
5. 如果报错指向/responses，还要确认目标服务商是否支持 OpenAI responses 协议；如果不支持，需要在配置中使用wire_api = "chat"。

7.2 Codex 提示模型不支持

有用户反馈配置 Codex 后提示类似the 'gpt-5.6-sol' model is not supported。这类报错的核心原因是模型名写入了config.toml，但模型服务商并不支持该模型，或者模型名拼写有误。

处理方式：

codex 提示模型不支持时，先查询服务商文档中可用的模型列表。 修改 ~/.codex/config.toml 中的 model 字段。 如果是第三方服务商，还需要确认接口协议是 chat 还是 responses。

也可以直接运行codex models查看当前配置可用的模型列表。

7.3 Claude Code 在 PowerShell 安装报错

Windows 用户使用 PowerShell 安装 Claude Code 时，可能遇到执行策略限制导致的报错，例如：

claude : 无法加载文件 ... 因为在此系统上禁止运行脚本

解决办法是修改 PowerShell 执行策略：

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

然后重新打开 PowerShell 验证：

claude --version

如果 npm 全局安装目录没有加入 PATH，也会出现“找不到命令”的情况，需要手动把 npm 全局 bin 目录加入环境变量。

7.4 组织禁用了 Claude 订阅访问

报错信息：your organization has disabled claude subscription access for claude code。

这个提示说明当前登录的 Claude 账号属于某个组织，但组织管理员在 Anthropic Console 里关闭了订阅用户的 Code 访问权限。

解决思路：

• 联系组织管理员开启 Claude Code 访问权限。
• 或者使用个人 Claude 账号登录。
• 或者改用 Anthropic API Key 方式访问。

7.5 记忆不生效

如果配置了 MemoraX Code，但 Codex 仍然没有按照记忆库内容回答，按下面顺序排查：

排查点	操作
AGENTS.md 是否有内容	查看项目根目录 AGENTS.md，确认同步成功后内容非空
文件位置是否正确	Codex 只自动读取工作目录下的 AGENTS.md，确认启动目录正确
是否执行过 sync	手动执行memorax sync后重启 Codex
是否为旧会话缓存	Codex 新会话才会重新读取 AGENTS.md，旧会话不受影响

8. 最佳实践与工程建议

8.1 记忆内容规范化

记忆库文件虽然可以随意写，但如果内容过于散乱，反而会拉低注入效率。建议每个记忆文件只聚焦一个主题，控制在 50 行以内。全局记忆放“不变的规则”，项目记忆放“本项目的约定”，会话记忆放“阶段性结论”。定期清理过时会话记忆，避免记忆库膨胀后影响提示词的精确性。

8.2 Token 成本控制

记忆注入本质上是把更多文字塞进上下文，必然会增加 token 消耗。为了控制成本，注意以下几点：

• 不要把大段代码复制进记忆库，只记录关键路径、命令和结论。
• 项目无关的通用知识放在 global 目录，按需同步。
• 结合 MemoraX Code 的搜索能力，只注入当前任务相关的记忆片段，而不是全部注入。
• 使用第三方模型提供商时，关注输入 token 单价，长上下文任务的成本会明显高于短任务。

8.3 多 Agent 协同

如果同时使用 Codex 和 Claude Code，建议把记忆文件当作“接口协议”来维护。Claude Code 在设计中确定了某些技术选型，Codex 在实现中就必须遵守。可以通过 review 命令让 Claude Code 检查 Codex 生成的代码是否违反记忆库中的约定：

claude "请检查 AGENTS.md 中的代码风格约束，然后 review 最近一次提交的代码"

这样两个模型互相监督，比单工具自审的可靠性更高。

8.4 隐私与安全

记忆库中不要存放明文密码、密钥、Token、内网地址等敏感信息。需要记录时，使用环境变量占位符，例如：

# 数据库连接 - host: ${DB_HOST} - username: ${DB_USER} - password: 不要写入，统一使用环境变量

AGENTS.md 和 CLAUDE.md 默认会进入 Git 仓库的话要注意：.memorax目录如果包含团队内部约定，建议纳入版本管理；如果包含个人使用习惯，建议加入.gitignore。生产环境相关的敏感路径和内部系统地址，最好只保留在本地全局记忆里，不要提交到仓库。

8.5 版本管理与回滚

记忆库文件本身就是纯文本，非常适合纳入 Git 管理。每次执行重要变更前先提交一次记忆快照，如果后续发现记忆注入导致 Codex 行为异常，可以快速回滚到上一个可用版本。这比在会话中反复纠正模型要高效得多。

9. 总结

Codex 和 Claude Code 都是非常优秀的终端 AI 编程工具，但它们默认不会替你保存跨会话记忆。MemoraX Code 通过“记忆库 → AGENTS.md / CLAUDE.md → 模型上下文”的链路，解决了这个最关键的问题。实测下来，接入记忆后 Codex 在同一个项目中的代码一致性、命令准确性都有了明显提升，和 Claude Code 配合使用时也会减少很多重复沟通成本。

如果你也正在被“AI 每次都要重新交代上下文”这个问题困扰，建议先从一个commands.md开始，把项目最常用的构建、测试、部署命令写进去，同步到 AGENTS.md 后重启 Codex 试一次。你会发现之前反复纠正的很多小问题，其实一条记忆就能解决。