Claude Code 源码深度解析：CLI 运行机制与 Memory 模块配置实战

1. 从一次 CLI 启动说起Claude Code 到底在终端里做了什么Claude Code 是 Anthropic 官方推出的命令行 AI 编程助手你可以把它理解成“住在终端里的 AI 程序员”它能读文件、写代码、跑命令、搜代码库还能跨会话记住你的偏好。很多人第一次用它注意力都在“模型回答得好不好”但真正决定体验上限的其实是 CLI 的启动链路和 Memory 模块——前者决定它能不能稳定跑起来、能不能接上你自己的 API 通道后者决定它是不是每次都像失忆一样重新问你一遍项目背景。这篇聚焦两件事一是把 Claude Code CLI 从进程启动到进入 REPL 的链路拆开看二是把 Memory 模块的读写路径讲清楚并给出一份可以直接复制的settings.json骨架配合 TaoToken 统一 Key/API 通道完成一次端到端配置验证。适合已经在本地装好 Claude Code、想搞清楚“为什么我的配置不生效”“记忆到底写哪去了”的开发者。我试过在几个不同项目里反复调这套配置踩过的坑基本集中在两处环境变量和settings.json的优先级打架以及 Memory 目录权限不对导致写入静默失败。下面按启动链路、配置骨架、验证动作、排障顺序展开。2. 前置准备TaoToken 统一 Key 与 API 通道Claude Code 默认走 Anthropic 官方端点但在本地开发调试场景里用统一网关接管请求会更方便做日志、限额和模型切换。TaoToken 提供的就是这样一条统一通道一个 Key 覆盖对话与编码场景端点固定配置项少。你需要先拿到两样东西一个 API Key在控制台的 API Keys 页面创建形如sk-...只显示一次记得存好。确认接入端点https://taotoken.net/api这是所有请求的基地址不要带任何查询参数。创建 Key 的入口在这里API Keys 管理页https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite如果你还没决定用哪个模型跑 Claude Code可以先去模型对话页试一下响应速度和风格确认通道通畅再写配置模型对话体验https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite接入文档里有完整的端点说明和参数表配置前扫一眼能省掉很多试错接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite这里要强调一个原则Key 只放在本地环境变量或用户级配置文件里不要提交进 Git。Claude Code 会读取ANTHROPIC_API_KEY和ANTHROPIC_BASE_URL这类变量把它们写进 shell 的 profile 是最省事的做法。3. CLI 启动链路拆解从进程到 REPL理解启动链路排障时才能定位到具体环节。Claude Code 的启动大致分四步每一步都有对应的失败表现。3.1 进程入口与运行时Claude Code 的入口是src/main.tsx运行时用的是 Bun 而不是 Node.js语言是 TypeScript/TSXCLI 框架是 Commander.js终端 UI 用 React 加自定义的 Ink 框架。启动时它先做初始化解析命令行参数、加载配置、准备状态管理Zustand然后才进入交互式 REPL。这一步最常见的失败是运行时缺失或版本过低。如果你看到启动即崩、报模块解析错误先确认 Bun 在 PATH 里再确认版本满足要求。3.2 配置加载顺序配置不是只读一个文件而是按优先级叠加。用户级配置在~/.claude/settings.json项目级在项目根目录的.claude/settings.json本地私有配置在.claude/settings.local.json。后加载的覆盖先加载的环境变量又在更高优先级上覆盖文件配置。这就是为什么“我明明改了 settings.json 却不生效”——大概率是环境变量里有一个旧的ANTHROPIC_BASE_URL把它盖住了。排查时先env | grep ANTHROPIC看一眼。3.3 进入 REPL 与查询循环配置就绪后进入 REPL用户输入被包装成 User Message交给 QueryEngine 管理多轮状态再进入核心查询循环queryLoop()。这个循环的逻辑是准备消息压缩、裁剪→ 组装 System Prompt → 调用模型流式→ 收集工具调用 → 执行工具 → 把结果发回模型 → 重复直到模型不再调用工具。关键点是Claude Code 不是“发一条收一条”的简单程序而是一个循环执行引擎。Memory 的写入就挂在这个循环的收尾阶段——查询结束后触发 Stop Hooks其中一步就是记忆提取。3.4 Memory 在启动链路中的位置Memory 分两条注入路径。一条是行为规则作为 System Prompt 的动态部分注入告诉模型“怎么用记忆”另一条是实际的记忆内容和CLAUDE.md一起作为第一条 User Message 注入告诉模型“记忆里有什么”。两者职责不同位置也不同这点后面单独讲。4. 可复制的 settings.json 骨架下面这份骨架可以直接用把占位符替换成你自己的值即可。它同时覆盖了 API 通道和 Memory 相关的基础配置。{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的Key, CLAUDE_CODE_DISABLE_AUTO_MEMORY: 0 }, permissions: { allow: [ Read, Grep, Glob, Edit, Write ], deny: [ Bash(rm -rf:*) ] }, hooks: { Stop: [ { matcher: *, hooks: [ { type: command, command: echo \[$(date -Iseconds)] session stop\ ~/.claude/audit.log } ] } ] } }几个参数说明字段作用建议值ANTHROPIC_BASE_URL请求基地址https://taotoken.net/apiANTHROPIC_API_KEY鉴权 Key控制台创建勿提交CLAUDE_CODE_DISABLE_AUTO_MEMORY是否禁用自动记忆0表示启用permissions.allow免确认工具白名单按需收紧permissions.deny硬拒绝规则至少挡住危险删除注意settings.json里的env字段只在 Claude Code 进程内生效不会污染你的全局 shell。如果你同时在 shell profile 里设了同名变量进程内的值优先但为了排查方便建议只保留一处来源。如果你更习惯用环境变量而不是写进 JSON可以在 shell profile 里这样设export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEYsk-你的Key改完记得source ~/.zshrc或重开终端否则当前会话读不到。5. Memory 模块读写路径与验证动作Memory 是 Claude Code 最容易被误解的模块。很多人以为“记忆”是一个大文件其实它是一套目录系统按类型拆分还有索引文件。5.1 目录结构跨会话的持久记忆放在项目对应的目录下形如~/.claude/projects/项目路径标识/memory/ ├── MEMORY.md # 索引文件注入第一条 User Message ├── user_role.md # type: user ├── feedback_testing.md # type: feedback ├── project_auth.md # type: project └── reference_linear.md # type: referenceMEMORY.md是索引每行指向一个记忆文件有行数和字节上限约 200 行 / 25000 字节超了会被截断。真正的记忆内容分散在各个主题文件里每个文件带 frontmatter。5.2 单个记忆文件的格式--- name: 用户是后端工程师 description: 用户有多年 Go 经验第一次接触 React 前端 type: user --- 用户是资深后端工程师主要用 Go。 解释前端概念时用后端类比比如把组件生命周期类比为中间件链。type字段是分类标签取值user、feedback、project、reference四种。同一类型可以有多个文件每个文件聚焦一个主题。5.3 写入的两条路径路径 A主模型直接写。当你在对话里说“记住我喜欢用 tabs”主模型会直接调用 Write 写记忆文件。这条路径由 System Prompt 里的行为指令驱动。路径 B后台提取。每轮查询结束后Stop Hooks 会触发一个后台子 Agent分析最近的对话把值得保存的信息提炼成记忆文件。这条路径是自动的不阻塞你。两条路径互斥如果主模型本轮已经写过记忆后台提取会跳过避免冲突。5.4 验证记忆是否真的写进去了配置完成后做一次端到端验证。先启动 Claude Codeclaude然后在对话里明确要求它记住一件事请记住这个项目所有测试必须连真实数据库不要 mock。等它回复完成后退出会话检查记忆目录ls -la ~/.claude/projects/*/memory/ cat ~/.claude/projects/*/memory/MEMORY.md如果看到新增了一个feedback_*.md文件并且MEMORY.md里多了一行指向它的索引说明写入成功。再开一个新会话问它“这个项目的测试有什么约定”如果它能答出“不要 mock 数据库”说明跨会话读取也通了。5.5 主动召回是怎么工作的除了启动时注入的索引每轮对话开始前还有一次主动召回扫描记忆目录下所有.md文件最多 200 个把候选清单交给一个轻量模型打分选出最多 5 个最相关的文件读取完整内容后作为附件注入当前轮。已经被选过的文件会在本会话内去重不会重复注入。这意味着即使某个记忆文件没写进MEMORY.md索引只要它在目录里仍可能被召回。索引的价值是让模型快速浏览“有哪些记忆”而不是召回的硬门槛。6. 常见错误排查6.1 启动报鉴权失败现象一启动就提示 API Key 无效或 401。排查顺序先env | grep ANTHROPIC确认没有旧变量覆盖再确认ANTHROPIC_BASE_URL是https://taotoken.net/api结尾不要多斜杠、不要带查询参数最后确认 Key 没有多余空格。如果都正常去控制台确认 Key 状态是否可用。6.2 配置改了不生效现象改了settings.json行为没变。原因通常是优先级。检查是否有环境变量、项目级配置或本地配置在更高优先级上覆盖了它。用claude --help或启动时的调试输出确认实际加载了哪些配置源。6.3 记忆写了但读不到现象明明看到记忆文件生成了新会话里模型却不知道。先确认MEMORY.md索引里有没有对应条目——如果只有主题文件没有索引行启动注入时看不到它。再确认文件 frontmatter 格式正确type字段拼写无误。最后确认没有设置CLAUDE_CODE_DISABLE_AUTO_MEMORY1把整个功能关掉。6.4 记忆目录写入失败现象对话里让它记住但目录里什么都没有。检查目录权限ls -ld ~/.claude/projects/*/memory/。如果目录不存在或不可写写入会静默失败。手动创建并确保当前用户有写权限即可。另外注意后台提取受功能开关控制如果被禁用只有主模型直接写这条路径可用。6.5 上下文被压缩后记忆丢失现象长对话进行到一半模型突然“忘了”之前的约定。这是上下文压缩的正常行为。压缩会替换旧消息但记忆文件本身不受影响——它们在下一次会话或下一轮召回时仍会被加载。如果你希望某些约定在压缩后依然稳定存在把它们写进CLAUDE.md或记忆文件而不是只靠对话历史。7. 把配置固化下来长期编码场景的建议如果你打算把 Claude Code 当作日常编码和 Agent 工作流的主力工具建议把配置和记忆策略一起固化API 通道用统一 Key避免每个项目重复配。项目级约定写进CLAUDE.md个人偏好写进记忆文件两者分工明确。定期清理过期的记忆文件避免索引膨胀到被截断。用 Stop Hook 记录会话审计日志方便回溯。需要长期跑编码任务、频繁调用模型的场景可以了解一下 Coding Plan它在配额和调用方式上更适合持续使用Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite配置骨架和验证动作都跑通之后你对 Claude Code 的启动链路和 Memory 读写就有了完整的掌控。剩下的就是按项目实际情况微调权限白名单和记忆分类让它真正贴合你的工作流。