★ FEATURED ARTICLE 1. Claude Code 到底是什么它不只是一个聊天框第一次意识到 Claude Code 和以往所有“AI 编程助手”不是一回事是在一个 React 项目里。我让它把某个模块的异步错误处理从 try/catch 改成统一的错误边界封装它没有给我一段让我自己粘贴回编辑器的代码而是自己打开了项目里的十几个文件逐个修改然后跑了一遍测试把两处因为改漏而挂掉的用例找出来顺手修完最后在终端里给我列了一份改动清单。那一瞬间我意识到Claude Code 不是一个“写代码的聊天机器人”它是一个真正住在你项目目录里的 AI 代理。它不只是生成代码片段而是能读取整个项目的上下文、自己规划任务步骤、调用命令行工具、读写文件、跑测试跑构建并根据报错自我修正。简单说它把“AI 写代码”从“复制粘贴”变成了“委派执行”。这篇手册我会按照一条从入门到精通的路线走先讲清楚它的核心工作模式再讲安装和首次使用然后深入日常高频操作、权限控制、Skills 扩展、SDK 集成、第三方模型接入最后是我自己在跨平台使用中踩过的一堆坑和我现在的工作流。每部分都会给出可以直接照抄的命令和配置。适合谁来读这片内容如果你是第一次听说 Claude Code想搞清楚它和 Copilot、ChatGPT 的区别如果你已经装了但只会开个对话框问问题如果你正在纠结要不要用 DeepSeek 之类的第三方模型来省成本如果你在不同操作系统上被安装问题折磨过——这篇都能对得上。2. 为什么终端里的 AI 反而比网页版靠谱三种工作模式2.1 CLI 形态的真正优势上下文不再断裂网页版的 AI 编程助手有个天生的死穴——上下文断层。你在网页里描述需求它生成代码你复制回编辑器跑一下报错再把报错信息贴回网页再等它修改再复制回来。一次完整的改动要在两个工具之间来回折腾七八趟而且每一趟都会丢失一部分上下文。Claude Code 以 CLI 形态直接运行在项目目录里这个设计解决的不只是“方便”两个字。它意味着 AI 和你的代码库之间没有“复制粘贴”这层隔膜它能自己打开文件看内容能自己执行npm test、git diff这些命令来验证自己的改动能自己从报错堆栈里定位到具体文件和行号。整个过程发生在同一个终端环境里上下文是连续的不存在“你忘了把报错信息粘给我”的问题。如果把网页版 AI 比作一个只能隔着一扇窗户看工地、然后把图纸扔给你的顾问Claude Code 就是那个直接走进工地、拿起工具干活、干完还帮你检查了一遍水电的包工头。2.2 三种操作模式对应三种不同的使用场景实际用下来Claude Code 的操作场景可以粗分成三类理解这三类是你用好它的基础直接执行模式你用自然语言下达任务比如“把登录接口的超时时间改成可配置并在文档里更新说明”它自己拆解步骤、修改代码、运行验证。适合中等规模、目标明确的改动。计划评审模式遇到大改动先让它出一份实施计划比如“先重构数据访问层再调整调用方最后补测试”。你确认计划没问题再让它动手。适合涉及多个模块、影响面比较大的任务。提问调研模式只让它读代码、解释逻辑、定位问题不实际改文件。比如“这个内存泄漏是怎么产生的”“订单状态机的状态流转画成文字描述”。我会在提问时带上“只读”的要求或者用/init生成项目说明后配合--mode plan这类限制避免它手快改坏东西。这三种模式不是分开的工具而是在同一个会话里随时切换的。小任务直接做大任务先出方案拿不准的先调研这个节奏最稳。2.3 它能做的和它不该做的能做的事非常多跨文件重构、写单元测试、修 lint 报错和类型错误、批量重命名、解释陌生项目的代码、生成提交信息、做技术调研、甚至按你的模板生成周报。它最擅长的其实是“需要顺着代码线索追好几层才能找到答案”的活比如“为什么生产环境偶尔出现重复订单”这种任务人查起来费神它查起来反而很快。但要记住它的边界。所有涉及生产环境数据库、密钥文件、不可逆删除、对外发布的操作都不应该放给 AI 自动执行。默认情况下 Claude Code 对这类操作会要求你确认这个设计是保护你的别为了省事把这道防线全拆了。我自己只在一次性测试容器里用过完全跳过确认的模式平时一定留确认。3. 安装与首次启动从零到跑通第一个真实任务3.1 环境准备Node 版本是第一道坎Claude Code 本质是一个 npm 包安装前要确认你的 Node.js 环境。我建议 Node 18 及以上npm 9 以上。很多安装失败不是因为包本身有问题而是 Node 版本太老。检查环境node -v npm -v git --version如果你还没装 Node不同系统的处理方式不一样macOS推荐先装 Homebrew然后brew install node。Windows直接去 Node 官网下载 LTS 版本安装包也可以用 wingetwinget install OpenJS.NodeJS.LTS。Ubuntu/Debian系统自带 apt 里的 Node 版本通常偏老我建议用 nvm 来装避免后续权限和版本问题。curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash nvm install 20 nvm use 20装完 Node 之后全局安装 Claude Codenpm install -g anthropic-ai/claude-code装完验证一下claude --version能输出版本号说明安装成功了。3.2 登录与区域可用性的那个提示第一次运行claude会引导你登录。它有两条路一个是浏览器 OAuth 登录订阅账号一个是填 Anthropic API Key。个人使用订阅账号更方便自动化脚本和 CI 里用 API Key 更合适。如果你在终端里看到类似 “might not be available in your country” 的提示它的意思是官方根据 IP 归属地对服务可用性做了限制。这种情况最稳妥的处理方式不是去找第三方工具绕过校验——那些来路不明的工具往往带有安全风险也违反服务条款。正确做法是先确认你所在的地区是否在官方支持列表里如果是企业场景走合规渠道通过 Anthropic 销售团队或官方云服务平台接入不要自己折腾流量出口。登录的细节在终端里运行claude后它会输出一个链接浏览器打开后完成授权终端自动收到确认。如果你是在没有图形界面的服务器上操作可以用claude --print之类的参数配合 API Key 直连模式我后面在排错章节会细说。3.3 跑通第一个真实任务让它在你的项目里干活安装登录完成后先找个真实项目练手不要用 hello world。我建议在你手头任何一个有点代码量的项目里执行cd your-project claude进入交互界面后第一件事让它先读项目请先浏览一下项目结构告诉我这个项目是做什么的、用了哪些技术栈、入口文件在哪里。它会把项目根目录浏览一遍结合 README 和配置文件给你一份概述。这一步有两个作用一是验证它能正常读取你的项目二是帮你热身看它对你项目的理解程度。然后给一个真实的小任务比如把 README 里所有过时的安装命令更新成正确的版本然后跑一遍 markdown lint。你会看到它开始列出计划、打开文件、修改、执行 lint 命令。这个过程里如果涉及修改文件或执行命令它会逐条询问你是否确认。这条确认机制很重要初期阶段我建议一条一条看别嫌烦看几次你就懂它的意图了后面再配置白名单省事。3.4 卸载与干净重装被装坏了怎么处理如果你装坏了想重来或者版本升级出问题卸载其实很简单npm uninstall -g anthropic-ai/claude-code但要注意全局卸载只删了程序本体配置和会话历史是留在本地的。很多人以为卸载重装后该干净了结果发现旧配置、旧权限还在就是因为漏了这些目录~/.claude/包含配置文件、skills、会话记录对应 shell 的配置文件里可能残留的 PATH 或别名想要完全干净重装卸载后手动删掉~/.claude目录即可。不过删之前想清楚你的 sessions 历史、CLAUDE.md 项目指令、自定义 skills 都在里面删了就真没了。Windows 上如果 npm 全局卸载后命令仍能执行检查一下是不是之前用安装脚本而不是 npm 装的两者是独立的安装路径得分别清理。4. 日常使用的核心姿势权限、会话与思考深度4.1 怎么避免“每次确认”权限白名单的正确用法刚用 Claude Code 时最烦人的是每动一个文件、每执行一条命令它都要向你确认。用久了会想能不能让它别问了能但不要一刀切。Claude Code 的权限系统是分层的你可以精确控制哪些操作免确认、哪些必须留确认。常用方式有三种在会话里用/permissions打开权限管理勾选信任的操作。编辑~/.claude/settings.json在permissions.allow数组里加白名单规则。启动时用命令行参数指定比如只允许跑 npm 的某类命令。我实际在配置文件里放的规则参考{ permissions: { allow: [ Read, Edit, Bash(npm run lint), Bash(npm test), Bash(git status), Bash(git diff) ], deny: [ Bash(rm -rf *), Bash(git push*) ] } }注意我特意把git push放在 deny 里。为什么因为 AI 自动推送代码的风险远大于便利——你还没看 diff 呢它就把代码推上去了这要是推到生产分支妥妥的生产事故。类似的禁忌还有直接操作线上数据库、修改密钥文件、强推 git 历史。你还可以用--dangerously-skip-permissions参数启动它跳过所有确认。我只在一次性容器或明显是沙箱环境下才建议用在真实项目里开这个参数等于把保险栓拔了再玩枪。不过我也要提醒一点权限白名单别配得又细又死。配得太细你会发现它想干点白名单外的正经事时频繁卡住体验还不如默认全确认。我建议的力度是把“验证类命令”放开跑测试、lint把“不可逆命令”收紧push、删除、部署这个平衡点最舒服。4.2 思考等级调整复杂任务需要更深的推理用过 ChatGPT 的人都知道同一个问题让模型“慢慢想”和“直接答”效果差距很大。Claude Code 也提供类似的思考深度调节只是默认值比较保守。如果你在做一个跨模块的大重构或者让 AI 排查一个藏在多层调用链里的 bug建议把思考预算调高。Claude Code 支持调整 extended thinking 的级别和 token 预算你可以通过会话内的命令类似/think或配置项里的 thinking 参数来控制。一个经验参考任务类型思考等级建议改一个函数的逻辑低/默认响应快跨 3 个文件以上的小功能中重构架构、排查深层 bug高需要对比多种方案再决策最高更实用的做法是借助 Workflows 来固化这种节奏。Workflows 意思是把一组提示词、工具权限、思考参数打包成一个可复用的流程模板。比如我给自己配了一个“重构专用 workflow”要求它先梳理模块依赖、列出影响面清单把思考等级调到 high在我确认计划后才动手。这样每次做重构不用临时去调一堆参数一条 workflow 就全搞定了。不过也要说句实话思考等级调高不是免费的。响应会明显变慢token 消耗也会涨。所以日常改小东西别开高思考等级有点杀鸡用牛刀你不着急钱包也着急。4.3 会话管理让 AI 记得住今天的事接得上明天的活Claude Code 的会话历史是持久化的。你中断一个会话后回到同一个项目目录再次打开可以用--resume恢复之前的会话claude --resume它会列出所有历史会话按时间和项目分组选择要恢复的那个即可。恢复会话的价值在于上下文不丢。比如上午你让它调研了某个模块的缺陷下午想接着改这个模块直接恢复到上午的会话它就记得之前所有结论不用你重新解释一遍来龙去脉。上下文太长也会出问题。上下文窗口有限聊得越久前面的有效信息越可能被截断或稀释。当你感觉它开始“失忆”时用/compact压缩会话它会把当前的结论和关键信息提炼成摘要作为新的上下文继续用。我习惯在做完一个阶段性任务后主动/compact一次效果比等到它忘光了再补救好得多。另一个容易被忽视但价值极高的文件是CLAUDE.md——项目根目录下的这个文件相当于给 AI 写的工作手册。你把项目的架构约定、代码风格、目录职责、常用命令都写进去它每次进入项目会自动读取并遵循。我维护的项目里都会放一份效果相当于给每次会话做了一个“岗前培训”。4.4 常用命令速查不需要全记但要会查在 Claude Code 交互界面里斜杠开头的命令是你的操作台。下面这些是我印象里最常用的其他记不全也没关系随时输入/help就能查/init让 AI 根据项目生成或更新 CLAUDE.md/review让 AI 检查当前未提交改动的潜在问题/clear清空当前会话上下文开始新话题/cost查看当前会话的 token 消耗估算/permissions管理权限白名单/model切换或查看当前使用的模型/compact压缩上下文5. 进阶扩展Skills、SDK 与开发工具集成5.1 Skills把你的私有方法论装进 AI基础用法玩熟了之后Claude Code 真正拉开差距的地方在于扩展能力而 Skills 是我最推荐先深入的一项。Skill 是什么你可以把它理解成给 AI 附加的专业知识包。默认情况下 AI 只懂通用知识但当你给它一个定义良好的 Skill它能按你预设的方法论执行特定领域任务。Skill 在文件系统里就是一个目录里面有SKILL.md描述文件和若干资源文件。标准位置是~/.claude/skills/ └── my-skill/ ├── SKILL.md └── scripts/SKILL.md的核心结构包括name技能名称description什么时候该用这个技能instructions执行步骤和方法论举个我自己的例子。我在做前端项目时经常要检查可访问性这是个很细碎的活靠人一个个查既不全面又总忘。我写了一个a11y-auditskillSKILL.md里写明“当用户要求做无障碍审查时按这个清单检查键盘导航、屏幕阅读器语义、颜色对比度、焦点管理……”还配了一个脚本让它自动抓取页面里疑似有问题的元素。此后我只要在会话里说一句“用 a11y 技能检查这个页面”它就会按我的标准执行不是它的通用理解。手动安装 GitHub 上的第三方 skill 也很简单# 把 skill 仓库克隆到本地 skills 目录 git clone https://github.com/some-user/awesome-skill ~/.claude/skills/awesome-skill装完后重启会话它会在合适的场景自动使用这个 skill。自己写 skill 有个要点SKILL.md一定要写清楚何时使用否则 AI 会在不合适的场景把事情搞得更复杂。我第一版 skill 就是描述写得模棱两可结果它在不该介入的简单任务上也强行用反而碍事。5.2 用 SDK 把 AI 编程能力嵌入自己的工具链当你不再满足于在终端里和它聊天想把 Claude Code 的编程代理能力嵌入自己写的脚本、工具后台时SDK 就是答案。官方提供了 TypeScript 和 Python 两种 SDK。一个最小的 TypeScript 示例逻辑如下import { Agent } from anthropic-ai/claude-agent-sdk; const agent new Agent({ model: sonnet, cwd: /path/to/my-project, }); for await (const message of agent.query(修复所有 eslint 报错)) { // 处理流式输出 console.log(message); }Python 版本对应写法from claude_agent_sdk import Agent agent Agent(modelsonnet, cwd/path/to/my-project) for message in agent.query(修复所有 eslint 报错): print(message)SDK 的价值在于你可以把“AI 编程代理”当成一个服务来编排。比如我写过一个小工具监听 GitHub Actions 的失败通知自动把报错堆栈发给 Agent让它在对应分支上修复并提交 PR。这本质上把 AI 变成了自动化流水线里的一环。不过 SDK 的坑是 API 变化比较快我建议以官方文档为准别死记示例代码。另外SDK 的能力边界和 CLI 不完全一致有些 CLI 才有的功能要在 SDK 里自己实现。5.3 VS Code、桌面版与可视化不熟悉终端也有选择不是所有人都喜欢纯终端尤其 Windows 用户终端体验参差不齐。有两个方向可以选一个是 VS Code 扩展。装了之后你可以在编辑器里分屏使用左边看代码右边和 AI 对话改动会直接落到文件上配合编辑器自身的 diff 视图审阅修改非常顺畅。我认识的不少同事用这种方式日常开发终端只是偶尔切进去看细节。另一个是官方桌面版客户端。桌面版本质上是给 CLI 包了一层图形界面底层的 Agent 能力完全一致但增加了图形化的会话管理、项目切换、权限配置界面。对刚入门、命令行不熟的人来说桌面版的上手曲线低很多对我来说方便的是它能同时开多个项目的会话切换不用反复cd。我自己是终端派VS Code 扩展装来应急审查 diff 用桌面版偶尔在演示给同事看的时候开一下。你选哪个不重要重要的是别让工具形态限制你发挥能力上限。6. 第三方模型接入用 DeepSeek 把成本打下来6.1 环境变量切网关的原理Claude Code 的模型默认是 Anthropic 自家的 Claude 系列。但它的通信协议本质上是标准的 Anthropic API 协议而协议本身是可以指向任意兼容端点的。这句话翻译成人话就是只要某个服务商提供了兼容 Anthropic API 格式的端点Claude Code 就能把请求发到那里去。用 DeepSeek 来举例。DeepSeek 提供了 Anthropic 兼容的 API 端点你只需要设置两个环境变量export ANTHROPIC_BASE_URLhttps://api.deepseek.com/anthropic export ANTHROPIC_AUTH_TOKEN你的-deepseek-api-key设置完之后再启动claude它会把模型请求发到 DeepSeek 的端点底层跑的是 DeepSeek 模型但整个 CLI 的交互体验完全不变。这个原理不限于 DeepSeek任何提供 Anthropic 兼容端点的服务商都可以这么接入。懂了这个机制之后你会发现所谓“接入某模型”在工程上就只是一个环境变量的事难点从来不在技术而在模型能力和兼容性的落差。6.2 cc-switch 这类工具到底在管什么环境变量切换本身不难难的是来回切很痛苦。你不可能每次想用 Claude 官方模型就重新 set 一遍环境变量再换回 DeepSeek 再 set 一遍。cc-switch 这类工具解决的就是这个痛点。装好 cc-switch 后你可以预先配置好几套供应商配置Claude 官方一套、DeepSeek 的 deepseek-chat 一套、DeepSeek 的 deepseek-reasoner 一套以及其他你常用的模型服务商。切换的时候鼠标点一下它帮你改写对应的环境变量或配置文件然后你启动claude就是新配置。这里要注意 DeepSeek 的两种模型的区别。deepseek-chat 和 deepseek-reasoner 对应不同的能力侧重前者响应快后者推理强。cc-switch 里可以把它们分别配成两个入口根据任务类型切换。搜索“cc-switch 怎么切换 deepseek 的两种模型”的人多半是配了但不知道在哪切——答桉就是在 cc-switch 的配置界面里分别添加两个供应商条目一个把模型映射到 chat一个映射到 reasoner。6.3 这种接法的边界与风险我必须把风险也说清楚因为网络上有种吹法好像接入 DeepSeek 后 Claude Code 就免费了似的那是误导。首先模型能力差异是实打实的。Claude Code 的高级功能比如高等级 extended thinking、某些精细的工具调用能力需要模型和协议端点的配合。DeepSeek 的兼容端点能覆盖大部分日常编码场景但遇到特别复杂的任务规划质量的差距能明显感觉到。其次不是所有功能都能走第三方端点。部分高级特性和官方服务深度绑定接第三方后这些功能可能会静默降级或失效。我见过有人接完第三方后抱怨某个功能没了其实不是功能丢了是端点不支持。最后是稳定性和安全性。API Key 本身就是一个敏感资产你把它写在全局配置文件或导出成环境变量就要承担泄露风险。我的做法是第三方 API Key 单独用一个环境变量文件管理不进 shell history不提交到 git 仓库。从成本角度看第三方模型确实便宜得多甚至一些会有免费额度。如果你在大量跑自动化测试、批量代码审查这类对成本敏感的场景这个方案非常实用。但核心业务的复杂开发任务我的建议还是优先用官方模型省心。7. 跨平台实战排错Windows、Ubuntu、macOS 系列坑7.1 Ubuntu 安装到启动失败的排查思路Ubuntu 上是安装问题最多的地方九成出在 Node 环境。如果你用 apt 直接装的 node版本大概率很老某些 LTS 镜像上甚至还是 12 或 14而 Claude Code 要求 18。判断方法很简单node -v如果是 16 或更低别挣扎直接用 nvm 装新版nvm install 20 nvm alias default 20第二个常见问题是权限。用 npm 全局安装时如果报EACCES说明你 npm 全局目录没有写权限。不要急着sudo npm install那会把权限问题越搞越乱正确做法是npm config get prefix确认全局目录后把这个目录的属主改成当前用户或者配置 npm 的全局安装路径到用户目录。第三个问题比较隐蔽无图形界面的服务器上首次登录。没有浏览器OAuth 流程容易卡住。我的做法是用 API Key 模式claude --api-key $ANTHROPIC_API_KEY或者干脆在配置里把 key 写好避免每次启动都要输入。7.2 Windows 下的终端、编码与路径问题Windows 上第一个建议是用 Windows Terminal别用老旧的 cmd 或 PowerShell 5。这里不是审美问题UTF-8 支持和选中复制体验直接决定了你每天和终端打交道的幸福感。第二个常见问题是执行策略。PowerShell 可能因为执行策略不允许运行 npm 脚本。解决办法不是关掉安全策略而是在当前用户范围内设为 RemoteSignedSet-ExecutionPolicy -Scope CurrentUser RemoteSigned第三个是路径和乱码问题。项目路径里尽量不要放中文或空格虽然新版本对路径处理好了很多但某些第三方工具链尤其是配合 SDK 或部署脚本时遇到带空格路径照样炸。中文乱码如果出现检查终端是否 UTF-8老版本 PowerShell 把chcp 65001改了往往能解决。很多人问 Windows 上要不要用 WSL。我的意见是如果你已经在纯 Windows 环境跑通了不必非要上 WSL如果你是在 WSL 里跑 Linux 工作流的那在 WSL 里装和 Ubuntu 一样处理即可。不要两个环境各装一套然后混着用——离线配置文件和技能目录不互通你会有两份~/.claude。7.3 macOS 与常见网络提示的合规处理macOS 上安装相对最顺用 Homebrew 装 Node 后 npm 全局安装即可。不过 mac 上容易忽略的是如果你用了公司代理或某些网络管理软件首次登录 OAuth 的回环地址可能被拦截导致授权后终端没反应。这个情况先检查网络环境而不是反复重新登录。关于服务可用性的提示前面已经说过这里再啰嗦一遍原则官方根据 IP 归属地判断服务范围提示 might not be available 时你要做的不是找绕过办法而是确认自己的使用场景是否符合官方政策。个人使用建议直接参考官方的支持地区说明团队或公司场景走商用授权和合规接入途径。用非正当手段修改网络出口去“解锁”不仅违反服务条款还会把你项目里的全部对话数据暴露给不信任的中间链路这笔账怎么算都不划算。7.4 一张常见报错速查表省去上网查的时间症状原因解法claude: command not foundnpm 全局目录不在 PATH重新配置 PATH或重装EACCES: permission deniednpm 全局目录无写权限修正目录属主或改全局安装路径启动后卡在登录网络环境或 OAuth 回环被拦换网络环境或用 API Key 模式对话经常失忆上下文过长/compact压缩或新开会话某些工具命令总是卡确认权限白名单没配settings.json里加规则运行 npm 命令报编码错Windows 终端编码问题用 Windows Terminalchcp 650018. 三周高强度使用后我的个人工作流沉淀最后这部分不做什么名词总结就说几个让我“回不去”的实操细节。第一每个项目先花五分钟写好 CLAUDE.md。以前我觉得这是额外负担直到某次接手一个代码风格混乱的老项目我让 AI 重建一份 CLAUDE.md把自己项目里的约定写进去之后它生成的代码风格明显贴合项目现状少了很多“改完还要人工调格式”的活。现在新项目我第一件事就是让它读项目然后生成 CLAUDE.md再自己审定一遍。第二测试命令进白名单push 命令永远留在确认区。我把npm test、npm run lint设为免确认它每改完一批代码就跑一遍测试省掉了我逐条审批的繁琐。而git push这类命令我从不放白名单每次推送前我都会自己先git diff审一遍。这个习惯让我避免了好几次它准备把带着调试日志的代码推上去的场面。第三跨天工作用--resume阶段收尾用/compact。我现在已经养成了习惯下班前不关会话第二天claude --resume接着聊完成一个阶段就手动 compact 一次。这样 AI 能记住项目来龙去脉而不会被无限堆积的上下文拖到“失忆”。关于“手册附下载”这个事我说句实在的网上那些标着“下载链接”的所谓手册很多只是把官方文档换了个排版。真正有用的手册是你自己从使用记录里沉淀出来的。我的做法是把这篇内容连同你自己的常用命令整理成一个 Markdown 文件放在本地笔记里随时查、随时往里面追加新的心得。想转成 PDF 的话浏览器打开后打印目标选“另存为 PDF”就行。一份手册的价值不在于它多厚而在于它是不是你自己验证过的经验。
阅读完成 · 觉得有帮助？
