---
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="/docs/opencode/official/07-sdk/server" />
  <Card title="使用 SDK" description="如果目标是从 JS/TS 程序调用 OpenCode，优先看 SDK。" href="/docs/opencode/official/07-sdk/sdk" />
  <Card title="Windows WSL" description="Windows 上使用 Web 时，优先从 WSL 运行以保证文件系统和终端一致。" href="/docs/opencode/official/08-platform/windows-wsl" />
  <Card title="权限配置" description="Web 接入真实项目前，先收紧文件、shell、MCP 和分享权限。" href="/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)
