Claude Code 安装指南：从 IDE 扩展、桌面应用到 CI/CD 的完整配置路径

1. 为什么 Claude Code 的安装路径要分三种场景Claude Code 是 Anthropic 推出的终端智能编码工具它能在命令行里直接读写项目文件、跑测试、改代码也能以 IDE 扩展或桌面应用的形式嵌进你的日常工作流。适合谁如果你平时在 VS Code、JetBrains 里写代码或者需要在 CI 流水线里做自动代码审查那它值得花半小时装一遍。但很多人第一次装会踩同一个坑把 IDE 扩展、桌面应用、CLI 当成三件互不相干的事结果装完发现命令找不到、扩展连不上、CI 里跑不起来。实际上它们共享同一套认证和配置体系只是入口不同。我试过在一台机器上同时装 VS Code 扩展和 CLI结果 PATH 冲突导致claude doctor报了两个版本排查了半小时。这篇指南按「本地 CLI → IDE 扩展 → 桌面应用 → CI/CD」的顺序走每一步都给可复制的配置片段。核心是三件套Base URL、API Key、Model ID只要这三样对齐三种场景都能跑通。对于需要稳定调用、不想自己维护账号体系的场景可以用 TaoToken 这类兼容 Anthropic 接口的服务来统一管理 Key 和额度官网入口在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end API 地址是 https://taotoken.net/api 。先明确一个概念Claude Code 的「安装」不只是把二进制放到磁盘上还包括认证配置和权限配置。认证决定它能不能调模型权限决定它能碰哪些文件。这两块配错装得再干净也白搭。下面从 CLI 开始因为它是所有其他形态的基础——IDE 扩展和桌面应用底层都依赖 CLI 运行时。2. 前置环境与 CLI 安装从零到 claude --version 通过2.1 系统与依赖要求先对一下环境避免装到一半发现版本不够。macOS 需要 13.0 Ventura 及以上Windows 需要 10 1809 或 Server 2019Linux 推荐 Ubuntu 20.04、Debian 10、Alpine 3.19。内存最低 4 GB建议 8 GB 以上磁盘预留 500 MB 到 1 GB。推荐用 Native 安装方式不需要额外装 Node.js。如果你坚持用 npm 方式那 Node.js 至少 18.0.0建议 22.x LTSnpm 9.0Git 2.23。验证命令node --version npm --version git --version2.2 各平台安装命令速查macOS 官方脚本推荐curl -fsSL https://claude.ai/install.sh | bashHomebrew 方式分稳定通道和最新通道brew install --cask claude-code brew install --cask claude-codelatest注意 Homebrew 安装不会自动更新需要手动brew upgrade claude-code。想开自动更新可以设环境变量export CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE1Windows 用 PowerShell 脚本irm https://claude.ai/install.ps1 | iex如果执行策略限制先跑Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUserWinGet 方式winget install Anthropic.ClaudeCode。Linux 官方脚本和 macOS 一样装完把~/.local/bin加进 PATHecho export PATH$HOME/.local/bin:$PATH ~/.bashrc source ~/.bashrc2.3 安装后自检装完先跑两个命令claude --version claude doctorclaude doctor会做全面健康检查包括 PATH、认证状态、版本冲突。如果报command not found八成是 PATH 没配好回到上一步检查 shell 配置文件。如果 Linux 安装时遇到Killed通常是内存不足被 OOM Killer 终止加个 swapsudo fallocate -l 2G /swapfile sudo swapon /swapfile到这里 CLI 应该能跑起来了。下一步是认证配置这是三件套里最关键的一环。3. 认证与 settings.json 配置Base URL、Key、Model ID 三件套3.1 两种认证方式Claude Code 支持 OAuth 浏览器登录和 API Key 两种方式。OAuth 适合有 Pro/Max/Team/Enterprise 订阅的用户终端跑claude会自动打开浏览器SSH 远程环境按c复制认证 URL 到本地浏览器打开再粘贴授权码。API Key 方式适合用 Console API 或第三方兼容服务的用户。永久设置echo export ANTHROPIC_API_KEYsk-ant-... ~/.zshrc source ~/.zshrc或者在配置文件里设{ env: { ANTHROPIC_API_KEY: sk-ant-... } }API Key 优先级高于 OAuth如果同时存在会按 API 用量计费而非订阅额度。3.2 用 TaoToken 统一管理接入如果你不想自己维护 Anthropic 账号或者需要在多个项目、多个 CI 环境里共享同一套额度可以用 TaoToken 的兼容接口。它提供 Anthropic 兼容的 Base URL把 Key 和模型 ID 统一管理。接入文档在 https://taotoken.net/doc API Keys 管理在 https://taotoken.net/api-keys 。配置时把 Base URL 指向https://taotoken.net/apiKey 用你在控制台生成的Model ID 按文档填。这样本地 CLI、IDE 扩展、CI 流水线都能用同一套凭证不用每个环境单独配。3.3 settings.json 完整片段配置文件有四个层级优先级从低到高全局用户~/.claude/settings.json、全局本地~/.claude/settings.local.json、项目级project/.claude/settings.json、项目本地project/.claude/settings.local.json。项目级配置会覆盖全局本地配置不进 Git。一个可复制的完整片段{ model: sonnet, effortLevel: xhigh, alwaysThinkingEnabled: false, skipDangerousModePermissionPrompt: false, env: { ANTHROPIC_API_KEY: sk-ant-..., ANTHROPIC_BASE_URL: https://taotoken.net/api }, permissions: { allow: [ Bash(npm:*), Read(/tmp/**) ], deny: [] }, autoUpdatesChannel: stable }model填 Model IDenv里放 Base URL 和 Keypermissions.allow控制哪些命令免确认。配完在项目根目录跑/init生成CLAUDE.md帮助它理解代码库结构。3.4 auth.json 示例CI 场景CI 环境没法走 OAuth 浏览器流程需要用auth.json做无交互认证。文件放在~/.claude/auth.json{ apiKey: sk-ant-..., baseUrl: https://taotoken.net/api, model: sonnet }在 GitHub Actions 里通过 secrets 注入不要硬编码。Docker 场景可以挂载卷或构建时写入。注意auth.json权限设为 600避免被其他进程读到。三件套对齐后跑一次非交互调用验证claude -p hello --print能返回内容就说明认证通了。接下来验证 IDE 扩展和 CI 场景。4. IDE 扩展与桌面应用VS Code、JetBrains 配置差异4.1 VS Code 扩展安装前提是 VS Code 1.98.0。图形界面安装打开扩展面板CtrlShiftX / CmdShiftX搜索 Claude Code确认发布者是 Anthropic点安装。命令行安装code --install-extension anthropic.claude-code核心功能包括专用聊天面板、内联 Diff 审查、 提及文件和文件夹、多会话并行、Chrome 浏览器集成。常用快捷键聚焦输入框 CmdEsc / CtrlEsc新标签页 CmdShiftEsc / CtrlShiftEsc插入 文件 OptionK / AltK。推荐的settings.json配置{ claude-code.useTerminal: false, claude-code.initialPermissionMode: default, claude-code.autosave: true, claude-code.respectGitIgnore: true }4.2 JetBrains 扩展安装JetBrains 系列IntelliJ IDEA、PyCharm、WebStorm、GoLand的扩展不捆绑 CLI必须先装 CLI 再装插件。第一步装 CLIcurl -fsSL https://claude.ai/install.sh | bash第二步配 PATH关键echo export PATH$HOME/.local/bin:$PATH ~/.zshrc source ~/.zshrc验证claude --version通过后第三步在 Settings → Plugins → Marketplace 搜索 Claude Code [Beta]发布者 Anthropic PBC安装后完全重启 IDE。第四步在 Settings → Tools → Claude Code [Beta] 的 Claude command 里填claude或完整路径如/Users/用户名/.local/bin/claude。JetBrains 常见问题报 Cannot launch Claude Code 是 PATH 没配好填完整路径即可nvm 用户找不到 claude 是因为 IDE 不继承 shell PATH同样填完整路径ESC 键无法中断是 Settings → Tools → Terminal 里取消 Move focus to the editor with Escape。4.3 桌面应用安装Anthropic 已发布 Claude Code Desktop。macOS 是.dmg支持 Intel 和 Apple SiliconWindows 是.exe/.msix64Linux 不提供桌面版只有 CLI。官方下载地址 https://claude.com/download 。重要前提必须有付费订阅Pro/Max/Team/Enterprise免费账号无法使用 Code 选项卡Windows 用户必须装 Git for Windows桌面版自带运行时无需单独装 Node.js 或 CLI。三大选项卡Chat 只能普通对话不能访问文件Cowork 能长时间自主代理任务但用云端虚拟机Code 能交互式编程、读写本地文件。桌面版核心特性包括并行多会话 Git Worktree 自动隔离、可视化 Diff、拖拽拼接面板、应用预览、三种运行环境本地/云端/SSH 远程、Computer Use。4.4 三步验证动作第一步本地命令自检claude --version和claude doctor都通过。第二步 IDE 内触发一次补全在 VS Code 或 JetBrains 里打开一个文件用快捷键唤起 Claude Code 面板输入一个简单请求如「解释这个函数」看是否返回。第三步 CI 中跑通一次非交互调用见下一节。5. CI/CD 无交互配置与常见报错排查5.1 Docker 与 GitHub Actions 配置Docker 场景FROM node:22-alpine RUN npm install -g anthropic-ai/claude-code ENV CLAUDE_CODE_CI_MODEtrue ENTRYPOINT [claude, -p]GitHub Actions 场景- name: Install Claude Code run: npm install -g anthropic-ai/claude-code - name: Run Code Review env: ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }} ANTHROPIC_BASE_URL: https://taotoken.net/api run: | git diff origin/main...HEAD | claude -p \ Review this diff for bugs and security issues \ --output-format json review.json关键 CI 参数-p prompt非交互单次提示--output-format json结构化 JSON 输出--dangerously-skip-permissions跳过交互确认仅 CI--max-turns N限制代理迭代次数--allowedTools Read,Grep,Glob限制可用工具。5.2 真实报错对照排查401 认证失败Key 无效或 Base URL 配错。检查auth.json里的apiKey和baseUrl是否与 TaoToken 控制台一致注意 Base URL 不要带尾部斜杠。CI 里确认 secrets 注入成功。local proxy failed本地代理配置冲突。检查环境变量HTTP_PROXY/HTTPS_PROXY是否指向了不可用的地址CI 环境通常不需要代理清掉即可。reading choices 报错响应格式解析失败通常是 Base URL 指向了非兼容接口。确认用的是https://taotoken.net/api而不是其他路径Model ID 填对。OAuth 相关报错SSH 远程环境无法打开浏览器。按c复制认证 URL 到本地浏览器授权后粘贴回终端。CI 环境不要用 OAuth改用auth.json。command not foundPATH 没配。macOS 加到~/.zshrcLinux 加到~/.bashrcWindows 关闭重开终端。多次安装冲突npm native Homebrew 多个版本共存。先清理再重装npm uninstall -g anthropic-ai/claude-code brew uninstall --cask claude-code which -a claude claude doctor curl -fsSL https://claude.ai/install.sh | bashmacOS Gatekeeper 阻止系统设置 → 隐私与安全性 → 点击仍要打开或xattr -dr com.apple.quarantine /opt/homebrew/bin/claudenpm EACCES 权限被拒改用 Native 安装器完全不需要 npm。Windows Git is required装 Git for Windows 并重启应用。Windows 执行策略限制Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser。TLS 连接错误更新 CA 证书sudo apt-get install ca-certificates企业代理场景设export NODE_EXTRA_CA_CERTS/path/to/corp-ca.pem。5.3 更新与卸载更新claude doctor查看自动更新状态claude update手动触发指定版本curl -fsSL https://claude.ai/install.sh | bash -s -- 2.1.100。禁用自动更新在 settings.json 里设env: { DISABLE_AUTOUPDATER: 1 }。卸载Native 安装rm -f ~/.local/bin/claude rm -rf ~/.local/share/claudeHomebrewbrew uninstall --cask claude-codeWinGetwinget uninstall Anthropic.ClaudeCodenpmnpm uninstall -g anthropic-ai/claude-code。清除全部配置rm -rf ~/.claude rm -f ~/.claude.json注意这会删除所有设置、已授权工具、MCP 配置和会话历史。6. 按场景选对入口把三件套配到位装 Claude Code 最容易犯的错是把三种形态当成三套独立系统。实际上 CLI 是底座IDE 扩展和桌面应用都依赖它认证和权限配置是共享的配一次三处通用。我的建议是先在本地把 CLI 装好、claude doctor跑通、claude -p hello验证认证再去装 IDE 扩展最后配 CI。三件套Base URL、API Key、Model ID对齐是核心。本地开发用 OAuth 或 API Key 都行CI 必须用auth.json做无交互认证。如果你需要在多个项目和流水线之间共享额度、统一管理 Key用 TaoToken 的兼容接口会省事很多接入文档在 https://taotoken.net/doc 模型对话调试在 https://taotoken.net/chat 长期编码和 Agent 场景可以看 Coding Plan https://taotoken.net/coding-plan 。最后给个实用技巧把~/.claude/settings.json里的permissions.allow按项目需要收紧比如只允许Bash(npm:*)和Read(/tmp/**)避免代理误操作生产文件。CI 里务必加--max-turns和--allowedTools限制别让它在流水线里无限迭代。装完跑一遍三步验证本地命令自检、IDE 内触发补全、CI 非交互调用三个都过就算落地了。