Claude Code OAuth 403 错误解决方案📢 重要说明本文档专门解决 OAuth 403 认证错误。

📢 重要说明

本文档专门解决 OAuth 403 认证错误。 如果您是第一次使用 Claude Code，建议先阅读：

👉 Claude Code macOS 通用安装指南

本文档适用场景

✅ 适用：

企业内网环境（需要配置公司代理服务器）
教育机构网络
需要通过 HTTP 代理访问互联网
遇到 OAuth error: Failed to fetch user roles: 403 错误
遇到 OAuth error: connect ECONNREFUSED 错误

❌ 不适用：

首次安装和基础使用 → 请看通用安装指南
普通家庭网络环境 → 请看通用安装指南

问题诊断

典型错误信息

如果您在登录时看到以下错误之一：

OAuth error: Failed to fetch user roles: Request failed with status code 403

或

OAuth error: connect ECONNREFUSED 127.0.0.1:PORT

这通常是网络代理配置问题。

根本原因

Claude Code 使用 OAuth 进行身份认证，需要访问 api.anthropic.com。在企业或教育网络中，通常需要通过 HTTP 代理服务器访问外部网络。

关键信息： Claude Code 仅支持 HTTP/HTTPS 代理，不支持 SOCKS 代理。

快速自检

在终端运行以下命令：

# 1. 检查系统代理配置
scutil --proxy

# 2. 测试网络连通性
curl -I https://api.anthropic.com

如果第二个命令失败，说明网络配置有问题。

解决方案

第一步：检查网络配置

1.1 查看系统代理设置

scutil --proxy

输出示例：

<dictionary> {
  HTTPEnable : 1
  HTTPPort : 7890
  HTTPProxy : 127.0.0.1
  HTTPSEnable : 1
  HTTPSPort : 7890
  HTTPSProxy : 127.0.0.1
}

重点关注：

HTTPPort - HTTP 代理端口（例如：7890）
HTTPProxy - 代理服务器地址（通常是 127.0.0.1）

💡 记下这个端口号，下一步会用到。

1.2 测试代理连通性

# 测试代理是否工作（替换 7890 为您的实际端口）
curl -x http://127.0.0.1:7890 -I https://api.anthropic.com

如果看到 HTTP/2 200，说明代理配置正确。

第二步：配置 CLI 环境

2.1 清理旧配置

# 清除环境变量
unset HTTP_PROXY
unset HTTPS_PROXY
unset http_proxy
unset https_proxy

# 删除旧凭证
rm -rf ~/.anthropic

2.2 设置代理环境变量

⚠️ 重要： 将下面的 7890 替换为您在第一步中找到的实际端口号。

export HTTP_PROXY="http://127.0.0.1:7890"
export HTTPS_PROXY="http://127.0.0.1:7890"
export NO_PROXY="localhost,127.0.0.1"

2.3 验证配置

# 验证环境变量
echo $HTTP_PROXY

# 测试连接
curl -I https://api.anthropic.com

应该看到 HTTP/2 200 响应。

2.4 重新登录

claude /login

浏览器会打开，完成登录流程。

第三步：配置 VS Code

VS Code 扩展需要单独配置代理环境变量。

3.1 清理 VS Code 扩展

# 删除旧扩展
rm -rf ~/.vscode/extensions/anthropic.claude-code*

# 清除缓存
rm -rf ~/Library/Application\ Support/Code/CachedData
rm -rf ~/Library/Application\ Support/Code/CachedExtensionVSIXs

在 VS Code 中卸载 Claude Code 扩展，然后完全退出（Cmd+Q）。

3.2 配置代理

重新打开 VS Code
按 Cmd+Shift+P
输入：Preferences: Open User Settings (JSON)
添加以下配置：

{
  "claudeCode.environmentVariables": [
    {
      "name": "HTTP_PROXY",
      "value": "http://127.0.0.1:7890"
    },
    {
      "name": "HTTPS_PROXY",
      "value": "http://127.0.0.1:7890"
    },
    {
      "name": "NO_PROXY",
      "value": "localhost,127.0.0.1"
    }
  ]
}

⚠️ 记得替换 7890 为您的实际端口。

3.3 重新安装扩展

保存 settings.json
按 Cmd+Q 完全退出 VS Code
重新打开 VS Code
安装 Claude Code 扩展
点击左侧 Claude 图标，应该可以直接使用

第四步：永久配置

避免每次打开终端都要重新设置环境变量。

4.1 添加到 Shell 配置文件

# 添加到 ~/.zshrc（macOS 默认 shell）
cat >> ~/.zshrc << 'EOF'

# Claude Code 代理配置
export HTTP_PROXY="http://127.0.0.1:7890"
export HTTPS_PROXY="http://127.0.0.1:7890"
export NO_PROXY="localhost,127.0.0.1"
EOF

如果使用 bash：

cat >> ~/.bash_profile << 'EOF'

# Claude Code 代理配置
export HTTP_PROXY="http://127.0.0.1:7890"
export HTTPS_PROXY="http://127.0.0.1:7890"
export NO_PROXY="localhost,127.0.0.1"
EOF

⚠️ 记得替换端口号。

4.2 重新加载配置

# zsh
source ~/.zshrc

# bash
source ~/.bash_profile

4.3 验证永久配置

打开新的终端窗口，运行：

echo $HTTP_PROXY

应该显示：http://127.0.0.1:7890

常见代理工具配置

不同的代理工具有不同的默认端口，这里列出常见工具的配置方法。

Clash / ClashX

默认端口： 7890

查看端口：

打开 Clash
设置 → 端口设置
查看 "HTTP 端口" 或 "Port"

V2RayU

默认端口： 1087

查看端口：

打开 V2RayU
偏好设置
查看 "HTTP 监听端口"

Shadowsocks

默认端口： 1087 或 8118

查看端口：

打开 Shadowsocks
偏好设置
HTTP 代理设置

Surge

默认端口： 6152

查看端口：

打开 Surge
设置
查看 HTTP Proxy Port

企业代理服务器

如果使用企业提供的代理服务器：

联系 IT 部门获取代理地址和端口
配置格式：http://代理地址:端口
例如：http://proxy.company.com:8080

故障排除

问题 1：ECONNREFUSED 错误

错误信息：

OAuth error: connect ECONNREFUSED 127.0.0.1:8118

原因： 端口号不正确。

解决方案：

运行 scutil --proxy 查找正确端口
更新环境变量中的端口号
重新登录

问题 2：代理工具未运行

诊断：

# 检查端口是否在监听（替换为您的端口）
lsof -i :7890

解决方案：

启动您的代理工具
确认 HTTP 代理已启用
重新测试连接

问题 3：仍然无法连接

可能原因：

代理工具只启用了 SOCKS 代理，未启用 HTTP 代理
防火墙阻止了连接
代理服务器地址错误

解决方案：

确认代理工具中 HTTP 代理 已启用（不只是 SOCKS）
检查防火墙设置
如果使用企业代理，联系 IT 部门确认配置

问题 4：网络环境切换

场景： 在公司和家里使用不同网络。

解决方案： 创建快速切换函数

添加到 ~/.zshrc：

# 启用代理
proxy_on() {
  export HTTP_PROXY="http://127.0.0.1:7890"
  export HTTPS_PROXY="http://127.0.0.1:7890"
  export NO_PROXY="localhost,127.0.0.1"
  echo "✓ Proxy enabled"
}

# 禁用代理
proxy_off() {
  unset HTTP_PROXY HTTPS_PROXY
  echo "✓ Proxy disabled"
}

使用：

proxy_on   # 在公司网络时
proxy_off  # 在家时

验证配置

CLI 验证

# 1. 检查环境变量
echo $HTTP_PROXY

# 2. 测试网络
curl -I https://api.anthropic.com

# 3. 测试 Claude Code
claude --version

VS Code 验证

打开 VS Code
点击 Claude 图标
发送测试消息
应该正常回复

诊断脚本

将以下内容保存为 diagnose.sh，快速诊断问题：

#!/bin/bash

echo "=== Claude Code 网络诊断 ==="
echo ""

echo "1. 系统代理设置："
scutil --proxy | grep -E "HTTP|HTTPS"
echo ""

echo "2. 环境变量："
env | grep -i proxy
echo ""

echo "3. 监听的端口："
for port in 7890 7891 1087 8118 6152; do
  if lsof -i :$port 2>/dev/null | grep -q LISTEN; then
    echo "✅ Port $port is active"
  fi
done
echo ""

echo "4. 测试连接："
if curl -s -I https://api.anthropic.com | grep -q "HTTP/2 200"; then
  echo "✅ 可以访问 Anthropic API"
else
  echo "❌ 无法访问 Anthropic API"
fi
echo ""

echo "5. Claude Code 版本："
claude --version 2>&1
echo ""

echo "诊断完成！"

运行：

chmod +x diagnose.sh
./diagnose.sh

Claude Code OAuth 403 错误解决方案

📢 重要说明

本文档适用场景

问题诊断

典型错误信息

根本原因

快速自检

解决方案

第一步：检查网络配置

1.1 查看系统代理设置

1.2 测试代理连通性

第二步：配置 CLI 环境

2.1 清理旧配置

2.2 设置代理环境变量

2.3 验证配置

2.4 重新登录

第三步：配置 VS Code

3.1 清理 VS Code 扩展

3.2 配置代理

3.3 重新安装扩展

第四步：永久配置

4.1 添加到 Shell 配置文件

4.2 重新加载配置

4.3 验证永久配置

常见代理工具配置

Clash / ClashX

V2RayU

Shadowsocks

Surge

企业代理服务器

故障排除

问题 1：ECONNREFUSED 错误

问题 2：代理工具未运行

问题 3：仍然无法连接

问题 4：网络环境切换

验证配置

CLI 验证

VS Code 验证

诊断脚本

总结

核心步骤

关键点

参考资源