---
title: "启动服务器"
description: "通过 HTTP 与 OpenCode server 交互，并理解 serve、web、TUI、SDK 和 OpenAPI 的关系。"
verifiedAt: "2026-05-09"
---

`opencode serve` 会启动一个无界面的 HTTP server。它暴露 OpenAPI 3.1 规范和一组 API，让 TUI、SDK、IDE 插件或你自己的系统可以通过 HTTP 与 OpenCode 交互。

> [!NOTE]
> **这一篇用 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 |

> [!IMPORTANT]
> 如果要把 server 绑定到局域网或公网地址，先配置 `OPENCODE_SERVER_PASSWORD`。未认证 server 会暴露项目上下文和工具能力。

## OpenCode 的 server 架构

```mermaid
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。

## 启动方式

最小启动：

```bash
opencode serve
```

常用参数：

- `--port`：监听端口，默认 `4096`。
- `--hostname`：监听主机名，默认 `127.0.0.1`。
- `--mdns`：启用 mDNS（multicast DNS，局域网内自动发现服务的协议，不依赖 DNS 服务器）发现。
- `--mdns-domain`：自定义 mDNS 服务域名，默认 `opencode.local`。
- `--cors`：额外允许的浏览器来源（CORS 即跨源资源共享，浏览器为防止恶意站点偷调你的 API 默认会拦截跨域请求；这里写白名单告诉 server 哪些前端域名是被信任的），可以传多次。

允许多个 CORS 来源：

```bash
opencode serve --cors http://localhost:5173 --cors https://app.example.com
```

## 认证必须先配

设置 HTTP Basic Auth：

```bash
export OPENCODE_SERVER_PASSWORD="change-me"
opencode serve
```

默认用户名是 `opencode`。需要改用户名时：

```bash
export OPENCODE_SERVER_USERNAME="team-agent"
export OPENCODE_SERVER_PASSWORD="change-me"
opencode serve --hostname 0.0.0.0 --port 4096
```

`OPENCODE_SERVER_PASSWORD` 同时适用于 `opencode serve` 和 `opencode web`。

> [!WARNING]
> `--hostname 0.0.0.0` 会让其他机器访问到这个 server。没有认证、没有网络边界、没有反向代理保护时不要这样启动。

## OpenAPI spec 在哪里

server 会发布 OpenAPI 3.1 规范：

```text
http://<hostname>:<port>/doc
```

本机默认是：

```text
http://localhost:4096/doc
```

这个页面适合做三件事：

- 查看当前 server 真实暴露的 endpoint。
- 检查请求体和响应类型。
- 生成客户端，或和官方 SDK 类型对照。

> [!TIP]
> API 变动时，以当前 `/doc` 和官方 SDK 生成类型为准，不要长期依赖手抄 endpoint 表。

## 最小健康检查

本地无认证时：

```bash
curl http://127.0.0.1:4096/global/health
```

启用认证后：

```bash
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`。

## 一条最小集成路径

先不要一上来写复杂客户端。按这个顺序验证：

1. `opencode serve` 能启动。
2. `/global/health` 能返回 healthy。
3. `/doc` 能打开。
4. 能列出当前项目或 session。
5. 能创建一个 session。
6. 能发送一个只读 message。
7. 能读取 diff 或结果。
8. 能正确处理权限请求、错误和 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 清理。

## 接下来去哪

<Cards>
  <Card title="使用 SDK" href="/docs/opencode/official/07-sdk/sdk">
    JS/TS 集成优先用 SDK，避免手写 HTTP 类型和请求体。
  </Card>
  <Card title="使用 CLI" href="/docs/opencode/official/00-getting-started/cli">
    只想脚本化跑一次任务时，CLI `run` 通常比 server 更简单。
  </Card>
  <Card title="排查故障" href="/docs/opencode/official/08-platform/troubleshooting">
    server 连接失败、端口冲突、provider 错误时按排障页定位。
  </Card>
  <Card title="权限配置" href="/docs/opencode/official/05-security/permissions">
    server 接入真实项目之前，先把文件、shell、MCP 和分享权限收紧。
  </Card>
</Cards>

## 官方资料

- [OpenCode server](https://opencode.ai/docs/server/)
- [OpenCode SDK](https://opencode.ai/docs/sdk/)
- [OpenCode CLI](https://opencode.ai/docs/cli/)
- [OpenCode permissions](https://opencode.ai/docs/permissions/)
