컨텐츠로 건너뛰기
학습 비교 레시피 생태계 소스 코드 문서

서버

opencode serve 명령은 opencode 클라이언트가 사용할 수 있는 OpenAPI 엔드포인트를 노출하는 헤드리스 HTTP 서버를 실행합니다.

사용법

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

옵션

플래그설명기본값
--port수신 대기할 포트4096
--hostname수신 대기할 호스트명127.0.0.1
--mdnsmDNS 검색 활성화false
--mdns-domainmDNS 서비스의 사용자 지정 도메인opencode.local
--cors허용할 추가 브라우저 오리진[]

--cors는 여러 번 전달할 수 있습니다:

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 모두에 적용됩니다.

OPENCODE_SERVER_PASSWORD=your-password opencode serve

작동 방식

opencode를 실행하면 TUI와 서버가 시작됩니다. TUI는 서버와 통신하는 클라이언트입니다. 서버는 OpenAPI 3.1 사양 엔드포인트를 노출합니다. 이 엔드포인트는 SDK를 생성하는 데에도 사용됩니다.

이 아키텍처를 통해 opencode는 여러 클라이언트를 지원하고 프로그래밍 방식으로 상호작용할 수 있습니다.

opencode serve를 실행하여 독립 서버를 시작할 수 있습니다. opencode TUI가 실행 중인 경우, opencode serve는 새 서버를 시작합니다.

기존 서버에 연결

TUI를 시작하면 포트와 호스트명이 무작위로 할당됩니다. 대신 --hostname과 --port 플래그를 전달할 수 있습니다. 그런 다음 이를 사용하여 서버에 연결합니다.

/tui 엔드포인트는 서버를 통해 TUI를 구동하는 데 사용할 수 있습니다. 예를 들어 프롬프트를 미리 채우거나 실행할 수 있습니다. 이 설정은 OpenCode IDE 플러그인에서 사용됩니다.

사양

서버는 다음에서 볼 수 있는 OpenAPI 3.1 사양을 게시합니다:

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

예를 들어, http://localhost:4096/doc. 사양을 사용하여 클라이언트를 생성하거나 요청 및 응답 타입을 확인하세요. 또는 Swagger 탐색기에서 확인하세요.

APIs

opencode 서버는 다음 API를 노출합니다.

Global

메서드경로설명응답
GET/global/health서버 상태 및 버전 조회{ healthy: true, version: string }
GET/global/event전역 이벤트 조회(SSE 스트림)Event stream

Project

메서드경로설명응답
GET/project모든 프로젝트 목록 조회Project[]
GET/project/current현재 프로젝트 조회Project

Path & VCS

메서드경로설명응답
GET/path현재 경로 조회Path
GET/vcs현재 프로젝트의 VCS 정보 조회VcsInfo

Instance

메서드경로설명응답
POST/instance/dispose현재 인스턴스 해제boolean

Config

메서드경로설명응답
GET/config설정 정보 조회Config
PATCH/config설정 업데이트Config
GET/config/providersprovider 및 기본 모델 목록 조회{ providers: Provider[], default: { [key: string]: string } }

Provider

메서드경로설명응답
GET/provider모든 provider 목록 조회{ all: Provider[], default: {...}, connected: string[] }
GET/provider/authprovider 인증 방법 조회{ [providerID: string]: ProviderAuthMethod[] }
POST/provider/{id}/oauth/authorizeOAuth로 provider 승인ProviderAuthAuthorization
POST/provider/{id}/oauth/callbackprovider의 OAuth 콜백 처리boolean

Sessions

메서드경로설명비고
GET/session모든 세션 목록 조회반환 Session[]
POST/session새 세션 생성body: { parentID?, title? }, 반환 Session
GET/session/status모든 세션의 상태 조회반환 { [sessionID: string]: SessionStatus }
GET/session/:id세션 상세 조회반환 Session
DELETE/session/:id세션과 모든 데이터 삭제반환 boolean
PATCH/session/:id세션 속성 업데이트body: { title? }, 반환 Session
GET/session/:id/children세션의 하위 세션 조회반환 Session[]
GET/session/:id/todo세션의 할 일 목록 조회반환 Todo[]
POST/session/:id/init앱을 분석하고 AGENTS.md 생성body: { messageID, providerID, modelID }, 반환 boolean
POST/session/:id/fork특정 메시지에서 기존 세션 분기body: { messageID? }, 반환 Session
POST/session/:id/abort실행 중인 세션 중단반환 boolean
POST/session/:id/share세션 공유반환 Session
DELETE/session/:id/share세션 공유 해제반환 Session
GET/session/:id/diff이 세션의 diff 조회query: messageID?, 반환 FileDiff[]
POST/session/:id/summarize세션 요약body: { providerID, modelID }, returns boolean
POST/session/:id/revert메시지 되돌리기body: { messageID, partID? }, returns boolean
POST/session/:id/unrevert되돌린 모든 메시지 복원반환 boolean
POST/session/:id/permissions/:permissionID권한 요청에 응답body: { response, remember? }, 반환 boolean

Messages

메서드경로설명비고
GET/session/:id/message세션의 메시지 목록 조회query: limit?, 반환 { info: Message, parts: Part[] }[]
POST/session/:id/message메시지 전송 후 응답 대기body: { messageID?, model?, agent?, noReply?, system?, tools?, parts }, 반환 { info: Message, parts: Part[] }
GET/session/:id/message/:messageID메시지 상세 조회Returns { info: Message, parts: Part[] }
POST/session/:id/prompt_async메시지 비동기 전송(대기 없음)body: /session/:id/message와 동일, 반환 204 No Content
POST/session/:id/command슬래시 명령 실행body: { messageID?, agent?, model?, command, arguments }, 반환 { info: Message, parts: Part[] }
POST/session/:id/shell셸 명령 실행body: { agent, model?, command }, 반환 { info: Message, parts: Part[] }

Commands

메서드경로설명응답
GET/command모든 명령 목록 조회Command[]

Files

메서드경로설명응답
GET/find?pattern=<pat>파일에서 텍스트 검색path, lines, line_number, absolute_offset, submatches를 포함한 매치 객체 배열
GET/find/file?query=<q>이름으로 파일/디렉토리 찾기string[](경로)
GET/find/symbol?query=<q>워크스페이스 심볼 찾기Symbol[]
GET/file?path=<path>파일 및 디렉토리 목록 조회FileNode[]
GET/file/content?path=<p>파일 읽기FileContent
GET/file/status추적 중인 파일의 상태 조회File[]

/find/file 쿼리 매개변수

  • query (필수) — 검색 문자열 (퍼지 매치)
  • type (선택) — 결과를 "file" 또는 "directory"로 제한
  • directory (선택) — 검색의 프로젝트 루트 재정의
  • limit (선택) — 최대 결과 수 (1–200)
  • dirs (선택) — 레거시 플래그 ("false"는 파일만 반환)

Tools (Experimental)

메서드경로설명응답
GET/experimental/tool/ids모든 도구 ID 목록 조회ToolIDs
GET/experimental/tool?provider=<p>&model=<m>모델의 JSON 스키마를 포함한 도구 목록ToolList

LSP, Formatters & MCP

메서드경로설명응답
GET/lspLSP 서버 상태 조회LSPStatus[]
GET/formatter포맷터 상태 조회FormatterStatus[]
GET/mcpMCP 서버 상태 조회{ [name: string]: MCPStatus }
POST/mcpMCP 서버 동적 추가body: { name, config }, MCP 상태 객체 반환

Agents

메서드경로설명응답
GET/agent사용 가능한 모든 에이전트 목록 조회Agent[]

Logging

메서드경로설명응답
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

Auth

메서드경로설명응답
PUT/auth/:id인증 자격 증명 설정. Body는 provider 스키마와 일치해야 함boolean

Events

메서드경로설명응답
GET/event서버 전송 이벤트 스트림. 첫 이벤트는 server.connected, 이후 bus 이벤트Server-sent events stream

Docs

메서드경로설명응답
GET/docOpenAPI 3.1 specificationOpenAPI 사양이 포함된 HTML 페이지