启动与连接服务端
理解 OpenCode 服务生命周期、监听参数、认证、OpenAPI 和事件流。
This page has not been translated into English yet. The original Chinese version is shown below.
opencode serve 启动无 TUI 的 HTTP 服务。普通 opencode 也会启动服务，并让 TUI 作为客户端连接；已有 TUI 运行时再次执行 serve 会新建服务，不是连接原服务。
启动参数
opencode serve| 参数 | serve 默认值 |
|---|---|
--port | 4096 |
--hostname | 127.0.0.1 |
--mdns | false |
--mdns-domain | opencode.local |
--cors | [] |
--cors 可以重复传入，例如：
opencode serve --cors http://localhost:5173 --cors https://app.example.com这里列出的是 serve 的默认值；Web 与 TUI 的端口行为不同。要连接 TUI 自带的服务，可在启动 TUI 时明确设置 --hostname 和 --port。
认证与客户端
设置 OPENCODE_SERVER_PASSWORD 启用 HTTP Basic Auth，用户名默认 opencode，可用 OPENCODE_SERVER_USERNAME 修改。这个机制同时适用于 serve 和 web。
终端客户端用 opencode attach [url]；脚本可用 opencode run --attach <url>，两者均有用户名/密码选项。连接远程任务时，工作目录位于服务端；不能假设本地客户端路径一定存在于后端。
浏览器访问、网络监听和服务发现见Web 界面。
先检查服务与接口定义
GET /global/health 返回健康状态及版本，官方示意为 { healthy: true, version: string }。接口文档位于 http://<hostname>:<port>/doc，例如 http://localhost:4096/doc。
服务发布 OpenAPI 3.1 规范，SDK 也从它生成。/doc 的官方响应描述是带规范的 HTML 页面，因此不应未经核实就把它作为纯 JSON 响应处理。
具体请求与响应类型应与正在连接的服务版本匹配。项目、文件和系统端点见HTTP API，会话流程见会话 API。
订阅事件
| 端点 | 用途 |
|---|---|
GET /global/event | 全局 SSE 事件流 |
GET /event | 服务事件流，首先收到 server.connected，之后是总线事件 |
SSE 是持续事件流，不是一次性 JSON 响应。接入异步提示时，需要结合事件和会话状态获取任务进展；官方 Server 页没有在这两行中定义重连与持久投递保证。