---
title: "安装 ModelTrace Guard 插件"
summary: "安装 modeltrace-guard@modeltrace 后，在 /hooks 审查插件钩子。探针使用已配置的 Codex 账户，会消耗额度。"
category: skills
level: intermediate
surfaces: [cli, app]
tags: ["plugins", "hooks", "ModelTrace", "Skills"]
canonical: /tips/modeltrace-guard-codex-plugin/
---

# 安装 ModelTrace Guard 插件

安装 modeltrace-guard@modeltrace 后，在 /hooks 审查插件钩子。探针使用已配置的 Codex 账户，会消耗额度。

ModelTrace Guard 用 marketplace 加 xqy2006/ModelTrace，再 plugin add modeltrace-guard@modeltrace。这是仓库里的 **Codex 任务内监测插件**，不是根目录那个 `python start.py` 开的 7860 页面。清单 `.agents/plugins/marketplace.json` 的 name 是 `modeltrace`，展示名 Modeltrace，插件 name 是 `modeltrace-guard`，本地路径 `./codex-plugin/modeltrace-guard`。官方写出的 id 就是 `modeltrace-guard@modeltrace`。

```bash
codex plugin marketplace add xqy2006/ModelTrace
codex plugin add modeltrace-guard@modeltrace
```

本地改插件时在仓库根：

```bash
codex plugin marketplace add .
codex plugin add modeltrace-guard@modeltrace
```

升级用清单名，不是仓库路径：

```bash
codex plugin marketplace upgrade modeltrace
```

需要 Node.js 18+，以及能做原生快照 fork、临时任务、任务删除和异步 hooks 的 Codex App Server。多运行时把 `MODELTRACE_CODEX_PATH` 指到桌面配套 `codex` 的绝对路径。兼容性先跑 `node scripts/guard.mjs doctor --fork true`（在插件目录；`--fork true` 不发起推理）。

0.154 起先看**当前会话**；当前会话 `/plugins` 没有再新开。IDE 扩展没有 `/plugins`。装完打开一个**新** Codex 任务加载插件，再在 TUI 输入框敲 `/hooks`——这不是 shell 命令。只审 **ModelTrace Guard**：同步 `PreToolUse`，以及异步 `SessionStart`、`UserPromptSubmit`、`PostToolUse`。哈希变了要再审。网页 Cloud 不读本机 marketplace。

不要按社交帖字面「信任所有钩子」。Codex 不会因为 `plugin add` 就静默授权命令。企业开了 `allow_managed_hooks_only` 时，插件钩子整层不跑。

开启监测对目标任务说：使用 `$modeltrace-guard` 为本任务开启监测。默认大约每隔 16–32 次工作工具调用采一次，异常后复测 3 次。也可以在插件目录跑 `node scripts/guard.mjs start`，把 `CODEX_THREAD_ID` 指到目标任务。仪表盘是 `node scripts/guard.mjs dashboard`。数据默认 `~/.codex/modeltrace-guard`，可用 `MODELTRACE_GUARD_DATA` 覆盖。

探针由 Codex **自己**生成，用已配置的账户、模型和厂商，**会花推理额度**。没有每轮或任务累计上限。正常结果静默保存，主任务不等探针。首次指纹不一致会要求智能体告知并暂停工作；额外复测全不一致时锁定任务，`PreToolUse` 拦截后续受支持的工作工具。恢复要用户明确要求后才能 `resume --halt`。结果只是参考库内的相似性，不是后端身份认证。仓库声明：未收录模型什么结果都可能出现。

配置说明：

- 不要抄 `codex plugin install modeltrace-guard@modeltrace`。动词是 `add`。
- 不要和 Braintrust 的 `trace-codex@braintrust-codex-plugins` 搞成同一份。
- 不要把 README 的 PowerShell 围栏当成唯一 shell。
- 不要一上来 `--yolo` 或 `--dangerously-bypass-hook-trust`。

改完用 `codex plugin list --marketplace modeltrace` 核对 `modeltrace-guard` 已安装。

## 来源

- [xqy2006/ModelTrace](https://github.com/xqy2006/ModelTrace)
- [ModelTrace Guard README](https://github.com/xqy2006/ModelTrace/blob/main/codex-plugin/modeltrace-guard/README.md)
- [OpenAI · Hooks](https://learn.chatgpt.com/docs/hooks)