12.3 Web UI

模型: claude-opus-4-6 (anthropic/claude-opus-4-6) 生成日期: 2026-02-17

---

虽然 OpenCode 以"终端优先"为设计理念，但它也提供了完整的 Web UI——通过浏览器访问 OpenCode，获得更丰富的视觉体验。

衍生解释：SolidJS 与 React 的异同

SolidJS 是一个 JavaScript UI 框架，其 API 设计与 React 非常相似（都使用 JSX、组件、Hook 风格的 API），但底层实现完全不同：

特性	React	SolidJS
更新机制	Virtual DOM diffing	细粒度响应式（编译时确定依赖）
组件重渲染	整个组件函数重新执行	仅更新变化的 DOM 节点
性能	需要 useMemo、useCallback 优化	默认高性能，无需手动优化
包大小	~40KB (gzipped)	~7KB (gzipped)
生态	庞大	较小但快速增长

OpenCode 选择 SolidJS 作为 Web UI 的框架，可能考虑到了包大小和运行时性能——对于一个 CLI 工具的内嵌 Web 界面，轻量级是重要的。更重要的是，TUI 也使用了 @opentui/solid（Solid.js 的终端渲染器），因此 TUI 和 Web UI 可以共享一部分组件逻辑和设计理念。

12.3.1 Web UI 的架构

Web UI 位于 packages/app/ 目录，是一个独立的 SolidJS 应用：

packages/app/
├── src/
│   ├── entry.tsx        # 应用入口
│   ├── app.tsx          # 根组件
│   ├── components/      # UI 组件
│   ├── context/         # 状态上下文
│   ├── hooks/           # 自定义 Hook
│   ├── pages/           # 页面
│   ├── utils/           # 工具函数
│   ├── i18n/            # 国际化
│   └── index.css        # 全局样式
├── index.html           # HTML 模板
├── vite.config.ts       # Vite 构建配置
├── package.json
└── e2e/                 # 端到端测试
    └── playwright.config.ts

Web UI 使用 Vite 作为构建工具，支持开发时的热更新（HMR）和生产环境的优化构建。

12.3.2 启动 Web UI

用户通过 opencode web 命令启动 Web UI：

// cli/cmd/web.ts
export const WebCommand = cmd({
  command: "web",
  describe: "start opencode server and open web interface",
  handler: async (args) => {
    // 1. 安全警告
    if (!Flag.OPENCODE_SERVER_PASSWORD) {
      UI.println("! OPENCODE_SERVER_PASSWORD is not set; server is unsecured.")
    }

    // 2. 启动 HTTP Server
    const opts = await resolveNetworkOptions(args)
    const server = Server.listen(opts)

    // 3. 显示访问地址
    UI.println(UI.logo("  "))

    if (opts.hostname === "0.0.0.0") {
      // 显示本地和网络地址
      UI.println("  Local access:      ", `http://localhost:${server.port}`)

      const networkIPs = getNetworkIPs()
      for (const ip of networkIPs) {
        UI.println("  Network access:    ", `http://${ip}:${server.port}`)
      }

      if (opts.mdns) {
        UI.println("  mDNS:              ", `${opts.mdnsDomain}:${server.port}`)
      }

      open(`http://localhost:${server.port}`)
    } else {
      UI.println("  Web interface:    ", server.url.toString())
      open(server.url.toString())
    }

    // 4. 保持进程运行
    await new Promise(() => {})
  },
})

web 命令做了以下几件事：

1. 启动 HTTP Server：与 serve 命令共享同一个 Server 实现（基于 Hono 框架）。Server 既提供 API 端点，也托管 Web UI 的静态文件。

2. 显示访问地址：当监听 0.0.0.0 时（默认），显示本地地址和所有网络 IP 地址，方便从其他设备访问。

3. mDNS 服务发现：可选地启用 mDNS（Multicast DNS），使得同一局域网内的设备可以通过域名（如 opencode.local）而非 IP 地址访问。

4. 自动打开浏览器：使用 open 包在默认浏览器中打开 Web UI。

5. 安全警告：如果没有设置 OPENCODE_SERVER_PASSWORD 环境变量，显示安全警告。当 Server 暴露在网络上时，密码保护非常重要。

12.3.3 Web UI 与 Server 的实时通信

Web UI 通过 OpenCode SDK（@opencode-ai/sdk/v2）与 Server 通信。SDK 提供了类型安全的 API 客户端，支持：

• REST API：Session CRUD、消息发送、配置管理等。

• SSE 事件流：实时接收 Session 状态变化、消息更新、权限请求等事件。

// Web UI 中的典型用法
const sdk = createOpencodeClient({
  baseUrl: serverUrl,
  directory: projectPath,
})

// 创建会话
const session = await sdk.session.create({})

// 发送消息
await sdk.session.chat({
  sessionID: session.id,
  content: "Help me fix this bug",
})

// 订阅事件
const events = await sdk.event.subscribe({})
for await (const event of events.stream) {
  // 处理各种事件：message.updated、session.status 等
}

12.3.4 共享 UI 组件库

packages/ui/ 是一个共享的 UI 组件库，同时被 Web UI（packages/app/）和其他前端包使用。这种设计确保了 Web UI 和其他前端（如云控制台 packages/console/）的视觉一致性。

12.3.5 小结

Web UI 的设计遵循了几个原则：

1. Optional but Complete：Web UI 是可选的（opencode web 需要显式启动），但一旦启动，提供完整的功能。

2. 安全第一：默认不监听外部网络，当需要时通过密码保护。

3. 网络友好：支持 mDNS、多 IP 显示、CORS 配置，方便在各种网络环境中使用。

4. 复用 Server：Web UI 与 TUI 共享同一个 Server 实例和 API，没有为 Web UI 单独实现后端逻辑。