配置网络

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

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

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 服务器进行通信。你必须为此连接绕过代理，以防止路由循环。

最小配置形态是：

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

你可以使用 CLI 标志来配置服务器的端口和主机名。

为什么 NO_PROXY 必须配置

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

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

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

需要账号密码的代理

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

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

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

代理凭据不要进仓库

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

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 连接不通”混在一起。

常见配置组合

# 公司 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

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

企业环境验收

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

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

推荐落地方式

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

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

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

官方来源

• OpenCode Network

接下来去哪