ModelTrace Guard 插件入门:在 Codex 任务内实时模型归因监测

原创2026-10-11 15:23:002,642 阅读

ModelTrace Guard 插件入门:在 Codex 任务内实时模型归因监测

ModelTrace Guard 是 ModelTrace 项目自带的 Codex 插件,用于在 Codex 任务运行过程中做实时模型归因监测:它按工具调用次数在后台 fork 任务快照进行指纹检测,正常结果静默保存,发现异常时自动提醒并复测,帮助你在长任务中随时确认“当前回答的到底是不是你预期的那个模型”。

ModelTrace Guard 在 Codex 任务内实时模型归因监测

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

这是新手最容易漏掉的一步:仅安装不会开启监测。

  1. 安装后打开一个新的 Codex 任务加载插件。
  2. 在 Codex 交互输入框中输入 /hooks(注意:这不是 PowerShell 命令)。
  3. 找到 ModelTrace Guard,审阅并信任所需 hooks,包括同步 PreToolUse 工具拦截,以及异步 SessionStart、UserPromptSubmit、PostToolUse。
  4. 回到目标任务中请求开启监测即可。

💡 插件更新后,如果 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 最核心的机制,值得花一分钟了解:

  1. 冻结快照:由 Codex 原生 thread/fork 从原任务历史创建一个持久化临时基准,基准本身不运行模型。
  2. 独立 fork 检测:首次探针与 N 次复测分别对同一基准的同一轮次边界发起一次性(ephemeral)fork,每次只输出一个数字数组。
  3. 测后清理:独立清理进程核对所属任务与轮次后通过 thread/delete 删除基准,原任务的消息和目标始终不变。
  4. 离线评分:后台执行器读取结果、关闭临时进程后离线评分,评分核心来自 static/fingerprint-core.js。

同一快照独立 fork 的指纹检测流程示意

由于正常检测在后台完成,不要在任务里去手动生成、粘贴探针数字——插件明确禁止直接向受监测任务提交数字,这也会破坏检测有效性。

异常处理流程:提醒、复测与任务锁定

当检测结果与预期模型不一致时,插件按如下策略升级处理:

  • 首次不一致:立即写入提醒,要求智能体先告知“预期 X,指纹第一候选 Y”,再确认已告知,随后进入复测。
  • 复测阶段:后台连续完成 N 次复测(原任务暂停工作)。其中任一次相符则本组不触发停止,但异常记录保留。
  • 全部不一致:任务被锁定,PreToolUse 拒绝后续受支持的工作工具,只允许状态查询、告知确认、停止和用户授权恢复等管理命令。
  • 恢复方式:停止监测、确认提醒或换模型都不会自动解除锁定,必须由用户明确要求后执行 resume --halt <停止ID>。

提醒通道有两条:网页仪表盘通过带鉴权的实时事件流接收(可开启浏览器桌面通知),以及智能体在 Codex 内的主动告知。相关脚本见 scripts/alerts.mjs。

用网页仪表盘管理监测与查看历史

运行以下命令打开本地仪表盘:

node scripts/guard.mjs dashboard

ModelTrace Guard 网页仪表盘:任务历史分页与实时提醒

仪表盘按任务区分监测状态(不按工作目录合并),能力包括:

  • 任务开关、配置修改(间隔 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:不算。缺失、无效、超时或中断均不计为不一致,只会记录为覆盖缺口。

📌 最后提醒:测试结果仅供参考,并非判断模型的决定性证据。若待测模型不在指纹库中,任何归因结果都有可能出现。

登录后查看全文
ModelTrace