代理开着，为什么 Claude Code 还是连不上？

十有八九是把 HTTPS_PROXY 指到了 SOCKS 端口。官方明确：Claude Code 不支持 SOCKS 代理。代理客户端（Clash、V2Ray 等）要用 HTTP 代理端口，变量写成 http:// 协议头，例如 export HTTPS_PROXY=http://127.0.0.1:7890。另外注意端口号：混合端口通常兼容 HTTP，纯 SOCKS 端口不行。

改了代理环境变量为什么不生效？

环境变量在启动时读取一次，跑着的会话不会感知 shell 里后来的改动——改完必须退出重开 Claude Code。另外注意读取优先级是 https_proxy、HTTPS_PROXY、http_proxy、HTTP_PROXY 里第一个已设置的：小写变量会盖过大写，排查时用 env | grep -i proxy 把四个都看一遍。

装完提示 command not found: claude？

安装器把二进制放在 ~/.local/bin/claude（Windows 是 %USERPROFILE%\.local\bin），报这个错就是该目录不在 PATH 里。zsh 用户往 ~/.zshrc 追加 export PATH="$HOME/.local/bin:$PATH" 后 source 生效。另一个易混点：VS Code 扩展自带私有 CLI 副本、不会往 PATH 装 claude——只装了扩展的话终端里本来就没有这个命令，需要另跑标准安装。

提示 App unavailable in region 怎么办？

这是地区可用性判定，不是故障：Claude Code 在你所在国家/地区未提供服务，对照官方 supported countries 页面确认。国内用户请注意登录环境与账号地区的一致性和稳定性——频繁跳变 IP 是账号风控的高危因素，相关风险与安全使用清单见我们的封号避坑指南。

Claude Code 装不上、连不上排错指南（2026）：PATH、代理与证书一篇讲清

第一步永远是定位：网络、安装还是认证

「用不了」有三种完全不同的病因，一条命令先分诊：

curl -sI https://downloads.claude.ai/claude-code-releases/latest

结果	判断	下一步
HTTP/2 200	网络通	查安装（PATH / 二进制）或认证
403	代理/过滤器拦截，或地区不可用	查代理规则；对照 supported countries
5xx	服务端临时故障	等几分钟重试
无输出 / 超时 / 解析失败	网络被挡	配置代理（下一节）

代理配置：国内环境的核心一节

官方支持标准代理环境变量，装之前和运行时都认：

# 指向代理客户端的 HTTP 端口（Clash 系默认混合端口通常是 7890）
export HTTPS_PROXY=http://127.0.0.1:7890
export HTTP_PROXY=http://127.0.0.1:7890

# 内网直连白名单（空格或逗号分隔均可）
export NO_PROXY="localhost 192.168.1.1 .example.com"

# 然后再安装 / 启动
curl -fsSL https://claude.ai/install.sh | bash

四条规则，每条都对应一类疑难杂症：

不支持 SOCKS：官方明确写在文档里。socks5://127.0.0.1:xxxx 这种写法无效，代理客户端务必开 HTTP 端口并用 http:// 协议头。这是「明明有代理还连不上」的第一大根因。
启动时读一次：跑着的会话不感知 shell 里后改的变量——改完重启 Claude Code。
优先级：https_proxy → HTTPS_PROXY → http_proxy → HTTP_PROXY，取第一个已设置的。小写盖大写，排查用 env | grep -i proxy 四个全看。
回环不走代理：对 localhost / 127.0.0.0/8 的连接永不经代理，NO_PROXY 里不用写。

代理要账号密码就写进 URL（http://user:pass@proxy:8080）；NTLM / Kerberos 这类高级认证官方建议改走 LLM Gateway。所有变量也可以放 settings.json 的 env 块里，免得污染整个 shell。

证书问题：TLS 报错与公司内网

TLS connect error / unable to get local issuer certificate 一族的病根通常是 TLS 检查型代理的自签根证书不被信任。Claude Code 默认信任内置 Mozilla CA 集 + 操作系统证书库，两条修法：

# 法一：根证书装进系统信任库（推荐，装好即认）
# 法二：显式指定额外 CA 文件
export NODE_EXTRA_CA_CERTS=/path/to/company-root-ca.pem

注意一个版本细节：读取系统证书库需要运行时支持——原生安装版始终可以，npm 安装版要 Node 22.15+，更老的 Node 只认内置集和 NODE_EXTRA_CA_CERTS。信任来源可用 CLAUDE_CODE_CERT_STORE 显式控制（bundled / system / 两者）。

安装期高频错误对照

报错	原因与修法
command not found: claude	~/.local/bin 不在 PATH；zsh 往 ~/.zshrc 加 export PATH="$HOME/.local/bin:$PATH" 后 source。只装了 VS Code 扩展也会这样——扩展不往 PATH 装 CLI，需另跑标准安装
syntax error near unexpected token 或 curl 403	安装脚本被网络设备替换成了 HTML 拦截页；配好代理重下
exit code 137 / Killed	Linux 小内存机 OOM；加 swap 或换内存更大的机器装
npm error ENOTEMPTY	更新/重装时残留目录冲突；删掉报错提示的包目录重来
Error: claude native binary not installed	npm 装了包但原生二进制没落盘；按文档补全安装
cannot execute binary file（WSL）	WSL1 跑不了原生二进制；升级到 WSL2
App unavailable in region	非故障：地区不可用，对照 supported countries 页
OAuth error / 403 Forbidden	认证问题：确认登录的账号与套餐状态；参考文档 login and authentication 节

连上之后：运行期体检工具

/doctor：会话内自动体检安装、设置、扩展与上下文占用，给出修复建议、经你确认后执行；Claude Code 起不来就在 shell 里跑 claude doctor。
/mcp：MCP 服务器连接状态一览。
claude --safe-mode：怀疑插件 / MCP / hook 拖慢或搞挂会话时，用它临时禁用全部自定义项做对照实验。
CPU / 内存高：勤用 /compact、大构建目录进 .gitignore、任务间重启。
/heapdump 慎用：堆快照含完整对话与凭证，公开 issue 只附 -diagnostics.json，别传 .heapsnapshot。

国内用户的三条补充提醒

代理链路稳定比速度重要：频繁跳变出口 IP 是账号风控的高危因素，固定线路优于「哪个快用哪个」。详见封号避坑指南。
能跑通 curl 测试不等于万事大吉——安装、登录、API 调用走的域名不止一个，代理规则建议按域名后缀放行而不是逐条精确匹配。
公司电脑叠加了企业代理 + TLS 检查的，把本文代理与证书两节一起配齐，缺一个都会在不同阶段报错。

排错的正确顺序永远是「先分诊再下药」：一条 curl 定网络，一眼 PATH 定安装，一个 /doctor 定运行期。对照上面的表，绝大多数「装不上、连不上」十分钟内可以自己解决。