cc-proxy

本地 HTTPS 代理服务，通过 hosts 文件拦截 api.anthropic.com 的请求并转发到任意上游 API。

只允许本机（127.0.0.1）访问，外部 IP 一律拒绝。

快速开始

只需两步：

# 步骤 1: 全局安装代理
npm install -g @chuckray/cc-proxy

# 步骤 2: 首次运行（需要 sudo）
sudo ccp
# → 如果未安装 mkcert，会提示安装命令
# → 安装后重新运行 sudo ccp
# → 输入上游 API 地址（如 https://your-api.example.com）
# → 代理启动运行

之后每次启动都只需 sudo ccp，可选覆盖上游地址。

卸载：sudo ccp uninstall

依赖

• Node.js >= 14.0.0
• mkcert（用于生成本地受信任证书）

安装

只需一条命令：

npm install -g @chuckray/cc-proxy

首次运行时会自动检查 mkcert，如果未安装会提示安装命令。

使用

首次运行

sudo ccp

首次运行时会自动完成以下步骤：

1. 检查 mkcert（未安装会提示）
2. 显示工作原理说明
3. 生成 mkcert 本地 CA 和证书
4. 配置 NODE_EXTRA_CA_CERTS 全局环境变量
5. 修改 /etc/hosts，添加 127.0.0.1 api.anthropic.com
6. 要求输入上游 API 地址
7. 启动代理，监听 HTTPS 443 端口

后续每次运行

sudo ccp

会提示输入上游地址，可以：

• 按 Enter：使用上次保存的地址（默认值）
• 输入新地址：覆盖之前的配置

卸载代理

sudo ccp uninstall

会自动：

• 移除 NODE_EXTRA_CA_CERTS 配置
• 还原 /etc/hosts
• 删除证书文件
• 删除配置目录

为什么需要 sudo？

代理需要监听端口 443（HTTPS 标准端口）来拦截客户端对 api.anthropic.com 的 HTTPS 请求。只有 root 用户才能监听 1024 以下的系统保留端口，所以必须用 sudo 启动。

工作原理

1. 修改 hosts：127.0.0.1 api.anthropic.com

   • 这样 DNS 会将 api.anthropic.com 解析到本机

2. 生成证书：使用 mkcert 创建本地 CA 和自签名证书

   • 证书 CN（Common Name）设置为 api.anthropic.com

3. 系统信任证书：通过 NODE_EXTRA_CA_CERTS 配置让 Node.js 信任该证书

   • 这样 Node.js 应用（如 Claude Code）就能信任代理提供的证书

4. 监听请求：代理监听 HTTPS 443 端口

   • 客户端尝试连接 api.anthropic.com:443 时，实际连接到本机代理

5. 转发请求：代理将请求转发到配置的上游 API

   • 上游返回结果，代理转发回客户端

配置

配置文件存储在 ~/.cc-proxy/config.json，包含：

• upstream: 上游 API 地址
• installed: 是否已安装
• installedAt: 安装时间
• 证书路径信息

用户一般不需要手动编辑此文件，使用 ccp 命令时会交互式设置。

认证

代理自动检测请求中的认证方式（Authorization: Bearer 或 x-api-key），并以相同方式原样转发给上游，不做任何修改。

用户应在 Claude Code 等客户端配置自己的 API Key。

安全

• 本地访问限制：只允许来自 127.0.0.1 和 ::1 的请求，外部 IP 一律拒绝（403）
• 请求大小限制：最大 10MB，防止 DoS
• 请求超时：30 秒，防止长时间挂起
• Token 原样转发：代理不修改认证信息

常见问题

Q: 为什么需要 sudo？

A: 代理需要监听端口 443（HTTPS 标准端口）。只有 root 用户才能监听 1024 以下的系统保留端口。不使用 sudo 会得到权限错误提示。

Q: Node.js 应用仍报 self-signed certificate 错误？

A: 确保已运行过 sudo ccp（首次会自动 setup），然后重启该应用。

Q: 端口 443 已被占用怎么办？

# 1. 查找占用进程
sudo lsof -i :443

# 2. 关闭该程序
# 3. 重新运行代理
sudo ccp

Q: 上游 API 无法连接？

检查配置文件中的上游地址是否正确：

cat ~/.cc-proxy/config.json

或者重新运行 sudo ccp 输入正确的地址。

Q: 如何修改上游地址？

直接运行 sudo ccp，在提示时输入新地址即可。

许可

MIT