한국어
문서
서버

서버

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

인증

HTTP 기본 인증으로 서버를 보호하려면 OPENCODE_SERVER_PASSWORD를 설정하세요. 사용자명은 기본적으로 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를 노출합니다.

Global

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

Project

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

Path & VCS

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

Instance

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

Config

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

Provider

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

Sessions

메서드경로설명참고
GET/session모든 세션 나열Session[] (opens in a new tab) 반환
POST/session새 세션 생성body: { parentID?, title? }, Session (opens in a new tab) 반환
GET/session/status모든 세션의 세션 상태 가져오기{ [sessionID: string]: SessionStatus (opens in a new tab) } 반환
GET/session/:id세션 세부 정보 가져오기Session (opens in a new tab) 반환
DELETE/session/:id세션과 모든 데이터 삭제boolean 반환
PATCH/session/:id세션 속성 업데이트body: { title? }, Session (opens in a new tab) 반환
GET/session/:id/children세션의 자식 세션 가져오기Session[] (opens in a new tab) 반환
GET/session/:id/todo세션의 할 일 목록 가져오기Todo[] (opens in a new tab) 반환
POST/session/:id/init앱을 분석하고 AGENTS.md 생성body: { messageID, providerID, modelID }, boolean 반환
POST/session/:id/fork기존 세션을 메시지 지점에서 포크body: { messageID? }, Session (opens in a new tab) 반환
POST/session/:id/abort실행 중인 세션 중단boolean 반환
POST/session/:id/share세션 공유Session (opens in a new tab) 반환
DELETE/session/:id/share세션 공유 취소Session (opens in a new tab) 반환
GET/session/:id/diff이 세션의 diff 가져오기query: messageID?, FileDiff[] (opens in a new tab) 반환
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 반환

Messages

메서드경로설명참고
GET/session/:id/message세션의 메시지 나열query: limit?, { info: Message (opens in a new tab), parts: Part[] (opens in a new tab)}[] 반환
POST/session/:id/message메시지를 보내고 응답 대기body: { messageID?, model?, agent?, noReply?, system?, tools?, parts }, { info: Message (opens in a new tab), parts: Part[] (opens in a new tab)} 반환
GET/session/:id/message/:messageID메시지 세부 정보 가져오기{ info: Message (opens in a new tab), parts: Part[] (opens in a new tab)} 반환
POST/session/:id/prompt_async메시지를 비동기로 전송(대기 없음)body: /session/:id/message와 동일, 204 No Content 반환
POST/session/:id/command슬래시 명령어 실행body: { messageID?, agent?, model?, command, arguments }, { info: Message (opens in a new tab), parts: Part[] (opens in a new tab)} 반환
POST/session/:id/shell셸 명령어 실행body: { agent, model?, command }, { info: Message (opens in a new tab), parts: Part[] (opens in a new tab)} 반환

Commands

메서드경로설명응답
GET/command모든 명령어 나열Command[] (opens in a new tab)

Files

메서드경로설명응답
GET/find?pattern=<pat>파일에서 텍스트 검색path, lines, line_number, absolute_offset, submatches가 있는 일치 객체 배열
GET/find/file?query=<q>이름으로 파일 및 디렉토리 찾기string[](경로)
GET/find/symbol?query=<q>워크스페이스 심볼 찾기Symbol[] (opens in a new tab)
GET/file?path=<path>파일 및 디렉토리 나열FileNode[] (opens in a new tab)
GET/file/content?path=<p>파일 읽기FileContent (opens in a new tab)
GET/file/status추적된 파일의 상태 가져오기File[] (opens in a new tab)

/find/file 쿼리 매개변수

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

Tools (실험적)

메서드경로설명응답
GET/experimental/tool/ids모든 도구 ID 나열ToolIDs (opens in a new tab)
GET/experimental/tool?provider=<p>&model=<m>모델에 대한 JSON 스키마와 함께 도구 나열ToolList (opens in a new tab)

LSP, Formatters & MCP

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

Agents

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

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다음 제어 요청 대기Control request object
POST/tui/control/response제어 요청에 응답({ body })boolean

Auth

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

Events

메서드경로설명응답
GET/eventServer-sent events 스트림. 첫 이벤트는 server.connected, 그 다음은 버스 이벤트Server-sent events stream

Docs

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