--- title: Server description: Interact with opencode server over HTTP. --- import config from "../../../../config.mjs" export const typesUrl = `${config.github}/blob/dev/packages/sdk/js/src/gen/types.gen.ts` `opencode serve` 명령은 opencode 클라이언트가 사용할 수 있는 OpenAPI 엔드포인트를 노출하는 headless HTTP 서버를 실행합니다. --- ### 사용법 ```bash opencode serve [--port ] [--hostname ] [--cors ] ``` #### 옵션 | 플래그 | 설명 | 기본값 | | --------------- | ------------------------------------- | ---------------- | | `--port` | 수신 대기할 포트 | `4096` | | `--hostname` | 수신 대기할 호스트명 | `127.0.0.1` | | `--mdns` | mDNS 탐지 활성화 | `false` | | `--mdns-domain` | mDNS 서비스의 사용자 지정 도메인 이름 | `opencode.local` | | `--cors` | 허용할 추가 브라우저 origin | `[]` | `--cors`는 다수 시간을 통과될 수 있습니다: ```bash opencode serve --cors http://localhost:5173 --cors https://app.example.com ``` --- ### 인증 `OPENCODE_SERVER_PASSWORD`를 설정하여 서버를 HTTP Basic auth로 보호합니다. `opencode` 또는 `OPENCODE_SERVER_USERNAME`를 오버라이드로 설정하는 사용자의 기본값. 이것은 `opencode serve`와 `opencode web` 둘 다에 적용합니다. ```bash OPENCODE_SERVER_PASSWORD=your-password opencode serve ``` --- ### 어떻게 작동합니까? `opencode`를 실행하면 TUI와 서버를 시작합니다. TUI는 어디에 있습니까? 서버와 대화하는 클라이언트. 서버는 OpenAPI 3.1 spec을 노출 끝점. 이 엔드포인트는 [SDK](/docs/sdk)을 생성하는 데도 사용됩니다. :::tip opencode 서버를 사용하여 opencode programmatically와 상호 작용합니다. ::: 이 아키텍처는 opencode 지원 여러 클라이언트를 허용하고 opencode programmatically와 상호 작용 할 수 있습니다. 독립 서버를 시작하려면 `opencode serve`를 실행할 수 있습니다. 당신이 있는 경우에 opencode TUI 실행, `opencode serve` 새로운 서버를 시작합니다. --- #### 기존 서버에 연결 TUI를 시작하면 무작위로 포트와 호스트 이름을 할당합니다. 대신 `--hostname`와 `--port` [flags](/docs/cli)에서 전달할 수 있습니다. 그런 다음 서버에 연결하십시오. [`/tui`](#tui) 엔드포인트는 서버를 통해 TUI를 구동하는 데 사용될 수 있습니다. 예를 들어 미리 작성하거나 프롬프트를 실행할 수 있습니다. 이 설정은 opencode [IDE](/docs/ide) 플러그인에 의해 사용됩니다. --- ## 사양 서버는 OpenAPI 3.1 spec을 게시합니다. ``` http://:/doc ``` 예를 들어, `http://localhost:4096/doc`. 클라이언트를 생성하거나 요청 및 응답 유형을 검사하는 spec를 사용하십시오. 또는 Swagger 탐험가에서 볼 수 있습니다. --- ## API opencode 서버는 다음과 같은 API를 노출합니다. --- ## 글로벌 | 방법 | 경로 | 설명 | 응답 | | ----- | ---------------- | ------------------------- | ------------------------------------ | | `GET` | `/global/health` | 서버 건강 및 버전 | `{ healthy: true, version: string }` | | `GET` | `/global/event` | 글로벌 이벤트(SSE 스트림) | 이벤트 스트림 | --- ## 프로젝트 | 방법 | 경로 | 설명 | 응답 | | ----- | ------------------ | ----------------------- | --------------------------------------------- | | `GET` | `/project` | 모든 프로젝트 보기 | Project[] | | `GET` | `/project/current` | 현재 프로젝트 가져 오기 | 프로젝트 | --- ### 경로 & VCS | 방법 | 경로 | 설명 | 응답 | | ----- | ------- | ----------------------------- | ------------------------------------------- | | `GET` | `/path` | 현재 경로 받기 | Path | | `GET` | `/vcs` | 현재 프로젝트의 VCS 정보 받기 | VcsInfo | --- ### 인스턴스 | 방법 | 경로 | 설명 | 응답 | | ------ | ------------------- | -------------------- | --------- | | `POST` | `/instance/dispose` | 현재 인스턴스를 해제 | `boolean` | --- ### 콘피그 | 방법 | 경로 | 설명 | 응답 | | ------- | ------------------- | -------------------------- | ---------------------------------------------------------------------------------------- | | `GET` | `/config` | 구성정보 | Config | | `PATCH` | `/config` | 업데이트 구성 | Config | | `GET` | `/config/providers` | 목록 제공업체 및 기본 모델 | `{ providers: ` 사이트 맵`, default: { [key: string]: string } }` | --- ## 공급자 | 방법 | 경로 | 설명 | 응답 | | ------ | -------------------------------- | --------------------------- | ----------------------------------------------------------------------------------- | | `GET` | `/provider` | 모든 공급자 목록 | `{ all: `Provider[]`, default: {...}, connected: string[] }` | | `GET` | `/provider/auth` | 공급자 인증 메서드 가져오기 | `{ [providerID: string]: `ProviderAuthMethod[]` }` | | `POST` | `/provider/{id}/oauth/authorize` | OAuth를 사용한 공급자 허가 | ProviderAuthAuthorization | | `POST` | `/provider/{id}/oauth/callback` | 공급자를 위한 OAuth 콜백 | `boolean` | --- ## 세션 | 방법 | 경로 | 설명 | 주 | | -------- | ---------------------------------------- | ---------------------------------- | ----------------------------------------------------------------------------- | | `GET` | `/session` | 모든 세션 일람표 | 반환 Session[] | | `POST` | `/session` | 새 세션 만들기 | 몸: `{ parentID?, title? }`, 반환 Session | | `GET` | `/session/status` | 모든 세션의 세션 상태를 가져옵니다 | `{ [sessionID: string]: `SessionStatus` }` | | `GET` | `/session/:id` | 세션 상세보기 | 반품 Session | | `DELETE` | `/session/:id` | 세션 삭제 및 모든 데이터 | `boolean` | | `PATCH` | `/session/:id` | 업데이트 세션 속성 | 본체: `{ title? }`, 반환 Session | | `GET` | `/session/:id/children` | 세션의 어린이 세션 | 리턴 Session[] | | `GET` | `/session/:id/todo` | 세션별 도우미 목록 받기 | Todo[] | | `POST` | `/session/:id/init` | 분석 응용 프로그램 및 `AGENTS.md` | 몸: `{ messageID, providerID, modelID }`, 반환 `boolean` | | `POST` | `/session/:id/fork` | 메시지의 기존 세션 | 몸: `{ messageID? }`, 반환 Session | | `POST` | `/session/:id/abort` | 운영 중인 세션 | 반품 `boolean` | | `POST` | `/session/:id/share` | 세션 공유 | Session | | `DELETE` | `/session/:id/share` | 세션 공유 | Session | | `GET` | `/session/:id/diff` | `/session/:id/diff` | `messageID?`, 반환 FileDiff[] | | `POST` | `/session/:id/summarize` | 세션을 요약 | 본체: `{ providerID, modelID }`, `boolean` 반환 | | `POST` | `/session/:id/revert` | 메시지 재생 | 몸: `{ messageID, partID? }`, 반환 `boolean` | | `POST` | `/session/:id/unrevert` | 통일된 모든 메시지 | 반품 `boolean` | | `POST` | `/session/:id/permissions/:permissionID` | 허가 요청 대응 | 본체: `{ response, remember? }`, `boolean` | --- ## 메시지 | 방법 | 경로 | 설명 | 주 | | ------ | --------------------------------- | -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `GET` | `/session/:id/message` | 세션의 목록 메시지 | 쿼리: `limit?`, `{ info: `Message`, parts: `Part[]`}[]` | | `POST` | `/session/:id/message` | 응답을 위해 메시지를 보내고 기다립니다 | 몸: `{ messageID?, model?, agent?, noReply?, system?, tools?, parts }`, 반환 `{ info: `Message`, parts: `Part[]`}` | | `GET` | `/session/:id/message/:messageID` | 메시지 보내기 | `{ info: `Message`, parts: `Part[]`}` | | `POST` | `/session/:id/prompt_async` | 비동기적으로 메시지 보내기 | 몸: `/session/:id/message`와 동일, `204 No Content`를 반환 | | `POST` | `/session/:id/command` | 슬래시 명령어 실행 | 본체: `{ messageID?, agent?, model?, command, arguments }`, 반환 `{ info: `Message`, parts: `Part[]`}` | | `POST` | `/session/:id/shell` | 쉘 명령 실행 | 체: `{ agent, model?, command }`, 반환 `{ info: `Message`, parts: `Part[]`}` | --- ## 명령 | 방법 | 경로 | 설명 | 응답 | | ----- | ---------- | --------- | --------------------------------------------- | | `GET` | `/command` | 모든 명령 | Command[] | --- ## 파일 | 방법 | 경로 | 설명 | 응답 | | ----- | ------------------------ | ---------------------------- | --------------------------------------------------------------------------------------- | | `GET` | `/find?pattern=` | 파일에서 텍스트 검색 | `path`, `lines`, `line_number`, `absolute_offset`, `submatches`가 포함된 일치 객체 배열 | | `GET` | `/find/file?query=` | 이름으로 파일/디렉터리 찾기 | `string[]` (경로) | | `GET` | `/find/symbol?query=` | 워크스페이스 심볼 찾기 | Symbol[] | | `GET` | `/file?path=` | 파일 및 디렉터리 목록 | FileNode[] | | `GET` | `/file/content?path=

` | 파일 읽기 | FileContent | | `GET` | `/file/status` | 추적 중인 파일 상태 가져오기 | File[] | #### `/find/file` 쿼리 매개 변수 - `query` (required) - 검색 문자열 (fuzzy 일치) - `type` (선택 사항) - `"file"` 또는 `"directory"`에 제한 결과 - `directory` (선택 사항) - 검색에 대한 프로젝트 루트를 무시 - (선택) `limit` - 최대 결과 (1-200) - `dirs` (옵션) - 레거시 플래그 (`"false"`는 파일만 반환) --- ## 도구 (실험) | 방법 | 경로 | 설명 | 응답 | | ----- | ------------------------------------------- | ----------------------- | --------------------------------------------- | | `GET` | `/experimental/tool/ids` | 모든 도구 ID | 도구 | | `GET` | `/experimental/tool?provider=

&model=` | 모델용 JSON 스키마 목록 | 도구 목록 | --- ### LSP의 체재자 & MCP | 방법 | 경로 | 설명 | 응답 | | ------ | ------------ | ---------------------- | -------------------------------------------------------- | | `GET` | `/lsp` | LSP 서버 상태 | LSPStatus[] | | `GET` | `/formatter` | 형식의 상태를 확인 | FormatterStatus[] | | `GET` | `/mcp` | MCP 서버 상태를 얻는다 | `{ [name: string]: `MCPStatus` }` | | `POST` | `/mcp` | MCP 서버가 동적 | 본체: `{ name, config }`, MCP 상태 객체를 반환 | --- ## 에이전트 | 방법 | 경로 | 설명 | 응답 | | ----- | -------- | ------------------------- | ----------------------------------------------- | | `GET` | `/agent` | 이용 가능한 모든 에이전트 | 에이전트[] | --- ### 로깅 | 방법 | 경로 | 설명 | 응답 | | ------ | ------ | ----------------------------------------------------- | --------- | | `POST` | `/log` | 로그 입력 바디: `{ 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` | 인증 자격 증명 몸은 공급자 스키마를 일치해야 합니다 | `boolean` | --- ## 이벤트 | 방법 | 경로 | 설명 | 응답 | | ----- | -------- | ------------------------------------------------------------------------------- | ------------------------ | | `GET` | `/event` | 서버 침묵 이벤트 스트림. 첫 번째 이벤트는 `server.connected`, 그 후 버스 이벤트 | Server-sent event stream | --- ### 문서 | 방법 | 경로 | 설명 | 응답 | | ----- | ------ | ---------------- | ------------------------ | | `GET` | `/doc` | OpenAPI 3.1 사양 | HTML 페이지 OpenAPI 사양 |