将 Codex App Server 接入现有聊天前端与网关的实践教程，涵盖流式事件、thread 生命周期、refill、多后端路由与 MCP 工具同步。
把 Codex 接进现有聊天前端：App Server 网关适配、三引擎切换与 MCP 工具同步
文档状态：2026-08-22。本文聚焦 Codex；API 与 Claude Code -p 网络上有较多相关教程，这仅讲兼容边界。
本文在 gateway 的 mode 值中使用 codex，对应官方 Codex App Server 集成。claude-p 保留原名，因为它对应真实的 claude -p 执行模式。
这套方案适合已经拥有聊天前端、SSE 网关、会话数据库和自定义工具系统的人。最终效果是：同一前端可以按 conversation 在 API、Claude Code -p、Codex App Server 三条后端之间选择；三条后端共用消息存储、附件、流式 UI 和工具气泡；各 provider 的会话语义、提示词载体与原生事件留在各自 adapter 内。
1. gateway 负责产品语义：conversation、消息树、附件、持久化、统一 SSE、后台任务。 2. provider adapter 负责协议语义：启动、认证、session/thread、工具事件、错误和中断。 3. 工具注册拥有单一真源，再为 CC 与 Codex 渲染各自配置；不要维护两份人工列表。 4. persona、style、记忆检索和 refill 各有独立职责；混成一个巨大 system prompt 会让更新、缓存与会话恢复一起失控。
本文把 refill 定义为“在新建、恢复、分叉或 compact 后，为 Codex thread 回填必要的历史上下文”。gateway 从自己的消息库中按预算取出历史消息摘要、最近几组完整对话和必要状态，组成一个临时 context block，放进下一次 turn/start。refill 只填当前 thread 缺少的部分，不重复整份 transcript，也不替代 Codex 原生的 thread history。
接入面 适合场景 长聊天前端中的局限 --------- codex exec --json CI、脚本、一次性自动化 每轮进程与历史管理成本高，深度交互能力有限 Codex SDK 应用内编程调用、希望使用类型封装 很合适；仍需自行定义 gateway 事件与持久化契约 codex app-server 自定义富客户端、完整 thread/turn/event/approval 集成 协议面较宽，需要严谨 adapter 与版本测试
OpenAI 将 App Server 定位为富客户端集成接口，覆盖认证、conversation history、approvals 和 streamed agent events。自动化或 CI 更适合 SDK。官方 App Server 文档
我们选择一个长期运行的 App Server 进程服务多个逻辑 conversation。这样做可以减少反复启动成本，也便于集中处理认证、模型目录、MCP 初始化与全局通知。每个前端 conversation 仍绑定独立 Codex thread，adapter 必须维护 ownership，严禁把一个 thread id 同时交给两个窗口。
先让前端只认识一套 provider-neutral contract。一个够用的最小集合如下：
From the project README.
Add the radar badge to your README — it shows your project was picked up by MCP Radar and links to this page:
[](https://mcp.liqiwa.com/s/KKarsyline--codex-app-server-gateway-guide.html)
The top new MCP servers of the week, every Monday. No spam, unsubscribe anytime.