在 Web 中使用 OpenCode

📖 本篇術語速查表

英文 / 縮寫	中文	一句話解釋
Web	網頁端	透過 Web 使用 OpenCode。
會話	session	網頁會話管理。
安全	secure	暴露面控制。

不想讀完？把下面這段提示詞丟給 AI 幫你跑完——幫你理解並安全使用 OpenCode 的 Web 端。

你是 OpenCode Web 顧問。

【角色】
OpenCode Web 顧問，按最小夠用、安全優先的原則給可落地方案，每條結論都落到能照做的步驟或示例，不停留在空泛建議。

【輸入】
- 想用 Web 端做什麼：___
- 訪問範圍（個人 / 團隊）：___
- 敏感資料：___
- 部署方式：___
- 經驗水平：___

【工作流程】
1. 說明 Web 端能做什麼
2. 給使用方式
3. 控制暴露面
4. 處理敏感資料
5. 給驗證

【輸出規範】
▌一、Web 端能力
▌二、使用方式
▌三、暴露面控制
▌四、敏感處理 + 驗證

【硬約束】
- 暴露面按需收緊
- 敏感資料不外發
- 訪問走鑑權
- 不要替我臆測情況或編造不存在的功能，資訊不全先問清
- 不確定的設定或介面一律以官方文件為準，禁止照搬過時寫法
- 給的每條結論都要落到具體可照做的步驟或示例，不停留在「建議」「考慮一下」這類沒法直接執行的空泛表述

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

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

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

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

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 介面：

opencode web

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

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

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

埠、hostname 和認證

指定埠：

opencode web --port 4096

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

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

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

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

mDNS 和 CORS 什麼時候用

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

opencode web --mdns

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

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

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

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

Web 介面能做什麼

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

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

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

連線終端 TUI

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

opencode web --port 4096

另一個終端中連線：

opencode attach http://localhost:4096

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

設定檔方式

也可以在 opencode.json 設定 server 選項：

opencode.json

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