ModelTrace Guard 插件入门:在 Codex 任务内实时模型归因监测
ModelTrace Guard 插件入门:在 Codex 任务内实时模型归因监测
ModelTrace Guard 是 ModelTrace 项目自带的 Codex 插件,用于在 Codex 任务运行过程中做实时模型归因监测:它按工具调用次数在后台 fork 任务快照进行指纹检测,正常结果静默保存,发现异常时自动提醒并复测,帮助你在长任务中随时确认“当前回答的到底是不是你预期的那个模型”。
ModelTrace Guard 是什么?能解决什么问题
使用第三方 API 渠道或订阅服务时,你很难直接验证后端实际调用的模型。ModelTrace 是一个本地运行的主动模型归因工具:它通过三条长整数生成挑战提取输出指纹,再在统一候选库 data/unified_bank.json 中判断模型家族和具体版本。
ModelTrace Guard 则把这套指纹能力搬进了 Codex 任务内部:
- 后台运行,不打断工作:正常检测结果静默保存到本地,主任务无需等待探针,也不会收到探针数字数组。
- 快照级检测,结果更可信:每次检测都对“同一份冻结快照”独立 fork,复测不继承其他探针的结果。
- 异常自动升级处理:首次不一致立即提醒,复测全部不一致时锁定任务并拦截后续工作工具。
- 网页仪表盘:完整历史分页、实时提醒、按任务独立管理开关。
当前随插件打包的指纹库共收录两个模型家族、13 个模型(gpt-5.4 至 gpt-6-astra,claude-haiku-4-5 至 claude-opus-5)。
安装前准备:环境要求与兼容性检查
安装前请确认满足以下两项要求:
| 依赖 | 说明 |
|---|---|
| Node.js 18+ | 插件脚本运行环境 |
| 兼容的 Codex App Server | 需支持原生快照 fork、临时任务、任务删除和异步 hooks |
安装完成后可以运行兼容性自检:
node scripts/guard.mjs doctor --fork true
doctor --fork true 会检查原生分支、后台 hooks 和清理能力,不发起推理消耗。如果系统存在多个运行时,可将 MODELTRACE_CODEX_PATH 设置为 Codex 桌面应用配套可执行文件的绝对路径。
从仓库安装 ModelTrace Guard 插件的完整步骤
在终端运行:
codex plugin marketplace add xqy2006/ModelTrace
codex plugin add modeltrace-guard@modeltrace
也可以先下载源码,在 ModelTrace 仓库根目录本地安装:
codex plugin marketplace add .
codex plugin add modeltrace-guard@modeltrace
插件位于 codex-plugin/modeltrace-guard/ 目录,完整安装与使用说明见 ModelTrace Guard 插件文档。
加载插件:在 /hooks 中审阅并信任 hooks
这是新手最容易漏掉的一步:仅安装不会开启监测。
- 安装后打开一个新的 Codex 任务加载插件。
- 在 Codex 交互输入框中输入
/hooks(注意:这不是 PowerShell 命令)。 - 找到 ModelTrace Guard,审阅并信任所需 hooks,包括同步
PreToolUse工具拦截,以及异步SessionStart、UserPromptSubmit、PostToolUse。 - 回到目标任务中请求开启监测即可。
💡 插件更新后,如果 hook 定义发生变化,需要重新审阅。hooks 配置文件见 hooks/hooks.json。
如何开启实时模型归因监测:一行自然语言命令
对目标任务直接说:
使用 $modeltrace-guard 为本任务开启监测,每隔 16–32 次工作工具调用检测,异常后复测 3 次,使用中文和英语。
start 命令会把首次检测排入队列后立即返回,由后台 hook 自动执行。常用命令一览(在插件目录运行):
node scripts/guard.mjs start --tool-min 16 --tool-max 32 --retry-count 3 --languages zh,en
node scripts/guard.mjs configure --retry-count 5
node scripts/guard.mjs status
node scripts/guard.mjs dashboard
node scripts/guard.mjs stop
核心参数说明:
| 设置 | 默认值与含义 |
|---|---|
--tool-min N --tool-max M |
16–32 次观察到的工作工具完成;N=M 时固定间隔 |
--retry-count N |
首次不一致后的额外复测次数,默认 3,允许 1–100 |
--pending-seconds N |
探针发出到评分完成的时限,默认 180 秒(不是检测间隔) |
--languages zh,en,... |
默认中英;支持 zh/en/ja/ko/fr/de/es/pt/ru/ar 十种语言 |
--expected <模型标签> |
指定比较对象;auto 跟随 Codex 元数据 |
💡 探针由 Codex 自身生成,使用其已配置的账户与模型,会消耗对应推理额度,不需要另填 API Key;评分则使用插件附带的离线指纹库。
后台如何工作:同一快照、独立 fork、测后清理
这是 ModelTrace Guard 最核心的机制,值得花一分钟了解:
- 冻结快照:由 Codex 原生
thread/fork从原任务历史创建一个持久化临时基准,基准本身不运行模型。 - 独立 fork 检测:首次探针与 N 次复测分别对同一基准的同一轮次边界发起一次性(ephemeral)fork,每次只输出一个数字数组。
- 测后清理:独立清理进程核对所属任务与轮次后通过
thread/delete删除基准,原任务的消息和目标始终不变。 - 离线评分:后台执行器读取结果、关闭临时进程后离线评分,评分核心来自 static/fingerprint-core.js。
由于正常检测在后台完成,不要在任务里去手动生成、粘贴探针数字——插件明确禁止直接向受监测任务提交数字,这也会破坏检测有效性。
异常处理流程:提醒、复测与任务锁定
当检测结果与预期模型不一致时,插件按如下策略升级处理:
- 首次不一致:立即写入提醒,要求智能体先告知“预期 X,指纹第一候选 Y”,再确认已告知,随后进入复测。
- 复测阶段:后台连续完成 N 次复测(原任务暂停工作)。其中任一次相符则本组不触发停止,但异常记录保留。
- 全部不一致:任务被锁定,
PreToolUse拒绝后续受支持的工作工具,只允许状态查询、告知确认、停止和用户授权恢复等管理命令。 - 恢复方式:停止监测、确认提醒或换模型都不会自动解除锁定,必须由用户明确要求后执行
resume --halt <停止ID>。
提醒通道有两条:网页仪表盘通过带鉴权的实时事件流接收(可开启浏览器桌面通知),以及智能体在 Codex 内的主动告知。相关脚本见 scripts/alerts.mjs。
用网页仪表盘管理监测与查看历史
运行以下命令打开本地仪表盘:
node scripts/guard.mjs dashboard
仪表盘按任务区分监测状态(不按工作目录合并),能力包括:
- 任务开关、配置修改(间隔 16–32 次、复测次数等)与停止控制;
- “完整历史”分页查看已停止任务的历史记录;
- 实时提醒与可选浏览器系统通知。
注意:打开页面或选择任务不会开启探测;关闭网页也不会停止任务监测,两者相互独立。完整本地网址携带访问凭证,请勿公开。
数据保存位置与注意事项
- 数据默认保存在
~/.codex/modeltrace-guard,可用MODELTRACE_GUARD_DATA覆盖;完整样本与已确认提醒在_history中,可从网页翻页查看。 - 临时 fork 基准可能短暂出现在任务列表中,请勿把它用于工作。
- 检测结果反映的是 fork 请求的输出特征,属于参考库内的指纹相似性比较,不是后端身份认证;未收录模型仍会被归到最相似的现有候选。
- 插件自动化测试覆盖协议、后台并发、同快照复测、清理边界与告警拦截等场景,见 codex-plugin/modeltrace-guard/tests/。
常见问题快速解答
Q:安装插件后为什么没有开始检测?
A:监测需要手动开启,且必须先完成 /hooks 的审阅与信任。安装本身不启动任何探测。
Q:探针会消耗多少额度? A:探针由 Codex 自身生成并消耗对应推理额度;评分和页面刷新不消耗模型额度。
Q:改配置会清空历史吗? A:不会。修改设置不清空历史,正在进行的复测组保持创建时的配置。
Q:检测出错算“不一致”吗? A:不算。缺失、无效、超时或中断均不计为不一致,只会记录为覆盖缺口。
📌 最后提醒:测试结果仅供参考,并非判断模型的决定性证据。若待测模型不在指纹库中,任何归因结果都有可能出现。