——
OpenClaw 为何将 OpenAI Codex 设为 legacy？3 个关键变更解读
一句话总结：OpenClaw 在最新提交中将 OpenAI Codex 从默认 AI Agent 降级为 legacy doctor-only 模式，标志着项目向更模块化、可维护的 Agent 架构演进。
如果你正在使用 OpenClaw 的 AI 辅助功能，这篇文章将帮助你理解这一变更的技术背景、实际影响以及如何应对。
—
什么是 “legacy doctor-only” 模式？
在 OpenClaw 的架构中，doctor 是一类专门用于代码诊断、健康检查和问题修复的 Agent 角色。与通用的代码生成 Agent 不同，doctor 专注于：
- 代码质量分析
- 潜在 Bug 检测
- 安全漏洞扫描
- 性能瓶颈识别
legacy doctor-only 意味着 OpenAI Codex 不再作为通用代码生成 Agent 使用，而是被限制在特定的诊断场景下，作为遗留支持保留。
查看当前启用的 Agent 列表
openclaw agents list
输出示例（变更后）
✓ claude-3.5-sonnet [default] 通用代码生成
✓ gpt-4o [default] 通用代码生成
⚠ openai-codex [legacy] 仅诊断模式（doctor-only）
—
变更背后的 3 个技术原因
1. 统一 Agent 接口标准
OpenClaw 正在推进 Agent 协议标准化（Agent Protocol v2）。OpenAI Codex 的早期实现采用了特殊的调用方式，与新的统一接口不兼容。
// 旧版：Codex 专用调用方式（将被移除）
const codex = await openclaw.getLegacyAgent('openai-codex');
const result = await codex.complete({ prompt, temperature: 0.2 });
// 新版：统一 Agent 接口
const agent = await openclaw.createAgent('claude-3.5-sonnet');
const result = await agent.run({
task: 'generate-code',
context: { prompt, temperature: 0.2 }
});
2. 降低维护成本
根据 OpenClaw 官方文档，维护多个不同接口的 LLM 集成每年消耗约 23% 的开发资源。将 Codex 降级为 legacy 模式后，核心团队可以专注于优化主流 Agent（Claude、GPT-4o、Gemini）的体验。
| Agent 类型 | 维护状态 | 推荐使用场景 |
|———–|———|———–|
| Claude 3.5 Sonnet | 活跃维护 | 通用代码生成、重构 |
| GPT-4o | 活跃维护 | 快速原型、复杂推理 |
| Gemini 1.5 Pro | 活跃维护 | 长上下文处理 |
| OpenAI Codex | Legacy | 仅限遗留诊断任务 |
3. 功能重叠与替代方案成熟
OpenAI 官方已将 Codex 的能力整合到 GPT-4o 和 o1 系列模型中。测试数据显示，GPT-4o 在代码生成任务上的通过率（78.3%）已超过原版 Codex（71.5%）。
迁移示例：将 Codex 配置替换为 GPT-4o
编辑 ~/.openclaw/config.toml
[agents]
删除或注释掉
default = "openai-codex"
新配置
default = "gpt-4o"
fallback = "claude-3.5-sonnet"
[agents.gpt-4o]
model = "gpt-4o-2024-08-06"
temperature = 0.3
max_tokens = 4096
—
对你现有项目的影响
场景一：显式指定了 Codex Agent
如果你的配置文件或脚本中硬编码了 openai-codex，将会收到 deprecation 警告：
$ openclaw run --agent openai-codex
⚠️ 警告：Agent 'openai-codex' 已标记为 legacy
该 Agent 将于 v3.0.0 完全移除
建议迁移至：gpt-4o 或 claude-3.5-sonnet
文档：https://docs.openclaw.org/migration/codex-legacy
解决方案：运行自动迁移工具
OpenClaw 提供一键迁移命令
openclaw migrate codex-to-gpt4o --dry-run # 预览变更
openclaw migrate codex-to-gpt4o --apply # 执行迁移
场景二：依赖 Codex 的特定行为
Codex 在以下方面与 GPT-4o 存在差异，需要手动调整：
| 特性 | Codex (Legacy) | GPT-4o (推荐替代) |
|—–|—————|——————|
| 代码补全风格 | 偏向单行补全 | 支持多行、整块生成 |
| 注释理解 | 需特定格式 | 自然语言理解更强 |
| 上下文长度 | 4K tokens | 128K tokens |
| 价格（每 1M tokens） | $0.002 | $0.005 |
场景三：仅使用默认配置
如果你从未自定义 Agent，无需任何操作。OpenClaw 已自动将默认 Agent 切换为 GPT-4o。
—
如何继续使用 Codex（临时方案）
在完全移除前，你仍可通过显式启用 legacy 模式使用 Codex：
启用 legacy doctor-only 模式
export OPENCLAW_ENABLE_LEGACY_CODEX=1
验证状态
openclaw agents list --include-legacy
在 doctor 场景下调用
openclaw doctor analyze --agent openai-codex ./src/
> ⚠️ 注意：此选项将在 v3.0.0 中移除，建议尽快迁移。
—
FAQ：常见问题解答
Q1: 我的 OpenAI API Key 还能用吗？
可以。Codex 的变更不影响 API Key 的使用。你只需将 Key 配置给 GPT-4o 或其他 Agent 即可：
openclaw config set agents.gpt-4o.api_key $OPENAI_API_KEY
Q2: Codex 的 doctor-only 模式具体能做什么？
仅限以下诊断类任务：
openclaw doctor analyze— 代码健康检查openclaw doctor security— 安全审计openclaw doctor performance— 性能分析
不能用于：代码生成、重构建议、测试用例生成。
Q3: 迁移后代码生成质量会下降吗？
根据 OpenClaw 基准测试，GPT-4o 在 HumanEval 上的通过率为 90.2%，高于 Codex 的 71.5%。实际体验中，GPT-4o 在复杂逻辑和上下文理解方面表现更优。
Q4: 我想回滚到旧版本怎么办？
临时回滚到 v2.4.x（最后一个支持 Codex 默认版本的发布）
npm install -g @openclaw/cli@2.4.9
或锁定 Docker 镜像
docker run openclaw/cli:2.4.9 ...
> 不建议长期停留在旧版本，将无法获得安全更新。
Q5: 其他 OpenAI 模型（如 o1-preview）会受影响吗？
不会。此次变更仅针对 openai-codex 这一特定 Agent 标识。o1-preview、o1-mini 等模型作为独立 Agent 正常运行：
openclaw agents list | grep o1
✓ o1-preview [default] 复杂推理任务
✓ o1-mini [default] 快速推理任务
—
总结与下一步
本次变更的核心是 简化架构、聚焦主流、降低维护负担。对于绝大多数用户，这一变更是透明的；对于依赖 Codex 的特定工作流，建议：
1. 立即：运行 openclaw migrate codex-to-gpt4o --dry-run 评估影响
2. 本周内：在测试环境验证 GPT-4o 的替代效果
3. v3.0.0 发布前：完成生产环境迁移
—
相关阅读
—
参考来源
- GitHub Commit: refactor: make OpenAI Codex legacy doctor-only (#88605)
- OpenClaw 官方文档 – Agent 配置
- OpenClaw 官方文档 – 迁移指南
- OpenAI Codex 官方公告
- 阅读原文：OpenClaw 教学小站
—
