Cover

在不破坏对话的前提下，将敏感值挡在 LLM 请求之外。

安装 · 快速开始 · 策略 · 监控 · Pi / OMP · 安全边界

Cover 是适用于 Codex、Claude Code、Cursor、SDK 及其他基于 HTTP 的 AI 客户端的本地隐私代理。它扫描出站 JSON，在本地替换匹配的值，并在 JSON 和流式响应中恢复可逆替换。LLM 收到的是受保护的值，而代理可以继续使用原始值。

Cover 以透明反向代理的方式运行，提供策略驱动的替换、确定性伪名、操作检查、Codex 支持以及严格的故障处理。它旨在保持本地化、可观测，并明确说明哪些内容无法检查。

flowchart LR
    A["Agent"] -->|"JSON request"| C["Cover<br/>detect · transform · enforce"]
    C -->|"protected request"| L["LLM or router"]
    L -->|"JSON or SSE response"| C
    C -->|"restored response"| A

亮点

安装

安装程序会克隆 Cover，使用 Go 构建它，将其安装到 ~/.local/bin/cover，配置选定的客户端，并启动代理。

curl -fsSL https://raw.githubusercontent.com/DavidCarliez/cover/main/scripts/install.sh | bash

要求：git 以及 go.mod 中声明的 Go 版本。

预构建的 Linux、macOS 和 Windows 归档及其校验和可从 GitHub Releases 获取。

如需非交互式安装：

COVER_AGENTS=openai,claude \
  curl -fsSL https://raw.githubusercontent.com/DavidCarliez/cover/main/scripts/install.sh | bash

git clone https://github.com/DavidCarliez/cover.git
cd cover
go build -o cover ./cmd/cover
install -m 0755 cover ~/.local/bin/cover

GOOS=linux GOARCH=arm64 go build -o cover-linux-arm64 ./cmd/cover
GOOS=windows GOARCH=amd64 go build -o cover.exe ./cmd/cover

快速开始

cover init             # write ~/.config/cover/config.yaml
cover start --detach   # run in the background
cover doctor           # verify the local setup
cover test             # local redaction round trip, no network call
cover monitor          # watch privacy-safe request metadata

cover init 会提示输入 OpenAI、Anthropic 或自定义上游。完整配置记录在 configs/config.example.yaml 中。

命令参考

停止 Cover 不会改变客户端配置。如果客户端仍指向 Cover，则在 Cover 重新启动或客户端重新指向其直接提供商或路由器之前，连接将失败。

隐私策略

内置正则检测涵盖 AWS 和 GCP 密钥、GitHub、GitLab、Slack、Stripe 和 Anthropic 令牌、私钥块、JWT、显式通用密钥赋值、电子邮件、SSN、信用卡、电话号码和 IBAN。裸的 OpenAI sk-... 值刻意不作为专用的内置类别。如果你的环境需要，请定义显式规则。

规则位于 ~/.config/cover/config.yaml 中的 rules 下。选择器可以是正则表达式、builtin_* 检测器或 JSON 对象键列表。

rules:
  password_fields:
    keys: [password, passwd, pwd, passphrase, user_password, database_password]
    category: password
    action: pseudonymize
    generator: password
    priority: 220

  ipv4_addresses:
    detector: builtin_ipv4
    category: ip_address
    action: pseudonymize
    generator: ipv4
    priority: 100

  customer_name:
    pattern: '(?i)\bNIKE\b'
    category: customer
    action: pseudonymize
    generator: alias
    priority: 80

  forbidden_secret:
    pattern: '(?i)secret\s*[:=]\s*(?P<value>[^\s,;]+)'
    action: block
    priority: 200

键选择器保护完整的字符串值。例如，{"password":"admin"} 会被保护，而不会将无关的 {"username":"admin"} 视为密码。命名的 (?P<value>...) 组可以让正则表达式只替换捕获的值。

伪名生成器：ipv4、ipv6、hostname、domain、fqdn、email、username、password、secret、uuid、url 和 alias。

规则在启动时进行验证。无效的选择器、表达式、动作、生成器或捕获组会阻止 Cover 启动。检测器错误、映射耗尽、格式错误的 JSON、压缩正文和显式阻止不会回退为转发原始请求。

稳定的伪名与可逆映射

Cover 以仅所有者权限创建 ~/.config/cover/pseudonym.key。HMAC-SHA-256 会在会话和重启之间为同一原始值推导出相同的伪名。不同的安装会产生不同的伪名。

该密钥无法恢复原始值。恢复使用仅保存在进程内存中的有界映射。映射按 X-Cover-Session 隔离，在配置的 TTL 之后过期，并在隔离请求完成时删除。只有当稳定的伪名连续性重要时才需要备份该密钥。

检查、诊断与监控

预览而不发送

cover inspect request.json
cover inspect request.json --session demo

报告包含转换后的请求、匹配的规则、类别、动作、警告和阻止状态。它不会发送网络请求，也不会打印可逆映射。

检查安装

cover doctor
cover doctor --json

Doctor 会验证配置、监听器策略、限制、伪名密钥、脱敏往返、上游环路保护、守护进程、故障关闭行为、审计日志、环境路由、Codex 提供方以及 Codex 请求压缩。其实时探测会在本地被拒绝，且不消耗模型令牌。

默认安全监控

cover monitor
cover monitor --follow=false -n 50
cover monitor --json

默认监控只显示允许列表中的元数据：时间、HTTP 状态、转换次数、字节数、延迟、类别和通用错误。审计日志绝不包含请求或响应正文、匹配值、映射、路径、查询或上游凭据。

显式敏感实时视图

cover monitor --show-content
cover monitor --show-content --once
cover monitor --show-content --json

此可选视图显示每个捕获的原始值和替换值，随后显示交给上游传输层的精确转换后 JSON。它仅实时存在，从不加入审计日志。捕获从经过身份验证的本地查看器连接时开始，并在其断开时停止。该流仅限回环，使用从安装密钥派生的令牌，并会断开慢速查看器。

[!WARNING] 此终端输出为敏感内容。请勿在共享终端、录制的会话、CI 日志或支持记录中使用 --show-content。

连接客户端

Cover 会将请求方法、路径、查询和标头转发到配置的上游。现有提供商身份验证仍然有效，因为 Cover 不会重写身份验证标头。

Codex 与 Codex Router

Codex 使用 Responses API。在 ~/.codex/config.toml 中添加用户级提供商，并禁用请求压缩，以便 Cover 检查正文：

model_provider = "cover"

[model_providers.cover]
name = "Cover"
base_url = "http://127.0.0.1:8317"
wire_api = "responses"
requires_openai_auth = true
supports_websockets = false

[features]
enable_request_compression = false

这些键遵循官方 Codex 配置参考。如果 [features] 已存在，请将该设置添加到该表中。对于从环境读取令牌的路由器，请将 requires_openai_auth 替换为 env_key = "YOUR_ROUTER_KEY_ENV_NAME"。

保持 Cover 的 upstream 指向真实路由器 URL。以 configs/codex-router.example.yaml 为起点。所选模型可以是 OpenAI、Anthropic、Gemini、DeepSeek 或其他模型，因为 Cover 作用于路由器的通用 JSON 流量。

Responses API 的 encrypted_content 字段是不透明的，并且经过加密验证。Cover 在请求扫描和响应恢复期间保持它们不变。

Claude Code、SDK 及其他客户端

export ANTHROPIC_BASE_URL=http://127.0.0.1:8317
export OPENAI_BASE_URL=http://127.0.0.1:8317/v1

Claude Code 使用第一种形式。兼容 OpenAI 的 SDK 和客户端通常使用 /v1 形式。安装程序可以持久化这些设置，cover env 会为安装期间选定的客户端打印导出项。

SDK 构造函数可以直接设置相同的 base URL：

client = OpenAI(base_url="http://127.0.0.1:8317/v1", api_key=os.environ["OPENAI_API_KEY"])
client = anthropic.Anthropic(base_url="http://127.0.0.1:8317", api_key=os.environ["ANTHROPIC_API_KEY"])

Cursor 和其他应用程序在暴露 API base URL 设置时可以使用相同的端点。使用 cover doctor 或 cover monitor 确认路由。

Pi 与 Oh My Pi

官方 harness 扩展允许从 Pi 或 Oh My Pi 控制 Cover，同时将隐私引擎保留在本地 Go 代理中：

pi install npm:cover-harness
# or
omp plugin install cover-harness

只配置必须经过当前 Cover 上游的提供方：

/cover providers openai-codex,deepseek=/
/cover on
/cover doctor

OpenAI 系列提供商默认使用 /v1 代理路径。=/ 为 DeepSeek 等自行添加请求路径的传输层选择代理根路径。使用 /cover status、/cover start、/cover stop 和 /cover monitor 进行正常操作。/cover off 恢复直接提供方路由。

保护是故障关闭的：启用时，配置的提供商在 Cover 守护进程不可用的情况下仍指向 Cover，因此请求会在本地失败，而不会绕过代理。扩展状态是私有的，并保存在 ~/.config/cover/harness.json 中。

同一软件包也出现在 Pi 软件包库 中。OMP 用户还可以将此仓库添加为市场：

omp plugin marketplace add DavidCarliez/cover
omp plugin install cover-harness@cover

可选本地 LLM 检测器

正则表达式和键感知规则无法识别每个名称、地址、客户 ID 或内部代号。Cover 可以运行一个小型本地 llama.cpp 模型作为额外的语义检测器。

cover models pull
cover models status
cover restart

默认模型是 Qwen2.5-0.5B-Instruct，约 490 MB 的 Q4 GGUF 格式。Cover 在回环上启动 llama-server，并强制每次调用和整体请求预算。当检测器启用时，缺少二进制文件、启动失败、超时和检测器错误都会故障关闭。返回的片段必须在输入中原样出现，Cover 才会接受。

在不支持的平台上请保持此功能禁用。有关限制、批处理、并发和模型路径，请参阅 configs/config.example.yaml 中的 detectors.llm_fallback 部分。

安全边界

Cover 保护实际经过代理的 JSON 正文中匹配的字符串值。它并不声称能发现每个敏感值。

当数据出现在以下情况时，它仍可能离开机器：

• 某个已启用的检测器或规则都无法识别的值；
• 被 allow 规则覆盖的字段；
• HTTP 标头、URL 路径或查询字符串；
• 图像像素、二进制媒体或不受支持的编码；
• 非字符串的 JSON 值；
• 结构性的协议字段，例如 model、role、type、ID 以及工具或函数名称；
• 不透明的 encrypted_content，出于协议安全必须保持原样；
• 来自绕过 Cover 的客户端的流量。

内联图像处理可通过 media.images: allow、warn 或 block 配置。Cover 不检查像素，任何媒体策略都无法识别所有可能的编码。

除非显式配置 network.allow_remote: true，否则 Cover 会拒绝非回环监听器。如果 Cover 与其上游路由器运行在不同主机上，请使用 TLS 或其他可信传输，并应用单独的网络访问控制。Cover 本身不验证普通代理流量。

请求、缓冲响应、总流和每个 SSE 事件的限制约束内存使用。过大的请求返回 HTTP 413，过大的缓冲响应返回 HTTP 502，过大的流会被终止。

报告漏洞前请阅读 SECURITY.md。请使用其中描述的私有报告途径，而不要公开发布 issue。

项目

• 开发与测试：CONTRIBUTING.md
• 行为准则：CODE_OF_CONDUCT.md
• 许可证：Apache License 2.0