企业官网建设流程全解析

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或~/.zshrc：

export CLAUDE_CONFIG_DIR="$HOME/.claude-work"

如果你要区分工作账号和个人账号，可以用 alias 隔离：

alias claude-work='CLAUDE_CONFIG_DIR=$HOME/.claude-work claude' alias claude-personal='CLAUDE_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_HISTORY=1

如果只是某一次非交互运行不想写 session，可以在claude -p场景下用--no-session-persistence：

claude -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_HISTORY=1跑一次非交互任务：

CLAUDE_CODE_SKIP_PROMPT_HISTORY=1 claude -p "输出当前目录名" --output-format json

记下执行前后的文件数量：

find "$CLAUDE_CONFIG_DIR/projects" -name "*.jsonl" | wc -l

对比两次数量，如果没有新增，说明跳过写入生效。再用--no-session-persistence单独验证一次 CLI flag 的效果，确认两种方式都能阻止本次写入。

5. 本篇常见错排查

报错一：cleanupPeriodDays设为 0 后启动报校验错误。这个值最小是 1，0 不合法。想彻底不保留历史，应该用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_HISTORY=1。需要审计时再单独保留，并配合cleanupPeriodDays控制周期。

6. 把会话管理接进你的日常工具链

配置改完之后，建议把验证动作固化成团队脚本，而不是靠记忆。比如在仓库里放一个scripts/check-claude-session.sh，每次环境变更后跑一遍，确认目录、保留周期、跳过写入三个开关都符合预期。

如果你需要统一管理多台开发机的 API 访问和密钥，可以在 TaoToken 的 API Keys 页面集中生成和管理密钥，接入文档里有各语言的最小示例，方便把 Claude Code 的调用接到现有工具链里。想先验证模型行为再决定怎么配，可以直接在模型对话里试一轮；长期做编码和 Agent 任务的团队，可以看 Coding Plan 的额度与协作方式。把会话记录治理和密钥管理放在同一套流程里，后面排查问题会省很多事。