한국어
문서
서버

서버

HTTP를 통해 opencode 서버와 상호작용합니다.

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 기본 인증으로 서버를 보호하세요. 사용자 이름은 기본적으로 opencode이며, OPENCODE_SERVER_USERNAME으로 변경할 수 있습니다. 이는 opencode serve와 opencode web 모두에 적용됩니다.

OPENCODE_SERVER_PASSWORD=your-password opencode serve

작동 방식

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

팁: opencode 서버를 사용하여 프로그래밍 방식으로 opencode와 상호작용하세요.

이 아키텍처를 통해 opencode는 여러 클라이언트를 지원하고 프로그래밍 방식으로 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 탐색기에서 확인하세요.

API

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

글로벌

메서드경로설명응답
GET/global/health서버 상태 및 버전 가져오기{ healthy: true, version: string }
GET/global/event글로벌 이벤트 가져오기 (SSE 스트림)이벤트 스트림

프로젝트

메서드경로설명응답
GET/project모든 프로젝트 나열Project[]
GET/project/current현재 프로젝트 가져오기Project

경로 및 VCS

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

인스턴스

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

설정

메서드경로설명응답
GET/config설정 정보 가져오기Config
PATCH/config설정 업데이트Config
GET/config/providers프로바이더 및 기본 모델 나열{ providers: Provider[], default: { [key: string]: string } }

프로바이더

메서드경로설명응답
GET/provider모든 프로바이더 나열{ all: Provider[], default: {...}, connected: string[] }
GET/provider/auth프로바이더 인증 방법 가져오기{ [providerID: string]: ProviderAuthMethod[] }
POST/provider/{id}/oauth/authorizeOAuth로 프로바이더 인증ProviderAuthAuthorization
POST/provider/{id}/oauth/callback프로바이더의 OAuth 콜백 처리boolean

세션

메서드경로설명참고
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 }, 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: Message, parts: Part[] }[] 반환
POST/session/:id/message메시지 전송 및 응답 대기body: { 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비동기로 메시지 전송 (대기 없음)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[] } 반환

명령어

메서드경로설명응답
GET/command모든 명령어 나열Command[]

파일

메서드경로설명응답
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"는 파일만 반환)

도구 (실험적)

메서드경로설명응답
GET/experimental/tool/ids모든 도구 ID 나열ToolIDs
GET/experimental/tool?provider=<p>&model=<m>모델용 JSON 스키마가 포함된 도구 나열ToolList

LSP, 포매터 및 MCP

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

에이전트

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

로깅

메서드경로설명응답
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/eventServer-sent 이벤트 스트림. 첫 번째 이벤트는 server.connected, 그 다음 버스 이벤트Server-sent 이벤트 스트림

문서

메서드경로설명응답
GET/docOpenAPI 3.1 스펙OpenAPI 스펙이 포함된 HTML 페이지
SDK플러그인