xiantong 文档
配置

网络代理

通过 HTTP/HTTPS 代理为企业网络和防火墙路由流量

xiantong 可以通过 HTTP 或 HTTPS 代理路由所有网络流量。这对于需要代理访问的企业网络、阻止直接连接的防火墙或需要网络检测的环境尤为有用。

配置#

打开 设置 → 网络 并配置：

字段说明示例
启用代理打开/关闭代理路由—
HTTP 代理用于 HTTP 请求的代理 URLhttp://proxy.corp.com:8080
HTTPS 代理用于 HTTPS 请求的代理 URL（未设置时使用 HTTP 代理作为回退）http://proxy.corp.com:8080
不使用代理以逗号分隔的要绕过的主机/域名列表localhost,127.0.0.1,.internal.com

设置会保存在 ~/.xiantong/config.json 中的 networkProxy 键下：

{
"networkProxy": {
"enabled": true,
"httpProxy": "http://proxy.corp.com:8080",
"httpsProxy": "http://proxy.corp.com:8080",
"noProxy": "localhost,127.0.0.1,.internal.com"
}
}

更改立即生效 — 无需重启。

工作原理#

启用代理后，xiantong 会在两个层面路由流量：

  1. Node.js（主进程） — 所有 fetch() 调用（OAuth 流程、MCP 服务器连接、API 请求）都通过使用 HTTPS CONNECT 隧道的 undici ProxyAgent 路由。
  2. Electron（浏览器窗口） — 浏览器面板请求和 OAuth 浏览器窗口通过 Chromium 的内置 Agent 支持（session.setProxy()）处理。
  3. SDK 子进程 — Claude Code 子进程会自动接收 HTTP_PROXY、HTTPS_PROXY 和 NO_PROXY 环境变量。

代理身份验证#

对于需要身份验证的 Agent，请在 URL 中包含凭据：

http://username:password@proxy.corp.com:8080

代理凭据以明文形式存储在 config.json 中。如安全策略要求加密凭据，请使用环境级的代理配置。

不使用代理规则#

不使用代理 字段接受以逗号分隔的绕过规则列表：

模式匹配对象
*所有主机（实际上禁用 Agent）
example.com精确主机名
.example.comexample.com 的所有子域
example.com:8080特定主机和端口
192.168.1.1精确 IP 地址
[::1]IPv6 地址
[::1]:8080带端口的 IPv6 地址

localhost 和 127.0.0.1 不会自动绕过。如果需要直接访问本地服务（例如本地 MCP 服务器），请将它们明确添加到“不使用代理”列表中。

TLS 拦截代理（企业防火墙）#

许多企业代理会通过内部证书颁发机构（CA）重新签名 HTTPS 流量以执行 TLS 检查。这会导致 fetch failed 错误，因为 Node.js 默认不信任代理的 CA。

症状#

  • OAuth 登录失败并提示 “fetch failed”，或没有浏览器窗口静默返回
  • MCP 服务器连接在企业网络中失败，但在个人网络中可用
  • 浏览器面板请求正常（Chromium 使用系统证书库），但代理发起的请求失败

解决方案#

在启动 xiantong 之前，将 NODE_EXTRA_CA_CERTS 环境变量设置为企业代理的 CA 证书路径：

  • macOS

  • Windows

  • Linux

终端中的一次性启动：

NODE_EXTRA_CA_CERTS=/path/to/corporate-ca.pem open -a "xiantong"

**永久生效（适用于 dock/Spotlight 启动的所有应用）：**Shell 配置文件（~/.zshrc）仅对终端会话生效。要为 Dock 或 Spotlight 启动的打包应用设置环境变量，请使用 launchctl：

# 为当前用户会话设置（在现代 macOS 上可在重启后继续生效）
launchctl setenv NODE_EXTRA_CA_CERTS /path/to/corporate-ca.pem

然后重新启动 xiantong。确认是否生效：

launchctl getenv NODE_EXTRA_CA_CERTS

稍后移除：

launchctl unsetenv NODE_EXTRA_CA_CERTS

在 macOS 10.10+ 上，launchctl setenv 会在 GUI 会话中跨重启保留。如果组织使用 MDM，IT 部门也可以通过 LaunchAgent plist 部署：

<!-- ~/Library/LaunchAgents/com.xiantong.proxy-ca.plist -->
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>Label</key>
<string>com.xiantong.proxy-ca</string>
<key>ProgramArguments</key>
<array>
<string>/bin/launchctl</string>
<string>setenv</string>
<string>NODE_EXTRA_CA_CERTS</string>
<string>/path/to/corporate-ca.pem</string>
</array>
<key>RunAtLoad</key>
<true/>
</dict>
</plist>

PowerShell 中的一次性启动：

$env:NODE_EXTRA_CA_CERTS = "C:\path\to\corporate-ca.pem"
& "$env:LOCALAPPDATA\xiantong\xiantong.exe"

**永久生效（适用于开始菜单/桌面启动的所有应用）：**选项 A — 通过“系统属性” UI：

  1. 按 Win + R，输入 sysdm.cpl，回车
  2. 转到 高级 选项卡 → 点击 环境变量
  3. 在 用户变量 下点击 新建
  4. 变量名：NODE_EXTRA_CA_CERTS
  5. 变量值：C:\path\to\corporate-ca.pem
  6. 对所有对话框点击 确定
  7. 注销并重新登录（或重启）以使更改生效

选项 B — 通过 PowerShell：

[System.Environment]::SetEnvironmentVariable(
"NODE_EXTRA_CA_CERTS",
"C:\path\to\corporate-ca.pem",
"User"
)

必须 注销并重新登录（或重启）以使通过资源管理器启动的应用生效。终端会话在打开新窗口后会立即生效。

稍后移除，删除“系统属性”中的变量，或运行：

[System.Environment]::SetEnvironmentVariable("NODE_EXTRA_CA_CERTS", $null, "User")

对于组织范围的部署，IT 可以将其设置为 计算机级 变量（通过“系统属性”或组策略）。

终端中的一次性启动：

NODE_EXTRA_CA_CERTS=/path/to/corporate-ca.pem xiantong

**永久生效（适用于桌面启动的所有应用）：**将其添加到 ~/.profile（登录 shell 读取）并 ~/.config/environment.d/proxy-ca.conf（大多数现代桌面环境使用的 systemd 用户会话读取）：

# ~/.config/environment.d/proxy-ca.conf
NODE_EXTRA_CA_CERTS=/path/to/corporate-ca.pem

然后注销并重新登录。验证：

systemctl --user show-environment | grep NODE_EXTRA_CA_CERTS

对于不使用 systemd 用户会话的旧桌面环境，可能需要使用 ~/.pam_environment 或 ~/.xprofile。

获取 CA 证书#

请向 IT 部门索要企业代理的 CA 证书。如果需要自行提取：

# 通过代理连接并捕获证书链
openssl s_client -connect api.anthropic.com:443 -proxy proxy.corp.com:8080 -showcerts </dev/null 2>/dev/null | openssl x509 -outform PEM > corporate-ca.pem

证书必须是 PEM 格式（以 -----BEGIN CERTIFICATE----- 开头）。如果收到 .cer 或 .der 文件，请转换：

openssl x509 -inform DER -in corporate-ca.cer -out corporate-ca.pem

故障排除#

OAuth 登录提示“Fetch failed”#

通常表示 TLS 拦截代理。请参阅上文的 TLS 拦截代理 部分。

代理对浏览有效但对 OAuth 无效#

浏览器面板使用 Chromium 的证书存储（包含系统安装的 CA），而 OAuth 发现和令牌交换使用 Node.js fetch()（仅信任 Node 的内置 CA 捆绑包）。设置 NODE_EXTRA_CA_CERTS 即可弥合差异。

MCP 服务器连接失败#

确保 MCP 服务器的主机名未包含在“不使用代理”列表中（除非希望直接访问）。对于本地 MCP 服务器（stdio 传输），代理设置不适用 — 它们作为本地子进程运行。

代理身份验证失败#

  • 使用 curl 验证凭据是否有效：curl -v --proxy http://user:pass@proxy:8080 https://api.anthropic.com
  • 对密码中的特殊字符进行 URL 编码（例如 p%40ss 表示 p@ss）
  • 某些企业代理使用 NTLM 身份验证，无法直接支持。可考虑使用 cntlm 作为本地 NTLM 到 Basic 的代理桥接

验证代理已启用#

检查应用日志中的启动代理配置：

[proxy] Applying proxy settings: { enabled: true, hasHttpProxy: true, hasHttpsProxy: true, hasNoProxy: true }

日志位置：~/Library/Logs/@xiantong/electron/main.log（macOS）

上一页LLM 连接