[Bug]远程隔离容器内 ZCode 无法访问 API（3.2.1 版本)

提交前确认 · Pre-submission checklist

• 我已搜索过现有 issue，确认这不是重复 / I searched existing issues and confirmed this isn't a duplicate.
• 我已阅读 CONTRIBUTING.md / I've read CONTRIBUTING.md.

问题类别 · Category

其他 / 不确定 · Other / Not sure

涉及的 Agent 框架 · Agent framework

ZCode Agent（自研）

严重程度 · Severity

阻塞使用 · Blocking (无法使用核心功能 / core function unusable)

复现频率 · Reproducibility

必现 · Always

问题描述 · Description

【补充反馈】远程隔离容器内 ZCode 无法访问 API（3.2.1 版本回归）

关联工单：ZCT-2072156092075761664
反馈类型：Bug / 功能回归
严重程度：P1-高
App 版本：3.2.1

---

问题摘要

ZCode 更新到 3.2.1 后，通过 Remote SSH 连接的 openclaw-rl 容器工作区无法访问 API，报 Connect Timeout。同一环境旧版本完全正常，怀疑是版本回归。

环境信息

• 本地：Windows + Clash Verge 代理（端口 7897）
• 远程：openclaw-rl Docker 容器（Ubuntu 24.04），经 Trae 跳板隧道 SSH 连接
• 容器网络：完全隔离，无外网出口（连 baidu.com / bigmodel.cn 都不通）
• 对比：Cursor / Codex 在同一容器内正常工作

复现步骤

1. 本地运行跳板隧道建立到容器的 SSH 连接
2. ZCode 连接 openclaw-rl 远程工作区
3. 发送任意消息

预期：正常返回响应（旧版本行为）
实际：报错 Cannot connect to API: Connect Timeout Error (attempted addresses: 2602:ffe4:407:20e8::23:443, 128.1.150.233:443, timeout: 10000ms)，provider_code=UND_ERR_CONNECT_TIMEOUT

版本回归证据

从容器内的 rollout 日志确认，同一个会话更新前后行为不同：

旧版本（2026-06-30）：会话 08b5b7cf 请求成功，durationMs=30321，正常返回
server 更新时间：2026-07-01 01:14:23（自动更新到 3.2.1）
同会话更新后（2026-07-01 01:43）：立即报 Connect Timeout Error

网络环境、provider（builtin:zai）、API 地址（api.z.ai）全程未变，唯一变量是版本更新。

根因分析

经过深入排查，定位到两个层面的问题：

1. 架构变更：agent 在容器内直接发 HTTP 请求

旧版本（推断）：API 请求通过 SSH/IPC 通道回传本地客户端执行（类似 Cursor/VS Code Remote），容器不需要外网。

新版本：agent 进程（zcode-server.cjs）在容器内用 Node.js fetch() 直接请求 api.z.ai。容器无外网出口 → 超时。

启动命令可见 API 地址被传到容器内进程：

sh -c "ZAI_BUSINESS_BASE_URL='https://api.z.ai' ... node zcode-server.cjs"

2. Node.js undici 不读代理环境变量

新版用 Node v22.16.0，其 fetch()（undici）不自动读 HTTP_PROXY/HTTPS_PROXY 环境变量。即使容器内有代理也无法使用，必须显式配置 ProxyAgent。

改进建议（按优先级）

P0：恢复"请求回传本地"的选项

提供一个配置项让远程工作区的 API 请求回传本地客户端执行：

{ "remoteApiRequestMode": "local" }  // local(回传本地) | remote(容器内直发)

这是解决隔离环境问题的根本方案，旧版本就是这种模式。

P1：让 HTTP_PROXY/HTTPS_PROXY 环境变量生效

在 server 启动时检测代理环境变量，为 undici 设置全局 ProxyAgent：

const proxy = process.env.HTTPS_PROXY || process.env.HTTP_PROXY;
if (proxy) {
  const { ProxyAgent, setGlobalDispatcher } = require('undici');
  setGlobalDispatcher(new ProxyAgent(proxy));
}

server 代码里已有 PROXY_ENV_KEYS 的处理逻辑（用于子 agent），只需应用到 server 自身的 fetch。

P1：超时后自动诊断并给出可操作的提示

当前报错只列 IP 地址，用户无从下手。建议检测容器网络环境后给出针对性建议（如有代理则提示配置 HTTPS_PROXY，如完全隔离则提示启用回传本地模式）。

当前的临时解决方案

在官方修复前，我搭建了四层代理绕过此问题：
容器内 fetch → /etc/hosts 劫持到 127.0.0.1 → Python HTTPS 反向代理 :443 → SSH 反向隧道 :7897 → 本地 Clash → api.z.ai

方案可行但维护成本高（依赖 SSH 隧道、自签证书、watchdog 守护），希望官方能从根本上解决。

复现步骤 · Steps to reproduce

复现步骤

本地运行跳板隧道建立到容器的 SSH 连接
ZCode 连接 openclaw-rl 远程工作区
发送任意消息

期望表现 · Expected behavior

预期：正常返回响应（旧版本行为）

实际表现 · Actual behavior

实际：报错 Cannot connect to API: Connect Timeout Error (attempted addresses: 2602:ffe4:407:20e8::23:443, 128.1.150.233:443, timeout: 10000ms)，provider_code=UND_ERR_CONNECT_TIMEOUT

ZCode 版本 · ZCode version

3.2.1

设备 / 系统 / 浏览器 · Device / OS / Browser

Windows 11

截图 / 录屏 / 日志 · Screenshots / Recordings / Logs

ZCode 报错信息

报错摘要
Cannot connect to API: Connect Timeout Error (attempted addresses: 2602:ffe4:407:20e8::23:443, 128.1.150.233:443, timeout: 10000ms)

Start by tracing the remote server entry point mentioned as zcode-server.cjs, including its fetch usage and the existing PROXY_ENV_KEYS handling. Reproduce the timeout in an isolated openclaw-rl container, then determine whether the supported fix is local request forwarding, explicit proxy support, or both. Done means API requests work in the reported remote environment and failures provide actionable diagnostics.