# claude_cli_patch

**Repository Path**: liushizhan/claude_cli_patch

## Basic Information

- **Project Name**: claude_cli_patch
- **Description**: claude_cli_patch
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-26
- **Last Updated**: 2026-04-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Claude CLI Proxy Patch

通过海外代理服务器中转 Claude CLI 的所有流量，绕过 IP 地域限制，让受限地区的 Claude Max / Pro 订阅用户正常使用 CLI。

## 原理

Claude CLI 有两条独立的 HTTP 通道，需要分别处理：

```
客户端 Claude CLI
  |
  |-- API 调用 (/v1/messages 等)
  |     SDK 客户端，读取 ANTHROPIC_BASE_URL
  |     --> 反向代理 (HTTP) --> api.anthropic.com
  |
  |-- OAuth 登录 (token exchange, create_api_key, roles)
  |     原生 axios，用绝对 HTTPS URL，走 https.globalAgent
  |     --> CONNECT 隧道 --> platform.claude.com / api.anthropic.com
  |
  代理服务器 (海外)
```

### 为什么需要两条通道

| 通道 | 触发方式 | 原因 |
|---|---|---|
| 反向代理 (HTTP) | `ANTHROPIC_BASE_URL` 环境变量 | SDK 客户端读取此变量，将 API 请求发到代理 |
| CONNECT 隧道 (HTTPS) | 替换 `https.globalAgent` | OAuth 请求用裸 axios + 绝对 URL + `proxy:false`，不受任何环境变量控制 |

### 逆向发现的关键点

1. **OAuth axios 实例** (`$1`) 使用全局默认 axios，`proxy:false`，不设 agent，不读 `HTTPS_PROXY`。只有替换 `https.globalAgent` 才能在底层拦截。

2. **`anthropic-beta: oauth-2025-04-20`** 是 OAuth 认证的必需 header。CLI 动态计算 beta headers，代理必须透传而不能覆盖。

3. **`CLAUDE_CODE_CUSTOM_OAUTH_URL`** 有白名单校验，只允许 3 个特定域名，无法用来重定向 OAuth。

4. **ESM 兼容性**：CLI 是 ESM 模块，Node.js v18+ 的 ESM 中 `require()` 未定义。Bootstrap 必须使用 `import` 语法。

## 架构

```
                      代理服务器 (claude-proxy.mjs)
                      监听 8080，单端口双模式

  客户端                模式 1: 反向代理 (HTTP)
  ──────────────────    ─────────────────────────
  ANTHROPIC_BASE_URL    /v1/*        --> api.anthropic.com
  (API 调用)            /oauth/*     --> platform.claude.com
                        /v1/oauth/*  --> platform.claude.com
                        其他         --> api.anthropic.com

  客户端                模式 2: CONNECT 隧道 (HTTPS)
  ──────────────────    ─────────────────────────
  https.globalAgent     TCP 管道透传，TLS 端到端加密
  (OAuth 流程)          白名单: api.anthropic.com,
                        platform.claude.com, claude.ai 等
```

## 文件说明

| 文件 | 部署位置 | 说明 |
|---|---|---|
| `claude-proxy.mjs` | 代理服务器 | Node.js 双模代理 (反向代理 + CONNECT 隧道) |
| `patch-claude-cli.py` | 客户端执行 | 交互式工具：注入 bootstrap + 配置环境变量 |

## 部署步骤

### 1. 服务端 (海外服务器)

**要求**：Node.js v18+，有公网 IP，防火墙放行 8080 端口。

```bash
# 启动代理
nohup node claude-proxy.mjs --port 8080 > claude-proxy.log 2>&1 &

# 验证
curl -s -o /dev/null -w "%{http_code}" http://localhost:8080/v1/messages
# 应返回 405 (正常，说明代理可达)
```

### 2. 客户端 (受限地区的机器)

**要求**：Python 3.6+，已安装 `claude-code` (`npm install -g @anthropic-ai/claude-code`)。

```bash
# 方式 1: 交互式
python3 patch-claude-cli.py
# 选择 1，回车确认代理地址

# 方式 2: 一键 patch
python3 patch-claude-cli.py --patch

# 方式 3: 自定义代理地址
python3 patch-claude-cli.py --patch http://your-server:8080
```

### 3. 使环境变量生效并登录

```bash
source ~/.zshrc   # macOS
# 或
source ~/.bashrc  # Linux

# 登录 (会通过代理完成 OAuth)
claude /login

# 使用
claude
```

### 4. 恢复原版

```bash
python3 patch-claude-cli.py --restore
```

## 环境变量说明

| 变量 | 是否需要 | 说明 |
|---|---|---|
| `ANTHROPIC_BASE_URL` | 需要 | 由 patch 脚本自动配置，API 调用走反向代理 |
| `HTTPS_PROXY` | **不要设** | 会与 bootstrap 的 globalAgent 冲突，导致 `UND_ERR_ABORTED` |
| `CLAUDE_CODE_CUSTOM_OAUTH_URL` | **不要设** | 白名单校验会拒绝自定义域名 |

## Patch 脚本功能

```
=======================================================
  Claude CLI 代理补丁 - 状态
=======================================================

  CLI 路径:    /Users/xxx/.nvm/versions/node/v23.3.0/lib/node_modules/@anthropic-ai/claude-code/cli.js
  CLI 版本:    2.1.84
  Patch 状态:  已注入 (代理: http://your-server:8080)
  备份文件:    ...cli.js.bak

  操作:
    1) 注入代理补丁 / 更新代理地址
    2) 恢复原版 (restore)
    3) 仅配置环境变量
    4) 仅清除环境变量
    5) 修改默认代理地址
    q) 退出
```

- 自动定位 CLI 安装路径 (nvm / fnm / Homebrew / pnpm / 系统全局)
- 注入前自动备份原版 `cli.js`
- 支持更新已有 patch 的代理地址
- 扫描并清理 `.bashrc` / `.bash_profile` / `.zshrc` / `.zprofile` 中的冲突配置
- 检测并警告 `HTTPS_PROXY` 等冲突环境变量
- 兼容 macOS (zsh) 和 Linux (bash)

## 代理服务器功能

- 单端口双模式：同时处理 HTTP 反向代理和 HTTPS CONNECT 隧道
- 按路径路由到不同上游域名
- 透传客户端 headers（特别是 `anthropic-beta` 和 `Authorization`）
- 清除暴露客户端环境的 headers（`x-stainless-*`、`x-forwarded-for` 等）
- CONNECT 隧道白名单，只允许 Anthropic 相关域名
- Node.js 实现，与 CLI 共享 TLS 指纹，无法从网络层面区分

## 注意事项

- **CLI 更新后需重新 patch**：`npm update -g @anthropic-ai/claude-code` 会覆盖 `cli.js`，需要重新运行 `patch-claude-cli.py`
- **代理服务器需保持运行**：CLI 每次使用都需要通过代理
- **仅供个人订阅用户使用**：需要有效的 Claude Max / Pro 订阅

## License

MIT