Claude Proxy 使用说明
====================

【软件简介】
Claude Proxy 是一个本地代理服务，让 Claude Desktop 能够使用私有模型。
无需安装任何环境，开箱即用。
开发者：YJ


【文件说明】
ClaudeProxy.exe     主程序（双击运行）
.env.template       配置文件模板（按说明填写后改名为 .env）
.env                配置文件（首次运行自动生成，需填写网关信息）
proxy.log           运行日志（自动生成）
cache.pkl           缓存文件（自动生成）
stats.json          统计数据（自动生成）


【首次使用步骤】

第一步：创建配置文件
  1. 将 .env.template 复制一份，重命名为 .env
     （或双击运行 ClaudeProxy.exe，程序会自动生成 .env 模板）
  2. 用记事本打开 .env，填写以下必填项：

     TARGET        = 你的网关地址（如 https://xxx.com/v1）
     API_KEY       = 你的网关 API Key
     PROXY_API_KEY = 自定义一个密码（后面填入 Claude Desktop）
     MODEL_SONNET  = 对应 claude-sonnet-4-5 的私有模型名
     MODEL_HAIKU   = 对应 claude-haiku-4-5 的私有模型名
     MODEL_OPUS    = 对应 claude-opus-4-5 的私有模型名

  3. 保存 .env 文件

第二步：启动代理
  双击 ClaudeProxy.exe，系统托盘出现图标即表示启动成功
  - 绿色图标 = 代理运行中（显示已运行时长）
  - 红色图标 = 代理已停止

第三步：配置 Claude Desktop
  打开 Claude Desktop -> Settings -> Developer -> Configure Third-Party Inference
  填写以下信息：
  - Credential kind:    Static API key
  - Gateway base URL:   http://localhost:4000
  - Gateway API key:    与 .env 中 PROXY_API_KEY 一致
  - Gateway auth scheme: bearer

  在 Models 部分，关闭 Model discovery，手动添加模型：
  - Model ID: claude-sonnet-4-5  /  Display name: 自定义（如 Kimi）
  - Model ID: claude-haiku-4-5   /  Display name: 自定义（如 GLM）
  - Model ID: claude-opus-4-5    /  Display name: 自定义（如 DeepSeek）

  点击 Test connection，看到绿色提示即配置成功


【托盘菜单说明】
  右键托盘图标可看到以下菜单：

  启动代理    启动代理服务（代理停止时可用）
  停止代理    停止代理服务（代理运行时可用）
  ─────────────────────────
  查看统计    浏览器打开统计页面（代理运行时可用）
  查看日志    打开 proxy.log 日志文件
  编辑配置    打开 .env 配置文件
  检测网关    手动检测代理连通性
  ─────────────────────────
  开机自启    开启/关闭开机自动启动
  ─────────────────────────
  关于        查看版本、开发者、运行时长等信息
  退出        退出程序


【统计页面（http://localhost:4000/stats）】

  代理运行时，浏览器访问 http://localhost:4000/stats 查看：

  1. 运行状态
     - 运行时长、总请求数、缓存命中率、网关错误次数等

  2. Token 使用统计
     - 输入/输出/总 Token 累计，以及平均每次请求消耗

  3. 模型映射
     - Claude Desktop 模型名与私有模型的对应关系

  4. MCP 工具管理（重要！）
     - 显示最近一次请求携带的所有 MCP 工具列表
     - 支持三种过滤模式：

       不过滤：所有工具全部发给模型（默认，token 消耗最高）

       白名单：只有勾选的工具发给模型
               适合：明确知道需要哪些工具时使用
               效果：大幅减少 token 消耗

       黑名单：勾选的工具不发给模型，其余全部保留
               适合：只想屏蔽少数不需要的工具时使用

     操作方法：
       a. 先发送一条消息，等工具列表出现
       b. 选择过滤模式（白名单/黑名单）
       c. 勾选需要保留或过滤的工具
       d. 点击「保存设置」按钮
       e. 设置即时生效，并自动写入 .env 持久保存


【.env 配置文件说明】

  必填项：
  TARGET=https://your-gateway.com/v1    网关地址
  API_KEY=your_key                       网关 API Key
  PROXY_API_KEY=your_password            代理访问密码
  MODEL_SONNET=your-model-1              sonnet 对应的私有模型
  MODEL_HAIKU=your-model-2               haiku 对应的私有模型
  MODEL_OPUS=your-model-3                opus 对应的私有模型

  可选项（有默认值）：
  CACHE_TTL=10                           缓存有效期（秒）
  MAX_CACHE_SIZE=100                     最大缓存条数
  MAX_RETRIES=2                          网关失败重试次数
  RETRY_DELAY=1.0                        重试间隔（秒）
  TOOL_DESC_MAX_LEN=100                  工具描述截断长度（越小越省 token）
  CONNECT_TIMEOUT=5.0                    连接超时（秒）
  READ_TIMEOUT=60.0                      读取超时（秒，慢模型可调大）
  WRITE_TIMEOUT=10.0                     写入超时（秒）
  LOG_FILE=proxy.log                     日志文件名
  TOOL_WHITELIST=                        工具白名单（逗号分隔，统计页面可配置）
  TOOL_BLACKLIST=                        工具黑名单（逗号分隔，统计页面可配置）


【关于 Token 消耗】

  如果发送简单消息但 token 消耗很高（如数万），原因通常是：
  - Claude Desktop 安装了大量 MCP 插件，每次请求都会携带所有工具定义
  - 工具定义本身会占用大量 token（55 个工具约 6 万 token）

  解决方法：
  1. 打开统计页面 http://localhost:4000/stats
  2. 发送一条消息后查看工具列表
  3. 使用黑名单过滤掉不需要的工具
  4. 或者在 Claude Desktop 里直接禁用不需要的 MCP 插件


【修改配置后如何生效】
  方法一：右键托盘 -> 编辑配置 -> 修改保存
          代理会自动检测到 .env 变化并重启（约 3 秒）

  方法二：右键托盘 -> 停止代理 -> 启动代理


【常见问题】

Q：双击 exe 后托盘没有图标？
A：稍等 3-5 秒，程序正在初始化。若仍无图标，查看同目录下 proxy.log。

Q：弹窗提示"请先在 .env 中填写真实配置"？
A：用记事本打开 .env，将占位符替换为真实的网关地址和 Key。

Q：弹窗提示"端口 4000 已被占用"？
A：关闭其他占用 4000 端口的程序，或检查是否已有一个代理在运行。

Q：弹窗提示"Claude Proxy 已在运行中"？
A：程序已在后台运行，查看系统托盘图标即可。

Q：Claude Desktop 显示连接失败？
A：1. 确认托盘图标是绿色（代理运行中）
   2. 确认 Gateway API key 与 .env 中 PROXY_API_KEY 一致
   3. 查看 proxy.log 了解详细错误

Q：代理崩溃后自动重启失败？
A：代理会自动重试 3 次，超过后托盘图标变红并弹窗提示。
   请查看 proxy.log 了解崩溃原因。

Q：日志文件太大怎么办？
A：日志文件会自动轮转（超过 5MB 自动备份），最多保留 3 个备份文件。
   也可手动删除 proxy.log，代理会自动创建新的。

Q：如何卸载？
A：右键托盘 -> 退出，如开启了开机自启先关闭，然后删除整个文件夹即可。
