第 8 章：常见问题

curl 语法错误（syntax error near unexpected token '<'）：你可能在不支持管道安装脚本的 Shell 中运行了命令，请确认使用 Bash/Zsh（macOS/Linux/WSL）或 PowerShell（Windows）。

403 或 curl 网络错误：检查网络代理、防火墙，或尝试备用安装方式：

# Homebrew（macOS）
brew install --cask claude-code

# WinGet（Windows PowerShell）
winget install Anthropic.ClaudeCode

command not found：安装成功但 Shell 找不到 claude，通常是 PATH 未包含 ~/.local/bin（见下一条 FAQ）。

更多安装问题见官方 Troubleshooting。

不能。Claude Code 需要以下账号之一：

• Claude Pro 或 Max 个人订阅
• Team 或 Enterprise 团队/企业订阅
• Claude Console（API 预付费额度）
• Amazon Bedrock、Google Cloud Agent Platform、Microsoft Foundry 等第三方提供商

免费 Claude.ai 计划不包含 Claude Code 访问权限。可在 claude.ai 升级订阅，或在 Console 创建 API 账号。

推荐原生安装（curl -fsSL https://claude.ai/install.sh | bash）：

• 自动后台更新，始终较新版本
• 不依赖 Node.js 版本
• 二进制安装到 ~/.local/bin/claude，路径清晰

npm 方式（npm install -g @anthropic-ai/claude-code）：

• 需要 Node.js 22+
• 可能遇到 npm 全局目录权限问题
• 需手动 npm install -g @anthropic-ai/claude-code@latest 升级
• 切勿使用 sudo npm install -g

两种方式安装的是相同的原生二进制，运行时并不调用 Node.js。

原生安装器将 claude 放在 ~/.local/bin/claude（Windows 为 %USERPROFILE%\.local\bin\claude.exe）。若 Shell 报 command not found，需把该目录加入 PATH。

Bash / Zsh（macOS / Linux），在 ~/.bashrc 或 ~/.zshrc 中添加：

export PATH="$HOME/.local/bin:$PATH"

保存后重新加载：

source ~/.zshrc   # 或 source ~/.bashrc

验证：

which claude
claude --version

npm 全局安装时，PATH 需包含 npm 全局 bin 目录（npm config get prefix 查看）。

在 Claude Code 会话中输入：

/login

终端会打开浏览器认证流程，可切换 Pro/Max/Team/Console 等不同账号。若使用 ANTHROPIC_API_KEY 环境变量，Claude 会提示确认 Key 而非打开浏览器；切换 API Key 需更新环境变量后重启 claude。

Shell 中运行（不启动会话）：

claude doctor

输出只读诊断：安装健康、settings 文件校验、PATH、Search/ripgrep 状态、可用修复建议等。

会话内运行：

/doctor

自动化检查安装、设置、扩展与上下文用量，并可在你确认后应用部分修复。

若 claude 完全无法启动，优先用 Shell 的 claude doctor；会话内还可用 /mcp 检查 MCP 服务器状态。

按顺序排查：

1. 确认账号计划包含 Claude Code（非免费计划）
2. 运行 /login 或删除本地凭证后重新认证
3. 检查组织是否禁用了 Claude Code（Enterprise 策略）
4. 若使用 Bedrock/Foundry 等云提供商，确认凭证与环境变量配置正确
5. 运行 claude doctor 查看认证相关警告

账号与计费问题可登录 claude.ai → 左下角头像 → Get help 联系 Anthropic 支持。

按 Ctrl+C 尝试取消当前操作。若完全无响应，关闭终端并重新运行：

claude --resume

或在同目录用 claude -c 继续最近对话。重启不会丢失历史会话。