OpenCode 설치 및 OmniProxy 구성

OpenCode는 터미널, IDE 또는 데스크톱에서 코드를 작성할 수 있는 오픈 소스 코딩 도우미입니다. 코드와 컨텍스트를 저장하지 않으므로 개인정보 보호가 중요한 프로젝트에 적합합니다. build는 프로젝트를 수정할 때 사용하며, plan은 기본적으로 읽기 전용이므로 익숙하지 않은 코드를 먼저 이해하고 수정 방안을 정리할 때 적합합니다. 모델 서비스는 필요에 따라 선택할 수 있습니다.

설치 전 준비

설치 스크립트를 사용하는 것이 가장 간단합니다. 명령을 실행하고 프로젝트 파일을 다룰 수 있는 최신 터미널 프로그램이 필요합니다. 예를 들면 WezTerm, Alacritty, Ghostty 또는 Kitty가 있습니다. Windows에서는 WSL을 우선 사용하는 것이 좋습니다. WSL은 Windows에서 Linux 환경을 실행하는 도구로, 성능과 기능이 더 완전합니다.

가장 쉬운 방법

설치 스크립트

curl opencode.ai/install
macOS Linux에서는 바로 사용
Windows에서는 WSL 권장

macOS Linux

Homebrew tap

anomalyco/tap/opencode
formula보다 더 자주 업데이트됨
Arch에도 패키지가 있음

Windows 네이티브

패키지 관리자

choco 또는 scoop
또는 npm 전역 설치
Releases에서 다운로드할 수도 있음

먼저 설치 스크립트를 사용하세요. 패키지 관리자에 익숙하다면 그다음 공식 목록에 있는 다른 명령을 사용하면 됩니다.

현재 모델 목록에 있는 모델 ID도 준비하세요. 모델 ID는 서비스가 특정 모델을 정확히 식별할 때 사용하는 이름입니다.

설치 및 최초 실행

가장 간단한 설치 명령은 다음과 같습니다.

curl -fsSL https://opencode.ai/install | bash

다음과 같은 설치 방법도 사용할 수 있습니다.

Node.js: npm install -g opencode-ai. Bun, pnpm, Yarn에도 각각 전역 설치 명령이 있으며, 문서 마지막의 소개 페이지에서 확인할 수 있습니다.
macOS 및 Linux의 Homebrew: brew install anomalyco/tap/opencode. Homebrew 팀이 관리하는 brew install opencode보다 업데이트가 더 자주 이루어지므로 이 tap을 사용하세요.
Arch Linux: 안정 버전은 sudo pacman -S opencode, 더 최신 버전은 AUR의 opencode-bin을 사용할 수 있습니다.
Windows: choco install opencode 또는 scoop install opencode를 사용하거나 npm install -g opencode-ai를 사용할 수 있습니다. Releases에서 바이너리 파일을 다운로드하는 방법도 안내되어 있습니다. Windows에서 Bun을 이용한 설치 지원은 아직 개발 중입니다.

프로젝트 디렉터리로 이동한 후 OpenCode를 실행합니다.

cd /path/to/project
opencode

처음 사용할 때 /init을 실행할 수 있습니다. 이 명령은 프로젝트를 분석하고 프로젝트 루트 디렉터리에 AGENTS.md를 생성합니다. 이 파일은 Git에 커밋할 수 있으므로 프로젝트에서 해당 안내를 계속 유지할 수 있습니다.

OmniProxy에서 연결 매개변수 가져오기

baseURL: https://your-omniproxy-origin.example/v1
API Key: <YOUR_OMNIPROXY_API_KEY>
Model ID: OmniProxy의 현재 모델 목록에서 전체 ID 복사

baseURL은 서비스 주소이고, API Key는 액세스 자격 증명이며, Model ID는 모델의 전체 이름입니다.

/v1/chat/completions를 사용할 때 npm 패키지는 @ai-sdk/openai-compatible을 사용합니다. 여기서 Chat Completions는 채팅 요청 인터페이스의 한 종류입니다. 모델이 /v1/responses를 사용할 때만 @ai-sdk/openai로 변경하세요. OmniProxy를 채팅 완성 경로로 사용할 때는 호환 패키지를 유지합니다.

모델 ID는 OmniProxy의 현재 목록에서 전체 문자열을 복사하고 슬래시도 그대로 유지합니다. 2026-10-09 기준 비교용 ID 두 개는 claude-sonnet-5-5와 gpt-6-luna입니다. gpt-6-luna는 Chat Completions를 지원합니다. Chat Completions에서 함수 호출은 reasoning_effort가 none일 때만 지원됩니다. 목록에 없는 ID는 그대로 사용하지 마세요.

도구 구성 입력

Provider는 OpenCode가 모델 서비스에 연결할 때 사용하는 구성 묶음으로 이해할 수 있습니다. Provider 문서에서는 「/connect 목록에 없는 OpenAI 호환 서비스」를 사용자 지정 Provider로 설명합니다. OpenAI 호환 서비스란 동일한 요청 형식을 사용하여 같은 유형의 클라이언트에서 호출할 수 있는 서비스입니다.

OpenCode에서 /connect를 실행한 후 Other까지 스크롤합니다.
Provider ID를 입력합니다. 아래에서는 omniproxy를 사용합니다. 구성 파일에서도 같은 ID를 사용해야 하므로 기억하기 쉬운 값을 선택하세요.
OmniProxy의 API Key를 입력합니다. 이 단계에서는 자격 증명만 저장되며, 주소와 모델은 별도로 opencode.json에 작성해야 합니다. 자격 증명은 ~/.local/share/opencode/auth.json에 저장됩니다.
프로젝트 디렉터리에서 opencode.json을 생성하거나 수정합니다.

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "omniproxy": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "OmniProxy",
      "options": {
        "baseURL": "https://your-omniproxy-origin.example/v1"
      },
      "models": {
        "claude-sonnet-5-5": { "name": "Claude Sonnet 5.5" },
        "gpt-6-luna": { "name": "GPT-6 Luna" }
      }
    }
  }
}

/models를 실행하면 사용자 지정 Provider와 모델이 목록에 표시됩니다.

/connect의 ID는 opencode.json의 키와 반드시 일치해야 합니다. 실제 비밀 키를 이 파일에 작성하지 마세요. /connect를 사용하지 않는 경우 options.apiKey에 {env:변수명}과 같은 환경 변수 형식을 사용할 수도 있습니다. 2026-10-09에 OpenCode 1.18.34로 테스트했을 때 /connect를 사용하지 않고 프로젝트의 options.apiKey에 키를 직접 작성해도 연결할 수 있었습니다. 게이트웨이에서 키를 검증하지 않는 경우 이 항목에는 로컬에서만 사용하는 자리표시자 문자열을 입력할 수 있습니다. models의 키에는 목록에 있는 전체 ID를 사용합니다.

키

/connect

맨 아래의 Other 선택
Provider ID는 직접 지정
auth.json에 저장됨

프로젝트

opencode.json

provider 키의 이름이 같아야 함
npm에는 호환 패키지 사용
baseURL은 /v1로 끝나야 함

선택

/models

목록에 모델이 표시됨
하나를 선택한 뒤 질문
ID는 게이트웨이 목록을 기준으로 함

키와 주소는 서로 다른 두 위치에 입력합니다. 두 위치의 Provider ID는 반드시 같아야 합니다.

실제 작업으로 확인

먼저 프로젝트 디렉터리에서 실제 작업을 한 번 실행합니다. 모델 참조 형식은 Provider ID/모델 ID이며, 모델 ID에 포함된 슬래시는 그대로 유지해야 합니다.

opencode run --model omniproxy/claude-sonnet-5-5 --auto "지정한 파일 하나가 어떤 작업을 하는지 설명하고, 파일은 수정하지 마세요."

--auto를 사용하면 이번 실행에서 파일 읽기 등의 도구를 사용할 수 있습니다. 2026-10-09에 OpenCode 1.18.34로 테스트했을 때 지정한 파일의 내용을 읽었습니다. 첫 실행에는 약 2분이 걸렸습니다.

대화형으로 사용하려면 opencode를 실행한 다음 /models에서 모델을 선택합니다. 공식 사용법에서는 @로 파일을 검색할 수 있습니다. opencode auth list를 사용해 /connect에서 저장한 자격 증명을 확인한 다음, OmniProxy의 호출 기록에서 호출 출처와 모델 ID를 확인할 수 있습니다.

시작

opencode가 실행됨

먼저 cd로 프로젝트로 이동
auth list에서 ID를 확인할 수 있음
설정 파일이 프로젝트 안에 있음

작업

코드를 읽음

특정 파일에 관해 질문하기
설명 확인하기
잘못되었으면 /undo

기록

게이트웨이에서 확인 가능

소스가 OpenCode임
모델 ID가 일치함
키를 커밋하지 않기

구성 파일을 저장한 후 프로젝트에서 실제 질문을 한 번 실행해야 합니다.

자주 발생하는 오류

/models에 OmniProxy가 없음: /connect의 ID와 opencode.json의 키가 일치하는지, npm이 @ai-sdk/openai-compatible인지, baseURL이 /v1로 끝나는지 확인하세요.
자격 증명이 보이지 않음: opencode auth list를 실행하세요. Bedrock처럼 환경 변수를 사용하는 Provider는 여기에 표시되지 않습니다. 사용자 지정 Provider에서 /connect를 사용했다면 표시되어야 합니다.
Windows 기능이 완전하지 않음: WSL에서 설치 스크립트를 사용하세요.
모델 ID가 유효하지 않음: OmniProxy의 현재 목록에서 다시 복사한 후 models의 키를 변경하세요.
요청이 잘못된 인터페이스로 전송됨: 채팅 완성에는 @ai-sdk/openai-compatible을 유지하세요. OmniProxy의 해당 모델이 실제로 /v1/responses를 사용하는 경우가 아니라면 Responses 인터페이스를 위해 패키지를 변경하지 마세요.

공식 참고 자료

설치는 OpenCode 소개를 참고하세요. 사용자 지정 Provider는 Providers를 참고하세요. 예시에 사용된 모델 ID는 Claude 모델 개요와 GPT-6 Luna에서 확인할 수 있습니다.

모든 플레이스홀더를 고유한 OmniProxy 구성의 값으로 바꾸세요. 실제 키를 게시하지 마세요.

저장된 결과나 HTTP 200 만으로는 전체 에이전트 호환성이 입증되지 않습니다. OmniProxy 호출 기록에서 소스와 모델을 확인하세요.

공식 소스 · OpenCode ↗