Claude Code 常见问题

排查前建议先运行 claude doctor，它会检查安装状态和配置文件格式，并给出修复建议。

安装与更新

安装后提示命令未找到

安装完成后需要打开一个新的终端窗口再运行 claude。仍然找不到命令，说明安装目录没有加入 PATH。官方安装脚本会把 claude 安装到：

macOS/Linux：~/.local/bin
Windows：%USERPROFILE%\.local\bin

macOS/Linux（使用 bash 时把 ~/.zshrc 换成 ~/.bashrc）：

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Windows：在「系统属性 → 环境变量」中，把 %USERPROFILE%\.local\bin 添加到用户变量 Path，然后重新打开终端。

安装命令报错

PowerShell 提示 The token '&&' is not a valid statement separator：你在 PowerShell 中运行了 CMD 命令，改用 irm https://claude.ai/install.ps1 | iex
CMD 提示 'irm' is not recognized：你在 CMD 中运行了 PowerShell 命令，改用 CMD 安装命令
curl 报错、返回 403 或 syntax error near unexpected token '<'：通常是网络无法访问 claude.ai，请检查网络，或改用 Homebrew、WinGet 安装

如何更新 Claude Code

配置了 CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC 后自动更新会关闭，需要手动更新：

claude update

Homebrew 安装的运行 brew upgrade claude-code，WinGet 安装的运行 winget upgrade Anthropic.ClaudeCode。

Windows 需要安装 Git 吗

不是必须的。未安装 Git for Windows 时，Claude Code 使用 PowerShell 执行命令；安装 Git for Windows 后改用 Git Bash，兼容性更好。已安装 Git 但 Claude Code 找不到 Git Bash 时，在 settings.json 的 env 中指定路径：

{
  "env": {
    "CLAUDE_CODE_GIT_BASH_PATH": "C:\\Program Files\\Git\\bin\\bash.exe"
  }
}

配置问题

配置文件在哪里

macOS/Linux：~/.claude/settings.json
Windows：C:\Users\你的用户名\.claude\settings.json

该文件对所有项目生效。

请求地址要不要加 /v1

不要。Claude Code 使用 Anthropic 格式，会自动补全 /v1/messages，请求地址填：

https://www.jiji.cc

如何确认配置已生效

启动 claude 后输入 /status：

Anthropic base URL 显示 https://www.jiji.cc：请求地址已生效。没有这一行说明没有读取到请求地址
Auth token 显示 ANTHROPIC_AUTH_TOKEN：API Key 已生效。如果显示的是 Login method 和 claude.ai 账号，说明没有读取到 API Key

settings.json 中的配置优先级高于终端里 export 的同名环境变量，以 /status 显示为准。

API 连接失败

先在终端中直接测试请求地址和 API Key，把 your-api-key-here 换成你的 Key：

curl -sS -w '\n%{http_code}\n' -X POST "https://www.jiji.cc/v1/messages" \
  -H "Authorization: Bearer your-api-key-here" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model": "claude-opus-5-5", "max_tokens": 1, "messages": [{"role": "user", "content": "."}]}'

Invoke-RestMethod -Method Post -Uri "https://www.jiji.cc/v1/messages" `
  -Headers @{ "Authorization" = "Bearer your-api-key-here"; "anthropic-version" = "2023-06-01" } `
  -ContentType "application/json" `
  -Body '{"model": "claude-opus-5-5", "max_tokens": 1, "messages": [{"role": "user", "content": "."}]}'

返回以 {"id":"msg_ 开头的 JSON，或提示模型不存在：网络和 Key 都正常，请检查 settings.json
返回 401：API Key 无效，参考下方「API Key 无效」
连接超时或无法解析域名：检查网络，关闭代理后重试

启动时提示 Auth conflict 或 auth may not work as expected

你之前登录过 claude.ai 账号，同时又配置了 API Key。在 Claude Code 中运行 /logout 退出 claude.ai 账号，只保留 API Key 即可。

使用问题

已配置 API Key 仍要求登录

确认 ANTHROPIC_AUTH_TOKEN 写在用户目录的 ~/.claude/settings.json 中，而不是项目目录下的 .claude/settings.json。项目级配置要在首次引导和信任目录确认之后才会生效。

提示无法连接到 Anthropic 服务

出现 Unable to connect to Anthropic services 或 Failed to connect to api.anthropic.com 时，在 ~/.claude.json 中写入 "hasCompletedOnboarding": true，跳过首次登录引导。

该字段写在用户目录下的 ~/.claude.json，不是 ~/.claude/settings.json。不要覆盖 settings.json，否则 API Key 配置会丢失。

node -e 'const fs=require("fs"),f=require("os").homedir()+"/.claude.json";const j=fs.existsSync(f)?JSON.parse(fs.readFileSync(f,"utf8")):{};j.hasCompletedOnboarding=true;fs.writeFileSync(f,JSON.stringify(j,null,2))'

$f="$env:USERPROFILE\.claude.json"
$j=if (Test-Path $f) { Get-Content $f -Raw | ConvertFrom-Json } else { [pscustomobject]@{} }
$j | Add-Member -NotePropertyName 'hasCompletedOnboarding' -NotePropertyValue $true -Force
$j | ConvertTo-Json -Depth 100 | Set-Content $f -Encoding UTF8

未安装 Node.js 时，也可以用文本编辑器打开 ~/.claude.json，在最外层花括号内手动添加该字段。完成后重新运行 claude。

VS Code 扩展一直要求登录

VS Code 扩展的登录检查不读取 ~/.claude/settings.json，需要在 VS Code 用户设置中单独配置，参考在 VS Code 中使用。

如何切换模型

会话中切换：输入 /model，从列表中选择
启动时指定：claude --model claude-opus-5-5
设置默认模型：在 settings.json 的 env 中加入 "ANTHROPIC_MODEL": "claude-opus-5-5"

可用的模型 ID 以模型广场为准。

部分功能不可用

使用 API Key 时，以下依赖 claude.ai 账号的功能不可用，属于正常现象：

Remote Control（远程控制）
语音输入
Claude Code 网页版、Slack 集成等云端功能

常用命令

命令	说明
`claude`	启动交互式会话
`claude -p "问题"`	一次性问答
`claude -c`	继续最近的会话
`claude doctor`	检查安装和配置
`claude update`	更新到最新版本
`/status`	查看当前请求地址和凭证
`/model`	切换模型
`/logout`	退出 claude.ai 账号

错误排查

API Key 无效

确认 API Key 已完整复制，没有多余空格
确认使用的是 ANTHROPIC_AUTH_TOKEN，不是 ANTHROPIC_API_KEY
确认 Key 所在分组包含 Claude 模型，账户余额充足
确认请求地址是 https://www.jiji.cc（不带 /v1）

SSL 证书错误

出现 SSL certificate verification failed 或 Self-signed certificate detected，通常是公司网络或代理软件拦截了 HTTPS 连接。关闭代理后重试，或联系网络管理员。

仍未解决？

提交工单

以上方法都无法解决时，请提交工单联系我们

快速开始

账户与计费

Claude Code

Claude Desktop

Codex

Gemini CLI

更多客户端

帮助中心

Claude Code 常见问题

安装与更新

配置问题

使用问题

错误排查

仍未解决？

提交工单

​安装与更新

​配置问题

​使用问题

​错误排查

​仍未解决？

提交工单

安装与更新

配置问题

使用问题

错误排查

仍未解决？