Claude Code 学习站
v2.1.201

FAQ / 问题排查

按主题分组的常见问题速查。如果你的问题没在这里,欢迎提 issue。

本页目录6

安装问题

npm install -g 报 EACCES 权限错误?

不要 sudo。改 npm 全局目录到家目录:

mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc
npm install -g @anthropic-ai/claude-code

claude: command not found(装完之后)

PATH 没生效。检查:

npm config get prefix
# 比如输出 /home/you/.npm-global
ls /home/you/.npm-global/bin/claude

把那个 bin 加到 PATH,重启终端。

Node 版本太低

node --version
# 低于 v18 就升级

推荐用 nvm 或 fnm 装 Node 20+ LTS。

WSL 里 claude 跑的是 Windows 的 Node?

WSL 会继承 Windows 的 PATH,可能命中 Windows 版 Node 导致异常。在 ~/.bashrc 里把 Linux 的 Node 提到最前:

export PATH="$HOME/.nvm/versions/node/$(nvm current)/bin:$PATH"

重开终端后再装 / 运行 claude。

公司网络 / 代理环境下安装器卡住?

先给终端设置代理,再重新跑安装:

export HTTPS_PROXY=http://proxy.example.com:port

国内网络同理,代理地址换成本地代理(如 http://127.0.0.1:7890),配置方式见下方「网络与代理」一节。

报 SELF_SIGNED_CERT_IN_CHAIN 或其他 TLS 证书错误?

公司网络常见 —— 让 Node 信任公司 CA 证书:

export NODE_EXTRA_CA_CERTS=/path/to/company-ca.pem

写进 ~/.zshrc / ~/.bashrc 长期生效。

登录与鉴权

OAuth 在服务器(没有浏览器)上跑不通

切到 API Key 模式:

export ANTHROPIC_API_KEY=sk-ant-xxx
claude

也可以写进 ~/.zshrc 或者用 .env 工具加载。

用了订阅但还是计费?

检查当前账号:

> /login

会显示当前登录身份。如果有 ANTHROPIC_API_KEY 环境变量,Claude 会优先用 API Key —— 临时 unset ANTHROPIC_API_KEY 再启动。

怎么切换账号?

> /logout

之后重新 claude 会重新走登录流程。

/login 打开了浏览器,但终端一直等不到回调?

改走手动流程:复制终端里显示的登录 URL,在任意浏览器完成登录,再把返回的 code 粘贴回终端。

国内网络环境下建议先按「网络与代理」一节给终端配好代理再重试;仍不行就直接用上面的手动粘贴流程。

设置了 ANTHROPIC_API_KEY 还是提示未认证?

依次排查:

echo $ANTHROPIC_API_KEY
  1. 确认变量在当前 shell 里确实存在;
  2. 确认 Claude Code 已批准使用该 key;
  3. 确认你的组织没有强制 SSO(强制 SSO 的组织不能用 API Key)。

都排查完仍不行,跑 claude doctor 生成诊断报告,提交支持工单时附上。

额度与套餐

用 Pro 还是 Max?

Pro 和 Max 的额度同时覆盖 Claude(网页/App)和 Claude Code。官方没有公布每档的具体用量数字,但升级路径明确:经常撞限、要跑更大的仓库,就从 Pro 升 Max 5x;还不够再升 Max 20x。建议先从 Pro 用起,实际撞限了再升级 —— 撞限时也可以选择等待重置,或临时切 API 按量付费。

网页版 Claude 和 Claude Code 共享额度吗?

共享。官方说明:Pro/Max 的用量限制在 Claude 和 Claude Code 之间是同一份,两边的所有活动都计入同一个额度。网页端聊得多,Claude Code 可用的就少,反之亦然。

额度是怎么消耗的?为什么长会话烧得快?

每一轮都会把三样东西发给模型:之前的完整对话、项目上下文(CLAUDE.md、读过的文件)、你的新提问。其中"对话历史"增长最快,所以会话越长每轮消耗越大。官方给的省额度手段:

> /compact   # 压缩历史,释放上下文
> /clear     # 开新对话(项目记忆保留)
> /context   # 查看当前上下文里装了什么

怎么查当前用量和剩余额度?

订阅用户(Pro/Max)看剩余额度:

> /status

API Key 用户看当前会话花了多少钱:

> /cost

API Key 的消费也可以在 Console 后台按 key 查看。看单轮对话的 token 明细则用 /usage(见下方「性能 / 上下文」节)。

被限额(rate limit)了怎么办?

先上 status.claude.com 确认不是服务端故障。确认是自己额度用完后,官方给的选项:

  1. 等额度窗口重置
  2. /model 切到更省额度的模型(Sonnet / Haiku)
  3. 开启 usage credits 继续用 —— 按标准 API 价格计费,且需要你明确同意才会开始扣费
  4. 升级套餐(Pro → Max 5x → Max 20x)
  5. 切 API Key 按量付费

订阅和 API Key,到底扣哪边的钱?

只要环境里有 ANTHROPIC_API_KEY,Claude Code 就会优先用它,费用按 API 单独计费,不走订阅额度。想用订阅:unset ANTHROPIC_API_KEY 后再启动,并用 /login 选择正确的账号。另外,撞限后开启的 usage credits 也是按标准 API 价格计费,和 Pro/Max 套餐费是两回事。

Opus / Sonnet / Haiku 怎么选?

官方定位:Sonnet 是默认,快、能干、省额度;Opus 推理更深,但消耗明显更多额度;Haiku 最快最便宜,适合快速查询。会话中用 /model 切换,切换不会清空对话。官方建议的省额度打法:用 Opus 做计划、用 Sonnet 执行;自动化流程(比如 CI 里的 review)直接 claude --model sonnet 降成本。

权限与工具

每次工具调用都问我,太烦

在 ~/.claude/settings.json 或项目 .claude/settings.json 里 allow 常用工具:

{
  "permissions": {
    "allow": [
      "Read(**)",
      "Grep(**)",
      "Glob(**)",
      "Bash(npm test:*)",
      "Bash(git status:*)"
    ]
  }
}

模式参考 docs.claude.com。

怎么知道 Claude 用了哪些工具?

启动加 --verbose,或者会话中说 /transcript 查看完整日志。

怎么阻止 Claude 跑某些命令?

用 PreToolUse hook(详见 Hooks),命令匹配后退出码 2 即可阻止。

网络与代理

中国大陆访问慢 / 失败

为 Node 设置代理:

export HTTPS_PROXY=http://127.0.0.1:7890
export HTTP_PROXY=http://127.0.0.1:7890
claude

把它写进 ~/.zshrc 一劳永逸。

用第三方网关(中转)

把 base URL 改到中转:

export ANTHROPIC_BASE_URL=https://your-gateway.example.com
export ANTHROPIC_API_KEY=sk-your-relay-key

注意要确认中转方支持 Claude Code 的完整 API(messages、streaming、tools、cache_control)。

性能 / 上下文

上下文用得很快怎么办?

  • 用 agent 做长任务,主上下文只拿结论(参考 子代理)
  • 大文件用 Read offset/limit 分段读,不要一次性塞
  • 定期 /clear 清掉无关的早期消息
  • 在 CLAUDE.md 写清楚项目结构,减少 Claude 探索成本

响应慢

检查:

  1. 网络延迟(curl -w '%{time_total}\n' https://api.anthropic.com 看 RTT)
  2. 上下文长度 —— 越长越慢,考虑 /clear 或开新会话
  3. Bash 命令本身慢(测试、build),用 run_in_background 异步跑

Token 用量怎么看?

> /usage

显示当前会话和今日累计的 token 用量。

回到 首页 →