Codex 提示后台服务设置不兼容？先查 CLI 与 daemon 的版本和配置
遇到 Background server has incompatible feature settings，先核对 Codex CLI、后台服务版本和持久化配置，再选择临时运行、更新或重启，并用新会话验收。
Ofox 
Codex 提示“Background server has incompatible feature settings”，表示 CLI 与共享后台服务对当前会话所需的功能设置存在分歧。 先比较两边版本，再决定是否改功能开关。如果版本相同，保存下来的后台服务覆盖项仍可能造成冲突；命令显示重启成功，也不代表下一个会话能正常启动。
本文处理终端 CLI 的兼容性提示，包括 api_key_model_discovery。它与桌面应用无法加载工作空间设置、Windows 找不到后台程序路径，是不同问题。下文的诊断检查不需要付费模型调用。
来源核对日期为 2026 年 10 月 16 日，包括公开故障报告及维护者限定范围的修复说明。本地只核验了 CLI 0.154.0 的命令可用性，没有复现报告中的 0.161.0 故障，也没有为了测试修复而打断正在运行的 daemon。本文由 Ofox 发布，更换 API 供应商不是已证实的启动设置协商修复办法。
先看清楚究竟是哪项设置冲突
提示可能要求开启 api_key_model_discovery，也可能要求关闭。方向非常重要，不要看到别人截图中的参数就原样照抄。
先记下四项信息：
| 信息 | 为什么要记录 |
|---|---|
| CLI 版本与可执行文件路径 | 当前终端可能没有调用你刚更新的那份安装 |
| 正在运行的 daemon 版本 | 共享服务与客户端可能处于不同版本 |
| 被要求的功能及开启/关闭方向 | 要求开启与要求关闭不是同一处理方式 |
| 是否存在活动或排队中的共享任务 | 重启共享服务可能影响其他会话 |
问题 #51758 同时记录了两个方向的版本错位：客户端较旧、后台服务较新，以及客户端较新、后台服务较旧。维护者在该讨论中说明，0.162.1 处理了普通启动时因默认功能设置不同而被阻止的情况，并建议通过对应安装渠道更新到 0.162.1 或更新版本。这项说明针对已记录的行为，不保证所有显式覆盖项或 daemon 错误都会因此消失。
先读取版本，不改动服务
在实际出现故障的终端执行：
codex --version
codex app-server daemon version
codex features listdaemon 的版本命令用于报告客户端和服务端版本信息。按已安装版本实际返回的字段记录，包括服务是否正在运行；字段缺失时，不要拿 CLI 版本补上。若某条子命令不被识别，先看当前版本帮助，不要把“不支持这条诊断命令”误判为第二个 daemon 故障：
codex app-server daemon --help
codex features --helpmacOS 或 Linux 可以用 command -v codex 查看命令解析结果。PowerShell 使用 Get-Command codex | Select-Object Source。它们显示的是当前 shell 选择的命令，不会列出桌面应用内部打包的所有程序。
通过 npm 更新，不一定会改变另一个包管理器安装的可执行文件。先确认自己运行的是哪份安装，再使用对应更新渠道；更新后在新终端里重新核对版本，不要同时重装所有来源。
按检查结果选择下一步
| 发现 | 下一步 | 要验收什么 |
|---|---|---|
| CLI 与 daemon 版本不同，没有主动设置覆盖项 | 对照有据可查的修复版本，通过正常渠道更新相关客户端 | 两边实际版本，以及一次新启动 |
| 版本相同，所需功能仍不一致 | 对照 CLI 功能列表与 daemon 保存的相应设置 | 是否仍有显式覆盖项 |
| 没有返回正在运行的 daemon | 保留启动错误，查看该版本 daemon 帮助 | 是服务启动失败，还是设置协商失败 |
| 报错指向缺失文件或 Windows 路径 | 转到 app-server 启动排查 | 后台进程能否真正启动 |
版本一致只是有用证据，不是完整健康检查。问题 #52085 记录了相同版本之间的启动冲突，因此不能看到数字一样就结束排查。该报告还出现了服务不由 Codex 管理、重启选项不可用的情况。如果你的提示也如此，应使用界面提供的临时路径，或联系服务管理者，不要假定 CLI 能重启独立管理的服务。
根据影响范围选择恢复方式
受影响版本提供过三种选择：本次不使用 daemon 运行、按显示的设置重启、取消。以自己安装的客户端实际显示的选项为准，选项名称和支持的参数可能变化。
| 选择 | 实际含义 | 何时应停止 |
|---|---|---|
| Run without daemon this time | 使用提供的临时路径，不立即更改共享服务设置 | 该路径无法承接所需会话或工作流时 |
| Restart with these settings | 持久修改共享服务设置并重启 | 不清楚活动/排队任务或其他客户端需求时 |
| Cancel | 保留现状，先收集证据 | 查清版本和服务归属后再继续 |
有紧急任务时，临时路径可能让你继续工作，而不必立刻更改共享服务。但它不是永久修复，也不能证明所有远端或后台工作流在没有 daemon 时都可使用。注意保留原任务的恢复或分叉意图，避免误开一个无关新任务。
若选择持久化重启，先保存工作，并确认哪些客户端正在共用服务。读完整份待应用的设置，不要只看第一行点名的开关。重启之后还要检查实际生效状态，并启动新会话。重启是正常 CLI 操作，并不代表它对其他会话没有影响。
为什么“重启成功”之后还是同样报错
问题 #51787 记录了特定的 0.161.0 行为：重启命令接受了开启功能的参数，却保留了冲突的已保存覆盖项。报告中的交互式恢复操作改变了保存状态，随后新会话才能启动。核对时该 issue 已关闭，但“已关闭”本身不等于对你所用版本逐一验证过。
这里要分清进程重启与实际生效的设置。进程可以成功重启，同时再次读取造成冲突的旧设置。因此，反复执行完全相同的重启命令，不是一套有效诊断流程。
报告中的文件位于实际 Codex 主目录下的 app-server-daemon/settings.json。如果设置了自定义 CODEX_HOME，应查看那个目录，不能直接假定是 ~/.codex。单独使用命名配置 profile，并不自动意味着有另一套主目录。只读取与冲突有关的覆盖项，不要公开整份设置文件；将其与 codex features list、提示要求的开启/关闭方向对照。
例如，保存值为 false、会话要求 true，是值得追查的差异，但不能据此直接删文件。其他设置可能服务于远端管理或其他使用者。有意修改前保留私密备份，优先使用受支持的恢复入口，并保留原值以便回退。服务归属不清楚时，先联系管理该服务的人。
不要一开始就改这些东西
- API 凭据：这类设置冲突可能出现在发起模型请求之前。删除认证状态，不能证明后台服务的功能设置发生了变化。
- 模型名称：设置不兼容不等于
model_not_found。先确认错误发生阶段，再决定是否改模型配置。 - 全部 Codex 数据：删除整个主目录会丢失无关状态，也让前后诊断更困难。
- 安全设置：扩大沙箱或文件权限，不能证明 CLI 与 daemon 已兼容。
需要理解更完整的配置关系，可以看 Codex config.toml 指南（英文）。如果实际故障是 Windows 路径或运行时缺失，请看 app-server 启动排错；如果是桌面工作空间加载提示，请看工作空间设置诊断。
用新会话验收，而不只看重启退出码
一次有效验收至少包括三部分：
- 重新采集版本与相关功能状态。 记下哪些变了、哪些没变。CLI 版本变化，并不能证明正在运行的服务也变了。
- 从原先失败的入口启动新会话。 不再出现兼容性提示、能够进入正常输入界面，才验证了启动协商阶段。验证这一阶段不需要发送付费模型请求。
- 单独核对原工作流。 需要恢复已有任务时，选择原本打算恢复的任务，检查状态后再提交新工作。远端或后台行为仅在实际工作流需要时测试。
只有临时不使用 daemon 的方式可用，应记录为“临时方案可用，共享服务冲突尚未解决”。普通新启动可用、另一个客户端却失败，也要记录这一故障，不能宣布全面修复。
需要进一步反馈时，可以使用以下记录：
观察时间与时区：
操作系统与安装渠道：
CLI 版本 / 实际解析的可执行文件：
daemon 版本 / 正在运行或不可用：
要求的具体功能，以及开启/关闭方向：
CLI 功能值 / 服务保存的相应覆盖项：
是否主动设置过覆盖项：是 / 否 / 不清楚
共享活动或排队任务：有 / 无 / 不清楚
尝试的操作与之后实际生效状态：
普通新启动 / 临时路径 / 原工作流的结果：分享前检查是否包含凭据和私人路径。真正有用的是差异与复测结果，而不是整份配置。修复成功意味着新启动正常、预期状态得到保留，不只是重启命令返回零退出码。
