AgentKit Studio
运行时与部署

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 Serverexecution: 'codex-app-server'
适配器Studio 进程内owner: 'studio'
契约studio.codex.adapter/v1contract
事件源studio-codex-adaptereventOwner
流式codex-turn/itemstreamOwner
会话与历史DSH Session每轮一个临时 thread
模型提供方标识agentkit-studio-codexsrc/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 更轻(见三运行时对照)。

配置入口

可执行文件解析顺序

  1. AGENTKIT_CODEX_BIN(显式路径优先)
  2. @openai/codex/bin/codex.js(随包解析)
  3. Windows 上优先解析原生二进制,避免 GUI 子进程弹出控制台窗口

依据:src/providers/codex-command.mjs:29-42。

环境变量

变量默认值说明
AGENTKIT_CODEX_MODEL—默认模型
AGENTKIT_CODEX_APPROVAL_POLICYnever审批策略
AGENTKIT_CODEX_SANDBOX—沙箱模式
AGENTKIT_CODEX_REASONING_SUMMARY可读摘要推理摘要,默认请求可读文本
AGENTKIT_CODEX_TIMEOUT_MS0(无总时限)整轮总预算
AGENTKIT_CODEX_IDLE_TIMEOUT_MS600000(10 分钟,最小 10000)空闲预算
AGENTKIT_CODEX_STREAM_IDLE_TIMEOUT_MS900000(15 分钟,最小 1000)SSE 静默预算
AGENTKIT_CODEX_MODEL_IDLE_TIMEOUT_MS流式预算 + 60 秒回环模型代理静默预算
AGENTKIT_CODEX_MODEL_API_KEY—仅注入子进程环境,不进入 argv 或用户配置
AGENTKIT_MANAGED_CODEX_APIresponses托管形态下可选 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_INVALIDsrc/providers/codex-runtime.mjs:165-166
必须绑定 Codex Agent未绑定就用 Codex 模型抛 CODEX_AGENT_REQUIREDsrc/providers/dsh-runtime.mjs:588
必须有 DSH 工作区会话未提供 cwd 抛 CODEX_WORKSPACE_UNAVAILABLEsrc/providers/dsh-runtime.mjs:620-621
模型需要网关地址提供商未配置 Codex 接口抛 CODEX_MODEL_PROVIDER_UNAVAILABLEsrc/providers/dsh-runtime.mjs:625-627
需要官方 Provider未安装或未启用抛 CODEX_PROVIDER_UNAVAILABLEsrc/providers/dsh-runtime.mjs:630-634
无总时限时不会超时AGENTKIT_CODEX_TIMEOUT_MS=0 表示只靠空闲预算兜底src/providers/codex-runtime.mjs:144
Sandbox 非法值降级无效的沙箱模式回退到运行时默认,不传给 Codexsrc/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_UNAVAILABLEDSH 会话没有提供工作区重新选择工作区后重开会话
CODEX_INPUT_INVALID既没有文字也没有图片输入输入内容后再发送
CODEX_MODEL_PROVIDER_UNAVAILABLE当前模型提供商没有配置 Codex 接口到模型设置里补上网关地址
CODEX_PROVIDER_UNAVAILABLECodex 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

本页导航