---
title: "在 Web 中使用 OpenCode"
description: "說明如何在瀏覽器中使用 OpenCode，並區分 Web 入口、SDK 和 server 的職責。"
verifiedAt: "2026-05-09"
---

OpenCode Web 讓你在瀏覽器裡使用 OpenCode。它適合偏好 Web 介面、Desktop/Web 客戶端、遠端機器或區域網訪問的場景，但安全邊界和 server 是同一類問題。

<img
  src="/images/opencode/web-new-session.png"
  alt="OpenCode Web - New Session"
  width="2766"
  height="1970"
  loading="eager"
/>

> [!NOTE]
> **這一篇用 8 分鐘換什麼**：你會知道 `opencode web` 適合什麼場景、埠和 hostname 怎麼配、什麼時候必須設定密碼，以及如何用 `attach` 讓 TUI 連線同一個 Web server。

## 先給結論：Web 是介面，server 是邊界

Web 不會讓 OpenCode 變成普通網頁應用。它背後仍然是能訪問專案、會話、模型和工具的 OpenCode server。

```mermaid
flowchart LR
  Browser["Windows / macOS 瀏覽器"] --> Web["opencode web"]
  TUI["終端 TUI"] --> Attach["opencode attach"]
  Attach --> Web
  Web --> Project["專案檔案和會話"]
  Web --> Provider["模型 provider"]
  Web --> Tools["tools / MCP / permissions"]

  style Web fill:#dbeafe,stroke:#3b82f6,stroke-width:2px
  style Attach fill:#dcfce7,stroke:#22c55e
  style Project fill:#fef3c7,stroke:#f59e0b
```

本機使用可以簡單啟動；一旦繫結到區域網或公網地址，就必須先處理認證、CORS 和網路邊界。

## 快速開始

啟動 Web 介面：

```bash
opencode web
```

這會在 `127.0.0.1` 上啟動本地 server，使用隨機可用埠，並自動在預設瀏覽器中開啟 OpenCode。

如果未設定 `OPENCODE_SERVER_PASSWORD`，server 將沒有安全保護。本機臨時使用問題不大；網路訪問時必須設定密碼。

> [!IMPORTANT]
> Windows 使用者建議從 WSL 中執行 `opencode web`，而不是 PowerShell。這樣檔案系統訪問、終端整合和開發工具鏈更一致。

## 埠、hostname 和認證

指定埠：

```bash
opencode web --port 4096
```

預設繫結到 `127.0.0.1`。要讓區域網訪問：

```bash
OPENCODE_SERVER_PASSWORD=change-me opencode web --hostname 0.0.0.0 --port 4096
```

使用者名稱預設是 `opencode`，可以用 `OPENCODE_SERVER_USERNAME` 更改。

> [!WARNING]
> 不要在沒有密碼的情況下使用 `--hostname 0.0.0.0`。這會把專案上下文和工具能力暴露給網路。

## mDNS 和 CORS 什麼時候用

啟用 **mDNS**（multicast DNS，區域網內自動發現服務的協議）可以讓本地網路其他裝置自動找到這個 server：

```bash
opencode web --mdns
```

這會自動將 hostname 設定為 `0.0.0.0`，並廣播為 `opencode.local`。同樣需要先處理密碼。

如果你要讓自定義前端訪問 OpenCode server，可以新增 **CORS**（cross-origin resource sharing，跨源資源共享——瀏覽器預設攔截跨域請求，這裡寫白名單告訴 server 哪些前端域名是被信任的）origin：

```bash
opencode web --cors https://example.com
```

不要為了省事放開所有 origin。自定義前端、區域網訪問和遠端訪問都應該有明確邊界。

## Web 介面能做什麼

啟動後，Web 介面可以檢視和管理 OpenCode 會話、建立新會話、檢視已連線 server 狀態。

<img
  src="/images/opencode/web-active-session.png"
  alt="OpenCode Web - Active Session"
  width="2766"
  height="1970"
  loading="eager"
/>

點選 “See Servers” 可以檢視已連線的 server 及其狀態。

<img
  src="/images/opencode/web-see-servers.png"
  alt="OpenCode Web - See Servers"
  width="2766"
  height="1970"
  loading="eager"
/>

Web 適合看會話和互動，不適合繞過專案安全基線。許可權、provider、share、MCP 仍然按 OpenCode 配置生效。

## 連線終端 TUI

你可以把終端 TUI 連線到正在執行的 Web server：

```bash
opencode web --port 4096
```

另一個終端中連線：

```bash
opencode attach http://localhost:4096
```

這樣 Web 和 TUI 可以共享相同的會話和狀態。適合你想在瀏覽器裡看會話，同時仍然用終端做高頻輸入和工具觀察。

## 配置檔案方式

也可以在 `opencode.json` 配置 server 選項：

```jsonc title="opencode.json"
{
  "$schema": "https://opencode.ai/config.json",
  "server": {
    "port": 4096,
    "hostname": "127.0.0.1",
    "mdns": false,
    "cors": ["https://example.com"]
  }
}
```

命令列標誌的優先順序高於配置檔案。團隊專案不要把只適合你本機的 hostname、port 或 CORS origin 寫進共享配置。

## 怎麼驗收

至少確認：

- 本機 `opencode web` 能開啟瀏覽器。
- 繫結 `0.0.0.0` 前已經設定 `OPENCODE_SERVER_PASSWORD`。
- CORS 只允許必要 origin。
- Windows 場景優先從 WSL 啟動。
- `opencode attach` 能連線同一個 server。
- Web 會話裡不包含不該公開的金鑰、客戶資料或內部日誌。

## 接下來去哪

<Cards>
  <Card title="啟動伺服器" description="Web 背後仍是 OpenCode server；先理解 OpenAPI、認證和健康檢查。" href="/zh-Hant/docs/opencode/official/07-sdk/server" />
  <Card title="使用 SDK" description="如果目標是從 JS/TS 程式呼叫 OpenCode，優先看 SDK。" href="/zh-Hant/docs/opencode/official/07-sdk/sdk" />
  <Card title="Windows WSL" description="Windows 上使用 Web 時，優先從 WSL 執行以保證檔案系統和終端一致。" href="/zh-Hant/docs/opencode/official/08-platform/windows-wsl" />
  <Card title="許可權配置" description="Web 接入真實專案前，先收緊檔案、shell、MCP 和分享許可權。" href="/zh-Hant/docs/opencode/official/05-security/permissions" />
</Cards>

## 官方資料

- OpenCode Web：[https://opencode.ai/docs/web](https://opencode.ai/docs/web)
- OpenCode Server：[https://opencode.ai/docs/server](https://opencode.ai/docs/server)
- Windows / WSL：[https://opencode.ai/docs/windows-wsl](https://opencode.ai/docs/windows-wsl)
