配置網路

這頁解決的是企業網路或代理環境下的連線問題。普通家庭網路通常不需要配置；如果你在公司網路、透明代理、內網閘道器或自建 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

接下來去哪