内部工具该选 Codex SDK 还是 App Server？

内部工具该选 Codex SDK 还是 App Server？

团队想在内部工具中加入“检查代码变更”按钮。点击后，系统让 Codex 阅读代码仓库，列出需要核查的发现，再交给人工审核者决定。该用 Codex SDK，还是 Codex App Server？本文帮你在约 30 分钟内选定集成方式，并试用一个只读的 Python 示例。你需要 Codex 使用权限、不含机密的测试仓库；运行示例还需要 Python 3.10 或更新版本，以及一位负责审核结果的人。

根据 OpenAI 的 Codex SDK 文档，SDK 适合在程序、CI 流程或内部工具中运行编程任务。Codex App Server 则是协议接口，适合需要自行管理身份验证、对话历史、审批和 Agent 事件流的应用。Python SDK 实际上通过 JSON-RPC 控制本地 app-server。两者的选择是集成层级的选择，而不是选择两个不同的 AI 大脑。

🧰 准备工作

先写清需求：“选择仓库后，点击检查代码变更，返回供人工核查的发现列表。”确定谁能选择仓库、进程在哪台机器运行、可以读取哪些数据，以及由谁批准修改。

如果开发者只是打开终端修复一个问题，Codex CLI 指南可能已经足够。只有团队需要可重复的流程时，才考虑集成。AI Agent 与聊天机器人有何不同解释了为什么仍需设定边界并核验结果。

准备一个带有安全测试命令的测试仓库。第一次不要使用客户仓库。检查运行环境中的 Codex 登录方式和 sandbox 策略。不要把密钥写入代码文件或提示词。如果任务可能修改文件，还应阅读如何为团队限制 Codex 权限。

🪜 分步操作

1. 只需要任务结果时选择 SDK

设想内部工具有一个“检查仓库”按钮。一个任务接收项目目录，请 Codex 阅读并给出回答，再把摘要保存到工作单。用户不必查看每一条细小事件、在运行中修改问题，也不必在界面里批准命令。这种场景适合从 SDK 开始。

TypeScript SDK 在 Node.js 18 或更新版本的服务端运行，可以启动、继续和恢复 thread。Python SDK 需要 Python 3.10 或更新版本。稳定版通过 pip install openai-codex 安装，并附带锁定版本的 Codex CLI 依赖。选择适合现有系统的语言即可，无须同时安装两种。官方 Python 文档列出 read_only、workspace_write 和 full_access 三种 sandbox 预设。

首次检查应当只读。在测试仓库中安装软件包：

pip install openai-codex

将以下代码保存为 review_repo.py。类和方法名称来自官方 SDK 文档。示例没有指定模型，因此会使用账户可访问的默认模型：

from openai_codex import Codex, Sandbox

with Codex() as codex:
    thread = codex.thread_start(sandbox=Sandbox.read_only)
    result = thread.run(
        "Read this repository and list three possible test gaps. "
        "Cite the relevant files. Do not edit anything."
    )
    print(result.final_response)

在测试仓库中运行 python3 review_repo.py，或使用等效的 Python 命令。输出是供人工核查的材料，不是仓库安全证明。如果登录或 sandbox 报错，应修正相应权限；不要仅为了跑通示例就改用 full_access。

这个最小 API 示例已与 OpenAI 文档核对，并通过 Python 语法检查。它尚未在你的项目里实际调用 Codex，因此不保证输出内容或账户权限。正式试运行时，记录 SDK 版本、仓库、时间、sandbox 和错误，以便复现。

2. 构建完整 Codex 应用时选择 App Server

如果内部工具需要展示 Agent 的每一步工作、保存多个对话、接收审批请求、让用户恢复 thread，并实时响应事件，App Server 更合适。例如，团队负责人打开内部页面，看到 Codex 运行测试，批准某个操作，再继续追问刚发现的错误。基础 SDK 能启动任务并获取结果；这样的应用需要更细致地控制整个生命周期。

根据文档，App Server 使用双向 JSON-RPC 消息。对于本地连接，codex app-server 默认使用 stdio，每行一条 JSON 消息。最小流程如下：

  1. 启动 App Server 并连接客户端。
  2. 对该连接发送一次 initialize，随后发送 initialized 通知。
  3. 调用 thread/start，取得对话 ID。
  4. 使用该 ID 和用户消息调用 turn/start。
  5. 持续读取进度通知，直到 turn/completed；期间也要处理需要权限决策的请求。

这是生命周期示意，不是完整的客户端代码。真正的客户端必须处理错误、断线、审批、身份验证和会话状态。App Server 还提供 thread/resume 用于继续历史对话，提供 turn/steer 用于给正在运行的回合补充指令。如果产品需要保留上下文，不要在用户每次输入时都重新创建 thread。

对于简单任务，自行编写协议客户端意味着要管理消息、thread、审批和错误。先确认界面的实际需求，再选择 App Server。

3. 上线给他人使用前设定权限和停止点

无论选择哪种方式，都要把读取与提出建议和编辑与写入分开。第一版只返回带文件路径的评论。审核者打开代码、运行测试并确认每一项发现。将来若允许 Codex 修改代码，就要授予合适的写入范围、限制仓库，并要求审核差异。SDK 文档说明，Sandbox.read_only 只读，workspace_write 允许写入 workspace 和已配置的可写根目录，full_access 则不限制文件系统访问。

App Server 客户端必须处理审批请求与事件。turn/completed 并不证明代码已经过审核。要区分任务失败、提出建议，以及人工批准的修改。

如果工具只是发送普通 AI 问题，不涉及仓库或编程工具，可以参考Python Responses API 指南，选择合适的 API。Codex SDK 面向编程 Agent 任务，它不是 Responses API 的另一个名称。

4. 用三种情况测试原型

使用三个仓库测试：一个明显缺少测试，一个没有明显问题，一个读取权限不足。记录请求、权限、响应、错误和审核结论。确认权限不足时系统不会自动扩大权限；没有明显问题时不会编造问题；有发现时会指出可供人工复查的位置。

如果使用 App Server，再测试回合运行中客户端断线、审批被拒，以及恢复旧 thread。使用 SDK 时，则测试任务失败和将结果保存到内部系统。目标是知道任务未完成时用户会看到什么，而不只是留下最好的一次运行截图。

✅ 示例结果

假设一个团队想在仓库管理页面加入“查找测试缺口”按钮。初期只需发现列表，因此选择 Python SDK 配合 Sandbox.read_only。任务在测试仓库上运行，返回三个待审核项目。审核者检查代码后发现：一项正确，一项已经由另一目录的测试覆盖，第三项缺少足够信息，无法判断。系统记录这三种状态，不自动创建 pull request。

几周后，团队希望用户查看进度、在同一对话里追问，并在界面中批准命令。此时他们试作本地 App Server，评估 thread、turn 与审批的生命周期。这只是说明性场景，不承诺 SDK 或 App Server 一定能准确找出三个问题。

💡 提高效果的小建议

根据用户界面选择。 如果只需运行任务并取得结果，SDK 是简洁的起点。如果产品需要历史、事件和审批按钮，再研究 App Server。

不要把库当作权限策略。 SDK 是调用 Codex 的方式；sandbox 与访问权限仍需设计。当 read_only 可用时，不要只靠提示词中的“不要修改”设边界。

把原型做小。 一个样本仓库、一个按钮、一位审核者和三种测试情况，往往比立刻建设大型控制台更早暴露设计问题。

⚠️ 需要了解的限制

官方文档目前将 App Server 的 WebSocket 连接标为实验性，且不支持生产工作负载。本地原型使用 stdio；设计远程连接前要重新核对支持状态。不要照搬 localhost 示例，就把 WebSocket 暴露到公司网络或互联网；必须先处理身份验证、TLS 和授权。本文不是生产部署指南。

不要因为 SDK 示例没有指定模型，就推断每个账户都能使用同一个模型；代码使用的是默认模型。仍需登录、遵守 workspace 策略并验证实际访问权限。Agent 的结果可能错误或不完整。负责人仍要阅读代码、检查测试并批准修改。

❓ 常见问题

SDK 和 App Server 使用的是两个不同的 Codex 吗？ 不是。它们是控制 Codex 的两种接口层级。OpenAI 文档说明，Python SDK 通过 JSON-RPC 控制本地 app-server。

SDK 可以用于 CI 或定时任务吗？ 可以。官方文档将 CI/CD 和自动化任务列为 SDK 的使用场景。你仍须根据环境设计登录、权限、错误处理和审核步骤。

什么时候需要 App Server，而不是 SDK？ 产品需要对话历史、审批、进度通知以及 thread/turn 控制的客户端时。如果任务只需一个结果，先从 SDK 开始。

文中的 Python 示例实际运行过 Codex 吗？ 没有。代码已经对照官方文档并通过语法检查，但实际运行取决于你机器上安装的软件包、登录状态、仓库和权限。

为了避免权限错误，应该使用 full_access 吗？ 不应作为默认设置。代码检查示例只需 read_only。日后确需修改时，应限制写入范围、记录审批，并在应用修改前审核差异。

主要来源：Codex SDK 与 Codex App Server，OpenAI Learn。核对日期：2026 年 10 月 5 日。#Codex #CodexSDK #AppServer #AI编程 #VibeCoding

更多文章