lessweb · kiangz · Jun 5, 2026 · Jun 5, 2026 · Jun 5, 2026
diff --git a/docs/configuration.md b/docs/configuration.md
@@ -49,6 +49,10 @@ Deep Code 使用 `settings.json` 设置文件进行持久化配置，支持两
 | `REASONING_EFFORT`  | string | 推理强度                                                |
 | `DEBUG_LOG_ENABLED`  | string | 是否启用调试日志输出                                     |
 | `TELEMETRY_ENABLED`  | string | 是否启用匿名使用数据上报                                   |
+| `HTTP_PROXY`    | string | HTTP 代理地址，例如 `"http://127.0.0.1:7890"`             |
+| `HTTPS_PROXY`   | string | HTTPS 代理地址，例如 `"http://127.0.0.1:7890"`           |
+| `SOCKS_PROXY`   | string | SOCKS5 代理地址，例如 `"socks5://127.0.0.1:1080"`         |
+| `NO_PROXY`      | string | 不走代理的地址列表，逗号分隔，例如 `"localhost,127.0.0.1,.example.com"` |
 | `<其他任意KEY>` | string | 自定义环境变量 |
 
 #### `thinkingEnabled` — 思考模式
@@ -197,3 +201,72 @@ DEEPCODE_TELEMETRY_ENABLED=0 deepcode
 3. 项目级settings.json: `{"mcpServers":{"github":{"env":{"GITHUB_PERSONAL_ACCESS_TOKEN":"..."}}}}`
 4. 项目级settings.json: `{"env": {"MCP_GITHUB_PERSONAL_ACCESS_TOKEN": "..."}}`
 5. 系统环境变量: `DEEPCODE_MCP_GITHUB_PERSONAL_ACCESS_TOKEN=... deepcode`
+
+## 代理配置
+
+Deep Code 支持通过 HTTP/HTTPS/SOCKS5 代理发送所有网络请求，包括 API 调用、遥测上报和联网搜索。
+
+### 支持的代理变量
+
+| 变量名         | 说明                                                          | 示例                                    |
+| -------------- | ----------------------------------------------------------- | --------------------------------------- |
+| `HTTPS_PROXY`  | HTTPS 代理（优先级最高）                                    | `http://127.0.0.1:7890`                 |
+| `HTTP_PROXY`   | HTTP 代理                                                   | `http://127.0.0.1:7890`                 |
+| `SOCKS_PROXY`  | SOCKS5 代理                                                 | `socks5://127.0.0.1:1080`               |
+| `SOCKS5_PROXY` | SOCKS5 代理（`SOCKS_PROXY` 的别名）                         | `socks5://127.0.0.1:1080`               |
+| `NO_PROXY`     | 不走代理的地址列表（逗号分隔，支持 `*`、`.example.com`）   | `localhost,127.0.0.1,.internal.corp`    |
+
+### 配置方式
+
+#### 一、通过 Shell 环境变量设置（优先级最高）
+
+**Bash / Zsh：**
+
+```bash
+export HTTPS_PROXY=http://127.0.0.1:7890
+export NO_PROXY=localhost,127.0.0.1
+deepcode
+```
+
+**PowerShell：**
+
+```powershell
+$env:HTTPS_PROXY = "http://127.0.0.1:7890"
+$env:NO_PROXY = "localhost,127.0.0.1"
+deepcode
+```
+
+也可以使用 `DEEPCODE_` 前缀：
+
+```bash
+DEEPCODE_HTTPS_PROXY=http://127.0.0.1:7890 deepcode
+```
+
+#### 二、通过 `settings.json` 的 `env` 字段配置
+
+```json
+{
+  "env": {
+    "HTTPS_PROXY": "http://127.0.0.1:7890",
+    "NO_PROXY": "localhost,127.0.0.1"
+  }
+}
+```
+
+### 优先级
+
+按以下优先级顺序应用（数字较小的会被数字较大的覆盖）：
+
+1. 用户级 `settings.json`：`{"env": {"HTTPS_PROXY": "..."}}`
+2. 项目级 `settings.json`：`{"env": {"HTTPS_PROXY": "..."}}`
+3. 系统环境变量：`HTTPS_PROXY=... deepcode` 或 `DEEPCODE_HTTPS_PROXY=... deepcode`
+
+### `NO_PROXY` 匹配规则
+
+| 模式             | 说明                                             |
+| --------------- | ---------------------------------------------- |
+| `*`             | 所有地址均不走代理                                  |
+| `localhost`     | 精确匹配 `localhost`                               |
+| `127.0.0.1`     | 精确匹配 `127.0.0.1`                              |
+| `.example.com`  | 匹配 `example.com` 及其所有子域名（如 `api.example.com`） |
+| `example.com`   | 匹配 `example.com` 及其所有子域名                   |
diff --git a/docs/configuration_en.md b/docs/configuration_en.md
@@ -49,6 +49,10 @@ The following are all the top-level fields supported in `settings.json`, along w
 | `REASONING_EFFORT`| string | Reasoning intensity                                             |
 | `DEBUG_LOG_ENABLED`| string| Enable debug log output                                         |
 | `TELEMETRY_ENABLED`| string| Enable anonymous usage reporting                                |
+| `HTTP_PROXY`       | string| HTTP proxy URL, e.g. `"http://127.0.0.1:7890"`                |
+| `HTTPS_PROXY`      | string| HTTPS proxy URL, e.g. `"http://127.0.0.1:7890"`               |
+| `SOCKS_PROXY`      | string| SOCKS5 proxy URL, e.g. `"socks5://127.0.0.1:1080"`            |
+| `NO_PROXY`         | string| Comma-separated list of hosts to bypass proxy, e.g. `"localhost,127.0.0.1,.example.com"` |
 | `<any other KEY>` | string | Custom environment variable                                     |
 
 #### `thinkingEnabled` — Thinking Mode
@@ -196,3 +200,72 @@ Applied in the following priority order (lower-numbered overridden by higher-num
 3. Project-level settings.json: `{"mcpServers":{"github":{"env":{"GITHUB_PERSONAL_ACCESS_TOKEN":"..."}}}}`
 4. Project-level settings.json: `{"env": {"MCP_GITHUB_PERSONAL_ACCESS_TOKEN": "..."}}`
 5. System environment variable: `DEEPCODE_MCP_GITHUB_PERSONAL_ACCESS_TOKEN=... deepcode`
+
+## Proxy Configuration
+
+Deep Code supports routing all network traffic (API calls, telemetry reporting, and web search) through HTTP, HTTPS, or SOCKS5 proxies.
+
+### Supported Proxy Variables
+
+| Variable       | Description                                                      | Example                                  |
+| -------------- | --------------------------------------------------------------- | ---------------------------------------- |
+| `HTTPS_PROXY`  | HTTPS proxy (highest priority)                                   | `http://127.0.0.1:7890`                  |
+| `HTTP_PROXY`   | HTTP proxy                                                      | `http://127.0.0.1:7890`                  |
+| `SOCKS_PROXY`  | SOCKS5 proxy                                                    | `socks5://127.0.0.1:1080`                |
+| `SOCKS5_PROXY` | SOCKS5 proxy (alias for `SOCKS_PROXY`)                          | `socks5://127.0.0.1:1080`                |
+| `NO_PROXY`     | Comma-separated list of hosts to bypass proxy (supports `*`, `.example.com`) | `localhost,127.0.0.1,.internal.corp` |
+
+### Configuration Methods
+
+#### 1. Shell Environment Variables (highest priority)
+
+**Bash / Zsh:**
+
+```bash
+export HTTPS_PROXY=http://127.0.0.1:7890
+export NO_PROXY=localhost,127.0.0.1
+deepcode
+```
+
+**PowerShell:**
+
+```powershell
+$env:HTTPS_PROXY = "http://127.0.0.1:7890"
+$env:NO_PROXY = "localhost,127.0.0.1"
+deepcode
+```
+
+You can also use the `DEEPCODE_` prefix:
+
+```bash
+DEEPCODE_HTTPS_PROXY=http://127.0.0.1:7890 deepcode
+```
+
+#### 2. `settings.json` `env` field
+
+```json
+{
+  "env": {
+    "HTTPS_PROXY": "http://127.0.0.1:7890",
+    "NO_PROXY": "localhost,127.0.0.1"
+  }
+}
+```
+
+### Priority
+
+Applied in the following priority order (lower-numbered overridden by higher-numbered):
+
+1. User-level `settings.json`: `{"env": {"HTTPS_PROXY": "..."}}`
+2. Project-level `settings.json`: `{"env": {"HTTPS_PROXY": "..."}}`
+3. System environment variable: `HTTPS_PROXY=... deepcode` or `DEEPCODE_HTTPS_PROXY=... deepcode`
+
+### `NO_PROXY` Matching Rules
+
+| Pattern         | Description                                                      |
+| --------------- | --------------------------------------------------------------- |
+| `*`             | Bypass proxy for all hosts                                       |
+| `localhost`     | Exact match for `localhost`                                       |
+| `127.0.0.1`     | Exact match for `127.0.0.1`                                      |
+| `.example.com`  | Matches `example.com` and all its subdomains (e.g. `api.example.com`) |
+| `example.com`   | Matches `example.com` and all its subdomains                     |
diff --git a/src/common/openai-client.ts b/src/common/openai-client.ts
@@ -4,6 +4,7 @@ import * as path from "path";
 import OpenAI from "openai";
 import { Agent, fetch as undiciFetch } from "undici";
 import { resolveCurrentSettings } from "../settings";
+import { getProxyDispatcher } from "./proxy";
 
 // Custom undici Agent with a 180-second keepAlive timeout.  The default
 // global fetch (undici) only keeps connections alive for 4 seconds, which
@@ -51,7 +52,8 @@ export function createOpenAIClient(projectRoot: string = process.cwd()): {
     };
   }
 
-  const cacheKey = `${settings.apiKey}::${settings.baseURL}`;
+  const proxyDispatcher = getProxyDispatcher(settings.baseURL);
+  const cacheKey = `${settings.apiKey}::${settings.baseURL}::${proxyDispatcher ? "proxy" : "direct"}`;
   if (cachedOpenAI && cachedOpenAIKey === cacheKey) {
     return {
       client: cachedOpenAI,
@@ -73,7 +75,7 @@ export function createOpenAIClient(projectRoot: string = process.cwd()): {
     apiKey: settings.apiKey,
     baseURL: settings.baseURL || undefined,
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    fetch: (url: any, init: any) => undiciFetch(url, { ...init, dispatcher: keepAliveAgent }),
+    fetch: (url: any, init: any) => undiciFetch(url, { ...init, dispatcher: proxyDispatcher ?? keepAliveAgent }),
   });
   cachedOpenAIKey = cacheKey;