错误与稳定性

Codex 和 Claude Code 中的 Postman 插件：检查与移除

检查 Postman 是否修改了 Codex、Claude Code 和 Cursor 的编程代理配置，在保留模型提供商和认证设置的同时，移除不需要的插件、远程 MCP 连接和 Codex 保存的 Hook 信任记录。说明 11 月 5 日的回滚公告、Codex 启动 Hook 删除、两种卸载路径、残留项排查、新会话验证以及团队托管策略。

BT

BetterToken

编辑团队
3 分钟阅读
本文内容
Codex 和 Claude Code 中的 Postman 插件：检查与移除

如果 Codex 或 Claude Code 中出现了不需要的 Postman 插件，先备份配置，再卸载插件，并撤销 Codex 中保存的 Hook 信任记录。不要为了消除报错而给未经你主动选择的 Postman MCP 连接授权。恢复正常开发前，先在新会话中验证清理结果。

Postman issue #14370 中报告了这样一条典型错误：

MCP server startup failed server_name="postman"
... error: Auth required, when send initialize request

报告者还发现，执行 API 开发任务时，Codex 会反复加载 Postman 技能。这些现象值得检查，但不能据此认定 API 数据已经被上传。

最初的报告之后发生了哪些变化？

截至 2026-11-10，Postman 已宣布回滚相关改动，Codex 插件的实现也发生了变化。因此，不能把最初的安装器行为当成所有当前版本仍然存在的问题。

最初的报告涉及 macOS 上的 Postman 桌面版 12.33.4、Codex 插件 1.1.0 和 Claude Code 插件 2.0.1。

另一份涉及 12.35.1 的报告也记录了自动安装行为。不过，第二台电脑没有保存 Codex Hook 信任记录，而且 Cursor 插件在这次操作之前就已存在。

11 月 5 日，仓库成员 preethammavin 宣布 Postman 正在回滚这项改动。这条回复与此前一些没有 GitHub 仓库成员身份标记的评论不同，不能将那些早期评论直接视为官方声明。

同样在 11 月 5 日，Pull Request #149 合并，移除了安装器主动批准 Codex Hook 的行为。该 PR 还删除了 hooks/codex-hooks.json，并将 Codex 插件清单中的 Hook 声明设为 "hooks": {}。

当前 Codex 插件清单仍保留这个空的 Hook 声明，但 Postman 技能和 MCP 服务器依然存在。

这些代码改动不代表已经安装的电脑完成了清理。你仍需检查本机文件，不能假定桌面版更新会自动移除旧插件注册项和信任记录。

删除之前，如何检查 Postman 改动了哪些配置？

先关闭 Postman 和正在运行的编程代理会话。修改文件前，私下备份受影响的配置、插件安装记录和相关日志。

检查时要使用出问题的会话实际采用的配置目录。终端与桌面应用的启动环境可能不同。

下面的 Bash 命令同时考虑 CODEX_HOME 和 Claude Code 文档中的 CLAUDE_CONFIG_DIR 自定义目录设置。

它只输出包含匹配内容的文件名，不会打印配置文件内容：

codex_root="${CODEX_HOME:-$HOME/.codex}"
claude_root="${CLAUDE_CONFIG_DIR:-$HOME/.claude}"

for file in \
  "$codex_root/config.toml" \
  "$claude_root/settings.json" \
  "$claude_root/plugins/installed_plugins.json"
do
  if [ -f "$file" ]; then
    grep -ilF -- postman "$file"
  fi
done

出现匹配结果，说明这个文件值得进一步查看，但不能单凭匹配就认定 Postman 自动安装过插件。没有匹配结果，也只能说明这些特定文件没有命中。

对于报告中的 macOS 安装，重点检查 ~/Library/Application Support/Postman/logs/main.log。

原始 issue 给出了以下安装结果：

{"source":"auto-existing-upgrade","results":["claude-code:installed","codex:installed"],"installer":"script"}

将日志时间与插件安装记录的时间进行比较。两者时间吻合，比单纯在配置里搜索到 Postman 更能说明安装过程发生了什么。

在 Codex 中，分别检查原始报告提到的三个配置项：

配置项检查内容
[marketplaces.postman]来源是否为 https://github.com/postmanlabs/postman-plugin.git。
[plugins."postman@postman"]插件是否处于启用状态。
[hooks.state."postman@postman:hooks/codex-hooks.json:session_start:0:0"]保存的批准记录是否包含 trusted_hash、trusted_content_hash 或两者。

没有 Hook 信任记录，不代表插件没有安装。 后续报告就出现了插件已安装、但没有相应信任记录的情况。

对于 Claude Code，检查 ~/.claude/settings.json 中的 enabledPlugins。报告中的插件标识符为 postman@claude-plugins-official。

然后检查 ~/.claude/plugins/installed_plugins.json，找到对应插件的安装范围、版本，以及 installedAt、lastUpdated 时间。

对于 Cursor，Postman 安装器的适配代码指出了两个目录：

~/.cursor/plugins/local/postman
~/.cursor/plugins/cache/cursor-public/postman

可以从这里开始排查，但不能看到目录就断定插件正在运行。还应进入 Cursor 的插件设置，确认其实际启用状态。

完整的设置文件和日志应保持私密。其中可能包含密钥、内部路径或账号信息。需要分享证据时，只提供相关片段，并先脱敏。

如何移除插件和已保存的 Hook 信任？

先选择一种卸载方式：使用编程代理自身的命令，或者使用 Postman 的移除工具。不需要把所有卸载方式依次执行一遍。

方案一：使用 Codex 和 Claude Code 的原生命令

对于原始报告中的 Codex 插件标识符，在 Bash 中运行：

codex plugin remove postman@postman

接着确认 marketplace 的来源，并检查是否还有其他需要保留的插件使用它。

只有确认不再需要时，才运行：

codex plugin marketplace remove postman

这些操作与当前 Postman Codex 适配代码中的处理方式一致。

如果你的旧版安装使用不同的插件标识符，应以本机实际注册的名称为准，不要直接套用示例。

对于报告中安装在用户范围的 Claude Code 插件，运行：

claude plugin uninstall postman@claude-plugins-official --scope user

Claude Code 的插件命令参考区分 user、project 和 local 三种安装范围。

如果确认插件安装在 project 或 local 范围，请进入相应项目并使用正确的范围。删除团队共享的项目配置前，还应与其他成员协调。

不要为了删除一个插件而移除整个 claude-plugins-official marketplace。也不要清空 installed_plugins.json，或直接用新文件覆盖完整的用户设置。

如果当前 CLI 不支持某条命令，先查看其 plugin --help。不要因为卸载命令不可用，就改为批量删除整个配置目录。

方案二：使用 Postman 仓库记录的移除工具

Postman 的当前仓库说明提供了这条命令：

npx @postman/postman-plugin@latest remove

只有在检查过包代码、认可其执行内容，并了解会影响哪些代理后，才建议采用这条路径。

当前安装器源码要求 Node.js 22 或更高版本。

务必保留 remove 子命令。直接运行不带该子命令的安装器，并不是卸载操作。

按照文档，这个移除工具会保留项目范围内的安装。它目前针对 Codex 的实现，还会尝试撤销旧版启动 Hook 的批准记录。

但这项撤销操作必须单独验证。相关源码允许在 Hook 信任记录清理失败的情况下，整体卸载流程仍不报错。

因此，要检查工具输出的警告，并在运行结束后重新查看配置文件。

手动清理 Codex 中残留的 Hook 信任记录

如果受影响的 Codex 用户配置仍包含以下子表，应将整个子表删除：

[hooks.state."postman@postman:hooks/codex-hooks.json:session_start:0:0"]

上面的代码块用来标识需要删除的配置段，不是让你添加的配置。

删除该表头及其所属的 trusted_hash、trusted_content_hash 字段。如果两个字段都存在，应一起删除。

遇到下一个 TOML 表头就停止，不要继续删除后面的内容。

保留 hooks.state 下其他 Hook 的记录。

手动编辑时，只删除已经确认属于 Postman 的项目。保留 model_provider、model_providers、base_url、认证配置和无关 Hook。

对于 Claude Code，同样应保留无关的 env 和权限设置。

使用原生命令卸载后，确认相应插件和 marketplace 的注册项都已消失。无论使用哪种路径，都要检查 Postman 的 Hook 信任记录是否真正删除。

只看到卸载成功提示，还不能证明这三处都已清理。

检查 Cursor、独立 MCP 配置和 Postman CLI

对于从 Cursor marketplace 安装的 Postman 插件，还需要在 Cursor Settings > Plugins 中执行卸载，然后重启 Cursor。

无论使用前面哪种卸载方式，都应再次检查 Cursor 的插件列表，确认有没有残留的 Postman 安装项。

如果 MCP 报错仍然存在，先检查服务器配置，不要通过登录账号来掩盖错误。

在 Bash 中，对受影响的工具分别执行：

codex mcp list
claude mcp list

如果 Postman MCP 服务器是独立配置的，就需要单独删除。

先确认不需要的独立服务器条目确实叫 postman，然后根据工具运行 codex mcp remove postman 或 claude mcp remove postman。

删除前还应核对条目的作用范围。

相关操作见 Codex CLI 参考文档和 Claude Code MCP 文档。

注意区分独立注册的 MCP 服务器与插件自带的 MCP 连接。如果连接来自已启用的插件，应删除提供该连接的插件。

Postman CLI 也应单独检查。

在 Bash 中，type -a postman 可以显示当前命令搜索路径中找到的对应程序。

原始报告在 ~/.local/bin 下发现了 Postman 可执行文件，但不能假定所有安装方式都使用这个位置。

应根据实际安装方式，遵循 Postman 的CLI 卸载说明。

对于非 npm 安装方式，文档给出的处理方法是删除对应可执行文件。删除其他附带文件前，先确认它们的用途。

不要仅仅因为报告提到 lib 目录，就把某个可能被其他程序共用的 lib 目录整个删除。

如何在新会话中验证清理结果？

验证时不仅要看报错是否消失，还要检查配置和实际加载的组件。

首先，查看受影响工具的插件清单：

codex plugin list --json
claude plugin list --json

检查所有 Postman 注册项，包括 marketplace 后缀不同或安装范围不同的情况。

确认当前生效的 Codex 配置中，已经不存在前面指出的 Postman Hook 信任子表。

然后在一次性使用的仓库工作副本中启动新的代理会话。

检查不需要的 Postman 插件和 MCP 连接是否仍被加载。对于已删除的集成，不应再出现由它触发的 Postman 身份验证警告。

不要把旧对话中出现过 Postman 字样当作唯一判断依据。旧对话的上下文与当前安装配置是两回事。

这里可以参考 Claude Code 何时应该新建会话、何时使用上下文压缩，了解两种操作的区别。

如果新会话仍出现 Postman，继续检查实际使用的配置根目录、安装范围、残留插件注册项和独立 MCP 连接。

在确认当前生效的配置来源前，不要反复删除同一个默认配置文件。

如果你准备继续使用 Postman 桌面版，可以在下一次受控启动或更新后，再次比较配置。

如果被删除的条目重新出现，应保存新日志的时间戳和配置差异，并调查究竟是哪个进程重新创建了这些条目。

在原因查明前，团队可以暂停该桌面版本的进一步部署。

为什么 Postman 安装器能够写入 Codex 的 Hook 信任记录？

旧版安装器使用 Codex 的配置接口保存批准状态。它并不只是注册插件，然后等待用户通过交互式界面决定是否信任 Hook。

在提交 6c8e452e0f4237f4bcc0901cb1ac442dec707e49 中，Hook 注册文件使用了 SessionStart 事件，以及 startup|clear|compact matcher。

对应的启动指令要求代理在处理非简单 API 工程任务时，先加载 postman:api-engineer 技能。

这个范围明显大于用户明确要求使用 Postman 的场景。

不过，指令本身也设置了例外：纯问答和非常简单的编辑无需加载该技能，并且明确规定用户指令优先。

旧版 approvePostmanHook 实现会启动 codex app-server。

随后，它通过 hooks/list 读取当前 Hook 的哈希值，进行检查，再调用 config/batchWrite，在 hooks.state 中写入 trusted_hash。

这段源码证明安装器尝试主动批准自己的 Hook，但不能证明该操作在所有 Codex 版本上都成功。

对于某台具体电脑中已经存在的信任记录，也不能仅凭记录本身确定是谁创建的。

根据 Codex 的Hook 信任机制文档，Codex 会将 Hook 与保存的哈希值比较。

新增或发生变化的 Hook 会在等待审查和批准期间被跳过。

因此，关键的安全边界在于谁有权修改信任状态。

一个匹配的哈希值，本身不能证明用户曾亲自批准该 Hook。

实际风险发生在本地：如果某个程序具有足够权限，能够写入代理配置，就可能修改影响安全性的状态。

插件是否启用、Hook 是否可信、远程 MCP 是否已认证，是三个独立的控制点。

只清理其中一个，其他配置仍可能留在系统中。

团队如何防止第三方工具再次改写代理配置？

团队可以维护一份经过审核、已去除敏感信息的配置基线，并在工具安装和更新后进行差异比较。

将配置模板和审核过的修改纳入版本控制，但不要提交真实密钥、有效凭据或整个个人配置目录。

配置 diff 可以发现变化，却无法阻止同一用户账号下的其他进程写入文件。

如果需要强制执行限制，应采用由管理员控制、普通桌面应用无法自行改写的托管策略。

对于 macOS 或 Linux 上的 Codex，系统级配置要求文件是 /etc/codex/requirements.toml。

在现有文件的顶层加入：

allow_managed_hooks_only = true

托管配置文档说明了不同平台的部署位置。

根据配置参考，启用该选项后，Codex 会跳过用户、项目、会话和插件提供的 Hook，但仍允许托管 Hook。

对于 macOS 上的 Claude Code，在现有的 /Library/Application Support/ClaudeCode/managed-settings.json 中合并以下设置：

{
  "allowManagedHooksOnly": true
}

这是托管策略配置，不能简单视为修改普通用户偏好设置。

Claude Code 的 Hook 控制文档说明，该设置可阻止用户、项目及其他插件 Hook。

不过，设置参考也列出了重要例外：托管 Hook、SDK Hook，以及通过托管 enabledPlugins 强制启用的插件所提供的 Hook，仍可以加载。

因此，不能把这个设置理解为禁止一切 Hook 执行。

在大范围部署前，应使用团队实际运行的客户端版本验证策略效果。

还要注意，限制 Hook 不会自动卸载插件，也不会删除 MCP 连接。这些组件仍需要单独管理。

同样的审计方法也应覆盖下载的指令文件和模型提供商设置。Codex 与 Claude Code 配置审计指南提供了更全面的检查清单，帮助你识别异常改动，同时保留正常工作的模型配置。

BetterToken · 企业采购
企业专属价
支持开发票对公转账 / 支付宝 / 微信支付全系列文本 / 编程、图像、视频模型
文本 / 编程
图像
视频
专属技术支持领取企业折扣价目表 →
错误与稳定性Claude Code 403 错误排查：地区限制、网关、TLS 还是登录问题？