1. 先搞清楚 claude project purge 到底动了哪些文件
Claude Code 用久了，~/.claude会变成一个很矛盾的存在：它既是让 resume、continue、rewind 顺滑运行的上下文仓库，也是明文保存工具输入输出的本地状态系统。官方文档写得很直白，应用数据里包含 plaintext，任何经过工具的内容都可能落进 transcript，包括文件内容、命令输出、粘贴文本。如果某次排错让 Claude Code 读了.env，或者某条 curl 把 Authorization header 打到了终端，这个值就可能写进projects/<project>/<session>.jsonl。
所以claude project purge解决的不是"删代码"的问题，而是"删项目级运行痕迹"的问题。它清掉的是 Claude Code 为某个项目在本机保存的 state：transcripts、task lists、debug logs、file edit history、prompt history lines，以及~/.claude.json里这个项目对应的 entry。仓库本身、Git 历史、业务代码都不在删除范围内。
这篇要交付的东西很具体：清理前后的目录对比命令、claude project purge的三种运行姿势、TaoToken 统一 Key/API 通道在settings.json与config.toml里的可复制配置骨架，以及一次能复现的验证动作。适合已经在用 Claude Code 做真实项目、准备交付或交接开发机的人。
2. TaoToken 前置：把 Key 和 API 通道先固定下来
清理本地数据之前，先把接入层固定住，否则 purge 完重新开 session 又要重新配一遍。TaoToken 在这里的角色是统一 Key 和 API 通道：官网入口是 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 基址是 https://taotoken.net/api ，Key 在控制台生成。
需要提前准备的东西不多：
- 一个 TaoToken 账号，进控制台创建 API Key，地址是 https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite
- Key 管理页在 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite ，生成后先复制到本地密码管理器，不要直接贴进项目文档
- 接入文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite ，配置字段以文档为准
这里有个顺序问题值得强调：先配好 Key，再执行 purge。因为 purge 会删掉~/.claude.json里对应项目的 entry，如果你把项目级配置写在那里，清完就没了。把接入配置放在用户级~/.claude/settings.json或独立的config.toml里，purge 不会碰它。
3. 可复制配置：settings.json 与 config.toml 骨架
Claude Code 的配置分两层。用户级~/.claude/settings.json作用于所有项目，项目级.claude/settings.json和.claude/settings.local.json只作用于当前 repo。接入相关的 Key 和 base URL 建议放用户级，避免被项目级 purge 波及。
3.1 settings.json 配置骨架
{ "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_API_KEY": "sk-你的TaoTokenKey" }, "permissions": { "deny": [ "Read(.env)", "Read(.env.*)", "Read(secrets/**)", "Read(config/credentials.json)" ] }, "cleanupPeriodDays": 14 }几个字段的作用需要说清楚。env块在启动时读取，ANTHROPIC_BASE_URL指向 TaoToken 的 API 通道，ANTHROPIC_API_KEY放你的 Key。permissions.deny是事前防线，匹配这些规则的文件会从 discovery 和 search result 里排除，read 操作也会被拒绝，这样.env和凭据文件就不容易进 transcript。cleanupPeriodDays从默认 30 天降到 14 天，让自动清理更积极一些。
注意：环境变量和 settings field 同时存在时，环境变量优先级更高。如果你在 shell 里 export 了
ANTHROPIC_API_KEY，它会覆盖 settings.json 里的值。排查接入问题时先确认这一点。
3.2 config.toml 配置骨架
如果你用的是支持 TOML 的客户端或自建工具链，可以这样写：
[api] base_url = "https://taotoken.net/api" api_key = "sk-你的TaoTokenKey" timeout_seconds = 60 [cleanup] period_days = 14 purge_on_archive = true [permissions] deny = [ ".env", ".env.*", "secrets/**", "config/credentials.json" ]purge_on_archive是个约定字段，表示项目从 active 转 archive 时触发一次 purge，具体是否生效取决于你的脚本实现。TOML 的好处是可读性强，适合放进 dotfiles 仓库统一管理。
3.3 清理前后的目录对比命令
purge 之前先拍一张快照，purge 之后再拍一张，对比才知道删了什么。下面这组命令在 macOS 和 Linux 上都能跑：
# 清理前：记录项目相关目录的文件数和总大小 find ~/.claude/projects -maxdepth 2 -type d | wc -l du -sh ~/.claude/projects ~/.claude/file-history ~/.claude/tasks 2>/dev/null # 记录 history.jsonl 里当前项目的 prompt 行数 grep -c "$(pwd)" ~/.claude/history.jsonl 2>/dev/null || echo "0" # 记录 ~/.claude.json 里当前项目的 entry 是否存在 python3 -c "import json,os; d=json.load(open(os.path.expanduser('~/.claude.json'))); print('entry exists' if os.getcwd() in d.get('projects',{}) else 'no entry')"Windows 上把~换成%USERPROFILE%，grep换成findstr。如果你设置了CLAUDE_CONFIG_DIR，所有路径都要跟着换到自定义配置目录下。
4. 验证请求：跑一次 purge 并确认接入状态
4.1 先 dry-run 预览删除计划
claude project purge ~/work/my-repo --dry-run--dry-run只打印删除计划，不动任何文件。对于客户项目、生产 repo、长期使用的主力项目，这一步必须做。计划里会列出要删的 transcript、tasks、debug、file-history 条目，以及history.jsonl里匹配的行数。
4.2 确认后执行
claude project purge ~/work/my-repo会弹一次确认提示。手动清理单个项目，这是最合适的姿势。脚本场景加--yes跳过确认：
claude project purge ~/work/my-repo --yes--all会清理所有项目的 state，而且对history.jsonl是直接删整个文件，不是按项目过滤。整机报废或转交才考虑它。-i可以按 deletion plan 逐项确认。
4.3 清理后再拍一次快照对比
find ~/.claude/projects -maxdepth 2 -type d | wc -l du -sh ~/.claude/projects ~/.claude/file-history ~/.claude/tasks 2>/dev/null grep -c "$(pwd)" ~/.claude/history.jsonl 2>/dev/null || echo "0"正常情况下，projects下该项目的目录数归零，file-history和tasks对应条目消失，history.jsonl里匹配行数变成 0。如果给定路径没有匹配到任何 state，命令会以 status 1 退出，脚本里要把它记录成"未发现可清理状态"，而不是误判为成功。
4.4 验证 TaoToken 接入是否还通
purge 完重新开一个 session，发一条最简单的请求确认接入没断：
claude -p "reply with ok" --no-session-persistence--no-session-persistence让这次请求不写 transcript，适合纯验证。如果返回ok，说明ANTHROPIC_BASE_URL和 Key 都还在生效。想更直观地看模型响应，可以走模型对话入口 https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_content=model-chat&utm_campaign=rewrite 手动发一条消息对照。
5. 本篇常见错排查
5.1 purge 后 resume 找不到历史会话
这是预期行为，不是 bug。~/.claude/projects/下的 transcript 被删了，resume、continue、rewind 自然失效。如果你还需要回溯，purge 之前先把关键 session 的 jsonl 备份到别处。Git 仍然是主线版本控制，checkpoint restore 只是额外保险。
5.2 history.jsonl 里还有残留
claude project purge是按项目路径过滤history.jsonl的匹配行。如果你在同一个项目下用过不同的路径写法（比如~/work/repo和/Users/you/work/repo），可能只匹配到其中一种。purge 前用grep确认一下实际写入的路径格式，必要时分多次 purge。
5.3 误删了 ~/.claude.json 导致登录态丢失
claude project purge只删~/.claude.json里对应项目的 entry，不会动整个文件。但如果你手工删了整个~/.claude.json，OAuth session、MCP server 配置、项目 trust 设置会一起消失。官方文档明确提醒不要删~/.claude.json、~/.claude/settings.json和~/.claude/plugins/，它们保存 auth、preferences 和 installed plugins。
5.4 配置改了但没生效
先检查环境变量优先级。shell 里 export 的ANTHROPIC_API_KEY会覆盖settings.json里的值。用env | grep ANTHROPIC确认当前 shell 有没有残留的旧 Key。另外确认CLAUDE_CONFIG_DIR是否被设置，如果设了，~/.claude/settings.json就不是实际读取路径。
5.5 purge 返回 status 1
说明指定路径没有匹配到任何 state。可能是路径拼错，也可能是这个项目本来就没产生过 Claude Code 数据。脚本里把 status 1 单独处理，不要和成功混淆。
6. 把清理动作接进你的工作流
claude project purge的定位是手术刀，不是定时扫地机。自动清理按cleanupPeriodDays在 startup 时删过期内容，默认 30 天，适合日常卫生。但当你明确知道某个项目 session 里出现过敏感内容，等 30 天不合适，这时候按项目精确清理才是对的。
我的做法是把 purge 接进项目收尾 checklist：功能合并、PR 关闭、客户资料从本机移除、项目从 active 转 archive，这几个时点各跑一次--dry-run预览，确认命中预期路径后再执行。开发机回收流程里，除了清 Git credential、SSH key、浏览器登录态，也把 Claude Code 的项目状态一起处理掉。
接入层这边，Key 和 base URL 固定在用户级配置里，purge 不会碰。需要长期跑编码任务或 Agent 工作流的，可以看 Coding Plan https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite ；接入细节和字段说明以文档 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite 为准。清理和接入这两件事分开管，互不干扰，才是能长期跑下去的状态。
