---
title: "配置网络"
description: "理解 OpenCode 的代理变量、NO_PROXY 和企业自定义证书配置。"
verifiedAt: "2026-05-09"
---

> [!NOTE]
> **这一篇用 10 分钟换什么**：把 OpenCode 在企业网络下的连接问题分成两条独立通道——**模型出站**（要走代理）和**本地 TUI 通信**（必须绕开代理）。读完后你不会再把"模型不通"和"本地服务不通"混在一起排障。

这页解决的是企业网络或代理环境下的连接问题。普通家庭网络通常不需要配置；如果你在公司网络、透明代理、内网网关或自建 LLM 网关后面使用 OpenCode，就需要先把网络路径理顺。

OpenCode 支持标准代理环境变量和自定义证书，适用于企业网络环境。

```mermaid
flowchart LR
    User["👤 你"]
    TUI["🖥 OpenCode TUI"]
    Local["🟢 本地 server<br/>localhost:port"]
    Proxy["🟦 企业代理<br/>HTTPS_PROXY"]
    Model["🤖 模型 API"]

    User --> TUI
    TUI -->|本地通信<br/>必须绕过代理| Local
    TUI -->|模型请求<br/>走代理| Proxy --> Model
    Local -.->|NO_PROXY=localhost,127.0.0.1| TUI
```

## 代理变量怎么理解

OpenCode 遵循标准代理环境变量。最常见的是 `HTTPS_PROXY`、`HTTP_PROXY` 和 `NO_PROXY`。

新手只需要先记住三件事：

- 优先配置 `HTTPS_PROXY`，因为模型 API 通常走 HTTPS。
- 只有没有 HTTPS 代理时才考虑 `HTTP_PROXY`。
- 必须把 `localhost` 和 `127.0.0.1` 放进 `NO_PROXY`。

TUI 与本地 HTTP 服务器进行通信。你必须为此连接绕过代理，以防止路由循环。

最小配置形态是：

```bash
export HTTPS_PROXY=https://proxy.example.com:8080
export NO_PROXY=localhost,127.0.0.1
```

你可以使用 [CLI 标志](https://opencode.ai/docs/cli#run)来配置服务器的端口和主机名。

## 为什么 `NO_PROXY` 必须配置

OpenCode 不只是向模型 API 发请求，它还会启动本地服务供 TUI 和客户端通信。如果把 `localhost` 或 `127.0.0.1` 也送进企业代理，本地通信可能绕一圈再回来，轻则超时，重则形成路由循环。

因此企业网络里的最小心智模型是：

| 流量 | 是否走代理 | 原因 |
| --- | --- | --- |
| 模型 API | 通常走 `HTTPS_PROXY` | 公司网络可能要求出站流量统一代理 |
| 本地 OpenCode server | 必须绕过代理 | TUI 与本地服务通信不该出站 |
| 自建 LLM 网关 | 看网关位置 | 内网网关可能需要 `NO_PROXY`，公网网关可能需要代理 |
| MCP 远程服务 | 取决于服务域名 | 企业代理和证书可能同时影响 |

排障时先用这一层分流判断，不要一上来怀疑模型或 OpenCode 本身。

## 需要账号密码的代理

如果你的代理需要基本身份验证，请在 URL 中包含凭据。

不要把密码写进仓库、脚本或团队共享配置。更稳的做法是把代理 URL 放在本机环境变量或系统凭据管理器里，只在当前 shell session 里读取。

对于需要高级身份验证（如 NTLM 或 Kerberos）的代理，建议使用支持相应身份验证方式的 LLM 网关。

## 代理凭据不要进仓库

官方示例里为了说明格式，会把 `username:password` 写进 URL。真实项目里不要把这种 URL 写进仓库、团队文档、shell 脚本或截图。更合理的方式是：

```bash
export HTTPS_PROXY="$COMPANY_HTTPS_PROXY"
export NO_PROXY="localhost,127.0.0.1"
opencode
```

`COMPANY_HTTPS_PROXY` 可以来自本机 shell profile、Keychain、1Password、企业设备管理或 CI secret。教程里的重点是变量关系，不是保存密码的位置。

## 自定义证书

如果你的企业使用自定义 CA 进行 HTTPS 连接，请配置 OpenCode 以信任这些证书。

关键变量是 `NODE_EXTRA_CA_CERTS`，它指向企业 CA 证书文件。这个配置同时适用于代理连接和直接 API 访问。

如果配置后仍然失败，优先判断这三件事：

1. 证书文件路径是否存在，当前用户是否可读
2. 代理是否真的用于模型 API 请求
3. 本地服务地址是否被 `NO_PROXY` 绕过

## 排障顺序

网络问题不要只看最终错误文本。建议按这个顺序缩小范围：

1. **确认本地服务**：去掉代理后，本地 `opencode` 是否能打开 TUI。
2. **确认模型出站**：只设置 `HTTPS_PROXY`，看模型请求是否可达。
3. **确认本地绕过**：设置 `NO_PROXY=localhost,127.0.0.1`，避免本地服务走代理。
4. **确认证书**：企业 CA 路径存在，并且当前 shell 能读取。
5. **确认认证方式**：basic auth 可以写 URL，高级认证优先走 LLM Gateway。
6. **确认 CLI flags**：如果改了 server port 或 hostname，代理绕过名单也要同步。

如果前 3 步没有分开验证，很容易把“模型 API 不通”和“本地 TUI 连接不通”混在一起。

## 常见配置组合

```bash
# 公司 HTTPS 代理 + 本地绕过
export HTTPS_PROXY=https://proxy.example.com:8080
export NO_PROXY=localhost,127.0.0.1

# 公司 CA
export NODE_EXTRA_CA_CERTS=/path/to/ca-cert.pem
```

不要盲目同时设置很多变量。变量越多，越难判断当前请求到底走了哪条网络路径。

## 企业环境验收

把网络配置交给团队前，至少验证这几个点：

| 检查项 | 通过标准 |
| --- | --- |
| 本地 TUI | OpenCode 能正常启动，本地 server 没有被代理拦截 |
| 模型请求 | 通过企业允许的代理或 LLM Gateway 发出 |
| 证书链 | `NODE_EXTRA_CA_CERTS` 指向可读 CA 文件，HTTPS 不再报证书错误 |
| 本地绕过 | `localhost`、`127.0.0.1` 已在 `NO_PROXY` |
| 凭据保存 | 代理账号密码不在仓库、文档截图或共享脚本里 |
| 团队说明 | 新同事能看懂哪些流量走代理，哪些流量必须直连本地 |

如果公司统一下发代理配置，也要额外确认 OpenCode 所在的 shell 能继承这些变量。GUI 终端、IDE 集成终端、login shell 和 CI runner 的环境变量来源可能不同。

## 推荐落地方式

个人机器可以放在 shell profile；团队项目不要提交真实代理地址和凭据，只提交变量说明：

```bash
# .env.example
HTTPS_PROXY=
HTTP_PROXY=
NO_PROXY=localhost,127.0.0.1
NODE_EXTRA_CA_CERTS=
```

真实值由每台机器或企业设备管理系统提供。这样教程、仓库和实际凭据分开，既能复现配置关系，又不会把网络凭据带进源码。

## 官方来源

- [OpenCode Network](https://opencode.ai/docs/network)

## 接下来去哪

<Cards>
  <Card title="权限控制" href="/docs/opencode/official/05-security/permissions" description="网络通了之后再聊代理的写入权限边界" />
  <Card title="排障" href="/docs/opencode/official/08-platform/troubleshooting" description="网络外的常见连接和启动问题" />
  <Card title="Windows / WSL" href="/docs/opencode/official/08-platform/windows-wsl" description="WSL 下的网络代理需要额外注意" />
  <Card title="ACP 跨进程协议" href="/docs/opencode/official/08-platform/acp" description="多进程通信也走本地，配代理时同样要绕开" />
</Cards>
