Clotr Guard

Clotr Guard

Clotr Guard 通过钩子检查受支持的 AI 编码助手中的提示词和文件读取。你也可以自行检查文本文件，或设置 Git 提交前检查。它使用与 Clotr 其他应用相同的本地引擎。干净的提示词会直接通过。发现中等和高风险问题时，会暂停提示词并显示问题类型及其脱敏形式。发现低风险问题时会直接通过，并在 stderr 上显示一行简短提示。默认情况下，电子邮件地址、车牌号、玩家昵称和分享链接会直接通过。在两分钟内再次发送相同的提示词即可照常发送。发现新问题时会再次暂停。

Clotr Guard 支持 macOS 和 Linux 上 Claude Code、Cursor、Gemini CLI、Codex CLI、Windsurf Cascade 和 Cline 的钩子。检查在你的电脑上运行。Clotr Guard 不会发起网络请求，也不会将文本发送到 Clotr 服务。助手获准发送的提示词仍会照常发送到该助手的 AI 服务。Guard 需要 Node.js 20 或更高版本。

在本地运行

Guard（包括其 clotr-mcp 服务）会作为 AI 客户端的子进程在你的设备上运行，并通过 stdio（标准输入和输出）与客户端通信。它不会建立网络连接，也不会存储扫描的文本。为让你可以重新发送暂停的提示词，提示词钩子会保留所发现内容的加盐指纹两分钟，但绝不会保留文本本身。MCP 将提供工具的一方称为“服务端”，这是因为它在协议中的角色如此，而不是因为它运行在远程机器上。

稳定版和预览版

稳定功能会在每次更改时进行测试，并会按照本页所述的方式持续运行。预览功能也会经过测试，但仍可能发生变化，具体原因见表格下方。

功能	状态	测试
在 Claude Code、Cursor、Gemini CLI、Codex CLI、Windsurf Cascade 和 Cline 中检查提示词	稳定	guard.test.js
在两分钟内重新发送已暂停的提示词	稳定	guard.test.js
在 Claude Code、Cursor、Gemini CLI、Windsurf Cascade 和 Cline 中检查文件读取	稳定	guard.test.js
各文件读取检查拒绝访问机密文件	稳定	guard.test.js
在 Claude Code 和 Cursor 中检查 MCP 工具调用	稳定	guard.test.js
在 Claude Code 和 Cursor 中检查 Shell 命令	预览	guard.test.js
setup 和 remove，支持 --project 和 --dry-run	稳定	guard.test.js
在 macOS 和 Linux 上使用 Cline 钩子	稳定	guard.test.js
check、commit-check 和 Git 提交前钩子	稳定	guard.test.js
clotr-mcp（或 clotr-guard mcp）及其三个工具	预览	mcp.test.js
助手技能	预览	guard.test.js
不发起网络请求	稳定	rules.test.js

Shell 检查目前是预览版，因为它能识别通常用于输出文件或环境变量的方式，但不认识的命令仍可能输出其中的内容。clotr-mcp 仅在助手决定调用时运行，其工具也可能随着助手的使用而变化。该技能是新功能，而且每个助手都会在自己的文件夹中查找技能。

安装

全局安装：

npm install -g clotr-guard

通过 npx 运行时，钩子设置和 clotr-mcp --print-config 会停止运行，并提示你先全局安装 Guard。MCP 服务是唯一可以直接通过 npx 运行的部分，命令为 npx -y clotr-guard mcp。

从克隆的仓库安装

在仓库根目录中，先运行 node tools/engine-bundle.js --out apps/guard/dist/clotr-engine.js 构建引擎包，然后运行 npm link ./apps/guard，将 clotr-guard 和 clotr-mcp 命令添加到 PATH 中。你也可以改为运行 node apps/guard/bin/clotr-guard.js。该 包由已检入的引擎文件构建，但构建产物本身不会检入仓库，因此在构建之前，每次检查都会提示 Clotr 无法检查文本。 引擎变更后请重新构建，否则 npm test 会因使用过时的副本而失败。

将 Clotr MCP 添加到助手

MCP 服务随 Guard 软件包一起提供，并使用其引擎和密钥文件规则。运行 clotr-mcp 或 clotr-guard mcp 即可启动，两者运行的是同一个服务。安装 Guard 后，打印你使用的助手对应的配置片段：

clotr-mcp --print-config claude
clotr-mcp --print-config cursor
clotr-mcp --print-config gemini
clotr-mcp --print-config codex
clotr-mcp --print-config windsurf
clotr-mcp --print-config cline
clotr-mcp --print-config vscode

将片段添加到 Claude Code 的 .mcp.json 或 MCP 设置、Cursor 的项目或用户 MCP 设置、Gemini CLI 的 ~/.gemini/settings.json 或项目 .gemini/settings.json、Windsurf 的 MCP 设置、Cline 的 MCP Servers 设置 或 CLI 的 ~/.cline/data/settings/cline_mcp_settings.json、VS Code 的 servers 下的 .vscode/mcp.json，或 Codex CLI 的 [mcp_servers.clotr] 下的 ~/.codex/config.toml。 Gemini CLI 的 MCP 指南介绍了其 mcpServers 设置。

若要跳过全局安装，可改为让助手通过 npx 启动；服务器首次启动时，npm 会将 Guard 下载到缓存中：

{
  "mcpServers": {
    "clotr": { "command": "npx", "args": ["-y", "clotr-guard", "mcp"] }
  }
}

该服务通过标准输入和输出在这台计算机上运行。只有助手调用它时，它才会执行检查，并返回发现类型和掩码形式。 include_personal_details 会向 check_text 和 clean_text 添加个人详细信息；无论是否启用此选项，凭据都会接受检查。

为助手提供 Clotr 技能

软件包中包含一个面向编码助手的技能文件， skills/clotr/SKILL.md。该文件会告知 助手：Clotr 阻止某项操作时，应告诉你阻止了什么，并将选择权留给你，而不是尝试其他方式来获取相同的文本。文件还说明了如何调用 MCP 工具。将 skills/clotr 文件夹复制到 Claude Code 使用的 ~/.claude/skills/clotr，或复制到 Codex CLI、Gemini CLI 和 Cursor 使用的 ~/.agents/skills/clotr。已安装的副本位于 npm root -g 输出的文件夹下的 clotr-guard/skills/clotr 中。

设置钩子

为你使用的每个助手运行一条命令：

clotr-guard setup claude
clotr-guard setup cursor
clotr-guard setup gemini
clotr-guard setup codex
clotr-guard setup windsurf
clotr-guard setup cline
clotr-guard setup git

这些命令会将提示词钩子添加到用户设置中，并在支持时添加文件读取钩子。在项目目录中运行命令并加上 --project，即可改为将钩子添加到该项目的设置中。使用 --dry-run 可预览变更。运行 clotr-guard remove <tool> 可移除 Clotr 的钩子，或添加 --project 以移除项目钩子。写入变更之前，Clotr 会在现有设置文件旁保存一份副本，并在文件名末尾加上 .clotr-guard.bak；你自己的 .bak 文件不会受影响。setup git 会在当前仓库中安装本地 pre-commit 钩子；remove git 会将其移除，或恢复之前存在的钩子。 Claude Code 使用 ~/.claude/settings.json 和其 UserPromptSubmit 钩子。Cursor 使用 ~/.cursor/hooks.json 和 beforeSubmitPrompt。Gemini CLI 使用 ~/.gemini/settings.json 和 BeforeAgent。Codex CLI 使用 ~/.codex/hooks.json 和 UserPromptSubmit。Windsurf Cascade 使用 ~/.codeium/windsurf/hooks.json、pre_user_prompt 和 pre_read_code；项目配置使用 .devin/hooks.json，或者在 .windsurf/hooks.json 是当前启用的旧版文件时使用它。Cline 使用 ~/Documents/Cline/Hooks/ 中不带扩展名的可执行钩子，以及其 UserPromptSubmit 和 PreToolUse 事件；项目配置使用 .clinerules/hooks/。在 Cline 中，请在 Feature Settings 中开启 Enable Hooks。Cline 的钩子指南列出了支持的 事件和平台。Cline 钩子仅支持 macOS 和 Linux。其他项目设置文件是在当前目录中的 .claude/settings.json、 .cursor/hooks.json、.gemini/settings.json 和 .codex/hooks.json。

默认情况下，提示词、文件读取和提交检查不会检查个人详细信息，但仍会检查凭据。要将个人详细信息纳入检查，请在 Guard 钩子配置或 commit-check 中添加 --personal-details。内部网络地址或主机名在此处也算作个人详细信息。启用此选项后，Guard 会用简短的一行说明检测到的内容，但仍会放行提示词、读取或 提交操作，因为向助手说明自己的服务器属于日常工作。

提示词钩子只检查每个工具发送给它的提示词字段。Claude Code 还会检查 mcp__ 工具参数，Cursor 则会检查 MCP 参数和 Shell 命令。这些检查会拦截凭据以及中危或高危发现，并在工具支持询问时让你决定是否继续。Bash 和 Shell 钩子会在命令、常见的 环境转储，以及可能输出机密文件的文件读取器中查找凭据。它们使用与读取和提交相同的机密文件规则，不会扫描普通命令词。文件读取钩子会检查 Claude Code 的 Read、Cursor 的 Agent 文件 读取、Gemini CLI 的 read_file、Windsurf Cascade 的 pre_read_code 和 Cline 的 PreToolUse。二进制文件和文件夹会直接放行，不显示消息。以 UTF-16 保存的文本（无论是否带字节顺序标记）以及采用较旧单字节代码页的文本，都会像其他文本一样接受检查。较大的文本读取只检查前 256 KiB，并会提示其余部分未经检查。读取钩子只显示发现类型和脱敏后的形式。所有工具都会拒绝读取机密 文件，并向助手说明原因，但不会向你发出提示。在 Claude Code 中，读取包含凭据的普通文件时会询问是否允许读取。其他工具会停止读取，因为再次读取将由助手而不是你发起，因此再次读取同一文件永远不会让其通过。Claude Code 还会获得一个 Bash 钩子，用于检查会输出机密文件或转储环境变量的普通命令。Gemini CLI 默认也会加载 .env 文件。运行 setup gemini 后，Clotr 会说明如何在 Gemini 的 settings.json 中通过 advanced.ignoreLocalEnv 关闭此功能；Clotr 不会修改该设置。钩子发现的内容不会在消息中包含完整值。在 Windows 上，Clotr 会将重复记录保存在 %LOCALAPPDATA%\Clotr\guard；其他系统则使用各自的用户应用程序数据文件夹。该记录是本地纯文本状态，同一计算机帐户或其进程可以读取，且 Guard 不会同步它。其中保存随机盐、发现项的加盐指纹以及首次警告的时间。Clotr 不会保存提示词文本或文件内容。如果 Clotr 在检查可读取的输入时遇到内部错误，Guard 会放行该操作，并显示提示说明输入未经检查。Guard 会拦截无法读取的输入，包括格式错误的钩子输入和超出大小限制的文本。Claude Code、Gemini CLI 和 Codex CLI 对每次检查的时限均为 15 秒。

搜索结果

读取钩子还会检查会返回匹配行的搜索：Claude Code 的 Grep 仅限 output_mode: "content"，Gemini CLI 的 search_file_content 和 grep_search、Cline 的 search_files，以及 Gemini 的 read_many_files。Claude 的 files_with_matches 和 count 模式仅返回路径或计数，因此会放行。Guard 会检查搜索路径和包含文件的 glob，然后最多遍历 2,048 个条目或总计 250 毫秒，并跳过 .git 和 node_modules。Ripgrep 和 Git 可达性探测共用相同的时间限制。如果达到限制，搜索会放行，Guard 会向 stderr 写入提示。

Guard 会遵循这些工具的过滤规则，判断找到的文件是否可以返回：

• Claude Code 的 Grep 会启用隐藏路径运行 ripgrep；但 ripgrep 的忽略规则仍然适用。Ripgrep 的常见问题介绍了其忽略文件行为。
• Cline 的 search_files 调用 ripgrep 时不带 --hidden，因此会跳过 .env 等隐藏路径，同时也会跳过 ripgrep 通常忽略的路径。如果 ripgrep 不可用，Cline 的备用方案会使用扩展名允许列表，并跳过没有扩展名的点文件。请参阅 Cline 的搜索执行器。
• Gemini 的内容搜索会先尝试 git grep --untracked，这会跳过被 Git 忽略的未跟踪文件，但可以搜索已跟踪文件；其系统 grep 备用方案则可能包含隐藏文件和被忽略的文件。names_only 仅返回路径，而 exclude_pattern 会过滤匹配行，而非文件名。请参阅 Gemini 的 grep 工具。
• Gemini 的 read_many_files 使用 glob 模式，并包含点文件。其默认排除项包括 .env、常见开发目录和二进制格式。默认情况下，它会遵循 .gitignore 和 .geminiignore；设置 useDefaultExcludes: false 或停用忽略过滤，可能会使文件变得可访问。请参阅 Gemini 的多文件读取器 和其默认排除项。

当 Guard 停止内容搜索时，其消息会指出机密文件，并给出一个可将其排除在外的文件 glob 示例。

使用 --min-severity low、medium 或 high 搭配 check、setup、hook 或 read，即可更改停止阈值。默认值为 medium。

自行检查文本

传入文件，或通过标准输入传递文本：

clotr-guard check prompt.txt
type prompt.txt | clotr-guard check --json

该命令会逐行输出经过掩码处理的发现结果；如果发现达到或超过最低严重级别的内容，则返回 1。--json 会输出结果对象，包括判定结果和经过掩码处理的发现内容。如果没有发现任何内容，命令会在终端中输出“Nothing found.”；如果输出被发送到其他程序，则不会输出任何内容。超过 1 MiB 的文件会返回与 Clotr 无法检查文本时相同的简短错误。

检查暂存的 Git 更改

提交前，运行 clotr-guard commit-check 检查暂存的更改。它会检查暂存差异中的新增行，以及暂存的机密文件名。即使 Git 忽略了暂存的机密文件，也会阻止提交，因为它是通过强制添加才进入暂存区的；请将它从提交中移除。凭据检测结果会显示带引号的文件名、行号、类型和经过掩码处理的值。Git 会将以 UTF-16 保存的文件视为二进制文件，因此 Clotr 会从暂存区读取该文件，并检查上次提交中没有的行。除非添加 --personal-details，否则个人详细信息不会阻止提交。不会扫描工作副本。Git 允许使用 git commit --no-verify 跳过 Git 钩子。

Guard 会分别读取每个暂存差异。如果某个差异大于 16 MiB，它会检查新增文本的前 256 KiB，指出文件名，说明其余部分未检查，并阻止提交。请拆分更改，或不要将大型生成文件纳入仓库。如果无法读取某个文件的差异，Guard 会指出该文件名，并在检查其他暂存文件后阻止提交。只有在检查完全无法运行时（例如不在 Git 仓库中，或缺少 Git 或 Guard），才会放行提交，并提示未进行检查。

clotr-guard setup git 会安装本地的 pre-commit 钩子。如果仓库已有钩子，Clotr 会将它保存在钩子旁边，并在暂存检查通过后调用它。即使找不到 Node.js，该钩子仍会运行，并提示已跳过 Clotr 检查。使用 clotr-guard remove git 可恢复该钩子。对于 Clotr 未编写的钩子（例如你在 clotr-guard commit-check 外封装的钩子），不会做任何更改。如果钩子旁边仍留有旧备份，安装程序会停止，并要求你先将其移走。使用自定义 core.hooksPath 的仓库不会被更改。再次运行安装程序，会将钩子指向你运行安装程序时所用的 Guard。如果钩子所用的 Guard 已被移除，提交会继续进行，并提示你重新设置检查；检查无法运行时也会如此。

对于 pre-commit 框架，请将以下内容添加到 .pre-commit-config.yaml：

repos:
  - repo: local
    hooks:
      - id: clotr-guard
        name: Check staged changes with Clotr Guard
        entry: clotr-guard commit-check
        language: system
        pass_filenames: false
        always_run: true

它会运行你全局安装的 clotr-guard。

.clotrignore

对于每个钩子和 pre-commit 检查，Clotr Guard 都会读取仓库根目录中的 .clotrignore。

只有 .clotrignore 中的精确值指纹才会抑制 Guard 的检测结果。路径模式会被忽略，无法关闭对某个文件的检查。值条目绝不会包含原始值，因为该文件会被提交，而且有人可能会把真实密钥粘贴进去，以此压制警告。相反，clotr-guard ignore-value [--kind <kind>] 会从标准输入读取值（绝不作为参数传入，因此不会留在 shell 历史记录中），并追加 fingerprint: <salted SHA-256>；每个仓库各自的盐值保存在 .clotrignore 本身中，格式为 salt: <random>。任何能读取仓库的人也能读取盐值，并尝试用所有可能的值匹配指纹，因此该命令会拒绝密码、个人详细信息，以及长度或字符多样性不足的值。调用方知道检测类型时，可以传入 --kind <kind>；值仍从标准输入读取。应从源文件中移除被拒绝的值，或在编辑器中忽略一次。文件中的原始值（value: ...）会被拒绝，并显示一条简短消息，提示改用该命令。

机密文件（共享的机密文件列表、.env 等）仍受 Guard 单独的机密文件规则保护。