用途
codex-mcp-tool 是一个 MCP 服务器，用于把 Claude、Cursor 等 IDE 或 AI 助手连接到本机的 Codex CLI。通过该桥接，编辑器或 AI 助手可以调用 Codex CLI 完成代码分析与编辑等操作。它并非 OpenAI 官方产品，采用 MIT 许可证。
主要能力
- 文件分析：支持以 @src/、@package.json 等语法引用文件。
- 多轮会话：具备工作区隔离的对话连续性。
- 原生恢复：使用 codex resume 保留上下文（需 CLI v0.36.0+）。
- 本地开源模型：可通过 localProvider 配合 Ollama 或 LM Studio 运行。
- 网络搜索：通过 search: true 启用研究能力。
- 沙箱模式：通过显式沙箱与审批策略实现安全自动化。
- 改动模式：为重构输出结构化的 OLD/NEW 补丁。
- 头脑风暴：提供 SCAMPER、设计思维、横向思维等框架。
- 健康诊断：监控 CLI 版本、功能与会话。
- 跨平台：支持 Windows、macOS、Linux。
图像生成
image-gen 驱动 Codex 内置的 image_gen 工具，使用 ChatGPT 登录，无需 OPENAI_API_KEY。该工具仅接受提示词与参考图路径：模型与像素尺寸由 Codex 决定，不支持尺寸、质量、格式或遮罩参数。因此 image-gen 将所有控制放入结构化提示词（用途、资产类型、风格、构图、精确文本、参考角色、编辑不变量、宽高比、预设），并要求 Codex 宿主模型转述而非自行发挥。图像由 Codex 保存到 $CODEX_HOME/generated_images/<thread>/，指定 outputPath 时会复制；若文件已存在，默认保留原文件并写入 -v2 副本，除非 overwrite: true。结果会报告每个文件的尺寸与 alpha 通道，因此可标记请求透明背景但返回不透明的情况。
模型与推理深度
默认省略 model 参数，Codex CLI 使用 ~/.codex/config.toml 中的默认模型（例如 model = "gpt-6.1-sol"）。仅在单次调用需要覆盖默认值时传入 model。推理深度按工具校准：ask-codex 使用 Codex CLI 默认推理（medium），仅在任务需要更多规划或检查时提高；brainstorm、do-act、review-changes 默认 reasoningEffort: "high"。Sol、Astra 和 Terra 模型提供 max 与 ultra 推理；Luna 模型最高 max，gpt-5.5 最高 xhigh。ultra 可能把工作委派给子代理，多数任务应保持 medium 或 high。需传入具体 slug：裸移动别名 gpt-6 和 gpt-5.6 会被 API 拒绝；gpt-6.1-sol 在 Codex CLI 0.157.x 中会以未知 slug 的相同 400 被拒，可用 npm install -g @openai/codex@latest 升级。
会话管理与要求
自 v1.4.0+ 起支持多轮会话与工作区隔离：CODEX_SESSION_TTL_MS 控制会话 TTL（默认 24 小时），CODEX_MAX_SESSIONS 控制最大会话数（默认 50）。需要 Codex CLI 0.95.0 或更新版本；旧版本会给出明确升级提示，而不会静默丢弃不支持的标志。升级命令为 npm install -g @openai/codex@latest，可用健康工具查看检测到的版本。前置条件：Node.js 18+，且已安装并认证 Codex CLI。配置位置：macOS 为 ~/Library/Application Support/Claude/claude_desktop_config.json；Windows 为 %APPDATA%\Claude\claude_desktop_config.json。
本地开源模型与高级选项
自 v1.6.0+ 起可用本地 Ollama 或 LM Studio 替代 OpenAI，要求本地运行 Ollama 并选用支持工具调用的模型（如 qwen3:8b）。CLI 兼容性方面，已针对 Codex CLI 0.144.3 验证；服务器保留旧功能守卫，但建议使用当前版本。当前行为要点：Codex CLI 已移除 --full-auto 与 on-failure 审批策略；MCP 的 sandbox: true / fullAuto: true 仍是 --sandbox workspace-write --ask-for-approval never 的兼容别名，不会绕过沙箱；使用原生 --search，不再使用已弃用的 web_search_request；当前 exec 标志包括 --strict-config、--ephemeral、--ignore-user-config、--ignore-rules。
故障排查与版本说明
可用健康工具诊断：'use health verbose:true'。常见问题是 GUI（Dock、Finder、开始菜单）启动的 MCP 客户端继承的 PATH 较精简，可能不含 Homebrew、nvm、volta 目录，导致终端可用但应用内找不到 codex。服务器会自动搜索这些位置；若仍找不到，可显式固定路径，其值可用 which codex 获取，健康工具会显示解析到的可执行文件及方式。版本演进：v2.5.x → v2.6.0 同步 Codex CLI 0.159.2 模型并新增 image-gen 工具，新增 gpt-6.1-sol（需 Codex CLI 0.159+）、gpt-6-sol 和 gpt-6-luna，破坏性变更为移除 gpt-5.4-mini（现返回 HTTP 400）。v2.4.x → v2.5.0 兼容 Codex CLI 0.153.4，新增 gpt-6-astra，移除 gpt-5.4 与移动别名 gpt-5.6（均返回 HTTP 400），并移除 0.153.x 不再解析的 untrusted 审批策略。v2.3.x → v2.4.0 审计 Codex CLI 0.144.3，新增 GPT-5.6 Sol/Terra/Luna、max/ultra 推理、当前 exec 标志、仅原生搜索，并对已移除的 --full-auto 和 on-failure 审批策略做安全兼容处理。v2.2.x → v2.3.0 将 gpt-5.5 设为新默认，新增 gpt-5.4-mini，移除退役模型（gpt-5.3-codex-spark、gpt-5.2-codex、gpt-5.1-codex-max、gpt-5.1-codex-mini）。v2.0.x → v2.1.0 将 gpt-5.4 设为新默认模型并更新回退链。v1.5.x → v1.6.0 支持本地开源模型（localProvider、oss）、默认 gpt-5.3-codex、xhigh 推理。v1.3.x → v1.4.0 新增 sessionId 参数、list-sessions/health 工具、结构化错误处理，无破坏性变更。
适用场景与限制
适用于在 Claude、Cursor 等 IDE 或 AI 助手中桥接本机 Codex CLI，进行代码分析、多轮编辑、沙箱自动化、重构补丁生成、头脑风暴与图像生成等开发任务。使用限制包括：需预先安装并认证 Codex CLI（0.95.0+）与 Node.js 18+；GUI 启动环境可能存在 PATH 问题；部分模型 slug 与旧标志被 API 或 CLI 拒绝；本地模型需 Ollama 并支持工具调用；收费、价格、具体平台或效果等资料暂未提供，需以实际配置为准。
