解决方案设计
技术研究 OpenCode 架构设计
解析 OpenCode Server 与 CLI 的架构关系、设计动机与典型应用场景
架构解析
客户端-服务器架构
OpenCode 采用客户端-服务器架构，这是理解 Server 功能的核心：
┌─────────────────────────────────────────────────────────────┐
│ OpenCode 整体架构 │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ TUI 客户端 │ │ Web 客户端 │ │ IDE 插件 │ │
│ │ (Terminal) │ │ (Browser) │ │ (VSCode等) │ │
│ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │
│ │ │ │ │
│ └──────────────────┼──────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ OpenCode Server (HTTP) │ │
│ │ │ │
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │
│ │ │ Session 管理 │ │ Message 处理 │ │ File 操作 │ │ │
│ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │
│ │ │ │
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │
│ │ │ MCP 管理 │ │ LSP 服务 │ │ Provider │ │ │
│ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │
│ └─────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ AI Provider (Claude/GPT/etc.) │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘默认行为解析
当执行 opencode 命令（无参数）时：
- 同时启动 TUI 和 Server：TUI 作为客户端连接到 Server
- 随机端口分配：Server 监听随机端口
- 本地回环地址：默认绑定
127.0.0.1
当执行 opencode serve 时：
- 仅启动 Server：无 TUI 界面
- 指定端口：默认
4096 - 可配置绑定地址：支持
0.0.0.0远程访问
通信协议
客户端 ◄───────► Server
│
├── HTTP/1.1 (REST API)
├── Server-Sent Events (事件流)
└── WebSocket (未来可能支持)为什么会有这个特性
设计动机
1. 多客户端支持
问题：传统的 CLI 工具通常只能通过单一终端界面使用。
解决：客户端-服务器架构允许多种客户端：
- TUI（终端用户界面）
- Web 界面（
opencode web） - IDE 插件（VSCode、Zed 等）
- 自定义客户端（通过 HTTP API）
# 示例：多客户端同时连接同一 Server
# Terminal 1: 启动 Server
opencode serve --port 4096 --hostname 0.0.0.0
# Terminal 2: TUI 客户端连接
opencode attach http://localhost:4096
# Browser: Web 界面访问
# http://localhost:40962. 远程开发场景
问题：开发者在本地机器上运行 AI 编码助手，但项目代码可能在远程服务器上。
解决：Server 可部署在远程机器，客户端从本地连接：
┌─────────────────┐ ┌─────────────────┐
│ 本地开发机 │ │ 远程服务器 │
│ │ │ │
│ ┌───────────┐ │ HTTP │ ┌───────────┐ │
│ │ TUI/Web │◄─┼──────────┼─►│ Server │ │
│ │ 客户端 │ │ │ │ │ │
│ └───────────┘ │ │ │ ┌─────┐ │ │
│ │ │ │ │代码库│ │ │
│ │ │ │ └─────┘ │ │
│ │ │ │ ┌─────┐ │ │
│ │ │ │ │ LSP │ │ │
│ │ │ │ └─────┘ │ │
└─────────────────┘ │ └───────────┘ │
└─────────────────┘3. 程序化访问
问题：需要通过脚本或程序调用 AI 编码助手的能力。
解决：HTTP API 支持完整的程序化访问：
# 示例：通过 curl 创建会话并发送消息
SESSION_ID=$(curl -s -X POST http://localhost:4096/session | jq -r '.id')
curl -X POST "http://localhost:4096/session/$SESSION_ID/message" \
-H "Content-Type: application/json" \
-d '{"parts": [{"type": "text", "text": "解释 Go 语言中的闭包"}]}'4. 资源共享
问题：MCP 服务器、LSP 服务启动耗时较长，每次启动 CLI 都需要重新初始化。
解决：Server 保持运行，客户端可随时连接，避免重复初始化：
首次启动: opencode serve (加载 MCP、LSP 等，耗时约 10-30 秒)
后续连接: opencode run --attach http://localhost:4096 (毫秒级连接)5. 企业部署
问题：企业需要集中管理 AI 编码助手，控制成本和访问权限。
解决：
- Server 可部署在内部服务器
- 通过 HTTP Basic Auth 控制访问
- 统一管理 API Key 和模型配置
与 CLI 工具的关系
关系图谱
| 组件 | 角色 | 启动方式 | 用途 |
|---|---|---|---|
opencode | CLI 入口 | opencode | 启动 TUI + Server |
| TUI | 客户端 | 自动启动 | 终端交互界面 |
| Server | 后端服务 | 自动启动 或 opencode serve | 提供核心能力 |
opencode serve | 独立 Server | 手动启动 | 无界面服务模式 |
opencode attach | 客户端连接 | 手动执行 | 连接已有 Server |
opencode web | Web 服务 | 手动启动 | Server + Web UI |
命令对比
# 标准模式：TUI + Server（本地）
opencode
# Server 模式：仅 Server（本地/远程）
opencode serve --port 4096 --hostname 0.0.0.0
# Web 模式：Server + Web UI
opencode web --port 4096
# 附加模式：TUI 连接到已有 Server
opencode attach http://remote-server:4096
# 运行模式：非交互式执行命令
opencode run "解释这段代码" --attach http://localhost:4096