Grok Build怎么接入脚本？headless输出、超时与结果文件核对

Grok Build能在终端交互，也可通过headless模式接到脚本。脚本不能只看一段回答就认为成功，还要处理认证、工作目录、退出状态、超时与输出格式。本文做一次练习仓库的代码导览，不自动改文件或调用部署；与批处理模型API不同，它运行的是本地CLI代理。

第一步：准备认证与干净练习目录

先按官方首次使用流程完成本机认证，或在安全环境提供XAI_API_KEY，不写进脚本或仓库。确定要分析的目录，检查已有改动及项目指令。headless不等于天然只读，提示限制仍需与实际工具权限和环境隔离配合，不能为了省事一律always-approve。

自动化环境可加–no-auto-update跳过后台更新检查，减少一次任务中额外状态变化；这不代替正常软件维护。模型与用量仍取决于实际账号设置，不把命令行执行描述成免费或不消耗额度。

第二步：先用单次提示验证行为

grok --no-auto-update --cwd /path/to/practice-repo -p "只读列出本练习仓库的入口文件与已有测试脚本，并提供来源。不要修改、安装、运行项目命令或访问外部服务。" --output-format json

替换目录后再使用，先在小仓库测试。-p发送一次提示，–cwd明确工作目录，json在结束时输出一个JSON对象。JSON外层是CLI结果，不保证内部回答已经符合你自己的业务Schema；读取前先检查本机版本实际返回结构。

需要逐步进度时使用streaming-json，它是逐行事件，不是一个普通JSON文档。plain适合人阅读。三者的解析方法不同，不把整个事件流交给json.loads，也不从混有错误日志的控制台文本中截一个大括号就当完整结果。

第三步：在脚本中检查状态后保存

import json, pathlib, subprocess

args = ["grok", "--no-auto-update", "--cwd", "/path/to/practice-repo",
        "-p", "只读说明仓库入口并给文件依据，不修改、不安装、不联网。",
        "--output-format", "json"]
run = subprocess.run(args, capture_output=True, text=True, timeout=120)
if run.returncode != 0:
    raise RuntimeError("Grok CLI failed; inspect redacted stderr")
result = json.loads(run.stdout)
if not isinstance(result, dict):
    raise ValueError("Expected one JSON object")
with pathlib.Path("grok-practice-result.json").open("x", encoding="utf-8") as out:
    json.dump(result, out, ensure_ascii=False, indent=2)

示例使用参数列表而非拼接Shell命令，输出文件采用x模式避免覆盖旧结果。重复运行前决定版本文件名，不以旧文件仍存在判断新任务成功。代码仅做语法检查，没有真实调用CLI模型；stderr可能含路径或敏感片段，应脱敏后用于排查。

第四步：处理超时与会话续接

timeout是本地等待上限，不是官方生成承诺。超时不会撤销已经发生的文件或外部操作，需要检查进程和任务实际状态，不能直接重跑所有写步骤。本文任务只读，仍应对照Git状态确认没有意外变化。

需要跨多轮保留会话时，–session-id、–resume或–continue有各自含义，官方将headless会话保存在~/.grok/sessions。不要在多个作业里同时共用最近会话，导致上下文串入另一项任务；批次并行与会话状态应由应用明确管理。

第五步：核对语义和交付状态

打开结果中的实际回答，对照入口路径与配置文件。格式可解析不意味着内容正确，没有文件依据的判断应标未知；没有执行测试，就不能写测试通过。若工具许可不足或认证失败，应保留失败状态，不生成一份空白成功报告掩盖问题。

最终同时验收命令状态、输出类型、事实依据和副作用。需要IDE集成时官方另有ACP入口，它使用JSON-RPC，不能把-p的普通JSON输出直接当ACP协议。先把一个单次脚本稳定做好，再扩展到正式流水线。

流水线中的超时、解析失败与模型回答未知应作为不同状态记录，便于重跑时判断需要修环境还是重新调查。输出较大时考虑按事件逐行处理并限制日志保留，不把全量会话内容无差别写进公开构建日志。

官方资料

资料核对日期：2026年11月9日。

• xAI：Headless and Scripting