我最早接触 Claude Code 的时候心里其实挺不以为然的——终端里跑一个 AI能比网页对话框强到哪去直到有一天它自己翻出一个三个月前改过的配置文件顺手修完 bug 还自动跑了一遍测试我才意识到这东西根本不是“聊天窗口搬到终端”而是真真切切多了一个能操作项目的同事。这篇指南之所以叫“不完全”是我没打算把它写成官方文档的中文翻译版。我想做的是把从安装、配 VS Code、接本地模型到省 token 这一路上的真实操作和踩坑记下来给同样想上手的人一条更顺的路。内容会覆盖 Claude Code 的安装下载、VSCode 插件配置、CC Switch 与 Ollama 本地模型接入、日常报错排查等高频场景适合还在观望、或者刚装完不知道从哪下手的读者。1. Claude Code 是个什么东西先说说它到底能帮你干什么1.1 它和网页聊天的核心区别只消一句话它不是另一个聊天窗口而是住在你项目里的 AI 代理。在项目根目录敲下claude它会基于当前目录里的文件和你对话。你说“帮我修一下登录接口的 bug”它不会甩给你一段修改建议而是自己去读路由文件、翻日志、找依赖然后动手改代码、跑命令、把测试结果反馈回来。你可以把它理解成一个“实习生”能力不错、干劲十足但需要你随时盯一眼过程、划好边界。它跟网页对话最大的区别在于——它手里有你的代码库也有你的终端。网页 AI 只能给“药方”它却能直接“抓药”。这个差异彻底改变了我的使用习惯以前遇到问题先复制报错信息粘贴给网页对话框现在直接让它自己去复现问题效率完全不在一个量级。1.2 我从“偶尔用”到“离不开”的三个场景我复盘了一下自己的使用记录发现频率最高的其实是下面这三类场景而不是网上常说的“自动写整个项目”。第一类在不熟悉的代码库里改东西。接手别人的项目时最头疼的是不知道入口在哪、配置文件都有什么作用。我会直接告诉它“帮我梳理一下这个项目的模块结构重点标出和用户认证相关的部分”它会先读目录、再看关键文件用几分钟时间帮我建起整个代码库的“地图”这个能力在接手旧项目时太值钱了。第二类自动化琐事。批量重命名、统一格式化、给几百个测试用例补参数这些活儿说难不难但极其消耗耐心。Claude Code 在处理这类重复性任务时几乎不会出错而且不会抱怨。第三类生成骨架代码和测试。让它照着接口文档写个 CRUD 模块或者给现有函数补单测它生成的内容基本能直接跑。这种活儿更像是“靠谱的参考实现”拿过来改改就能用。1.3 什么人适合什么人容易劝退先说适合的有命令行基础、长期泡在编辑器里、愿意折腾的开发者。硬件工程师也适用后面我会单独讲用 Claude Code 写 Verilog 的例子。再说容易劝退的完全没接触过终端的人打开黑乎乎的窗口就已经头大了以及只想“复制粘贴答案”的用户——Claude Code 的强项是动手操作如果连让它跑命令的底气都没有体验会大打折扣。新手入门之前建议先想清楚你是想让它替你干脏活累活还是只想找一个更智能的搜索引擎。这两者的期待值完全不同也直接决定了你接下来会不会骂骂咧咧地卸载。2. 安装实录从 CLI 找不到到 PowerShell 报错坑我都替你踩过了2.1 官方两条安装路线怎么选目前官方安装方式主要两种选哪个取决于你本机的环境。路线一是 npm 安装要求本机有 Node.js 18 或更高版本执行npm install -g anthropic-ai/claude-code路线二是原生安装脚本不依赖 Node 环境macOS 和 Linux 上执行curl -fsSL https://claude.ai/install.sh | bashWindows 用户现在也有官方原生安装器可以在 PowerShell 里直接跑。个人建议如果你机器上本来就有 Node 环境用 npm 最省事如果想尽可能少装依赖、少碰 Node 版本冲突选原生安装。装完先验证一下随手敲claude --version能输出版本号就是成功。我看过太多人装完不验证直接开干结果后面所有问题都分不清是环境问题还是使用问题。2.2 could not locate the claude cli on path出现频率最高这个报错是我被问得最多的一条完整提示是failed to run claude code: error: could not locate the claude cli on path。原因非常直白npm 全局安装会把可执行文件放到一个全局 bin 目录但当前终端的 PATH 环境变量里没有包含它系统自然找不到claude命令。排查就两步。先看看全局 bin 目录在哪npm prefix -g然后把输出目录加到 PATH。bash/zsh 环境下在~/.zshrc或~/.bashrc里加一行export PATH$PATH:$(npm prefix -g)/binWindows 上一般 npm 会自动把路径写进用户环境变量如果加了还不行试试用管理员身份重开一次终端或者去“系统属性 - 环境变量”里确认用户 PATH 中已经包含 npm 的全局路径。这里的底层逻辑值得多说一句安装本身通常没问题问题几乎都出在“安装到了哪里”和“系统去哪里找”这两个环节没有对齐。理解了这一点以后遇到任何“装了但命令不存在”的报错都能举一反三。2.3 PowerShell 执行策略报错怎么处理Windows 用户另一个高频现场是安装时报“无法加载文件因为在此系统上禁止运行脚本”之类的错误。这不是安装包有问题而是 PowerShell 的执行策略在拦你——它默认禁止运行来自网络的脚本。解决办法是在 PowerShell 里执行Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser这个策略的含义是本地写入的脚本可以运行从网上下载的脚本必须有可信签名对于日常开发来说是比较稳妥的折中方案不需要为了装一个工具把执行策略改成Unrestricted。还有种情况是安装脚本下载到一半就中断原因多种多样重新执行一次安装命令多数情况下就能继续。2.4 Mac 安装的权限细节Mac 上走 npm 全局安装如果 Node 是用系统自带方式装的很容易报EACCES: permission denied也就是没有目录写入权限。我自己就踩过一次。正常的解决办法有两个。一是用 nvm 把 Node 装到用户目录下再执行全局安装命令这样 npm 全局包默认落在用户目录里不再需要系统权限。二是手动把 npm 全局目录改到~/.npm-global。我不太建议直接sudo npm install -g虽然能装上但后面升级、卸载都会持续被权限问题纠缠典型的一时爽、长期痛。另一个 Mac 特有的细节原生安装脚本执行完首次运行claude时系统会弹“已阻止”提示因为 macOS 的 Gatekeeper 不认识这个刚下载的程序。处理方法是去“系统设置 - 隐私与安全性”里点“仍要打开”这一步在不少教程里都被忽略了导致很多人卡在“明明装好了却打不开”。2.5 登录、订阅与组织权限限制装好之后运行claude第一次会引导登录。官方支持两种身份一种是订阅账号走网页授权另一种是 API Key通过环境变量ANTHROPIC_API_KEY设置或者在登录流程里选 API Key 模式。如果你用的是企业发的工作账号可能会碰到your organization has disabled claude subscription access for claude code这样的提示。这不是技术故障是这个组织在管理后台关闭了 Claude Code 的订阅访问权限。遇到它别想着去绕过先问管理员能不能开通或者切回个人账号登录再不行就换 API Key 方式。我在实际中遇到过一次切到个人账号后问题直接消失。3. 把 Claude Code 嵌进 VS Code插件、桌面版与 JetBrains3.1 为什么要嵌进编辑器在纯终端里用claude虽然很爽但有个现实问题改代码要切回编辑器编辑器里看到问题又要切回终端看 AI 的输出来回切换很消耗注意力。VS Code 官方插件把 Claude Code 面板直接嵌在编辑器右侧它能读取当前打开的文件作为上下文给出的 diff 可以直接预览确认后一键应用。对比纯终端模式这种“对话、读代码、改代码”同屏完成的体验工作效率高出一大截。很多人看到“claude code desktop”和“visual studio claude code”两个词容易懵。其实桌面版就是官方做的一个带图形界面外壳的应用底子还是本地 CLIVS Code 插件也是同一个内核。所以无论用哪种外壳第 2 节的命令行安装都是前提。3.2 VS Code 插件安装与关键配置安装过程不复杂打开扩展市场搜索 Claude Code认准发布者是 Anthropic 的官方插件安装后在命令面板执行Claude Code: Login走一遍登录流程。真正需要注意的设置有三处。第一模型选择。插件里默认用的模型偏向速度和成本平衡如果你有更强需求可以在设置里切到能力更强的模型但响应会更慢、消费也会更高。第二自动执行命令的授权方式。插件选项里有一项是“是否允许 Claude 自动运行命令”我的建议是设成每次询问或按需授权尤其在你还不熟悉它行为模式的时候。等到配合默契了再放宽不迟不然它自作主张跑一个rm相关命令你哭都来不及。第三工作区信任。第一次打开某个项目时VS Code 会问你是否信任这个目录。别图省事直接“全部信任”不确定就先给最小范围确认项目来源没问题再开放。插件最终读写的是 CLI 在~/.claude/目录下生成的配置文件所以命令行模式下设过的规则它都能读到两者并不是割裂的。3.3 IDEA、PyCharm 里怎么用JetBrains 系工具目前没有官方 Claude Code 面板插件第三方插件版本参差不齐我不太推荐把核心工作流押在上面。更稳的做法是在 IDEA 或 PyCharm 里直接打开内置 Terminalcd到项目根目录运行claude。如果想要体验好一点在Settings - Tools - Terminal里把 Shell 改成 Windows Terminal保证字符集和交互渲染没问题。我的结论是VS Code 的沉浸感明显更强JetBrains 属于“能用但别指望太好用”的程度。如果你主力 IDE 是 IDEA又不想换编辑器那就在终端里老老实实用不要把时间花在折腾第三方插件上。4. 不止 Anthropic 的模型接 Ollama、DeepSeek 的实操记录4.1 为什么有人想给它换模型Claude Code 原生只认 Anthropic 的 API但很多人想接别的模型理由很现实价格、数据隐私、模型偏好。价格方面官方订阅是固定费用但 API 调用是量越大越贵数据隐私方面有些项目代码不能出内网最好用本地模型模型偏好方面有人用惯了某个开源模型不想强制切到 Claude。这些需求直接催生了“给 Claude Code 换模型”的社区方案。最常听到的组合是claude code cc switch ollama。cc switch 负责切换配置Ollama 负责跑本地模型。下面拆开说。4.2 CC Switch一键切换配置的管理工具CC Switch 是社区里的一个开源配置管理工具核心解决“我有多套 API 配置想一键切换”的痛点。它通常带一个简单的图形界面可以在里面维护多套供应商配置每套配置包括名称、API 地址、模型名、密钥。切换时它会自动改写 Claude Code 读取的环境变量或配置文件重启会话就生效。我自己维护三套配置Anthropic 官方主力质量最稳DeepSeek跑长任务和批量脚本成本低Ollama 本地隐私项目、断网调试时用。没有 CC Switch 时手工改环境变量非常容易出错尤其是配 API 地址和模型名的时候漏一个冒号都可能导致请求 404。有了它之后切换成本从“改配置 重启终端”变成“点一下”。4.3 接 Ollama 本地模型配上环境变量先在 Ollama 里拉一个代码模型我用的是 qwen2.5-coderollama pull qwen2.5-coder:14bOllama 服务默认监听11434端口。但 Claude Code 不能把请求直接发给 Ollama 的/v1/chat/completions接口因为两者的请求格式和协议规范不通用中间通常需要一层兼容网关把 Anthropic 格式的请求翻译成 OpenAI 格式再把响应翻译回去。装好适配层之后设置环境变量ANTHROPIC_BASE_URLhttp://localhost:8080 ANTHROPIC_AUTH_TOKENdummy ANTHROPIC_MODELqwen2.5-coder:14b然后启动claude用/model查看当前模型名确认已经切换到本地模型。这里必须说实话本地模型和 Claude 官方模型的编码能力差距是客观存在的尤其是复杂重构、跨多文件分析这类任务本地模型的成功率会明显下降。我建议把本地模型用在隐私敏感场景或简单任务上而不是指望它完全平替。4.4 接 DeepSeek 的性价比路线DeepSeek 这类第三方模型也可以走类似路线把 API 地址指向 DeepSeek 的接口模型名填deepseek-chat或deepseek-coder同样通过兼容网关转换协议。配置层面大致是ANTHROPIC_BASE_URL你的网关地址 ANTHROPIC_MODELdeepseek-chat实测下来DeepSeek 的响应速度尚可编码能力不如 Claude 的当家模型但优势在于便宜跑批量脚本、写测试用例这类任务性价比很香。有个坑要注意DeepSeek 对某些 Claude 专用参数不一定支持比如和思考过程相关的字段。遇到报错时可以考虑换个模型名或者查一下网关日志看看是哪个参数没被兼容适配。这块变化很快卡住时优先看日志定位而不是瞎猜。5. 省 token 的实用操作把每一分钱都花在刀刃上5.1 token 是怎么悄悄烧掉的Claude Code 每一次操作背后都是“当前对话 相关文件内容 工具返回结果”一起发给模型。一个长会话吃掉的 token远远超过在网页上连续聊半小时。烧 token 的大户有三个没完没了的工具调用、反复读大文件、历史对话越积越长。前两个是显性的第三个最隐蔽——你以为继续对话没花什么钱实际上每次请求都在把前面所有内容重新算一遍。5.2 /compact长会话的灭火器会话拉得太长上下文会爆炸。这时候在对话里输入/compactClaude Code 会把之前的对话压缩成一份摘要给上下文瘦身然后继续干活。我的习惯是每当它开始“忘记”前面讨论过的代码结构或者每修完一个独立问题就/compact一次。代价是压缩会丢掉细节所以重要结论我会在压缩之前让它先写进项目里的 TODO 或文档避免关键信息被摘要掉。5.3 .claudeignore给项目“减重”这是最容易被忽略、却立竿见影的省 token 手段。在项目根目录创建一个.claudeignore文件把不需要 AI 读取的目录和文件类型都列进去node_modules dist build .git *.log *.csv *.parquet .DS_StoreClaude Code 在扫描项目结构、搜索关键词时会自动跳过这些内容。前端项目里node_modules动辄几万个文件如果不排除掉它每次“看看项目结构”都能读出一大堆无用路径token 消耗肉眼可见地涨。这一个文件省下的资源甚至比后面其他技巧加一起都多。5.4 用权限白名单减少无效工具调用限制工具权限本质上是为了阻止模型陷入“跑命令、看输出、再跑命令”的死循环。有些任务它明明可以一次判断完成却因为权限太大反复试探各种方案每次尝试都是一笔 token 开销。我常用的启动方式是claude --permission-mode acceptEdits --allowedTools Read Glob Grep Edit这样它基本只能读代码、搜代码、改代码不能自动跑高风险命令。运行速度快了token 也烧得慢了。如果你需要让它偶尔跑构建命令可以把相关命令单独加进白名单而不是整包授权。5.5 任务拆分比压缩更治本技巧再多最治本的方式还是控制任务的边界。与其让一个超长会话干三个小时的活不如拆成三到四个短会话每个会话只聚焦一个目标干完就/clear。拆分的好处不止是省 token每个会话的上下文更干净模型对需求的把握也更准确输出质量通常更高。我现在遇到一个大需求第一反应永远是拆任务清单而不是直接把一坨需求全丢给它。6. Skills、历史记录与 CLI 命令进阶玩家的三件套6.1 Skills 机制让 AI 按你的流程干活Claude Code Skills 是官方提供的一套机制简单说把某个领域的方法、步骤、参考模板写成一个SKILL.md文件放到~/.claude/skills/或项目级.claude/skills/目录里Claude Code 遇到对应任务时会自动读取并调用这个文件按里面定义的流程干活。这个机制的价值在于它让“经验”变成了可复制的配置。比如“写 PPT”这种非典型编码任务社区里已经有人把“从大纲到生成 PPT 源码”的完整流程做成了 skillClaude Code 加载后就会按那套流程走而不是每次从零发挥。团队场景更好用。你可以把代码提交规范、接口设计文档模板做成团队专属 skill保证所有成员让 AI 干活时都遵循同一套标准。把个人的经验沉淀到 skill 文件里本质上是在给 AI 建立你的团队“军规”。6.2 对话历史存在哪怎么恢复和导出很多人担心的问题关掉终端之后之前的会话还能恢复吗答案是能。默认情况下Claude Code 会把每次会话记录以 JSONL 格式存到~/.claude/projects/目录下按项目名分子目录。想恢复某次会话重开终端运行claude --continue它会列出最近的会话供选择。也可以进入交互模式后输/resume翻历史记录。如果想把历史内容导出成可阅读的文本直接解析那个.jsonl文件就行每一行是一次请求或响应。用 jq 可以快速过滤用户输入jq -r select(.typeuser) | .message.content[]?.text ~/.claude/projects/你的项目/xxx.jsonl这个技巧在做复盘或者写周报的时候特别有用能直接还原当初和 AI 讨论问题的整个过程。6.3 我每天都会用到的 CLI 命令速查常用命令可以整理成一张速查表都是高频操作命令作用claude启动交互式会话claude --continue续接最近的会话claude --resume选择历史会话恢复claude --model启动时指定模型claude -p 问题非交互模式适合在脚本里调用/init让 AI 分析项目并生成初始化说明/clear清空当前会话/compact压缩上下文/status查看当前上下文与 token 使用情况这不是官方命令全集只是我个人天天用的那部分的浓缩。新上手的人我建议先把/compact、/status、/clear这三个摸透这套组合能解决 80% 的“越跑越慢、越跑越贵”问题其他高级命令后面再慢慢玩。6.4 不止写代码用 Claude Code 写 Verilog 的真实案例说个冷门的。我前阵子帮人做 FPGA 相关的模块Claude Code 对 Verilog 的理解超出了我的预期。让它写一个 UART 接收模块它不仅给出了可综合的代码还自动配了一个 testbench连时序约束都标得清清楚楚。用下来的方法跟写业务代码没有区别在 Verilog 项目根目录启动claude先让它读一下现有工程的端口定义和时钟约束再让它按接口生成模块。它的优势在于能结合已有的文件命名和风格来写比对着网页截图问 AI 要自然得多。这类“非典型编程任务”恰恰是 Claude Code 容易被低估的地方——它并不在意你写的是 TypeScript 还是硬件描述语言它只在意这个项目的上下文和约束。对硬件工程师来说这等于多了一个懂时序、懂综合的助手。7. Claude Code 还是 Codex别再纠结看差异选7.1 先明确它俩是同一类产品Codex 是 OpenAI 出的终端编程代理Claude Code 是 Anthropic 出的定位几乎一模一样在终端里读懂你的代码库自主完成编码任务。所以“选哪个”这个问题本质上是选模型生态和使用手感而不是“谁比谁高级”。7.2 一张表看懂主要差异对比维度Claude CodeCodex底层模型Claude 系列OpenAI 系列安装方式npm / 原生脚本npm类似编辑器集成VS Code 官方插件成熟官方插件也在迭代生态扩展Skills 机制完善社区适配层丰富插件社区起步中配置自由度环境变量 配置文件可玩性高相对封闭长任务处理长上下文口碑好跨文件理解稳部分场景表现亮眼第三方模型接入可通过兼容层接 Ollama、DeepSeek 等支持范围有限工具迭代速度都很快表里的细节会随版本变化但大方向是稳定的Claude Code 的开放性和可定制性更高Codex 更依赖自家模型体系。7.3 我的选择建议我的建议是按项目类型决定而不是按信仰站队。手头主要是 TypeScript、前端、全栈项目Claude Code 目前的工作流更顺尤其是 VS Code 插件和 Skills 机制能给团队协作带来额外价值。如果你已经在 OpenAI 的生态里代码风格、模型行为都习惯了用 Codex 也完全没问题不用额外折腾。如果经常想接开源模型、用 CC Switch 切换供应商Claude Code 的配置自由度明显更高。我最看重的还是它出问题时能被“拆开看”——环境变量、配置文件、日志都在明面上排查起来心里有底。我自己是主力开发机用 Claude Code另外一台轻量机器装了 Codex。两者工作流其实是互通的先让 AI 拆解任务再让它分步执行这套方法论放哪个工具上都成立。8. 高频报错现场与处理方案8.1 终端乱码编码问题与解决办法Windows 上最常见的就是中文乱码。Claude Code 默认输出 UTF-8而旧版 PowerShell 的默认代码页可能不是 UTF-8两者对不上就乱成一片。解决办法有三条路径在终端里执行chcp 65001把代码页切到 UTF-8直接改用 Windows Terminal它内置的编码处理更好在 VS Code 设置里调整终端默认配置文件并明确编码为 UTF-8。Mac 和 Linux 基本没遇到过乱码偶尔有也是字体渲染问题换个等宽字体即可。8.2 模型名不识别glm-5.2 is not a model...看到glm-5.2 is not a model this version of claude code recognizes这种报错大概率是你在配置里写了一个当前版本不认的模型名。常见原因三个模型名拼写不对你的适配层返回的模型列表里没有这个型号Claude Code 版本太老不知道这个新模型。排查顺序先claude --version看看版本再进交互模式用/model查看可选模型列表最后检查适配层日志里模型名是否被正确映射。多数情况下升级到最新版本就能解决。8.3 CLI 找不到但命令行又能用编辑器环境变量问题有个场景很迷惑终端里claude好好的VS Code 插件却报could not locate the claude cli on path。原因通常是插件启动的进程没有继承你的终端 PATH 配置。解决方法是把 npm 全局路径显式写进 VS Code 的设置Windows 上类似terminal.integrated.env.windows: { PATH: ${env:PATH}${pathSeparator}C:\\Users\\你的用户名\\AppData\\Roaming\\npm }如果嫌麻烦更省心的做法是用官方原生安装器让 claude 直接落在系统 PATH 目录里绕开环境变量继承的问题。8.4 组织已禁用订阅访问是策略不是故障your organization has disabled claude subscription access for claude code这个提示前文提过再强调一次它是组织策略不是技术故障。如果你是个人用户却看到了检查登录的是不是公司账号或者环境变量里是否残留了组织身份信息。可以尝试清除~/.claude/.credentials.json后重新登录个人账号。企业用户就走正规流程联系管理员开通不要用任何绕过手段。8.5 高频问题对照表症状原因处理方式中文乱码Windows 代码页与 UTF-8 不一致chcp 65001或改用 Windows TerminalCLI 找不到命令PATH 未包含 npm 全局目录检查npm prefix -g并加入 PATHPowerShell 禁止运行脚本执行策略限制Set-ExecutionPolicy RemoteSigned -Scope CurrentUser模型名不识别版本太老或适配层映射错误升级、/model查看、检查日志组织禁用订阅访问组织策略个人账号登录或联系管理员频繁要求重新登录本地凭证损坏或过期删除 credentials 文件重新登录8.6 兼容第三方配置的安全提醒最后多嘴一句。社区里有很多“魔改”方案和“免费”入口看着方便但要谨慎。凡是需要你输入 API Key 或账号凭证的先确认来源可靠任何绕过官方认证、试图破解订阅限制的脚本都不要碰。这类东西轻则泄露密钥重则让账号被风控得不偿失。合规使用工具才能让它在你的工作流里活得更久。9. 最后说几句实在话9.1 我给自己定的使用规矩文章写到这里其实最想分享的不是具体命令而是使用心态。Claude Code 从“玩具”变成“生产力工具”靠的不是某个魔法参数而是我给自己定下的几条明显有效的规矩。第一条让它动手之前先读关键文件。一个知道项目背景的 AI比一个上来就改代码的 AI 强十倍。第二条每个独立任务完成后/compact保持上下文干净。第三条凡是它改过的核心代码必须人工 review我只把它当“协作者”从来不当“背锅侠”。第四条不开放它自动执行高风险命令的权限这个底线从第一天到现在都没破过。这几条规矩听起来简单执行起来需要一点自律但效果立竿见影。9.2 一个七天上手路径参考最后给一份新手可抄的七天路径第一天只跑claude --help和简单问答熟悉交互界面第二天用/init生成项目说明看它怎么理解你的代码库第三天接入 VS Code体验面板模式的差异第四天拿一个小 bug 让它修完整走一遍“分析—修改—验证”第五天配置.claudeignore和权限白名单把基础安全边界立好第六天练习/compact和/clear学会管理长会话第七天评估自己是否需要接第三方模型再上 CC Switch。工具是慢慢养熟的不是一次配出来的。按这个节奏走一周后你会对它有一个完全不同的判断。
