Claude Code 安装踩坑实录

文章目录Claude Code 安装踩坑实录一、winget 安装此路不通二、npm 安装小心仿冒包三、首次启动模型访问错误四、诊断工具claude doctor五、配置探索5.1 查看配置的方式5.2 通过 /config 完成的设置5.3 配置文件体系5.4 settings.json 配置结构5.5 CLI 启动参数速查5.6 子命令5.7 交互模式斜杠命令六、经验总结Claude Code 安装踩坑实录记录在 Windows 上安装 Claude Code 的完整过程包括走过的弯路和最终的解决方案。供后来者参考避免重复踩坑。一、winget 安装此路不通第一反应是用 Windows 自带的包管理器 winget 安装连续尝试了 7 次C:\Users\CXWNwinget install ClaudeCode 找不到与输入条件匹配的程序包。结论Claude Code不在 winget 仓库中无法通过winget install安装。不要在这条路上浪费时间。二、npm 安装小心仿冒包放弃 winget 后转向 npm直觉性地执行了npminstall-gclaude-code安装成功了但运行时提示┌─────────────────────────────────────────────────────────────┐ │ │ │ Wrong package! │ │ │ │ Please install the correct package: │ │ │ │ npm install -g anthropic-ai/claude-code │ │ │ │ Official package: │ │ https://www.npmjs.com/package/anthropic-ai/claude-code │ │ │ └─────────────────────────────────────────────────────────────┘npm 上存在一个非官方仿冒包claude-code安装后命令是claude-code运行就会提示 “Wrong package!”。正确做法先卸载仿冒包再装官方包npmuninstall-gclaude-codenpminstall-ganthropic-ai/claude-code注意正确的包名是anthropic-ai/claude-code带anthropic-ai/前缀安装后的命令是claude不是claude-code。安装完成后验证C:\Users\CXWNclaude --version 2.1.74 (Claude Code)三、首次启动模型访问错误安装成功后在项目目录中启动 Claude CodeG:\workspace\git\temp\case-01claude界面正常显示了欢迎画面显示Opus 4.6 · API Usage Billing但输入任何内容都报错● Theres an issue with the selected model (claude-opus-4-6). It may not exist or you may not have access to it. Run /model to pick a different model.尝试用/model切换模型包括 opus、sonnet、Default每个都报同样的错误。甚至出现了带[1m]ANSI 转义码的异常模型 IDSet model to opus[1m] (claude-opus-4-6[1m])原因分析API Key 对应的账户暂时无法访问所选模型可能是权限问题或网络波动。解决多次重试后恢复正常能够正常对话❯ 你是谁啊 ● 我是 Claude CodeAnthropic 的官方命令行工具。我使用的模型是 Claude Opus 4.6。这类模型访问错误通常是临时性的重新启动 Claude Code 或等待片刻后重试即可。四、诊断工具claude doctor遇到问题时可以运行claude doctor进行健康检查G:\workspace\git\temp\case-01claude doctor Diagnostics └ Currently running: npm-global (2.1.74) └ Path: D:\Toolkit\Nodejs\node.exe └ Invoked: C:\Users\CXWN\AppData\Roaming\npm\node_modules\anthropic-ai\claude-code\cli.js └ Config install method: unknown └ Search: OK (vendor) Updates └ Auto-updates: enabled └ Update permissions: Yes └ Auto-update channel: latest └ Stable version: 2.1.58 └ Latest version: 2.1.74从诊断信息可以看到安装方式为 npm 全局安装npm-globalNode.js 路径为D:\Toolkit\Nodejs\node.exeClaude Code 的实际位置在C:\Users\CXWN\AppData\Roaming\npm\node_modules\anthropic-ai\claude-code\cli.js自动更新已启用当前版本已是最新2.1.74五、配置探索成功运行后开始探索 Claude Code 的配置体系。5.1 查看配置的方式交互模式中输入/config打开配置界面CLI 中运行claude config list查看配置注意该命令在某些版本中可能返回错误直接查看配置文件%USERPROFILE%\.claude\settings.json5.2 通过 /config 完成的设置❯ /config ⎿ Set response language to 简体中文 Enabled auto-connect to IDE设置了两项响应语言→ 简体中文自动连接 IDE→ 已启用5.3 配置文件体系文件路径说明全局设置~/.claude/settings.json所有项目生效项目设置.claude/settings.json仅当前项目优先级更高全局 MCP~/.claude/mcp.json全局 MCP 服务器配置项目 MCP.claude/mcp.json项目级 MCP 服务器配置5.4 settings.json 配置结构{ model: opus, // 默认模型 (opus / sonnet / haiku) language: 简体中文, // 响应语言 env: { // 环境变量 ANTHROPIC_API_KEY: ..., // API 密钥 ANTHROPIC_BASE_URL: ..., // 自定义 API 地址 ANTHROPIC_MODEL: ..., // 模型 ID API_TIMEOUT_MS: 300000, // API 超时毫秒 CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: 1, // 禁用遥测 CLAUDE_CODE_LOG_LEVEL: debug // 日志级别 }, permissions: {}, // 权限规则 hooks: {} // 钩子配置 }5.5 CLI 启动参数速查核心参数参数说明-p, --print非交互模式输出后退出适合管道-c, --continue继续最近一次对话-r, --resume [id]通过 session ID 恢复对话--model model指定模型如 opus、sonnet--effort level推理深度low / medium / high / max权限控制参数说明--permission-mode mode权限模式default / acceptEdits / plan / dontAsk / auto / bypassPermissions--allowed-tools tools允许的工具如Bash(git:*) Edit--disallowed-tools tools禁止的工具系统提示 输入输出参数说明--system-prompt prompt自定义系统提示--append-system-prompt prompt追加系统提示--output-format format输出格式text / json / stream-json会话管理参数说明--session-id uuid指定会话 ID--fork-session恢复时创建新会话分支--no-session-persistence禁用会话持久化工具 扩展参数说明--tools tools指定可用工具禁用全部--mcp-config configs加载 MCP 服务器配置文件--plugin-dir paths加载插件目录Agent 工作区参数说明--agent agent指定 agent-w, --worktree [name]创建 git worktree 隔离工作区--add-dir dirs添加额外的可访问目录调试 其他参数说明-d, --debug [filter]调试模式如api,hooks--verbose详细模式--max-budget-usd amountAPI 消费上限美元仅--print--fallback-model model主模型过载时的备用模型--ide自动连接 IDE5.6 子命令命令说明claude auth管理认证claude mcp管理 MCP 服务器claude agents列出已配置的 agentsclaude plugin管理插件claude doctor健康检查claude update检查并安装更新claude install [target]安装指定版本claude setup-token配置长期认证令牌5.7 交互模式斜杠命令命令说明/config打开配置界面/model切换模型/help帮助/clear清除上下文/compact压缩对话/cost查看当前会话花费/fast切换快速模式六、经验总结踩坑点教训winget 安装Claude Code 不在 winget 仓库别浪费时间npm 仿冒包正确包名是anthropic-ai/claude-code不是claude-code命令名安装后命令是claude不是claude-code模型错误“There’s an issue with the selected model” 通常是临时问题重试即可诊断工具遇到问题先跑claude doctor配置文件全局配置在%USERPROFILE%\.claude\settings.json