启动服务器
通过 HTTP 与 OpenCode server 交互，并理解 serve、web、TUI、SDK 和 OpenAPI 的关系。
opencode serve 会启动一个无界面的 HTTP server。它暴露 OpenAPI 3.1 规范和一组 API，让 TUI、SDK、IDE 插件或你自己的系统可以通过 HTTP 与 OpenCode 交互。
这一篇用 12 分钟换什么：你会知道什么时候需要 server、如何安全启动、怎么访问 OpenAPI spec、哪些 API 分组最常用，以及为什么不要把未认证 server 暴露到网络。
先给结论：server 是集成入口，不是第一上手入口
第一次用 OpenCode，先用 TUI 和 CLI。只有当你要把 OpenCode 接进其他客户端、后台服务、IDE 插件或自动化系统时，才需要 server。
| 场景 | 优先入口 |
|---|---|
| 人在终端里交互式写代码 | opencode TUI |
| 脚本里跑一次任务 | opencode run |
| 浏览器访问 OpenCode | opencode web |
| 程序通过 HTTP 调用 OpenCode | opencode serve |
| JS/TS 程序类型安全调用 | SDK |
如果要把 server 绑定到局域网或公网地址，先配置 OPENCODE_SERVER_PASSWORD。未认证 server 会暴露项目上下文和工具能力。
OpenCode 的 server 架构
flowchart LR
TUI[TUI] --> Server[OpenCode server]
Web[Web / Desktop / IDE] --> Server
SDK[JS/TS SDK] --> Server
Custom[你的系统] --> Server
Server --> Project[项目文件和会话]
Server --> Provider[模型 provider]
Server --> Tools[tools / MCP / LSP / formatter]
Server --> Spec[/doc OpenAPI 3.1]运行 opencode 时，TUI 本身也是一个 client，会和本地 server 通信。opencode serve 则启动一个独立 server；如果 TUI 已经在运行，再执行 serve 会启动一个新的 server。
启动方式
最小启动：
opencode serve常用参数：
--port：监听端口，默认4096。--hostname：监听主机名，默认127.0.0.1。--mdns：启用 mDNS（multicast DNS，局域网内自动发现服务的协议，不依赖 DNS 服务器）发现。--mdns-domain：自定义 mDNS 服务域名，默认opencode.local。--cors：额外允许的浏览器来源（CORS 即跨源资源共享，浏览器为防止恶意站点偷调你的 API 默认会拦截跨域请求；这里写白名单告诉 server 哪些前端域名是被信任的），可以传多次。
允许多个 CORS 来源：
opencode serve --cors http://localhost:5173 --cors https://app.example.com认证必须先配
设置 HTTP Basic Auth：
export OPENCODE_SERVER_PASSWORD="change-me"
opencode serve默认用户名是 opencode。需要改用户名时：
export OPENCODE_SERVER_USERNAME="team-agent"
export OPENCODE_SERVER_PASSWORD="change-me"
opencode serve --hostname 0.0.0.0 --port 4096OPENCODE_SERVER_PASSWORD 同时适用于 opencode serve 和 opencode web。
--hostname 0.0.0.0 会让其他机器访问到这个 server。没有认证、没有网络边界、没有反向代理保护时不要这样启动。
OpenAPI spec 在哪里
server 会发布 OpenAPI 3.1 规范：
http://<hostname>:<port>/doc本机默认是：
http://localhost:4096/doc这个页面适合做三件事：
- 查看当前 server 真实暴露的 endpoint。
- 检查请求体和响应类型。
- 生成客户端，或和官方 SDK 类型对照。
API 变动时，以当前 /doc 和官方 SDK 生成类型为准，不要长期依赖手抄 endpoint 表。
最小健康检查
本地无认证时：
curl http://127.0.0.1:4096/global/health启用认证后：
curl -u "opencode:$OPENCODE_SERVER_PASSWORD" http://127.0.0.1:4096/global/health健康接口返回 server 是否 healthy 和当前版本。它适合放在本地脚本、容器健康检查或集成测试的第一步。
常用 API 分组
不需要背完整 endpoint。先按分组理解：
- Global：
/global/health、/global/event，检查 server 状态和全局事件流。 - Project / Path / VCS：读取当前项目、路径和版本控制信息。
- Config / Provider / Auth：读取或更新配置、列 provider、处理 OAuth 或 provider 凭据。
- Session：创建、读取、删除、fork、abort、share、diff、todo、permissions。
- Message：发送 prompt、异步发送、执行 command、运行 shell。
- Files：查找文件、搜索文本、读取内容、查看文件状态。
- Tools / LSP / Formatter / MCP：读取工具、语言服务、格式化器和 MCP 状态。
- TUI：追加 prompt、提交 prompt、打开帮助、打开模型选择器、显示 toast。
- Docs：
/doc，查看 OpenAPI 3.1 规范。
其中最常用于自动化的是 Session、Message、Files 和 /global/health。
一条最小集成路径
先不要一上来写复杂客户端。按这个顺序验证：
opencode serve能启动。/global/health能返回 healthy。/doc能打开。- 能列出当前项目或 session。
- 能创建一个 session。
- 能发送一个只读 message。
- 能读取 diff 或结果。
- 能正确处理权限请求、错误和 abort。
如果你用 JS/TS，下一步直接用 SDK。SDK 会复用 server 的 OpenAPI 类型，比手写 fetch 更不容易错。
TUI endpoint 怎么理解
/tui/* endpoint 可以通过 server 驱动 TUI，比如追加 prompt、提交 prompt、打开 help、打开 session/model/theme 选择器、显示 toast。
这类能力适合 IDE 插件或桌面集成，不适合普通脚本滥用。普通脚本更应该直接用 session/message API 或 CLI run。
安全边界
server 能触达项目文件、会话、工具、provider 和模型。上线前至少确认：
- 是否启用了 Basic Auth。
- 是否限制了 hostname、端口和网络访问范围。
- 是否只允许必要 CORS origin。
- 是否禁用了不需要的分享、MCP 或高风险工具。
- 是否避免把 auth 信息写入代码仓库和日志。
- 是否能在请求失败时 abort session。
- 是否能在集成测试后清理临时 session。
如果这些答不清，先不要把 OpenCode server 接进团队后台或公网服务。
新手常见坑
- TUI 还没跑通就直接接 server，结果 provider、权限、项目配置问题全混在一起。
- 绑定
0.0.0.0但没设置OPENCODE_SERVER_PASSWORD。 - 前端调 server 时随手放开
--cors "*", 没有 origin 边界。 - 手抄 endpoint 表，忘了以
/doc和 SDK 类型为准。 - 用
/tui/*做普通自动化，而不是用 session/message API。 - 没有处理权限请求、abort、错误重试和 session 清理。
接下来去哪
使用 SDK
JS/TS 集成优先用 SDK，避免手写 HTTP 类型和请求体。
使用 CLI
只想脚本化跑一次任务时，CLI run 通常比 server 更简单。
排查故障
server 连接失败、端口冲突、provider 错误时按排障页定位。
权限配置
server 接入真实项目之前，先把文件、shell、MCP 和分享权限收紧。