evo-tls-proxy

中文说明

Transparent TLS proxy for Claude Code on Windows.

It keeps Claude Code talking to api.anthropic.com at the client side, while transparently forwarding the real traffic to a local or external Anthropic-compatible backend such as EvoRouter or MiniMax.

This is useful because Claude Code contains a first-party host check around api.anthropic.com. When you point ANTHROPIC_BASE_URL directly at a third-party gateway, some client-side capabilities can be silently degraded. This project preserves the first-party path while still letting you control the real upstream.

This project was also informed by the ideas discussed in this article: 使用第三方代理 Claude Code 的注意了，你的 tool_use 被优化没了

How It Works

Claude Code
  -> https://api.anthropic.com
  -> hosts hijack to 127.0.0.1
  -> evo-tls-proxy terminates TLS locally
  -> forwards to your real backend
     - local EvoRouter: http://127.0.0.1:4010
     - external gateway: https://api.minimaxi.com/anthropic

What Has Been Verified

• Claude Code v2.1.79 works through the transparent proxy path
• Main chat requests are forwarded as POST /v1/messages?beta=true
• Current Claude Code builds send the main auth header as Authorization: Bearer ...
• Background POST /api/event_logging/batch requests are handled locally by the proxy with 204
• ToolSearch behavior is restored more closely to the first-party api.anthropic.com path than when directly using ANTHROPIC_BASE_URL=http://localhost:4010

Requirements

• Windows
• Node.js installed
• Administrator rights for editing the hosts file
• Claude Code
• A backend that accepts Anthropic-compatible requests

Project Files

evo-tls-proxy/
├── enable.bat / enable.ps1
├── disable.bat / disable.ps1
├── start-proxy-visible.bat
├── generate-cert.js
├── tls-proxy.js
├── tls-proxy.config.json
├── test-proxy.js
└── certs/

Configuration

Edit tls-proxy.config.json.

Default local EvoRouter configuration:

{
  "listenPort": 443,
  "targetUrl": "",
  "targetHost": "127.0.0.1",
  "targetPort": 4010,
  "certsDir": "./certs"
}

External Anthropic-compatible gateway example:

{
  "listenPort": 443,
  "targetUrl": "https://api.minimaxi.com/anthropic",
  "targetHost": "127.0.0.1",
  "targetPort": 4010,
  "certsDir": "./certs"
}

Rules:

• If targetUrl is empty, the proxy uses targetHost + targetPort
• If targetUrl is set, it takes precedence
• If targetUrl includes a base path such as /anthropic, the proxy preserves and appends the incoming Claude path correctly

Claude Code Settings

Recommended Claude Code environment snippet:

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.anthropic.com",
    "ANTHROPIC_AUTH_TOKEN": "sk-ant-...",
    "NO_PROXY": "127.0.0.1,localhost,api.anthropic.com,.anthropic.com"
  }
}

Important notes:

• Use https://api.anthropic.com, not https://api.anthropic.com/v1
• If your system has HTTP_PROXY or HTTPS_PROXY, NO_PROXY must include api.anthropic.com
• Without that NO_PROXY entry, traffic may bypass the local hosts mapping and never hit this proxy

Quick Start

1. Configure tls-proxy.config.json for your target backend.
2. Run enable.bat. This generates certificates if needed, updates hosts, sets NODE_EXTRA_CA_CERTS, and then launches start-proxy-visible.bat.
3. If the proxy window does not appear automatically, start it manually with start-proxy-visible.bat. On the current tested setup, launching this .bat directly gives the best Windows Terminal behavior.
4. Make sure your real backend is running. For local mode, EvoRouter should be listening on 127.0.0.1:4010.
5. Fully restart Claude Code.
6. Send a test message and watch the proxy window.

Start Modes

• enable.bat Configures the system side, then attempts to launch the visible proxy window.
• enable.ps1 Performs the privileged setup steps and keeps the setup window open for review.
• start-proxy-visible.bat Starts the visible proxy window directly. You can run this manually if you want to start or restart only the proxy process.
• disable.bat Removes the hosts entry, restores NODE_EXTRA_CA_CERTS, and stops the proxy process.

This split is intentional. In the tested environment, the visible proxy window behaves best when it is ultimately launched from start-proxy-visible.bat.

Smoke Test

You can test the TLS path without Claude Code:

node .\test-proxy.js

If the proxy and backend are healthy, you should see a 200 response.

Expected Proxy Logs

Typical successful flow:

[TLS] Handshake success from 127.0.0.1:9871 SNI=api.anthropic.com
[#1] -> POST /v1/messages?beta=true [Claude Code]
[#1] -> Upstream POST http://127.0.0.1:4010/v1/messages?beta=true
[#1] <- 200

Background event logging is intentionally handled locally:

[#2] -> POST /api/event_logging/batch [Claude Code]
[#2] <- Local 204 for /api/event_logging/batch

ToolSearch Validation

We ran an A/B comparison:

• Direct third-party path: ANTHROPIC_BASE_URL=http://localhost:4010
• Transparent proxy path: ANTHROPIC_BASE_URL=https://api.anthropic.com plus hosts hijack

Observed result:

• Direct localhost mode still works for normal chat
• Transparent proxy mode behaves more like the first-party path during codebase exploration
• Claude becomes more likely to enter a fuller search/explore workflow instead of only doing shallow keyword probing

Supporting evidence from Claude logs:

• Third-party direct path can show: ToolSearch:optimistic disabled: ... is not a first-party Anthropic host
• First-party path can show: ToolSearch:optimistic ... result=true

This is not a formal benchmark, but it is the practical reason this project exists.

Why This Still Matters

Claude Code has also shipped a fix described roughly as:

Fixed API 400 errors when using ANTHROPIC_BASE_URL with a third-party gateway - tool search now correctly detects proxy endpoints and disables tool_reference blocks

That fix is useful, but it does not make the transparent proxy approach obsolete.

What it means in practice:

• Claude Code now behaves more safely when it detects a third-party gateway
• It avoids some incompatible request shapes that could previously cause 400 errors
• But this is still a third-party code path with feature-aware downgrade behavior

What this project is trying to preserve is different:

• Keep Claude Code on the first-party api.anthropic.com client path
• Avoid falling into the third-party gateway detection branch in the first place
• Preserve behavior that is closer to the official host path instead of only making the downgraded third-party path less error-prone

So the official fix improves third-party compatibility, while evo-tls-proxy still targets a different goal: preserving as much first-party client behavior as possible.

Known Limitations

• POST /v1/messages/count_tokens?beta=true is not fully handled in every backend setup yet
• For some backends this may timeout, while the main /v1/messages request still succeeds
• Classic Windows console behavior can differ depending on how the proxy window is launched
• The tested release target is Claude Code v2.1.79; future client versions may change request behavior

Security Notes

• This project installs a local CA certificate for interception of api.anthropic.com
• While enabled, any local process on the machine that resolves api.anthropic.com through the modified hosts file will be redirected to this proxy
• Keep the generated certs/ directory private
• Do not commit hosts.bak or private cert material

Release Checklist

Before publishing or sharing:

1. Confirm tls-proxy.config.json is set to generic defaults, not your personal upstream
2. Keep certs/ out of git
3. Keep hosts.bak out of git
4. Document your recommended Claude Code settings clearly
5. Test both local backend mode and any external gateway mode you claim to support

License

ISC. See LICENSE.