问题所在

Claude Code（以及所有其他 AI 编码 CLI）会将你的完整对话历史以纯文本 JSONL 形式存储在磁盘上，Claude Code 位于 ~/.claude/projects/，OpenAI Codex 位于 ~/.codex/sessions/。你粘贴的任何内容，无论是 AWS 密钥、.env 文件还是数据库 URL，都会以明文形式无限期保留。一个典型开发者的历史记录会在数月内累积数十个密钥，通常无人察觉。

agentsweep 会扫描这些历史记录，告诉你泄露了什么，并可以就地脱敏密钥值，同时逐字节保留 JSONL 结构。它还会告诉你哪些密钥需要轮换，并为每个提供商提供正确的吊销 URL。

保护范围： agentsweep 完全本地且离线。它只读取和写入你机器上的文件，不进行任何网络调用。它消除一个攻击面：本地历史文件中的密钥。它不会影响你的 AI 提供商已经接收到的内容。当你将密钥粘贴到 Claude Code、Cursor 或任何云端代理时，该密钥在写入磁盘之前就已经经过了提供商的服务器。如果你对此感到担忧，可以考虑使用本地托管的模型（Ollama、LM Studio、OpenCode），这样任何内容都不会离开你的机器，这与 agentsweep 搭配使用效果很好。

为什么这在当下很重要

供应链攻击正在加速。在 2024 年和 2025 年，一波恶意 npm 和 PyPI 软件包（sha256-universal、shailulid、数百个仿冒包）被发现从安装它们的机器上窃取开发者凭据。它们的目标包括环境变量、.env 文件、shell 历史记录、SSH 密钥，以及现在的 AI 代理历史文件。

AI 编码助手创造了一类两年前并不存在的全新凭据暴露：

• 你将生产 API 密钥粘贴到 Claude Code 中以调试某些内容 → 它现在永远留在 ~/.claude/projects/*/conversations/*.jsonl 中
• 一个被入侵的 npm 包运行 postinstall → 扫描常见路径 → 找到你的 JSONL 历史记录 → 在一次请求中窃取 50 个 API 密钥
• 你轮换了公开使用过的密钥，却忘记了历史记录中的另外十几个
• 与此同时，你的历史记录不断增长：你请 AI 帮忙处理的每个 .env、你为调试分享的每个数据库 URL、你为一行命令粘贴的每个令牌

AI 代理历史记录保存的是完整上下文，而不仅仅是 shell 历史记录所保留的命令。攻击者已经在扫描它。agentsweep 会在那发生之前将其清理干净。

快速开始

pip install uv                  # get uv (skip if you already have it)
uv tool install agentsweep      # install — adds `agentsweep` and `asweep` to PATH
asweep                          # run — interactive menu guides you through everything

无需激活 virtualenv，也无需调整 PATH。uv tool install 会为该命令提供其独立的隔离环境。

工作原理

agentsweep 运行一个固定的 5 阶段流水线。scan 在第 3 阶段后停止；fix 则继续执行直至完成脱敏处理。

flowchart LR
    A("🔍 DISCOVER\nwalk history dirs\nstream file list") --> B("⚡ SCAN\nAho-Corasick pre-filter\n207 regex rules + BIP-39")
    B --> C{"secrets\nfound?"}
    C -- "none" --> D("✅ CLEAN\nexit 0")
    C -- "found" --> E("📋 FINDINGS\nshow report\nexit 1")
    E -. "scan only" .-> F("⚠️ ROTATE\nkeys still live")
    E -- "type REDACT" --> G("✏️ REDACT\natomic write · .bak backup\npost-write JSON validation")
    G --> H("🔑 ROTATE\nper-provider\nrevocation links")

    style A fill:#1e3a5f,color:#fff,stroke:#2d5986
    style B fill:#1e3a5f,color:#fff,stroke:#2d5986
    style C fill:#4a3728,color:#fff,stroke:#7a5c3f
    style D fill:#1a4731,color:#fff,stroke:#2d7a52
    style E fill:#4a3a1e,color:#fff,stroke:#7a6030
    style F fill:#4a2020,color:#fff,stroke:#8b3a3a
    style G fill:#1e3a5f,color:#fff,stroke:#2d5986
    style H fill:#2d1e4a,color:#fff,stroke:#5a3a8b

八项安全不变量保护每一次写入：原子替换、强制 .bak 备份、拒绝符号链接、mtime 与进程门控，以及写入后 JSONL 校验。agentsweep undo 可从备份恢复。

安装

agentsweep 是一个命令行工具，因此请将其安装到独立的隔离环境中。以下两种推荐方式都会自动完成该设置。

uv（推荐）：

uv tool install agentsweep      # install
uv tool upgrade agentsweep      # update
uvx agentsweep@latest           # or run once without installing

可选的本地加速

默认安装是便携式的，并使用 Python 内置的 re 引擎。在 具有 google-re2 wheel 的平台上，安装可选的 fast 附加组件以使用 混合引擎：

uv tool install 'agentsweep[fast]'
# or, in a virtual environment:
pip install 'agentsweep[fast]'

这仅是加速：不支持的模式、非 ASCII 语义边界情况、短字符串以及极其密集的匹配仍保留精确的 Python re 路径。如果可选 wheel 不可用，AgentSweep 仍完全可用。参见性能说明和兼容性审计。

pipx：

pipx install agentsweep
pipx upgrade agentsweep

pip 也可以，但请将其放在虚拟环境中。现代 Linux 和 macOS 会阻止 pip install 安装到系统 Python（PEP 668），而且 CLI 本来也不该装在那里：

python -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate
pip install agentsweep

你不需要 conda。它是为重型二进制和科学计算栈而存在的，而 agentsweep 是纯 Python 编写的，只有三个小型依赖项。

Android（Termux）：

pkg install python clang
pip install agentsweep

clang 包使该原生依赖能够针对 Android 的 libc 进行构建。

没有 uv？请执行 pip install uv 或参阅 astral.sh/uv。需要 Python 3.11+。

Docker

从仓库根目录构建镜像：

docker build -t agentsweep .

agentsweep 会扫描某个来源的历史根目录下的文件（例如 ~/.claude），因此请将你真实的 home 目录（或仅相关的 agent 文件夹）挂载到容器中，并将 --root 指向它。-u $(id -u):$(id -g) 可确保写回挂载目录的文件（如 .bak 备份）归你所有，而不是 root：

docker run --rm -it -u $(id -u):$(id -g) \
  -v "$HOME/.claude:/home/sweeper/.claude:rw" \
  agentsweep scan --source claude-code

对于 agentsweep fix，保持相同的挂载为读写模式，以便它可以将脱敏内容和 .bak 备份写回你真实的历史目录。

Shell 补全

agentsweep 支持子命令、标志的 Tab 补全，并会为 --source 选项动态列出源名称。

Bash

要为当前会话激活补全：

eval "$(agentsweep completion bash)"
# Or using the register-python-argcomplete utility:
eval "$(register-python-argcomplete agentsweep)"

要使其永久生效，请将 eval 行添加到你的 ~/.bashrc（或等效文件）中。

Zsh

Zsh 使用 bashcompinit 兼容层。将以下内容添加到你的 ~/.zshrc：

# Initialize shell completion if not already done
autoload -U +X compinit && compinit
autoload -U +X bashcompinit && bashcompinit

eval "$(agentsweep completion zsh)"
# Or using the register-python-argcomplete utility:
eval "$(register-python-argcomplete agentsweep)"

Fish