---
title: Сервер
description: Взаимодействуйте с сервером opencode через HTTP.
---

import config from "../../../../config.mjs"
export const typesUrl = `${config.github}/blob/dev/packages/sdk/js/src/gen/types.gen.ts`

Команда `opencode serve` запускает автономный HTTP-сервер, который предоставляет конечную точку OpenAPI, которую может использовать клиент с открытым кодом.

---

### Использование

```bash
opencode serve [--port <number>] [--hostname <string>] [--cors <origin>]
```

#### Параметры

| Флаг            | Описание                                    | По умолчанию     |
| --------------- | ------------------------------------------- | ---------------- |
| `--port`        | Порт для прослушивания                      | `4096`           |
| `--hostname`    | Имя хоста для прослушивания                 | `127.0.0.1`      |
| `--mdns`        | Включить обнаружение mDNS                   | `false`          |
| `--mdns-domain` | Пользовательское доменное имя для mDNS      | `opencode.local` |
| `--cors`        | Разрешенные дополнительные источники (CORS) | `[]`             |

`--cors` можно передать несколько раз:

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

---

### Аутентификация

Установите `OPENCODE_SERVER_PASSWORD`, чтобы защитить сервер с помощью базовой аутентификации HTTP. Имя пользователя по умолчанию — `opencode` или установите `OPENCODE_SERVER_USERNAME`, чтобы переопределить его. Это относится как к `opencode serve`, так и к `opencode web`.

```bash
OPENCODE_SERVER_PASSWORD=your-password opencode serve
```

---

### Как это работает

Когда вы запускаете `opencode`, он запускает TUI и сервер. Где находится TUI
клиент, который общается с сервером. Сервер предоставляет спецификацию OpenAPI 3.1.
конечная точка. Эта конечная точка также используется для создания файла [SDK](/docs/sdk).

:::tip
Используйте сервер opencode для программного взаимодействия с открытым кодом.
:::

Эта архитектура позволяет открытому коду поддерживать несколько клиентов и позволяет программно взаимодействовать с открытым кодом.

Вы можете запустить `opencode serve`, чтобы запустить автономный сервер. Если у вас есть
TUI с открытым кодом запущен, `opencode serve` запустит новый сервер.

---

#### Подключиться к существующему серверу

Когда вы запускаете TUI, он случайным образом назначает порт и имя хоста. Вместо этого вы можете передать `--hostname` и `--port` [flags](/docs/cli). Затем используйте это для подключения к его серверу.

Конечную точку [`/tui`](#tui) можно использовать для управления TUI через сервер. Например, вы можете предварительно заполнить или запустить подсказку. Эта настройка используется плагинами opencode [IDE](/docs/ide).

---

## Спецификация

Сервер публикует спецификацию OpenAPI 3.1, которую можно просмотреть по адресу:

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

For example, `http://localhost:4096/doc`. Use the spec to generate clients or inspect request and response types. Or view it in a Swagger explorer.

---

## API

Сервер opencode предоставляет следующие API.

---

### Глобальный

| Метод | Путь             | Описание                                | Ответ                                |
| ----- | ---------------- | --------------------------------------- | ------------------------------------ |
| `GET` | `/global/health` | Получить состояние и версию сервера     | `{ healthy: true, version: string }` |
| `GET` | `/global/event`  | Получить глобальные события (поток SSE) | Поток событий                        |

---

### Проект

| Метод | Путь               | Описание                | Ответ                                         |
| ----- | ------------------ | ----------------------- | --------------------------------------------- |
| `GET` | `/project`         | Список всех проектов    | <a href={typesUrl}><code>Project[]</code></a> |
| `GET` | `/project/current` | Получить текущий проект | <a href={typesUrl}><code>Project</code></a>   |

---

### Путь и система контроля версий

| Метод | Путь    | Описание                                       | Ответ                                       |
| ----- | ------- | ---------------------------------------------- | ------------------------------------------- |
| `GET` | `/path` | Получить текущий путь                          | <a href={typesUrl}><code>Path</code></a>    |
| `GET` | `/vcs`  | Получить информацию о VCS для текущего проекта | <a href={typesUrl}><code>VcsInfo</code></a> |

---

### Экземпляр

| Метод  | Путь                | Описание                  | Ответ     |
| ------ | ------------------- | ------------------------- | --------- |
| `POST` | `/instance/dispose` | Удалить текущий экземпляр | `boolean` |

---

### Конфигурация

| Метод   | Путь                | Описание                                  | Ответ                                                                                    |
| ------- | ------------------- | ----------------------------------------- | ---------------------------------------------------------------------------------------- |
| `GET`   | `/config`           | Получить информацию о конфигурации        | <a href={typesUrl}><code>Config</code></a>                                               |
| `PATCH` | `/config`           | Обновить конфигурацию                     | <a href={typesUrl}><code>Config</code></a>                                               |
| `GET`   | `/config/providers` | Список провайдеров и моделей по умолчанию | `{ providers: `<a href={typesUrl}>Provider[]</a>`, default: { [key: string]: string } }` |

---

### Поставщик

| Метод  | Путь                             | Описание                                  | Ответ                                                                               |
| ------ | -------------------------------- | ----------------------------------------- | ----------------------------------------------------------------------------------- |
| `GET`  | `/provider`                      | Список всех провайдеров                   | `{ all: `<a href={typesUrl}>Provider[]</a>`, default: {...}, connected: string[] }` |
| `GET`  | `/provider/auth`                 | Получить методы аутентификации провайдера | `{ [providerID: string]: `<a href={typesUrl}>ProviderAuthMethod[]</a>` }`           |
| `POST` | `/provider/{id}/oauth/authorize` | Авторизация провайдера через OAuth        | <a href={typesUrl}><code>ProviderAuthAuthorization</code></a>                       |
| `POST` | `/provider/{id}/oauth/callback`  | Обработка callback OAuth для провайдера   | `boolean`                                                                           |

---

### Сессии

| Метод    | Путь                                     | Описание                                 | Примечания                                                                            |
| -------- | ---------------------------------------- | ---------------------------------------- | ------------------------------------------------------------------------------------- |
| `GET`    | `/session`                               | Список всех сессий                       | Возвращает <a href={typesUrl}><code>Session[]</code></a>                              |
| `POST`   | `/session`                               | Создать новую сессию                     | body: `{ parentID?, title? }`, возвращает <a href={typesUrl}><code>Session</code></a> |
| `GET`    | `/session/status`                        | Получить статус всех сессий              | Возвращает `{ [sessionID: string]: `<a href={typesUrl}>SessionStatus</a>` }`          |
| `GET`    | `/session/:id`                           | Получить детали сессии                   | Возвращает <a href={typesUrl}><code>Session</code></a>                                |
| `DELETE` | `/session/:id`                           | Удалить сессию и все её данные           | Возвращает `boolean`                                                                  |
| `PATCH`  | `/session/:id`                           | Обновить свойства сессии                 | body: `{ title? }`, возвращает <a href={typesUrl}><code>Session</code></a>            |
| `GET`    | `/session/:id/children`                  | Получить дочерние сессии                 | Возвращает <a href={typesUrl}><code>Session[]</code></a>                              |
| `GET`    | `/session/:id/todo`                      | Получить список задач для сессии         | Возвращает <a href={typesUrl}><code>Todo[]</code></a>                                 |
| `POST`   | `/session/:id/init`                      | Анализ приложения и создание `AGENTS.md` | body: `{ messageID, providerID, modelID }`, возвращает `boolean`                      |
| `POST`   | `/session/:id/fork`                      | Ответвление сессии от сообщения          | body: `{ messageID? }`, возвращает <a href={typesUrl}><code>Session</code></a>        |
| `POST`   | `/session/:id/abort`                     | Прервать запущенную сессию               | Возвращает `boolean`                                                                  |
| `POST`   | `/session/:id/share`                     | Поделиться сессией                       | Возвращает <a href={typesUrl}><code>Session</code></a>                                |
| `DELETE` | `/session/:id/share`                     | Отменить общий доступ к сессии           | Возвращает <a href={typesUrl}><code>Session</code></a>                                |
| `GET`    | `/session/:id/diff`                      | Получить diff для этой сессии            | query: `messageID?`, возвращает <a href={typesUrl}><code>FileDiff[]</code></a>        |
| `POST`   | `/session/:id/summarize`                 | Суммировать сессию                       | body: `{ providerID, modelID }`, возвращает `boolean`                                 |
| `POST`   | `/session/:id/revert`                    | Отменить сообщение                       | body: `{ messageID, partID? }`, возвращает `boolean`                                  |
| `POST`   | `/session/:id/unrevert`                  | Восстановить все отмененные сообщения    | Возвращает `boolean`                                                                  |
| `POST`   | `/session/:id/permissions/:permissionID` | Ответить на запрос разрешения            | body: `{ response, remember? }`, возвращает `boolean`                                 |

---

### Сообщения

| Метод  | Путь                              | Описание                                      | Примечания                                                                                                                                                               |
| ------ | --------------------------------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `GET`  | `/session/:id/message`            | Список сообщений в сессии                     | query: `limit?`, возвращает `{ info: `<a href={typesUrl}>Message</a>`, parts: `<a href={typesUrl}>Part[]</a>`}[]`                                                        |
| `POST` | `/session/:id/message`            | Отправить сообщение и ждать ответа            | body: `{ messageID?, model?, agent?, noReply?, system?, tools?, parts }`, возвращает `{ info: `<a href={typesUrl}>Message</a>`, parts: `<a href={typesUrl}>Part[]</a>`}` |
| `GET`  | `/session/:id/message/:messageID` | Получить детали сообщения                     | Возвращает `{ info: `<a href={typesUrl}>Message</a>`, parts: `<a href={typesUrl}>Part[]</a>`}`                                                                           |
| `POST` | `/session/:id/prompt_async`       | Отправить сообщение асинхронно (без ожидания) | body: как в `/session/:id/message`, возвращает `204 No Content`                                                                                                          |
| `POST` | `/session/:id/command`            | Выполнить слэш-команду                        | body: `{ messageID?, agent?, model?, command, arguments }`, возвращает `{ info: `<a href={typesUrl}>Message</a>`, parts: `<a href={typesUrl}>Part[]</a>`}`               |
| `POST` | `/session/:id/shell`              | Запустить команду оболочки                    | body: `{ agent, model?, command }`, возвращает `{ info: `<a href={typesUrl}>Message</a>`, parts: `<a href={typesUrl}>Part[]</a>`}`                                       |

---

### Команды

| Метод | Путь       | Описание           | Ответ                                         |
| ----- | ---------- | ------------------ | --------------------------------------------- |
| `GET` | `/command` | Список всех команд | <a href={typesUrl}><code>Command[]</code></a> |

---

### Файлы

| Метод | Путь                     | Описание                             | Ответ                                                                                        |
| ----- | ------------------------ | ------------------------------------ | -------------------------------------------------------------------------------------------- |
| `GET` | `/find?pattern=<pat>`    | Поиск текста в файлах                | Массив объектов совпадения с `path`, `lines`, `line_number`, `absolute_offset`, `submatches` |
| `GET` | `/find/file?query=<q>`   | Поиск файлов и директорий по имени   | `string[]` (пути)                                                                            |
| `GET` | `/find/symbol?query=<q>` | Поиск символов рабочего пространства | <a href={typesUrl}><code>Symbol[]</code></a>                                                 |
| `GET` | `/file?path=<path>`      | Список файлов и директорий           | <a href={typesUrl}><code>FileNode[]</code></a>                                               |
| `GET` | `/file/content?path=<p>` | Прочитать файл                       | <a href={typesUrl}><code>FileContent</code></a>                                              |
| `GET` | `/file/status`           | Получить статус отслеживаемых файлов | <a href={typesUrl}><code>File[]</code></a>                                                   |

#### `/find/file` параметры запроса

- `query` (обязательно) — строка поиска (нечеткое совпадение)
- `type` (необязательно) — ограничить результаты `"file"` или `"directory"`.
- `directory` (необязательно) — переопределить корень проекта для поиска.
- `limit` (необязательно) — максимальное количество результатов (1–200)
- `dirs` (необязательно) — устаревший флаг (`"false"` возвращает только файлы)

---

### Инструменты (Экспериментальные)

| Метод | Путь                                        | Описание                                       | Ответ                                        |
| ----- | ------------------------------------------- | ---------------------------------------------- | -------------------------------------------- |
| `GET` | `/experimental/tool/ids`                    | Список всех идентификаторов инструментов       | <a href={typesUrl}><code>ToolIDs</code></a>  |
| `GET` | `/experimental/tool?provider=<p>&model=<m>` | Список инструментов со схемами JSON для модели | <a href={typesUrl}><code>ToolList</code></a> |

---

### LSP, форматтеры и MCP

| Метод  | Путь         | Описание                        | Ответ                                                    |
| ------ | ------------ | ------------------------------- | -------------------------------------------------------- |
| `GET`  | `/lsp`       | Получить статус сервера LSP     | <a href={typesUrl}><code>LSPStatus[]</code></a>          |
| `GET`  | `/formatter` | Получить статус форматера       | <a href={typesUrl}><code>FormatterStatus[]</code></a>    |
| `GET`  | `/mcp`       | Получить статус сервера MCP     | `{ [name: string]: `<a href={typesUrl}>MCPStatus</a>` }` |
| `POST` | `/mcp`       | Добавить сервер MCP динамически | body: `{ name, config }`, возвращает статус объекта MCP  |

---

### Агенты

| Метод | Путь     | Описание                      | Ответ                                       |
| ----- | -------- | ----------------------------- | ------------------------------------------- |
| `GET` | `/agent` | Список всех доступных агентов | <a href={typesUrl}><code>Agent[]</code></a> |

---

### Ведение журнала

| Метод  | Путь   | Описание                                                              | Ответ     |
| ------ | ------ | --------------------------------------------------------------------- | --------- |
| `POST` | `/log` | Записать запись в журнал. Body: `{ service, level, message, extra? }` | `boolean` |

---

### TUI

| Метод  | Путь                    | Описание                                              | Ответ                     |
| ------ | ----------------------- | ----------------------------------------------------- | ------------------------- |
| `POST` | `/tui/append-prompt`    | Добавить текст в подсказку                            | `boolean`                 |
| `POST` | `/tui/open-help`        | Открыть диалог помощи                                 | `boolean`                 |
| `POST` | `/tui/open-sessions`    | Открыть селектор сессий                               | `boolean`                 |
| `POST` | `/tui/open-themes`      | Открыть селектор тем                                  | `boolean`                 |
| `POST` | `/tui/open-models`      | Открыть селектор моделей                              | `boolean`                 |
| `POST` | `/tui/submit-prompt`    | Отправить текущую подсказку                           | `boolean`                 |
| `POST` | `/tui/clear-prompt`     | Очистить подсказку                                    | `boolean`                 |
| `POST` | `/tui/execute-command`  | Выполнить команду (`{ command }`)                     | `boolean`                 |
| `POST` | `/tui/show-toast`       | Показать уведомление (`{ title?, message, variant }`) | `boolean`                 |
| `GET`  | `/tui/control/next`     | Ожидание следующего запроса управления                | Объект запроса управления |
| `POST` | `/tui/control/response` | Ответить на запрос управления (`{ body }`)            | `boolean`                 |

---

### Авторизация

| Метод | Путь        | Описание                                                                               | Ответ     |
| ----- | ----------- | -------------------------------------------------------------------------------------- | --------- |
| `PUT` | `/auth/:id` | Установить учетные данные аутентификации. Body должен соответствовать схеме провайдера | `boolean` |

---

### События

| Метод | Путь     | Описание                                                                                      | Ответ                                |
| ----- | -------- | --------------------------------------------------------------------------------------------- | ------------------------------------ |
| `GET` | `/event` | Поток событий, отправляемых сервером. Первое событие — `server.connected`, затем события шины | Поток событий, отправляемых сервером |

---

### Документы

| Метод | Путь   | Описание                 | Ответ                                  |
| ----- | ------ | ------------------------ | -------------------------------------- |
| `GET` | `/doc` | Спецификация OpenAPI 3.1 | HTML-страница со спецификацией OpenAPI |
