1. Claude Code 到底是什么：一个带状态机的终端 Agent
1.1 它不是 IDE 插件，而是一套“会动手”的 CLI
很多人第一次听说 Claude Code，以为它和 GitHub Copilot 一样，是某个编辑器里的代码补全插件。这种理解不算全错，但会直接影响你后续的使用姿势。Claude Code 本质上是一个跑在终端里的 Agent 工作流：它由 Anthropic 官方出品，核心是一个 Node.js 编写的命令行工具，启动后在终端里给你一个交互式会话界面。你可以在里边用自然语言描述需求，它会自己读文件、改文件、执行命令、跑测试、提交代码，甚至报错之后自己看日志再修一遍。
从整体架构设计看，它由这么几层组成：终端交互层负责渲染界面和处理输入；客户端运行时负责管理会话状态、上下文、权限和工具调用；底层通过 Anthropic API 调用大模型；工具执行层则内置了读取文件、编辑文件、运行 Shell 命令等一系列能力。理解这个分层特别重要，因为后续几乎所有配置项都是在往某一层上挂东西，比如权限配置挂的是“工具执行层”，CLAUDE.md 挂的是“会话上下文层”。
我第一次用的时候有个很直观的感受：它不像传统编程辅助工具那样“你写一半它补一半”，而是像来了个新同事，你交代任务，它去干活，干完回来跟你汇报，中间每一步你都能看到它在想什么、准备执行什么命令。这种体验差异背后，是两种完全不同的产品设计思路。IDE 插件做的是“增强”，Claude Code 做的是“代替执行”——所以它才需要一整套权限、审批、回滚机制来约束自己不要乱来。
1.2 为什么把主战场放在终端，而不是编辑器里
终端是这个工具最合适的主场，原因有几个。第一，终端是所有开发工具的公共接口，不管你是写 Python、Go、Java，还是前端工程里要跑 Node 脚本，终端的抽象层级足够低，天然能覆盖各种语言和工具链。第二，终端操作本身可以被记录、被审计、被回放，Agent 执行的每个命令都能留痕，这对“让 AI 动手”这件事来说太重要了。第三，不绑编辑器意味着它可以独立存在，配合 VS Code 的集成终端、JetBrains 的 Terminal，甚至纯 SSH 远程开发都能用。
网上搜“vscode配置claude code”，能找到一堆教程，很多人以为必须装官方 VS Code 扩展才能用。实际上那个扩展只是把终端界面嵌进了编辑器侧边栏，顺手加了几个快捷按钮。Claude Code 本身是独立的，装好之后在任意终端敲claude就能启动。我日常在 VS Code 里用，但其实是因为我本来就住在编辑器里，不是为了依赖它的扩展能力。
理解这个定位的意义在于：不要把 Claude Code 当“编辑器功能”去理解，而是把它当“团队里的一个终端操作员”。它有自己的工作目录，有自己的权限边界，有自己的记忆文件。搞清楚这套架构，后面配置起来你会非常顺手。
2. 核心工作流拆解：从用户意图到文件修改的链路
2.1 Tool Use 循环：Agent 的“动手引擎”
Claude Code 整个架构的心脏，是一套 Tool Use 循环。这个循环的工作方式可以这样理解：你输入一句“帮我把 src/utils 目录下没用的 import 清理掉”，模型先生成一个回复内容，同时可能申请调用某个工具，比如Glob列出目录文件、Read读取文件内容、Edit修改文件。客户端拿到这些工具调用请求后，在本地替你实际执行，再把执行结果当作后续对话的新内容回传给模型。模型看完结果继续决策，要么继续调工具，要么给出最终答案。整个过程会一直循环，直到任务解决。
这和普通网页聊天有本质区别。网页聊天是一次“生成”，顶多多轮对话；Agent 工作流是多次“生成 + 执行 + 观察”的循环。每一次工具调用结果都是新信息，模型基于这些信息不断逼近目标。比如清理 import 这种任务，模型不可能一次改对，它需要先读文件、找到引用关系、逐个修改、再跑一遍 lint 验证，每一步都在这个循环里完成。
架构上，Claude Code 内置的工具大致分为四类：文件操作类（Read、Write、Edit）、检索类（Glob、Grep、LS）、命令执行类（Bash）和其他辅助类。文件操作和检索类工具相对安全，因为改错了能用 git 恢复；Bash 工具就要谨慎得多，它等于把整台机器的控制权交给了模型，所以架构上必须配套权限系统来约束。
2.2 上下文工程：记忆、压缩与安全边界
一个完整的 Agent 工作流跑下来，对话历史会非常长。第一次整理，模型要读十几个文件，每次读文件的内容都要进上下文，命令输出也进上下文，多轮修修改改之后，早期大量的原始内容很快就把上下文窗口占满了。Claude Code 在这里用了一套分层记忆与压缩机制，这也是它整体架构里最值得研究的部分。
粗略拆解，上下文由这么几块构成：系统提示词、CLAUDE.md 项目记忆、以及对话历史本身。对话历史里又包含用户指令、模型回复、工具调用记录、工具执行结果。Claude Code 会对早期对话做压缩：当上下文长度逼近阈值时，客户端会把一部分历史内容总结成摘要，替换掉原始内容。这就解释了为什么长会话里你让它“还记得我们最开始说的需求吗”，它未必能完整复述——不是模型变笨了，是早期细节已经被摘要化。想要高质量结果，要么在关键节点用--continue保持会话延续但尽量精简中间过程，要么干脆开新会话，把真正重要的约束写进 CLAUDE.md。
另一层设计是安全边界。Claude Code 的修改操作默认都会向用户展示 diff，只有你确认后才真正写入文件。Bash 命令则根据风险等级分级处理，低风险的直接问一次，高风险的（比如删库、全量覆盖、rm -rf这类）会加重提醒甚至要求显式授权。这个架构设计思路值得所有 Agent 产品借鉴：AI 一定会犯错，架构的职责不是阻止犯错，而是保证犯错之后可以被发现、被恢复、被追责。
3. 记忆与配置的设计哲学：CLAUDE.md、权限模型与 Skills
3.1 三层记忆：全局、项目与会话
Claude Code 的记忆体系分三层，每层的职责边界非常清晰。全局层是~/.claude/CLAUDE.md，这里写你最稳定的偏好，比如“代码里禁止使用 lodash”“注释用中文写”“Go 项目用 make 构建”之类。项目层是项目根目录下的CLAUDE.md，这里写这个项目特有的信息，比如目录结构、构建命令、测试命令、架构约定等。会话层则是当前对话的上下文，会随着交互实时更新。
这三层记忆在架构上并不是“查字典”式的按需加载，而是在每轮请求时都会随上下文注入到模型中。这就带来一个非常实际的问题：CLAUDE.md 写太长，每轮请求都会吃掉大量 token。我见过有人把整个团队 wiki 塞进项目级 CLAUDE.md，结果一次请求光记忆文件就占了几千 token，长会话没几下就触顶压缩。我的建议是，CLAUDE.md 控制在二百行以内，只写“模型不知道就无法正确工作”的信息，比如测试命令是npm test还是make test、项目里有哪些目录不能动、代码风格有哪些硬性要求。那些可以在需要时搜索的详细文档，不要往这里堆。
如果你的团队多人协作，可以把 CLAUDE.md 提交进 git 仓库，让所有成员共享一份项目记忆。这在架构层面相当于给团队沉淀了一套“AI 入职手册”，新成员用 Claude Code 的时候天然就能理解项目上下文，效果比口口相传稳定得多。
3.2 权限模型：在可回退的边界里放权
权限模型是 Claude Code 架构里最需要用户主动理解的部分。它默认提供几种运行模式：default 模式下，文件修改和命令执行都要经过确认；acceptEdits 模式会自动接受文件编辑，但命令还是要问；bypassPermissions 模式完全放权，适合在 CI 等可信环境里跑自动化任务；plan 模式则只读分析，不执行任何修改，适合让 AI 先出一份改造方案。这里插一句，我喜欢用 plan 模式做代码架构梳理，让它把一份服务端老代码从入口到存储层的调用关系捋成文档，全程不碰文件，安全性拉满。
权限配置可以持久化到settings.json。全局配置在~/.claude/settings.json，项目配置在项目.claude/settings.json，后者会覆盖前者。常用配置项包括 permissions.allow 和 permissions.deny，你可以把某些高频命令加入 allow 列表省去每次确认，同时把危险命令加入 deny 列表直接禁止。实际操作里我建议这样配：允许那些“跑错也没关系”的命令，比如npm run lint、git status、ls；对于rm、mv、git push、docker这类的，保持人工确认。
权限层级用表格看更清楚：
| 模式 | 文件编辑 | 命令执行 | 适用场景 |
|---|---|---|---|
| plan | 禁止 | 禁止 | 分析、梳理、出方案 |
| default | 每次确认 | 每次确认 | 日常开发 |
| acceptEdits | 自动接受 | 每次确认 | 批量小改动 |
| bypassPermissions | 自动接受 | 自动接受 | CI、可信自动化 |
这里要补充一个架构层面的理解：为什么 Claude Code 宁可打断用户体验也要频繁确认？因为它在执行的是不可完全预测的行为。你无法预知 Agent 下一步会跑什么命令，所以只能通过“执行前确认”把控制权保留在用户手里。理解了这点，你就不会觉得那些确认弹窗烦人了——它们本身就是安全架构的一部分。
3.3 Skills：把团队流程沉淀成资产
随着版本更新，Claude Code 引入了 Skills 机制，官方文档里也把它作为扩展能力的重要入口。简单说，Skills 是一组遵循特定格式的指令包，放在~/.claude/skills/<skill-name>/SKILL.md目录下。SKILL.md 用 Markdown 编写，带 YAML frontmatter 声明技能的名称和描述，正文则是执行流程、规则、注意事项。模型会按需加载技能，而不是每轮都强制注入。
这个设计解决了一个真实痛点：CLAUDE.md 是“全局记忆”，不适合塞太具体的操作流程；Skills 则是“按需调用的操作手册”。举个例子，我们团队把代码审查流程做成了一个 skill：先跑 lint，再检查单测覆盖率，再按一份 checklist 逐项核对安全性，最后输出结构化的 review 报告。以前这些流程要人工记住，现在 Claude Code 一句话“帮我 review 一下本次改动”就能按完整流程执行。
这就是模型架构里的“函数库”思想：CLAUDE.md 是全局变量，Skills 是函数定义，调用时才加载。善用两者，你的 Claude Code 使用体验会有质的提升。
4. Token 消耗、模型切换与安装阶段的隐藏依赖
4.1 Token 花在哪了：四个流向与省钱实操
网上经常有人问“claude code如何用省token”，这个问题要回答清楚，得先厘清 token 消耗的四个去向。第一是系统提示词，这是每次请求都会带上的固定开销，改不了，只能接受。第二是 CLAUDE.md 及各层记忆，这部分取决于你怎么写记忆文件，写多了就烧钱。第三是对话历史，随着会话变长线性增长，这也是长会话最耗 token 的原因。第四是工具执行结果，很多人忽略这一点，比如让 Claude Code 读一个几千行的配置文件，或者跑一条输出海量日志的命令，这些内容全部会进上下文。
四个去向里，后三个都是可优化的。CLAUDE.md 精简，前面已经说过；对话历史层面，可以在任务推进到阶段性里程碑时开新会话，把已完成的部分交个底再继续，避免把大量中间过程带进新任务；工具输出层面，尽量不要让 AI 直接读整个大文件，而是先用grep精确定位到行号，再用sed或Read读取特定区块。命令输出也可以用管道截断，比如npm test 2>&1 | tail -50，只把后 50 行交给模型，而不是让它接收完整输出。
4.2 本地模型与配置切换：cc-switch + ollama 的边界
搜索引擎里高频出现“claude code + cc switch + ollama”的组合，这是一个典型的“配置切换”需求。Claude Code 默认连接 Anthropic 官方 API，但它支持通过环境变量或配置文件指定 API 端点。cc-switch 这类社区工具的作用，是帮你把不同的 base_url、api_key、model 组合保存成 profile，在官方服务和自建端点之间一键切换。
我自己实际测过这个方案：用本地推理服务跑一个小模型，通过兼容层把 Anthropic 格式的请求转成 OpenAI 格式发给本地模型，Claude Code 里配置好端点之后确实能跑起来。但必须说清楚边界——本地小模型的能力和官方大模型差距明显。简单任务，比如“给这段代码加注释”“把 for 循环改写成 map”，它还勉强能应付；一旦涉及多文件联动的重构、复杂依赖分析，表现会急转直下。Claude Code 的核心能力高度依赖模型的工具调用（tool calling）水平，本地模型在这方面的稳定性和格式遵循能力普遍弱于官方模型。
所以我的建议是：本地模型适合做“不涉及敏感数据的学习和实验”，或者跑一些低风险的批量小任务；真正要动代码库、做复杂 Agent 工作流，还是用官方模型划算。另外，切换配置时务必注意 session 隔离，我踩过一次坑：切换 provider 之后继续旧的会话，模型对前面上下文的记忆出现了错乱，因为新模型看到的压缩摘要格式跟旧模型不完全一致。切换配置后最好开新会话。
4.3 安装与订阅报错的底层原因
安装方面的高频问题，我在搜索引擎里看到大量记录：“claude code powershell安装报错”“claude code安装完全指南”“vscode配置claude code”。这些问题的根源大多不在 Claude Code 本身，而在前置环境。官方提供两种常见安装路径：一是通过 npm 全局安装npm install -g @anthropic-ai/claude-code，二是用官方安装脚本。无论哪种方式，本机都需要先有可用的 Node.js 运行时，以及能正常访问远程源的网络环境。
PowerShell 下安装报错，十有八九是这两种情况：Node.js 未安装或不在 PATH 里，或者 PowerShell 执行策略限制了脚本运行。排查路径很固定：先执行node -v和npm -v确认运行时存在，再确认 PATH 环境变量包含 Node 安装目录，最后检查执行策略Get-ExecutionPolicy。网络问题则表现为下载超时、连接被重置，这种时候没有太多技巧，重试、更换网络环境、或者找一个繁忙时段避开高峰，都能提高成功率。
还有一个报错信息在热词里出现得很典型：“your organization has disabled claude subscription access for claude code”。这个报错的含义是：你登录用的 Claude 订阅套餐（比如 Team 或 Enterprise 组织账户）没有被管理员启用 Claude Code 的访问权限。这不是技术问题，是权限问题。处理路径只有两条：找组织管理员开通 Claude Code 权限，或者改用个人订阅账户/自带 API Key 的方式登录。搞清楚报错层次是解决问题的第一步——是环境层、网络层、还是账号权限层出了问题，别一上来就重装。
5. 排错实战：用架构认知代替搜索引擎
5.1 PowerShell 安装报错的完整排查链路
我拿一次真实的 PowerShell 安装报错来走一遍完整排查链路，你会看到架构认知如何直接转化为排查效率。对方反馈执行安装命令后直接报错，信息量很少。我先让他确认是否装过 Node：node -v。结果显示命令不存在。到这里，问题已经定位了一大半——Claude Code 是 Node.js 应用，没有运行时一切免谈。解决方式是安装 Node.js LTS 版本，装完重开终端再验证。
但同一类问题里，也遇到过 Node 存在但 npm 全局目录不在 PATH 的情况。这时候安装命令执行成功，但敲claude提示找不到命令。排查逻辑是：npm 全局安装的可执行文件放在特定目录（Windows 下通常是%APPDATA%\npm），这个目录需要加入 PATH。你看，这类问题的排查完全是顺着架构分层来的：运行时 → 包管理器 → 可执行文件路径 → 网络可达性，每一层验证完再往下一层，根本不需要背报错信息。
这里分享一个通用的排错建议：遇到安装类报错，先不急着复制到搜索引擎，而是脑子里过一遍这个工具的依赖链。Claude Code 的依赖链就是 Node 运行时、npm 或安装脚本、网络、认证。从底层往上逐个验证，绝大多数问题五分钟内就能定位。
5.2 配置不生效 / 会话丢失记忆
另一个高频问题是“我明明写了 CLAUDE.md，它好像没读到”。排这个错同样要回到架构设计上。CLAUDE.md 的加载发生在会话启动时，而且是从当前工作目录向上查找项目根目录下的CLAUDE.md。如果你在错误的目录下启动了claude，或者文件命名大小写不对（macOS/Linux 区分大小写，写成claude.md是无效的），配置就不会被加载。
还有一种情况是嵌套项目结构。比如你在一个 monorepo 的某个子包里启动 Claude Code，它会向上找到仓库根目录的 CLAUDE.md 并加载。但如果子包和根目录都有 CLAUDE.md，加载关系是怎样的？按照大量社区实践，Claude Code 会优先使用项目根目录的设置和记忆文件，子目录级记忆可以并存但优先级不同。我的习惯是：根目录放全仓通用的架构说明，子包如果需要额外上下文，直接在子包目录里启动并维护好相应的 CLAUDE.md，避免在全局文件里堆太多仓库结构信息。
会话层的问题则是另一个方向：对话到一半丢了“记忆”，常常不是配置问题，而是上下文压缩生效了。长会话里早期内容被压缩成摘要，模型看到的是摘要而非原始细节。如果任务需要强一致性的背景信息，用/status查看一下上下文占用，感觉快顶到上限了就及时开新会话，把必要的背景重新交代一遍，别硬撑着继续用旧会话。
5.3 工具调用失败与上下文溢出的高频问题
工具调用失败在 Agent 工作流里非常常见。最典型的是 Bash 命令执行失败：工作目录不对、命令不存在、权限不足。遇到这类问题，先看执行结果里带出的报错信息，八成能直接定位。比如 Claude Code 默认在某些情况下会在项目的根目录执行命令，如果你的脚本依赖特定目录结构，就得在命令里先cd到正确位置。
还有一个高频现象是命令输出过大导致上下文溢出。有时候模型自己会跑一个cat读取整个日志文件，几十万行输出直接把上下文塞爆。这种问题可以通过权限或善用工具调用来规避：在命令里加限制输出的管道，或者读到后面用/compact主动压缩上下文。假如已经溢出了，界面上会有明显的报错提示，最简单的处理是开新会话，把当前做的任务背景写成一段摘要贴过去继续。
工具调用超时也值得一提。Claude Code 对部分工具调用是有超时时间的，长任务（比如npm install或大型构建）可能会被中断。这种场景下，我的经验是先把命令放后台执行（比如nohup ... &），再用轮询的方式查看结果，避免工具调用一直阻塞在等待返回的状态。
写在最后的一点操作体会
用了这么久，我最深的感受是：Claude Code 值得你用“架构图”而不是“命令手册”的方式去学。它的所有配置、报错、优化手段，本质上都在回答一个问题——Agent 在哪个环节和真实世界发生了交互？CLAUDE.md 管的是“它知道什么”，权限系统管的是“它能动什么”，工具调用管的是“它怎么动手”，上下文压缩管的是“它记住多少”。每次出问题，先判断是哪个环节出了状况，再去找对应的解决手段，基本就不会手足无措。
最后分享一个小技巧：日常使用中准备几个固定模板的提示词，比如“按这套流程先梳理一遍再动手改”，配合自定义的权限配置，能让 Claude Code 的输出稳定性明显提升。记住，工具本身只是一套框架，规则和记忆都是你喂给它的，越早养成维护 CLAUDE.md、配置权限、控制上下文的习惯，这个工具在你手下的可用性就越高。
