智能体通宵工作,最后留下了一段乐观的总结。但下一个脚本需要知道:应该安排审核、因缺少凭据而暂停,还是重试失败的任务?从总结里搜索「成功」二字,并不能构成交接契约。
我们用 Codex 结构化输出,把供人阅读的对话与供程序处理的结果分开。本文讨论结果交接,而不是如何让进程持续运行;有关进程持久化,请先看后台任务指南。
Codex 结构化输出:事件不等于最终结果
官方非交互模式文档介绍了三种不同的输出机制:
| 机制 | 内容 | 我们的用途 |
|---|---|---|
--json | 执行事件的 JSONL 流 | 诊断与活动历史 |
--output-schema | 最终回复的 JSON Schema 契约 | 为下游提供稳定字段 |
-o | 将智能体最终消息写入文件 | 独立的交接产物 |
JSONL 文件包含许多 JSON 对象,每行一个。它并不是一份最终 JSON 文档。不要把完整事件日志交给只接受单个结果对象的程序。
模式约束的是回复的结构,而不是内容的真实性。智能体即使返回有效 JSON,也可能误解测试失败的原因。每个下游决策都必须保留这一区分。
在 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 已完成一轮任务。
进入审核队列之前验证产物
我们的下游契约要求满足以下全部条件,而不只是文件能被解析:
- 记录的进程退出码为零。退出码缺失或非零,都代表失败或未完成。
result.json存在且非空,并通过 JSON Schema 验证器对同一模式的验证。仅检查 JSON 语法不够。- 保存的基准提交与正在审核的工作副本一致。针对昨天代码的结果,不能证明今天分支的状态。
- 审核者核对引用的路径,并独立运行相关测试,再决定如何处理发现的问题。
把 JSON 中的字符串视为不可信文本。绝不要将 suggested_checks 插入 shell 执行,也不要把模型给出的路径直接用于不受限制的文件读取。以后如果围绕这套流程构建自动化,应使用命令白名单,并将路径限制在仓库范围内。
| 故障 | 安全的下一步 |
|---|---|
| 缺少结果或模式验证失败 | 保留日志;将本次尝试标记为未完成 |
| 身份验证错误或用量限制 | 暂停等待操作人员处理;避免密集重试 |
| JSON 有效但发现缺乏依据或有误 | 请求审核;格式正确不代表结论正确 |
| 进程在产生外部变更后被中断 | 重试前检查实际状态 |
虽然此示例只读,但以后允许写入的任务需要更加谨慎。重试智能体不是幂等操作:上一次尝试可能已经修改文件或调用外部工具。每次尝试使用新的运行目录,保留之前的证据,并在恢复前检查分支。更多健康信号请参阅监控指南。
为持续在线的智能体建立交接契约
Office Claws 让 Codex 智能体运行在你自己的 Contabo VPS 上,并提供 CLI 或像素风桌面控制界面。上述模式验证与产物处理需要你自己的脚本,并不意味着 Office Claws 内置了 JSON 工作流引擎。保留策略、访问控制、更新与最终审核仍由你负责。
各项费用仍然独立:Office Claws 首个智能体起价为 $4.99/月,VPS 另行付费,受支持的 ChatGPT 套餐在其用量限制内提供 Codex 访问权限。服务器持续开机并不意味着模型用量无限。规划队列前,请先阅读订阅与 API 成本对比。
我们的建议是:先在一台执行主机上生成一份只读报告。将事件、最终 JSON、退出状态与提交标识放在一起。只有单次运行的契约可靠后,才增加并行消费者;多个 Codex 智能体指南解释了如何分离它们的工作区。