---
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="/zh-Hant/docs/opencode/official/05-security/permissions" description="網路通了之後再聊代理的寫入許可權邊界" />
  <Card title="排障" href="/zh-Hant/docs/opencode/official/08-platform/troubleshooting" description="網路外的常見連線和啟動問題" />
  <Card title="Windows / WSL" href="/zh-Hant/docs/opencode/official/08-platform/windows-wsl" description="WSL 下的網路代理需要額外注意" />
  <Card title="ACP 跨程序協議" href="/zh-Hant/docs/opencode/official/08-platform/acp" description="多程序通訊也走本地，配代理時同樣要繞開" />
</Cards>
