Codex 结构化输出:为 VPS 智能体建立可靠的 JSON 交接

Codex 结构化输出:为 VPS 智能体建立可靠的 JSON 交接 — 使用 Codex 结构化输出、exec、JSON Schema 与独立事件日志,让 VPS 后台任务交出可审核的结果,同时避免把有效 JSON 当成成功证明。
2026年11月15日2 分钟阅读
Share with

智能体通宵工作,最后留下了一段乐观的总结。但下一个脚本需要知道:应该安排审核、因缺少凭据而暂停,还是重试失败的任务?从总结里搜索「成功」二字,并不能构成交接契约。

我们用 Codex 结构化输出,把供人阅读的对话与供程序处理的结果分开。本文讨论结果交接,而不是如何让进程持续运行;有关进程持久化,请先看后台任务指南。

Codex 结构化输出:事件不等于最终结果

官方非交互模式文档介绍了三种不同的输出机制:

机制内容我们的用途
--json执行事件的 JSONL 流诊断与活动历史
--output-schema最终回复的 JSON Schema 契约为下游提供稳定字段
-o将智能体最终消息写入文件独立的交接产物

JSONL 文件包含许多 JSON 对象,每行一个。它并不是一份最终 JSON 文档。不要把完整事件日志交给只接受单个结果对象的程序。

将执行事件、最终 JSON 结果与人工审核分离

模式约束的是回复的结构,而不是内容的真实性。智能体即使返回有效 JSON,也可能误解测试失败的原因。每个下游决策都必须保留这一区分。

大约 3 分钟运行你的第一个智能体

安装 Office Claws CLI,连接你的 Contabo 账户和 Codex 订阅,你的智能体就会拥有自己的 VPS 和办公室里的一张桌子。

curl -fsSL https://officeclaws.com/downloads/install.sh | sh

$4.99/月 + 你自己的 Contabo VPS · 密钥保存在你的钥匙串中

在 VPS 上建立一个小型只读交接流程

在自己的执行主机上使用可信的 Git 工作副本,并提前完成 Codex 身份验证。采用示例前,请核对已安装版本的 codex exec --help。这是一套手动 shell 操作,不是 Office Claws 内置的任务调度器。

把产物目录放在工作副本之外,避免生成的日志成为仓库输入。模式刻意只保留少量字段:摘要、发现与建议检查项。它不要求智能体为自己的工作出具安全证明。

cd ~/work/product-api
umask 077
RUN_DIR=$(mktemp -d "$HOME/codex-report.XXXXXX")
cat > "$RUN_DIR/schema.json" <<'JSON'
{
  "type": "object",
  "properties": {
    "summary": { "type": "string" },
    "findings": {
      "type": "array",
      "items": { "type": "string" }
    },
    "suggested_checks": {
      "type": "array",
      "items": { "type": "string" }
    }
  },
  "required": ["summary", "findings", "suggested_checks"],
  "additionalProperties": false
}
JSON
 
git rev-parse HEAD > "$RUN_DIR/base-commit.txt"
codex --version > "$RUN_DIR/codex-version.txt"
if codex exec --sandbox read-only --json \
  --output-schema "$RUN_DIR/schema.json" \
  -o "$RUN_DIR/result.json" \
  "Inspect the repository for risky retry logic. Do not edit files. Report findings with file paths; suggest checks without running them." \
  > "$RUN_DIR/events.jsonl" 2> "$RUN_DIR/stderr.log"; then
  printf '0\n' > "$RUN_DIR/exit-code.txt"
else
  rc=$?
  printf '%s\n' "$rc" > "$RUN_DIR/exit-code.txt"
fi
printf 'Artifacts: %s\n' "$RUN_DIR"

只读沙箱限制写入,但不构成保密边界。只在已验证账户有权访问的代码上执行任务,移除环境中不必要的凭据,并在执行前检查项目配置与已连接工具。绝不要把身份验证文件打包进产物。

显式保存退出码很重要:监督程序需要区分进程失败和成功执行但发现问题这两种情况。如果使用超时机制或服务管理器,也要记录其终止状态。持久运行的主机不保证 Codex 已完成一轮任务。

进入审核队列之前验证产物

我们的下游契约要求满足以下全部条件,而不只是文件能被解析:

  1. 记录的进程退出码为零。退出码缺失或非零,都代表失败或未完成。
  2. result.json 存在且非空,并通过 JSON Schema 验证器对同一模式的验证。仅检查 JSON 语法不够。
  3. 保存的基准提交与正在审核的工作副本一致。针对昨天代码的结果,不能证明今天分支的状态。
  4. 审核者核对引用的路径,并独立运行相关测试,再决定如何处理发现的问题。

把 JSON 中的字符串视为不可信文本。绝不要将 suggested_checks 插入 shell 执行,也不要把模型给出的路径直接用于不受限制的文件读取。以后如果围绕这套流程构建自动化,应使用命令白名单,并将路径限制在仓库范围内。

故障安全的下一步
缺少结果或模式验证失败保留日志;将本次尝试标记为未完成
身份验证错误或用量限制暂停等待操作人员处理;避免密集重试
JSON 有效但发现缺乏依据或有误请求审核;格式正确不代表结论正确
进程在产生外部变更后被中断重试前检查实际状态

虽然此示例只读,但以后允许写入的任务需要更加谨慎。重试智能体不是幂等操作:上一次尝试可能已经修改文件或调用外部工具。每次尝试使用新的运行目录,保留之前的证据,并在恢复前检查分支。更多健康信号请参阅监控指南。

为持续在线的智能体建立交接契约

Office Claws 让 Codex 智能体运行在你自己的 Contabo VPS 上,并提供 CLI 或像素风桌面控制界面。上述模式验证与产物处理需要你自己的脚本,并不意味着 Office Claws 内置了 JSON 工作流引擎。保留策略、访问控制、更新与最终审核仍由你负责。

各项费用仍然独立:Office Claws 首个智能体起价为 $4.99/月,VPS 另行付费,受支持的 ChatGPT 套餐在其用量限制内提供 Codex 访问权限。服务器持续开机并不意味着模型用量无限。规划队列前,请先阅读订阅与 API 成本对比。

我们的建议是:先在一台执行主机上生成一份只读报告。将事件、最终 JSON、退出状态与提交标识放在一起。只有单次运行的契约可靠后,才增加并行消费者;多个 Codex 智能体指南解释了如何分离它们的工作区。

作者

Office Claws Team

在 Office Claws 构建 AI 智能体管理的未来。分享关于基础设施、安全和开发者体验的见解。

大约 3 分钟运行你的第一个智能体

安装 Office Claws CLI,连接你的 Contabo 账户和 Codex 订阅,你的智能体就会拥有自己的 VPS 和办公室里的一张桌子。

curl -fsSL https://officeclaws.com/downloads/install.sh | sh

$4.99/月 + 你自己的 Contabo VPS · 密钥保存在你的钥匙串中