mirror of
https://github.com/Piebald-AI/claude-code-system-prompts.git
synced 2026-06-23 05:39:28 +08:00
100 lines
4.9 KiB
Markdown
100 lines
4.9 KiB
Markdown
<!--
|
|
name: 'Data: Claude Code agent proxy troubleshooting guide'
|
|
description: Troubleshooting guide for Claude Code's policy-enforcing HTTPS agent proxy, covering TLS trust setup, status checks, git, docker, and unsupported traffic
|
|
ccVersion: 2.1.186
|
|
variables:
|
|
- AGENT_PROXY_URL
|
|
- AGENT_PROXY_CA_BUNDLE_PATH
|
|
- AGENT_PROXY_STATE_DIR
|
|
- AGENT_PROXY_PORT
|
|
-->
|
|
# Claude Code agent proxy
|
|
|
|
Outbound HTTPS from this session goes through a local proxy at ${AGENT_PROXY_URL}
|
|
(set via HTTPS_PROXY) which tunnels to a policy-enforcing egress proxy. TLS is
|
|
re-terminated there, so every tool must trust the CA bundle at
|
|
${AGENT_PROXY_CA_BUNDLE_PATH}. The standard CA environment variables, the system trust
|
|
store (where possible), a JVM truststore, the Bazel system bazelrc, the
|
|
browser NSS store, and gsutil's boto config are already set up.
|
|
|
|
## Quick diagnosis
|
|
|
|
1. Run: curl -sS ${AGENT_PROXY_URL}/__agentproxy/status
|
|
It reports proxy state, which trust and git accommodations are active
|
|
(javaTrustStorePath, toolTrustFailureCodes, gitSshRewrite,
|
|
gitConfigConflicts), and the most recent proxy-side failures.
|
|
2. Find the failure class below and apply the matching fix; gitConfigConflicts
|
|
codes map to the git section, toolTrustFailureCodes to the JVM section.
|
|
3. Never disable TLS verification, never unset HTTPS_PROXY, and do not retry
|
|
organization policy denials (403/407) — report them instead.
|
|
|
|
## Failure classes and fixes
|
|
|
|
### "certificate verify failed" / "self-signed certificate in chain" / PKIX errors
|
|
|
|
The failing tool is not reading the pre-set CA configuration. In order:
|
|
|
|
- If the tool has a CA flag or env var, point it at ${AGENT_PROXY_CA_BUNDLE_PATH}
|
|
(examples: --cacert, SSL_CERT_FILE, NODE_EXTRA_CA_CERTS, REQUESTS_CA_BUNDLE,
|
|
AWS_CA_BUNDLE, DENO_CERT, CARGO_HTTP_CAINFO, PIP_CERT, GIT_SSL_CAINFO,
|
|
BUNDLE_SSL_CA_CERT, HEX_CACERTS_PATH, NIX_SSL_CERT_FILE).
|
|
- Tool config files override environment variables. If one of these sets its
|
|
own CA or disables verification, point it at the bundle instead:
|
|
pip.conf "cert", npm "cafile" (npm config get cafile), ~/.curlrc "cacert",
|
|
.wgetrc "ca_certificate", conda "ssl_verify", git "http.sslCAInfo",
|
|
gradle.properties / MAVEN_OPTS "-Djavax.net.ssl.trustStore".
|
|
- JVM tools (Maven, Gradle, plain Java): when a JDK is present, a truststore
|
|
is built at ${AGENT_PROXY_STATE_DIR}/java-truststore.p12 (password "changeit") and
|
|
injected via JAVA_TOOL_OPTIONS — confirm javaTrustStorePath is set in the
|
|
status output before pointing a build at it (toolTrustFailureCodes explains
|
|
why it is missing). If the image or the build sets its own trustStore, that
|
|
one wins — import the proxy CA into it with
|
|
keytool -importcert -noprompt -alias ccr-agent-proxy -file ${AGENT_PROXY_STATE_DIR}/agent-proxy-ca.crt -keystore <their store>
|
|
or point the build at the ready-made one. Bazel reads the managed block in
|
|
/etc/bazel.bazelrc rather than JAVA_TOOL_OPTIONS.
|
|
|
|
### "405 Method Not Allowed" from the proxy
|
|
|
|
The tool sent a plain-HTTP (non-CONNECT) request: usually axios older than
|
|
1.16.1 (upgrade it) or a tool configured with HTTP_PROXY (unset HTTP_PROXY for
|
|
that tool — only HTTPS_PROXY is supported).
|
|
|
|
### 403 / 407 from the proxy
|
|
|
|
The destination host is not allowed by your organization's egress policy for
|
|
this session. Do not retry or route around it — report the blocked host.
|
|
Note: curl hides response bodies on failed CONNECTs; the status endpoint
|
|
records the reason.
|
|
|
|
### Tool ignores the proxy entirely (timeouts with no proxy error)
|
|
|
|
Some clients do not read HTTPS_PROXY: Node's built-in fetch (run that command
|
|
with NODE_USE_ENV_PROXY=1 on Node >= 22.21), aiohttp (pass trust_env=True),
|
|
Ruby bundler (reads only HTTP_PROXY, which this proxy does not serve),
|
|
hand-rolled Go dialers. Prefer the tool's own proxy option where one exists.
|
|
|
|
### git
|
|
|
|
SSH-form GitHub remotes (git@github.com:...) are rewritten to HTTPS
|
|
automatically unless this session has its own SSH setup or supplies its own
|
|
GIT_CONFIG_* (see gitSshRewrite in the status output). A gitconfig that sets
|
|
http.proxy / http.<url>.proxy (even empty), its own http.sslCAInfo, or an
|
|
https-to-ssh insteadOf makes git bypass the proxy or fail verification — the
|
|
status output's gitConfigConflicts codes name which of these were detected;
|
|
adjust those keys for this session if git times out.
|
|
|
|
### docker build / docker run
|
|
|
|
Processes inside containers cannot reach 127.0.0.1:${AGENT_PROXY_PORT} and do not trust
|
|
the CA. Workarounds: run builds with --network host, copy ${AGENT_PROXY_CA_BUNDLE_PATH}
|
|
into the build context and install it in an early layer, and pass proxy/CA
|
|
settings explicitly to the build.
|
|
|
|
### Not supported through the proxy (report, do not work around)
|
|
|
|
gRPC / HTTP/2-only APIs, WebSocket upgrades, client-mTLS, certificate-pinned
|
|
clients (e.g. Snowflake, ngrok), non-443 HTTPS ports, raw-TCP databases.
|
|
|
|
If a tool still cannot work through the proxy, report it to your
|
|
administrator or Anthropic support so the policy or tooling can be fixed.
|