Claude Code 錯誤碼排查

先分清錯誤發生在哪一層

INSTALL

安裝 / 執行時

command not found、Node 版本、npm 許可權、WSL 路徑和原生安裝器問題。

AUTH

登入 / 認證

OAuth 回撥、API key、Console 組織、SSO 和本地 auth 狀態問題。

NETWORK

網路 / 代理

企業代理、防火牆、證書、超時、403/429 和必需域名不可達。

常見錯誤與處理

claude: command not found

常見原因: 安裝目錄沒有加入 PATH, 或當前 shell 還沒重新載入配置。

處理: 開啟新終端, 或把 Claude Code 安裝目錄加入 PATH 後重新載入 shell 配置。

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

Node version not supported / silent crash

常見原因: Node 版本低於官方要求, 或 WSL 呼叫了 Windows 側 Node。

處理: 升級 Node, 或使用官方 native installer。WSL 下用 which node / which npm 確認路徑來自 Linux 環境。

node -v
which node
which npm

EACCES / permission denied

常見原因: 全域性 npm 目錄歸 root 所有, 或之前用 sudo 安裝導致許可權混亂。

處理: 不要用 sudo 安裝 Claude Code。改 npm prefix 到使用者目錄, 或使用 native installer。

npm config set prefix ~/.npm-global
export PATH="$HOME/.npm-global/bin:$PATH"

Waiting for authentication...

常見原因: 瀏覽器 OAuth 回撥沒有回到本機 CLI, 常見於 remote SSH、devcontainer、嚴格防火牆或 localhost 回撥被攔。

處理: 確認瀏覽器和 CLI 在同一臺機器可互通。必要時退出登入、重啟 Claude Code, 再重新完成認證。

/logout
# 關閉 Claude Code 後重新執行
claude

SELF_SIGNED_CERT_IN_CHAIN / certificate error

常見原因: 公司代理或安全網關注入了自籤 CA, Node 預設不信任該證書鏈。

處理: 讓 IT 提供公司 CA bundle, 並通過 NODE_EXTRA_CA_CERTS 指定。

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

proxy connection failed / timeout

常見原因: 代理變數寫錯、代理協議不支援、NO_PROXY 覆蓋了目標域名, 或企業防火牆阻斷。

處理: Claude Code 使用標準 HTTP/HTTPS proxy 環境變數; 官方說明不支援 SOCKS 代理。先用 HTTPS_PROXY 複測。

export HTTPS_PROXY=http://proxy.example.com:8080
echo $HTTPS_PROXY
echo $NO_PROXY

403 Forbidden

常見原因: 組織未啟用 Claude Code、企業 allowlist 未包含當前出口、帳號/地區/策略限制或代理被拒絕。

處理: 個人帳號先確認支援地區和帳號狀態; 企業帳號讓管理員檢查 Claude Code 許可權、SSO、IP allowlist 和防火牆。

429 / rate limit

常見原因: 請求過密、併發過高、帳號計劃限制或組織級限流。

處理: 降低外層併發, 停止迴圈重試, 等待恢復。不要用多 worker 包 Claude Code 做強行加速。

API key not recognized / SSO mismatch

常見原因: API key 來自另一個 shell、Console key 與 OAuth 會話衝突, 或組織要求 SSO 登入。

處理: 檢查 ANTHROPIC_API_KEY 是否來自當前 shell。組織帳號按管理員要求走 Console/SSO 登入。

echo $ANTHROPIC_API_KEY

代理和企業網路基線

官方文件說明 Claude Code 支援標準 HTTPS_PROXY / HTTP_PROXY / NO_PROXY 環境變數, 但不支援 SOCKS 代理。企業自簽證書需要通過 NODE_EXTRA_CA_CERTS 指定 CA bundle。

export HTTPS_PROXY=http://proxy.example.com:8080
export NO_PROXY="localhost,127.0.0.1"
export NODE_EXTRA_CA_CERTS=/path/to/company-ca.pem

最小復現流程

確認 `node -v` 滿足官方要求, 或使用 Claude Code native installer。
關閉外層指令碼和 worker, 只在一個終端視窗執行 `claude`。
用 `echo $HTTPS_PROXY`、`echo $NO_PROXY` 確認代理變數沒有寫錯。
訪問 api.anthropic.com、claude.ai、statsig.anthropic.com、sentry.io 是否被防火牆允許。
如果是登入卡住, 執行 `/logout` 後重啟 Claude Code, 必要時清理本地 auth 檔案再重新登入。

官方依據

Claude Code 企業網路配置

代理、CA、mTLS 和必需訪問 URL。

Claude Code 安裝與認證排障

官方列出的安裝、Node、許可權、代理和登入常見問題。

Claude Code 資料與遙測

Statsig、Sentry、/bug 和停用非必要流量的環境變數。

Claude Code FAQ

企業代理、Console 組織和常見許可權問題。