Codex Agent
Codex App Server 适配层的执行模型、配置项、超时预算与沙箱限制,以及它在什么情况下会拒绝启动。
Codex Agent(codex)把每一轮交给一个临时的 Codex thread,DSH 仍然是可见会话与历史的拥有者。 Studio 不把 Codex 伪装成一个 OpenAI 兼容网关模型,而是保持与官方 Codex Provider 相同的 codex app-server --stdio 协议边界(src/providers/codex-runtime.mjs:3-8)。
执行模型
| 环节 | 归属 | 依据 |
|---|---|---|
| 模型 / 工具循环 | Codex App Server | execution: 'codex-app-server' |
| 适配器 | Studio 进程内 | owner: 'studio' |
| 契约 | studio.codex.adapter/v1 | contract |
| 事件源 | studio-codex-adapter | eventOwner |
| 流式 | codex-turn/item | streamOwner |
| 会话与历史 | DSH Session | 每轮一个临时 thread |
| 模型提供方标识 | agentkit-studio-codex | src/providers/codex-models.mjs:4 |
依据:src/runtime-contract.mjs:30-34。
每轮开始时新建 thread,所以权限、沙箱与推理档位只对当轮生效,不会写进用户配置(src/providers/codex-runtime.mjs:169-178)。
什么时候选它
- 任务是改代码、跑命令、看仓库差异——Codex 的工具集与沙箱模型就是为这个设计的。
- 你需要 Codex 的审批语义(
approvalPolicy)而不是 DSH 的工具审批。 - 团队已经在用 Codex 官方 Provider,希望复用同一套 CLI 与应用服务器。
- 需要按原生请求重放(
replay)且仍然走 DSH 会话。
不需要代码任务时,DSH Native 更轻(见三运行时对照)。
配置入口
可执行文件解析顺序
AGENTKIT_CODEX_BIN(显式路径优先)@openai/codex/bin/codex.js(随包解析)- Windows 上优先解析原生二进制,避免 GUI 子进程弹出控制台窗口
依据:src/providers/codex-command.mjs:29-42。
环境变量
| 变量 | 默认值 | 说明 |
|---|---|---|
AGENTKIT_CODEX_MODEL | — | 默认模型 |
AGENTKIT_CODEX_APPROVAL_POLICY | never | 审批策略 |
AGENTKIT_CODEX_SANDBOX | — | 沙箱模式 |
AGENTKIT_CODEX_REASONING_SUMMARY | 可读摘要 | 推理摘要,默认请求可读文本 |
AGENTKIT_CODEX_TIMEOUT_MS | 0(无总时限) | 整轮总预算 |
AGENTKIT_CODEX_IDLE_TIMEOUT_MS | 600000(10 分钟,最小 10000) | 空闲预算 |
AGENTKIT_CODEX_STREAM_IDLE_TIMEOUT_MS | 900000(15 分钟,最小 1000) | SSE 静默预算 |
AGENTKIT_CODEX_MODEL_IDLE_TIMEOUT_MS | 流式预算 + 60 秒 | 回环模型代理静默预算 |
AGENTKIT_CODEX_MODEL_API_KEY | — | 仅注入子进程环境,不进入 argv 或用户配置 |
AGENTKIT_MANAGED_CODEX_API | responses | 托管形态下可选 responses 或 chat-completions |
依据:src/providers/codex-runtime.mjs:132-160、:189、src/managed-runtime-host.mjs:32-42、src/managed-runtime-definition.mjs:22-23。
为什么默认预算比 Codex 大
Codex 默认在 SSE 静默 300 秒后中止单轮,而托管运行时的业务轮次可能持续输出推理与报告。Studio 因此把每轮静默预算固定为 15 分钟并允许部署调整,同时让回环模型代理的预算略大于 Codex 自身,避免代理先切断仍然存活的上游(src/providers/codex-runtime.mjs:146-158)。
限制
| 限制 | 表现 | 依据 |
|---|---|---|
| 工作目录必须是绝对路径 | 相对路径抛 CODEX_WORKSPACE_INVALID | src/providers/codex-runtime.mjs:165-166 |
| 必须绑定 Codex Agent | 未绑定就用 Codex 模型抛 CODEX_AGENT_REQUIRED | src/providers/dsh-runtime.mjs:588 |
| 必须有 DSH 工作区 | 会话未提供 cwd 抛 CODEX_WORKSPACE_UNAVAILABLE | src/providers/dsh-runtime.mjs:620-621 |
| 模型需要网关地址 | 提供商未配置 Codex 接口抛 CODEX_MODEL_PROVIDER_UNAVAILABLE | src/providers/dsh-runtime.mjs:625-627 |
| 需要官方 Provider | 未安装或未启用抛 CODEX_PROVIDER_UNAVAILABLE | src/providers/dsh-runtime.mjs:630-634 |
| 无总时限时不会超时 | AGENTKIT_CODEX_TIMEOUT_MS=0 表示只靠空闲预算兜底 | src/providers/codex-runtime.mjs:144 |
| Sandbox 非法值降级 | 无效的沙箱模式回退到运行时默认,不传给 Codex | src/providers/codex-runtime.mjs:174 |
沙箱与审批
沙箱取值与执行策略共用同一枚举:read-only、workspace-write、danger-full-access(src/execution-policy.mjs:8)。托管形态下默认 workspace-write,上限 danger-full-access(src/execution-policy.mjs:10-11);请求只能收窄、不能突破部署上限(src/execution-policy.mjs:29-33)。
chat-completions 模式下 web_search 会被显式禁用——托管 Responses 工具在 Chat Completions 里没有等价物(src/providers/codex-runtime.mjs:186-187)。
失败形态
| 错误码 | 触发条件 | 你能做什么 |
|---|---|---|
CODEX_AGENT_REQUIRED | 选择了 Codex 模型但没有绑定 Codex Agent | 先在 Agent 上把运行时设为 Codex Agent |
CODEX_WORKSPACE_INVALID | 工作目录不是绝对路径 | 改用绝对路径 |
CODEX_WORKSPACE_UNAVAILABLE | DSH 会话没有提供工作区 | 重新选择工作区后重开会话 |
CODEX_INPUT_INVALID | 既没有文字也没有图片输入 | 输入内容后再发送 |
CODEX_MODEL_PROVIDER_UNAVAILABLE | 当前模型提供商没有配置 Codex 接口 | 到模型设置里补上网关地址 |
CODEX_PROVIDER_UNAVAILABLE | Codex App Server Provider 未注册 | 安装并启用官方 Codex Provider |
CODEX_RUNTIME_FAILED | 应用服务器内部失败 | 查看运行中心日志;可重试一次 |
Codex 的取消是协作式的:本地确认取消不等于远端工具已停止(src/runtime-contract.mjs:30-34 只声明 cancel,不声明强杀)。资源降级规则见降级与重试。
源码依据
| 结论 | 位置 |
|---|---|
| 协议边界与 thread 归属 | src/providers/codex-runtime.mjs:1-8 |
| 配置解析 | src/providers/codex-runtime.mjs:127-160 |
| 每轮覆盖与沙箱回退 | src/providers/codex-runtime.mjs:165-190 |
| 可执行文件解析 | src/providers/codex-command.mjs:29-42 |
| 模型提供方标识 | src/providers/codex-models.mjs:4 |
| 路由失败分支 | src/providers/dsh-runtime.mjs:588-634 |
| 执行策略枚举与收窄 | src/execution-policy.mjs:8-33 |