Codex

在 Kaiwu 中配置 Codex，包括默认 App Server 后端、可安装项、本地控制以及恢复行为。

本文档介绍 Kaiwu 如何集成 Codex，以及日常使用中与 Codex 相关的关键行为特性。

安装 Codex

Kaiwu 可以代为安装：

kaiwu install provider codex

也可以自行安装后重启 Kaiwu：

npm install -g @openai/codex
codex --version

Kaiwu 本地认证

Codex 支持在以下路径进行设备本地的认证管理：

设置 → AI 与智能体 → AI 后端 → Codex

在此界面中，你可以：

查看当前选定设备上 Codex 是否已登录
查看 Kaiwu 检测到的是 CLI 登录还是 OPENAI_API_KEY
直接在 Kaiwu 内部打开 codex login
在 Kaiwu 外部完成登录后，点击立即检查

通用指南请参阅提供商认证。

认证方式（订阅与 API Key）

Codex 可通过 Kaiwu 关联服务进行认证：

OpenAI Codex 订阅（openai-codex）：支持设备代码 OAuth 认证、粘贴重定向 URL，或在原生客户端使用内置浏览器
OpenAI API Key（openai）：手动输入密钥

在 App 中配置：

设置 → 关联服务 → OpenAI (Codex)

在 CLI 中配置：

# Subscription auth (recommended): device code flow
kaiwu connect codex --device

# Headless fallback: paste the redirect URL
kaiwu connect codex --paste

# API key mode
kaiwu connect codex --api-key

注意事项：

设备认证可能需要在 ChatGPT 设置中启用“Codex 设备代码授权”。
若关联了多个配置文件，可在启动新会话时选择要使用的配置。
在 Web 端，Kaiwu 仅支持设备代码流或粘贴 URL 流。内置 OAuth 仅限原生端使用。

Codex 关联服务的选择还会影响会话浏览以及恢复会话选择器。详见：

会话交接

Codex 支持 Kaiwu 的会话交接功能，目前处于实验性阶段。

实际使用中的具体表现：

交接操作可将同一个 Kaiwu 会话 ID 迁移至另一台设备
目标设备就绪时，跨设备的 Codex 上下文连续性可以保持正常运作
该特性的成熟度目前低于 Claude 或 OpenCode 的交接功能

实用建议：

若追求当前最稳定的跨设备交接体验，建议优先使用 Claude 或 OpenCode
确保目标设备上的 Codex 已完成认证并就绪
尽量使用关联服务，以减少设备本地认证带来的摩擦

参阅：

后端与本地控制

Kaiwu 可根据当前可用环境及启用的功能，使用不同后端运行 Codex：

Codex App Server（默认）：Kaiwu 中常规 Codex 会话的推荐及默认路径。它支持 App 优先工作流、本地/远程切换，并在会话元数据可用时支持厂商原生恢复。
Codex ACP：将 Codex 切换至 ACP 模式时，仍可作为显式回退方案使用。
Codex MCP：全新会话仍可使用该后端，但在当前 Kaiwu 版本中，纯 MCP 既非默认配置，也不是常规的厂商恢复路径。
本地控制：Kaiwu 可将会话切换至“本地控制”模式以镜像 Codex 的活动（适用于将控制权从 App 切回终端的场景）。

Codex 关键行为说明：

Kaiwu 默认将 Codex 设为 App Server 后端
旧版的 mcp_resume 行为已移除
启动新会话时若 App Server 不可用，Codex 默认启动将直接报错，而不会默默回退；如需使用其他后端，请显式选择 ACP 或 MCP
本地/远程切换以及常规的 Codex 恢复均在默认的 App Server 路径上运作

若在设置中手动将 Codex 切换为纯 mcp，新会话仍可正常运行，但该纯 MCP 路径不支持厂商原生恢复。

Codex 本地控制具有排他性。当会话由 Codex TUI 接管时，Kaiwu 会监听 Codex 的轮次边界和进程状态，以准确判断何时可以安全恢复远程处理。轮次完成、轮次中止以及提供商进程退出，均会被视为将控制权交还给 Kaiwu 的安全边界。

Codex 模型可用性取决于当前激活的 Codex 后端、已安装的运行时以及账户状态。新会话引擎选择器可显示当前可用的 Codex 模型、特定模型选项（如推理深度），以及在所选后端支持时显示收藏的 Codex 模型快捷入口。

完整模型指南请参阅：

模型与引擎选择

Kaiwu 中面向用户的完整 MCP 指南请参阅：

MCP 服务器

Codex ACP 可安装组件行为

Codex ACP 依赖设备本地的 Codex ACP 可安装组件。

Kaiwu 将其呈现在：

设备详情 → 可安装组件

该组件至关重要，原因有二：

冷启动性能——预装 Codex ACP 二进制文件可避免首次运行时的安装与配置延迟
ACP 模式可靠性——如果显式选择了 ACP 模式，保持预装 Codex ACP 能免去安装等待，避免因缺少依赖而报错

默认行为

对于受管的 Codex ACP 可安装组件，Kaiwu 默认设置为：

必要时自动安装：开启
自动更新：自动

如果为新会话选择了 Codex ACP 后端且设备缺少该组件，Kaiwu 可在后台自动安装，从而让该设备后续启动会话更稳定、启动开销更低。

关键区别：新会话与恢复会话

对于新 Codex 会话：

策略允许时，Kaiwu 可在后台安装 Codex ACP
该设备后续的 ACP 会话可直接受益于提前就绪的组件

对于 ACP 模式下的恢复：

Codex ACP 必须已处于可用状态
Kaiwu 不会静默使用全新会话替代恢复操作

如果希望在该设备使用 ACP 时获得可预期的 Codex 恢复体验，请保持安装 Codex ACP 并启用自动更新，除非有特定理由关闭。若使用默认的 App Server 路径，常规恢复则无需此 ACP 可安装组件。

完整指南：可安装组件。

Kaiwu 启动，终端接续

Codex 支持 Kaiwu 对 App 启动会话的接入（attach）工作流：

在 Kaiwu App 中启动会话，
让其在设备后台远程运行，
后续在同一台设备的终端中运行 Kaiwu attach ⟦K7⟧，
需要直接使用 Codex 终端 UI 时，切换至本地控制。

稍后你还可以切换回远程控制，继续在 Kaiwu 中使用该会话。

本地控制从终端发起。在宿主设备上使用 Kaiwu attach ⟦K8⟧ 即可。

在 Codex 处于本地控制期间，若从 App 发送消息，Kaiwu 会先将其放入待处理队列中。若 Codex 处于空闲状态，Kaiwu 可切回远程控制并处理该消息；若 Codex 仍在执行本地轮次，Kaiwu 会等待当前轮次完成、中止或退出后再执行切换，避免打断当前 Codex TUI 的轮次。

在支持 tmux 的设备上，这通常是基于 tmux 的接入流程。在 Windows 上，请使用 Kaiwu 的 Windows 远程会话模式（Windows Terminal、Console 或 Hidden），而不要依赖 tmux。

完整端到端工作流请参阅功能特性 → 接入运行中的会话。

恢复非活跃 Codex 会话

Kaiwu 中的 Codex 恢复通常走默认的 App Server 路径。显式选择 ACP 时，ACP 恢复依然有效。

非活跃 Codex 会话在满足以下条件时可以恢复：

会话具备有效的 Codex 恢复元数据
当前后端与设备的组合支持恢复该会话（默认为 App Server，显式指定时为 ACP）
所选恢复路径依赖的各项设备环境均已安装就绪

在 CLI 中，使用：

Kaiwu resume

或：

Kaiwu resume <session-id>

在 App 或 Web 界面中，非活跃 Codex 会话同样只有通过上述检查后方可恢复。

恢复机制判定极为严格：若 Codex 恢复失败，Kaiwu 绝不会静默新建一个 Codex 会话取而代之。

权限与模式

Kaiwu 采用与提供商无关的权限模式（default、read-only、safe-yolo、yolo），并尽可能以最佳方式将其映射至 Codex。

完整用户指南（包括 CLI 参数、UI 选择器、默认值和应用时机）请参阅：

权限模式在 Codex 中的含义

Codex 的策略执行由两部分共同组成：

Kaiwu 工具审批拦截（决定 Kaiwu 会自动批准、拒绝还是提示确认），以及
提供商原生沙箱/策略（Codex 后端内部强制执行的安全规则）。

重要说明：

当由 Kaiwu 负责审批时，Kaiwu 会通过拒绝写类操作（编辑/补丁/执行）来强制执行 read-only。
safe-yolo 和 yolo 决定 Kaiwu 对有权审批的操作是弹出提示还是自动批准。
Codex 后端的沙箱策略可能在会话启动时即已固定。在会话中途更改权限模式仍能更新 Kaiwu 的审批行为，但可能无法更改 Codex 的内部沙箱，直至启动新的 Codex 会话。

计划模式（Plan mode）

计划是会话模式，而非权限模式，Codex 启用该模式的方式与 Claude 不同。

Claude 的计划模式由提供商原生支持，因此 Kaiwu 为其提供了专属控制项。Codex 的模式则是从运行中的 Codex app-server 通过 ACP 传入，因此当前可用的模式取决于该版本为当前会话通告的内容——plan 就在其中。你需要在模式控制项中选择它，而非通过计划专属开关来切换。

由于该列表动态来自运行时，Kaiwu 仅在当前 Codex 后端和会话确实声明了可用模式时才显示“模式”控制项；如果未声明，控制项将自动隐藏，以避免展示后调用失败。

Kaiwu 保持对旧写法的兼容：--permission-mode plan 会映射至 --agent-mode plan。

代码审查

Codex 可直接调用专属审查 API 执行代码审查，无需在对话提示词中用自然语言发起，审查结果也会以结构化结论而非段落文本呈现。

在对话中直接启动审查：

/codex.review

Kaiwu 自身的审查入口在请求支持安全表达时，同样使用该路径。返回的结论经过格式规范化，会在会话记录中渲染为审查卡片而非自由文本；进入与退出审查的过程也会作为事件记录在会话记录中。

若当前运行的 Codex 版本不提供该审查 API，Kaiwu 会明确提示该方法不受支持，而不是静默退化为伪装成审查的普通提示词调用。

若需自行标记 diff 并将批注发送给智能体（适用于任意智能体，不仅限于 Codex），请参阅审查评论。

切换与权限持久化

更改权限模式时：

变更会规范存储在会话元数据中，并且
在另一台设备打开同一会话或在本地与远程之间切换时，设置将完整继承。

如果在 App 中勾选了生效时机：下一条提示词：

该选择仅应用于你发送的下一条消息（作为消息元数据生效），并且
仅在该消息提交后，才会成为整个会话的全局配置。