Claude Code 会话记录到底存在哪里：工程团队管理 JSONL 文件的配置骨架与验证动作

1. 先搞清楚 Claude Code 到底把会话写到了哪里Claude Code 的会话记录也就是 transcript默认会以 JSONL 格式落在本地磁盘上。默认路径是~/.claude/projects/project/session-id.jsonl。这里的project不是仓库名而是由当前工作目录路径派生出来的Claude Code 会把路径里的非字母数字字符替换成-。session-id则是本次会话的唯一标识。这个文件里每一行都是一个独立的 JSON 对象可能是一条用户消息可能是一次工具调用也可能是一条元数据记录。官方明确提醒过这个条目格式属于 Claude Code 内部格式会随版本变化所以直接写脚本解析 JSONL 随时可能在升级后失效。更稳妥的做法是用/export导出人类可读的会话或者用claude -p --output-format json这类结构化接口拿结果。对工程团队来说真正要解决的问题不是「文件在哪」而是三件事多台开发机的历史记录怎么统一管理、敏感项目的会话要不要落盘、CI 或脚本任务怎么避免污染本地历史。这篇就围绕CLAUDE_CONFIG_DIR、cleanupPeriodDays、CLAUDE_CODE_SKIP_PROMPT_HISTORY三个配置项给出一套可复制的配置骨架和三类验证动作。2. 前置准备确认版本、目录与配置入口在动手改配置之前先把当前环境摸清楚。Claude Code 的配置分两层项目级的.claude/settings.json和用户级的~/.claude/settings.json。会话记录、插件、缓存这些属于用户级数据默认都在~/.claude下面。Windows 上~/.claude会解析到%USERPROFILE%\.claude。先确认版本和默认目录claude --version ls -la ~/.claude ls -la ~/.claude/projects如果projects目录还不存在说明你还没在这个用户下跑过会话或者已经通过CLAUDE_CONFIG_DIR把数据挪走了。接着确认当前 shell 里有没有相关环境变量env | grep -E CLAUDE_CONFIG_DIR|CLAUDE_CODE_SKIP_PROMPT_HISTORY这一步很关键。很多团队排查「session 找不到」时最后发现是某台机器上有人设了CLAUDE_CONFIG_DIR数据写到了另一个目录而文档里只写了默认路径。如果你打算把会话数据纳入团队统一管理建议先规划好目录结构。比如按账号或按项目风险等级分目录而不是所有机器都往默认 home 里塞。下面这套骨架可以直接抄。3. 可复制配置骨架三个开关怎么配3.1 CLAUDE_CONFIG_DIR把数据根目录搬到你指定的位置CLAUDE_CONFIG_DIR用来覆盖默认的~/.claude。设置之后settings、session history、plugins 都会落到这个路径下。Linux 和 Windows 上 credentials 也会在该路径下macOS 上 credentials 在系统 Keychain。在 shell 配置文件里加一行比如~/.bashrc或~/.zshrcexport CLAUDE_CONFIG_DIR$HOME/.claude-work如果你要区分工作账号和个人账号可以用 alias 隔离alias claude-workCLAUDE_CONFIG_DIR$HOME/.claude-work claude alias claude-personalCLAUDE_CONFIG_DIR$HOME/.claude-personal claude容器或 CI 场景里直接指向临时目录任务结束整体销毁export CLAUDE_CONFIG_DIR/tmp/claude-run-$(date %s)注意目录搬走以后所有依赖默认~/.claude的习惯都会失效。团队文档必须写清楚实际配置否则排查 session 丢失会浪费大量时间。3.2 cleanupPeriodDays控制本地保留周期Claude Code 默认保留本地 session transcript 30 天。这个周期通过settings.json里的cleanupPeriodDays调整默认 30最小 1设置为 0 会触发校验错误。启动时 Claude Code 会删除超过该周期的 session 文件这个设置还会影响孤儿 subagent worktree 的自动清理年龄。在用户级~/.claude/settings.json里写{ cleanupPeriodDays: 14 }按项目风险分层时可以这样考虑普通学习项目保留 30 天方便回看几周前的改动生产系统、客户私有化交付项目设短一点比如 7 天长期研究型项目想留久一点但要同步评估磁盘占用和敏感信息暴露。3.3 CLAUDE_CODE_SKIP_PROMPT_HISTORY从源头不写盘把CLAUDE_CODE_SKIP_PROMPT_HISTORY设为1后Claude Code 会跳过 prompt history 和 session transcripts 的磁盘写入。用这个变量启动的 session 不会出现在--resume、--continue或上箭头历史里适合短生命周期脚本 session。export CLAUDE_CODE_SKIP_PROMPT_HISTORY1如果只是某一次非交互运行不想写 session可以在claude -p场景下用--no-session-persistenceclaude -p 分析这段错误日志 --no-session-persistence环境变量像总闸CLI flag 像本次任务的开关。交互式开发默认保留批处理任务默认不保留带敏感输入的任务不保留。4. 三类验证动作定位、清理、跳过写入4.1 验证定位确认 session 文件真的写到了预期目录跑一次交互式会话随便问一句然后退出。接着定位文件find $CLAUDE_CONFIG_DIR/projects -name *.jsonl -newermt -5 minutes如果没有设CLAUDE_CONFIG_DIR就把变量换成$HOME/.claude。找到文件后看一眼结构head -n 3 /path/to/session-id.jsonl | jq -c keys你会看到每行是一个 JSON 对象字段随版本变化。这一步只用来确认写入位置不要把它当成稳定接口去解析。4.2 验证清理确认 cleanupPeriodDays 生效先手动造一个「过期」文件来验证清理逻辑比等 30 天现实得多。把某个旧 session 文件的修改时间改到 40 天前touch -d 40 days ago /path/to/session-id.jsonl然后启动一次 Claude Code再检查文件是否被删除ls -la /path/to/session-id.jsonl如果cleanupPeriodDays设为 14这个 40 天前的文件应该被清掉。如果没被清掉先确认你改的是不是当前CLAUDE_CONFIG_DIR下的文件以及 settings.json 是否被正确加载。4.3 验证跳过写入确认敏感任务没有落盘用CLAUDE_CODE_SKIP_PROMPT_HISTORY1跑一次非交互任务CLAUDE_CODE_SKIP_PROMPT_HISTORY1 claude -p 输出当前目录名 --output-format json记下执行前后的文件数量find $CLAUDE_CONFIG_DIR/projects -name *.jsonl | wc -l对比两次数量如果没有新增说明跳过写入生效。再用--no-session-persistence单独验证一次 CLI flag 的效果确认两种方式都能阻止本次写入。5. 本篇常见错排查报错一cleanupPeriodDays设为 0 后启动报校验错误。这个值最小是 10 不合法。想彻底不保留历史应该用CLAUDE_CODE_SKIP_PROMPT_HISTORY或--no-session-persistence而不是把清理周期设成 0。报错二设了CLAUDE_CONFIG_DIR但--resume找不到历史。大概率是启动 Claude Code 时环境变量没生效或者不同终端里变量值不一致。用env | grep CLAUDE_CONFIG_DIR确认再检查projects目录下有没有对应 project key。报错三脚本解析 JSONL 在升级后字段对不上。这是预期行为。entry format 是内部格式会随版本变化。自动化流程应该改用claude -p --output-format json或stream-json需要逐条事件时读 hooks 或 status line 输入里的transcript_path。报错四以为删了 UI 历史就等于清了本地文件。本地 transcript 有自己的路径和保留周期默认明文保留 30 天。安全清单里要单独列这一项不能只依赖界面操作。报错五CI 里跑了 Claude Code本地历史被污染。在 CI 脚本里默认加上--no-session-persistence或者整个 job 设CLAUDE_CODE_SKIP_PROMPT_HISTORY1。需要审计时再单独保留并配合cleanupPeriodDays控制周期。6. 把会话管理接进你的日常工具链配置改完之后建议把验证动作固化成团队脚本而不是靠记忆。比如在仓库里放一个scripts/check-claude-session.sh每次环境变更后跑一遍确认目录、保留周期、跳过写入三个开关都符合预期。如果你需要统一管理多台开发机的 API 访问和密钥可以在 TaoToken 的 API Keys 页面集中生成和管理密钥接入文档里有各语言的最小示例方便把 Claude Code 的调用接到现有工具链里。想先验证模型行为再决定怎么配可以直接在模型对话里试一轮长期做编码和 Agent 任务的团队可以看 Coding Plan 的额度与协作方式。把会话记录治理和密钥管理放在同一套流程里后面排查问题会省很多事。