01-Claude-Code完整安装指南

01 Claude Code完整安装指南 01 Claude Code完整安装指南 Modified May 9 • 限制 model • 限制 ANTHROPIC MODEL • 限制 Config 工具中的模型切换 注意：model 不是强制锁定 model 只是会话启动时默认选哪个，并不代表用户不能换。 如果你要真正治理模型体验，通常要组合这三类配置： • model • availableModels • ANTHROPIC DEFAULT SONNET MODEL / OPUS / HAIKU 8.5.6 第三方部署与 modelOverrides 如果你跑的是： • Bedrock • Vertex AI • Foundry 就不要只写别名，还要考虑模型版本绑定。 为什么需要 modelOverrides 因为第三方平台上，Claude Code 看到的是 Anthropic 的模型 ID，但真正发给平台的，可能要换成： • ARN • deployment name • provider specific model ID 典型配置 Code block JSON Copy { "modelOverrides": { "claude opus 4 6": "arn:aws:bedrock:us east 2:123456789012:application inference profile/opus prod", "claude sonnet 4 6": "arn:aws:bedrock:us east 2:123456789012:application inference profile/sonnet prod" } } 用在： • 企业按版本精确路由 • 不同区域 / 不同成本中心分流 • 防止别名自动飘到新版本 8.5.7 自定义模型入口 如果你有内部网关或特殊部署，可用： • ANTHROPIC CUSTOM MODEL OPTION • ANTHROPIC CUSTOM MODEL OPTION NAME • ANTHROPIC CUSTOM MODEL OPTION DESCRIPTION 这样可以在 /model 里额外加一个选项，而不是替换原有别名。 适合： • 自研 LLM gateway • A/B 测试特殊路由 • 内部灰度模型 8.5.8 推荐配置场景 个人开发者 Code block JSON Copy { "model": "sonnet", "effortLevel": "medium" } 建议： • 日常用 sonnet • 架构问题临时切 opus 或 opusplan • 遇到超大仓库时再用 [1m] 高强度架构 / 重构 Code block JSON Copy { "model": "opusplan", "effortLevel": "medium" } 建议： • 默认用 opusplan • 真正卡住时再把 effort 提到 high 团队成本控制 Code block JSON Copy { "model": "sonnet", "availableModels": ["sonnet", "haiku"] } 建议： • 限掉随手切 opus • 只给必要团队开更强模型 8.5.9 常见误区 误区 真相 model 就是强制锁模型 不是。它只是初始值。 opusplan = 永远更贵 不完全对。它是"规划用 Opus，执行回 Sonnet"，很多复杂任务反而更划算。 1M 一定更好 不一定。上下文更大不等于响应更快，也不等于更省钱。 effort 越高越好 也不对。高 effort 在简单任务上很容易"过度思考"。 8.5.10 实用速查 Code block Bash Copy 当前会话直接切模型 /model opus 开 1M 上下文 /model sonnet[1m] 切高 effort /effort high 启动就用 opusplan claude model opusplan 8.5.11 下一步建议 • 想把模型配置纳入团队治理和企业实战：继续看 企业实战完整指南 • 想跨设备继续本地会话：继续看 Remote Control完整指南 • 想理解 Channels 与计划任务：继续看 Channels与计划任务完整指南 总结与检查清单 完成本课后，请确认以下所有项： 系统要求： 操作系统兼容（Windows 10+ / macOS 10.15+ / Linux） 终端可用（PowerShell / Terminal / Bash） 至少2GB可用磁盘空间 账号准备： 注册了Anthropic账号（或使用中转站） 获取了API Key Key已保存到安全位置 系统配置： 环境变量ANTHROPIC API KEY已配置 终端能正确显示中文 网络能访问api.anthropic.com（或配置了代理） Claude Code安装： Claude Code原生安装成功 claude version 显示正确版本（带native标识） claude help 显示帮助信息 功能验证： 通过基础测试套件 完成Hello World项目 IDE集成配置完成（可选） 如果以上全部勾选，恭喜你已经完成准备工作！🎉 ⚠️ 2026年更新说明：本课程现已更新为“原生安装 + npm 标准安装并存”的口径。如果你是从旧版教程过来的，请优先参考本章新的安装路径说明，不要再默认把 npm 视为唯一入口，也不要误以为 Node.js 已被完全移除。 附录 A. 常用命令速查 Code block Bash Copy Claude Code版本和帮助 claude version 查看版本（应显示native标识） claude help 查看帮助 claude /doctor 系统诊断 Claude Code操作 claude 进入交互模式 claude "你的问题" 单次提问 claude p "问题" 打印模式（脚本友好） 更新Claude Code claude install 重新安装/更新到最新版本 环境变量查看 $env:ANTHROPIC API KEY PowerShell 7（推荐） echo $ANTHROPIC API KEY macOS/Linux echo %ANTHROPIC API KEY% Windows CMD（不推荐） 网络测试 ping api.anthropic.com 测试连通性 curl I https://api.anthropic.com 测试HTTPS访问 配置管理 claude config list 查看所有配置 claude config get <key 查看特定配置 claude config set <key <value 设置配置 B. 从npm迁移到原生安装 如果你之前通过npm安装过Claude Code，请按以下步骤迁移： 步骤1：检查当前安装方式 Code block Bash Copy 企业实战完整指南 Remote Control完整指南 Channels与计划任务完整指南 api.anthropic.com • 限制 model • 限制 ANTHROPIC MODEL • 限制 Config 工具中的模型切换 注意：model 不是强制锁定 model 只是会话启动时默认选哪个，并不代表用户不能换。 如果你要真正治理模型体验，通常要组合这三类配置： • model • availableModels • ANTHROPIC DEFAULT SONNET MODEL / OPUS / HAIKU 8.5.6 第三方部署与 modelOverrides 如果你跑的是： • Bedrock • Vertex AI • Foundry 就不要只写别名，还要考虑模型版本绑定。 为什么需要 modelOverrides 因为第三方平台上，Claude Code 看到的是 Anthropic 的模型 ID，但真正发给平台的，可能要换成： • ARN • deployment name • provider specific model ID 典型配置 用在： • 企业按版本精确路由 • 不同区域 / 不同成本中心分流 • 防止别名自动飘到新版本 8.5.7 自定义模型入口 如果你有内部网关或特殊部署，可用： • ANTHROPIC CUSTOM MODEL OPTION • ANTHROPIC CUSTOM MODEL OPTION NAME • ANTHROPIC CUSTOM MODEL OPTION DESCRIPTION 这样可以在 /model 里额外加一个选项，而不是替换原有别名。 适合： • 自研 LLM gateway • A/B 测试特殊路由 • 内部灰度模型 8.5.8 推荐配置场景 个人开发者 建议： • 日常用 sonnet • 架构问题临时切 opus 或 opusplan • 遇到超大仓库时再用 [1m] 高强度架构 / 重构 建议： • 默认用 opusplan • 真正卡住时再把 effort 提到 high 团队成本控制 建议： • 限掉随手切 opus • 只给必要团队开更强模型 8.5.9 常见误区 误区 真相 model 就是强制锁模型 不是。它只是初始值。 opusplan = 永远更贵 不完全对。它是"规划用 Opus，执行回 Sonnet"，很多复杂任务反而更划算。 1M 一定更好 不一定。上下文更大不等于响应更快，也不等于更省钱。 effort 越高越好 也不对。高 effort 在简单任务上很容易"过度思考"。 误区 误区 真相 真相 model 就是强制锁模型 model 就是强制锁模型 不是。它只是初始值。 不是。它只是初始值。 opusplan = 永远更贵 opusplan = 永远更贵 不完全对。它是"规划用 Opus，执行回 Sonnet"，很多复杂任务反而更划算。 不完全对。它是"规划用 Opus，执行回 Sonnet"，很多复杂任务反而更划算。 1M 一定更好 1M 一定更好 不一定。上下文更大不等于响应更快，也不等于更省钱。 不一定。上下文更大不等于响应更快，也不等于更省钱。 effort 越高越好 effort 越高越好 也不对。高 effort 在简单任务上很容易"过度思考"。 也不对。高 effort 在简单任务上很容易"过度思考"。 8.5.10 实用速查 8.5.11 下一步建议 • 想把模型配置纳入团队治理和企业实战：继续看 企业实战完整指南 企业实战完整指南 • 想跨设备继续本地会话：继续看 Remote Control完整指南 Remote Control完整指南 • 想理解 Channels 与计划任务：继续看 Channels与计划任务完整指南 Channels与计划任务完整指南 总结与检查清单 完成本课后，请确认以下所有项： 系统要求： 操作系统兼容（Windows 10+ / macOS 10.15+ / Linux） 终端可用（PowerShell / Terminal / Bash） 至少2GB可用磁盘空间 账号准备： 注册了Anthropic账号（或使用中转站） 获取了API Key Key已保存到安全位置 系统配置： 环境变量ANTHROPIC API KEY已配置 终端能正确显示中文 网络能访问api.anthropic.com（或配置了代理） api.anthropic.com Claude Code安装： Claude Code原生安装成功 claude version 显示正确版本（带native标识） claude help 显示帮助信息 功能验证： 通过基础测试套件 完成Hello World项目 IDE集成配置完成（可选） 如果以上全部勾选，恭喜你已经完成准备工作！🎉 ⚠️ 2026年更新说明：本课程现已更新为“原生安装 + npm 标准安装并存”的口径。如果你是从旧版教程过来的，请优先参考本章新的安装路径说明，不要再默认把 npm 视为唯一入口，也不要误以为 Node.js 已被完全移除。 附录 A. 常用命令速查 B. 从npm迁移到原生安装 如果你之前通过npm安装过Claude Code，请按以下步骤迁移： 步骤1：检查当前安装方式 步骤2：运行迁移命令 步骤3：验证迁移成功 步骤4：卸载npm版本（可选） 迁移时会保留： • ✅ 所有配置文件（ /.claude/） • ✅ API Key配置 • ✅ 自定义命令和技能 • ✅ 信任目录设置 特殊场景：使用nvm的用户 如果你用nvm管理多个Node版本，可能需要手动处理： C. 推荐学习资源 Claude Code官方文档： • 英文：https://docs.anthropic.com/en/docs/claude code • 中文：https://code.claude.com/docs/en/ Anthropic API文档： • https://docs.anthropic.com/ 终端使用教程： • Windows Terminal：https://learn.microsoft.com/zh cn/windows/terminal/ • macOS终端：https://support.apple.com/zh cn/guide/terminal/ 社区支持： • Claude Discord：https://discord.gg/anthropic • GitHub Discussions：https://github.com/anthropics/claude code/discussions 课程制作：老金最后更新：2026年4月（已对照 GitHub v2.1.90 / v2.1.92 release 增补登录与 Bedrock 向导说明；安装路径仍以「原生 + npm」双轨为准）版本：V3.1（v2.1.92 release 对齐补丁）许可：本课程采用CC BY NC SA 4.0许可 版本更新日志 V3.1（2026 04 05） • 认证步骤旁：增补 v2.1.92 官方 release 中 3rd party platform → interactive Bedrock setup wizard 的说明（附 release 链接，不编造向导界面） • 页脚：与 v2.1.92 验证口径对齐，避免仍显示「仅 2026 02」造成读者误以为未更新 • 文内「下一步」：修正第 13 篇相对链接为 ./13 Channels与计划任务完整指南.md（与教程序号、文件名一致，避免死链） V3.0 重大更新（2026 02 02） 阅读提示：下表为当时改版公告摘要。当前正文口径以文首「双轨安装」为准：原生安装可不单独装 Node；npm install g @anthropic ai/claude code 仍受支持且需要 Node.js 18+。 更新项 变化说明 安装方式 主推原生安装，与 npm 标准安装并存（非互斥） Node.js 原生路径可不单独安装 Node；npm 路径仍需要 Node.js 18+ 安装时间 从40分钟缩短到5分钟 自动更新 新增后台自动更新功能 系统要求 简化系统要求检查清单 FAQ 新增8个原生安装相关常见问题 迁移指南 新增从npm迁移到原生的完整指南 更新项 更新项 变化说明 变化说明 安装方式 安装方式 主推原生安装，与 npm 标准安装并存（非互斥） 主推原生安装，与 npm 标准安装并存（非互斥） Node.js Node.js 原生路径可不单独安装 Node；npm 路径仍需要 Node.js 18+ 原生路径可不单独安装 Node；npm 路径仍需要 Node.js 18+ 安装时间 安装时间 从40分钟缩短到5分钟 从40分钟缩短到5分钟 自动更新 自动更新 新增后台自动更新功能 新增后台自动更新功能 系统要求 系统要求 简化系统要求检查清单 简化系统要求检查清单 FAQ FAQ 新增8个原生安装相关常见问题 新增8个原生安装相关常见问题 迁移指南 迁移指南 新增从npm迁移到原生的完整指南 新增从npm迁移到原生的完整指南 V2.1 修正内容（2025 12 23） 修正项 问题 修正后 API测试模型名称 claude sonnet 4 20250514 格式和日期错误 修正为 claude sonnet 4 6 修正项 修正项 问题 问题 修正后 修正后 API测试模型名称 API测试模型名称 claude sonnet 4 20250514 格式和日期错误 claude sonnet 4 20250514 格式和日期错误 修正为 claude sonnet 4 6 修正为 claude sonnet 4 6 💡 审查方法：基于官方Claude API文档验证模型名称准确性。 Claude Code 完整安装指南：从零开始到成功运行 课程信息 • 作者：老金 • GitHub：https://github.com/KimYx0207 • 公众号：老金带你玩AI • X（Twitter）：老金带你玩AI • 个人博客：https://aiking.dev • 预计学时：2 3小时（原生安装更简单！） • 难度等级：⭐ 零基础入门 • 更新日期：2026年4月 • 适用版本：Claude Code v2.1.133（验证于 2026 05 08） • 重要更新：当前同时支持原生安装与标准 npm 安装；原生更省心，npm 路径仍然受支持且需要 Node.js 18+ https://aiking.dev 课程信息 • 作者：老金 • GitHub：https://github.com/KimYx0207 • 公众号：老金带你玩AI • X（Twitter）：老金带你玩AI • 个人博客：https://aiking.dev https://aiking.dev • 预计学时：2 3小时（原生安装更简单！） • 难度等级：⭐ 零基础入门 • 更新日期：2026年4月 • 适用版本：Claude Code v2.1.133（验证于 2026 05 08） • 重要更新：当前同时支持原生安装与标准 npm 安装；原生更省心，npm 路径仍然受支持且需要 Node.js 18+ 📚 本课学习目标 完成本课学习后，你将能够： 1. 理解Claude Code的核心价值：掌握Claude Code与传统AI编程工具的本质区别 2. 了解两条安装路径：知道什么时候优先用原生安装，什么时候仍然可以走 npm 标准安装 3. 配置Anthropic服务：获取并正确配置API密钥 4. 完成Claude Code安装：掌握原生安装与 npm 标准安装两条主路径 5. 集成到主流IDE：VS Code、Cursor、JetBrains等编辑器配置 6. 验证环境可用性：通过Hello World测试确认所有组件正常工作 7. 掌握故障排查技能：独立解决90%的常见安装问题 8. 了解从npm迁移：如果你之前用npm安装过，如何迁移到原生版本 🗺️ 学习路径导航（先看这里！） 💡 根据你的情况选择学习路径：这是一篇3000+行的长教程，不用全看！根据你的目标选择路径。 路径A：快速上手（⏱️ 30分钟） 适合人群：急着体验Claude Code，想快速跑起来 只看这些章节（其他跳过）： 30分钟后你能达到：成功启动Claude Code，运行Hello World示例 路径B：完整学习（⏱️ 2 3小时） 适合人群：想深入理解每个细节，掌握所有功能 学习顺序：从头到尾所有章节 建议分段学习： • 第1阶段（1小时）：第1 4部分（理解+API Key+安装） • 第2阶段（1小时）：第5 6部分（验证+IDE集成） • 第3阶段（30分钟）：第7 8部分（故障排查+FAQ） 路径C：问题排查（⏱️ 10分钟） 适合人群：安装过程遇到问题，需要快速解决 直接跳到这些章节： 使用方法： 1. 按 Ctrl + F 搜索你的错误信息关键词 2. 找到对应的Q&A 3. 按步骤解决 路径D：专项学习（⏱️ 30 60分钟/主题） 适合人群：已经装好Claude Code，想学习某个特定功能 想学什么 看哪几节 预计时间 IDE集成 第6部分 30分钟 权限配置 第6.5节（危险参数）+ 第7.3节 20分钟 从npm迁移 附录：迁移指南 15分钟 想学什么 想学什么 看哪几节 看哪几节 预计时间 预计时间 IDE集成 IDE集成 第6部分 第6部分 30分钟 30分钟 权限配置 权限配置 第6.5节（危险参数）+ 第7.3节 第6.5节（危险参数）+ 第7.3节 20分钟 20分钟 从npm迁移 从npm迁移 附录：迁移指南 附录：迁移指南 15分钟 15分钟 术语表（小白必读） ⚠️ 2026年重要更新：Claude Code 现在提供原生安装，但 npm 标准安装仍受支持。Node.js 和 npm 不再是唯一入口，但也没有“彻底消失”。 在开始之前，先了解这些关键术语： 术语 英文全称 通俗解释 CLI Command Line Interface 命令行界面，就是那个黑色/白色的文字输入窗口，通过打字来操作电脑 原生安装器 ⭐ Native Installer Claude Code官方提供的独立安装程序，不需要其他依赖 Node.js • JavaScript 运行环境；如果你走 npm install g @anthropic ai/claude code 这条标准安装路径，仍需要 18+ npm Node Package Manager Node.js 的包管理器；Claude Code 的标准安装路径之一仍然会用到它 LTS Long Term Support 长期支持版本，稳定、bug少、官方持续维护，适合正式使用 API Application Programming Interface 应用程序接口，软件之间"对话"的方式 API Key • API密钥，类似"通行证"，证明你有权使用某个服务 Token • 计费单位，AI处理文字的最小单元，约等于0.75个英文单词或1 2个汉字 环境变量 Environment Variable 操作系统级别的配置项，程序可以读取但不会写在代码里 PATH • 系统环境变量之一，告诉电脑去哪里找可执行程序 终端/Terminal • 运行命令行的程序窗口 全局安装 Global Install 安装后在电脑任何位置都能使用的安装方式 术语 术语 英文全称 英文全称 通俗解释 通俗解释 CLI CLI Command Line Interface Command Line Interface 命令行界面，就是那个黑色/白色的文字输入窗口，通过打字来操作电脑 命令行界面，就是那个黑色/白色的文字输入窗口，通过打字来操作电脑 原生安装器 ⭐ 原生安装器 ⭐ Native Installer Native Installer Claude Code官方提供的独立安装程序，不需要其他依赖 Claude Code官方提供的独立安装程序，不需要其他依赖 Node.js Node.js • • JavaScript 运行环境；如果你走 npm install g @anthropic ai/claude code 这条标准安装路径，仍需要 18+ JavaScript 运行环境；如果你走 npm install g @anthropic ai/claude code 这条标准安装路径，仍需要 18+ npm npm Node Package Manager Node Package Manager Node.js 的包管理器；Claude Code 的标准安装路径之一仍然会用到它 Node.js 的包管理器；Claude Code 的标准安装路径之一仍然会用到它 LTS LTS Long Term Support Long Term Support 长期支持版本，稳定、bug少、官方持续维护，适合正式使用 长期支持版本，稳定、bug少、官方持续维护，适合正式使用 API API Application Programming Interface Application Programming Interface 应用程序接口，软件之间"对话"的方式 应用程序接口，软件之间"对话"的方式 API Key API Key • • API密钥，类似"通行证"，证明你有权使用某个服务 API密钥，类似"通行证"，证明你有权使用某个服务 Token Token • • 计费单位，AI处理文字的最小单元，约等于0.75个英文单词或1 2个汉字 计费单位，AI处理文字的最小单元，约等于0.75个英文单词或1 2个汉字 环境变量 环境变量 Environment Variable Environment Variable 操作系统级别的配置项，程序可以读取但不会写在代码里 操作系统级别的配置项，程序可以读取但不会写在代码里 PATH PATH • • 系统环境变量之一，告诉电脑去哪里找可执行程序 系统环境变量之一，告诉电脑去哪里找可执行程序 终端/Terminal 终端/Terminal • • 运行命令行的程序窗口 运行命令行的程序窗口 全局安装 全局安装 Global Install Global Install 安装后在电脑任何位置都能使用的安装方式 安装后在电脑任何位置都能使用的安装方式 第一部分：Claude Code 简介 1.1 什么是 Claude Code Claude Code 是 Anthropic 公司开发的命令行AI编程助手。与传统代码编辑器插件不同，它是一个独立运行的CLI工具，通过终端与开发者交互。 核心特征： • 本地优先架构：代码在你的电脑上处理，不上传到云端 • 全能AI助手：基于Claude模型，理解复杂技术需求 • 工具整合能力：可调用文件操作、终端命令、Web搜索等工具 • 对话式开发：用自然语言描述需求，AI帮你生成和修改代码 简单理解： 把Claude Code想象成一个24小时在线的高级程序员。你用中文或英文告诉他需求，他能帮你写代码、改bug、搜资料、运行测试。最大特点是通过命令行工作，可以直接操作你的代码文件、运行系统命令，完全脚本化和自动化。 1.2 核心优势：为什么值得学习 优势1：隐私与安全 传统在线AI工具需要你把代码上传到服务器分析。Claude Code不同： • ✅ 代码文件留在本地，AI只读取你授权的文件 • ✅ 可在企业内网环境使用（配合私有Claude部署） • ✅ 敏感项目（如金融、医疗系统）也能安全使用 优势2：真正的编程助手 实际案例： 优势3：多语言多框架支持 不限于特定技术栈： • 前端：React、Vue、Next.js • 后端：Node.js、Python、Go • 移动端：React Native、Flutter • 基础设施：Docker、Kubernetes配置 1.3 与主流工具对比 CLI工具 vs IDE集成工具对比： 对比项 Claude Code（CLI） Cursor（IDE集成） 运行方式 命令行独立运行 VS Code编辑器内置 文件操作 ✅ 直接读写 ✅ 直接读写 项目理解 ✅ 全项目上下文 ✅ 全项目上下文 脚本自动化 ✅ 完美支持 ⚠️ 有限 CI/CD集成 ✅ 原生支持 ❌ 困难 远程服务器 ✅ 完美支持 ❌ 需要图形界面 隐私性 ✅ 本地优先 ⚠️ 云端处理 学习曲线 中等（需要CLI基础） 低（图形界面） 对比项 对比项 Claude Code（CLI） Claude Code（CLI） Cursor（IDE集成） Cursor（IDE集成） 运行方式 运行方式 命令行独立运行 命令行独立运行 VS Code编辑器内置 VS Code编辑器内置 文件操作 文件操作 ✅ 直接读写 ✅ 直接读写 ✅ 直接读写 ✅ 直接读写 项目理解 项目理解 ✅ 全项目上下文 ✅ 全项目上下文 ✅ 全项目上下文 ✅ 全项目上下文 脚本自动化 脚本自动化 ✅ 完美支持 ✅ 完美支持 ⚠️ 有限 ⚠️ 有限 CI/CD集成 CI/CD集成 ✅ 原生支持 ✅ 原生支持 ❌ 困难 ❌ 困难 远程服务器 远程服务器 ✅ 完美支持 ✅ 完美支持 ❌ 需要图形界面 ❌ 需要图形界面 隐私性 隐私性 ✅ 本地优先 ✅ 本地优先 ⚠️ 云端处理 ⚠️ 云端处理 学习曲线 学习