OpenCode

OpenCode는 터미널에서 동작하는 오픈소스 코딩 에이전트입니다. 명령어 하나로 Synthorai에 로그인하면 OpenCode 전용 API 키와, 그 키로 호출할 수 있는 모델을 보여 주는 Synthorai 프로바이더가 생깁니다. 키를 복사하거나 설정 파일을 고칠 필요가 없습니다.

1단계 - 로그인

opencode auth login https://synthorai.io

OpenCode는 https://synthorai.io/.well-known/opencode를 읽고, 거기에 지정된 로그인 명령을 실행합니다. 이 명령은 링크와 BCDF-GHJK 같은 8자리 코드를 출력한 뒤 브라우저를 엽니다.

콘솔에 로그인해 화면의 코드가 터미널의 코드와 같은지 확인하고, 키 유효 기간(7일, 30일, 90일 중 선택, 기본값 90일)을 고른 다음 허용을 클릭합니다. 터미널에 Signed in이 출력되고 OpenCode가 새 키를 저장합니다.

ℹ

로그인 명령에는 sh와 curl이 필요하므로 macOS, Linux, WSL, Git Bash에서 실행됩니다. 네이티브 Windows에서는 API 키로 직접 설정하세요.

SSH로 접속해 실행하면 브라우저가 열리지 않으니, 출력된 링크를 다른 기기에서 열어 로그인하면 됩니다. 로컬에서도 이렇게 하려면 SYNTHORAI_NO_BROWSER=1을 설정하세요.

2단계 - 모델 선택

opencode
# then, inside OpenCode:
/models

OpenCode를 실행하고 /models를 입력합니다. Synthorai 프로바이더에 키로 호출할 수 있는 모델이 컨텍스트 한도, 가격과 함께 표시됩니다. 목록은 OpenCode를 시작할 때마다 새로 고쳐집니다.

모델마다 알맞은 프로토콜이 자동으로 쓰이므로 따로 설정할 것이 없습니다. Claude 모델은 Anthropic Messages API(프롬프트 캐싱 유지), OpenAI 모델은 Responses API, 나머지 모델은 Chat Completions를 사용합니다.

OpenCode가 쓰는 키

이 키는 콘솔의 API 키 페이지에 OpenCode · …(뒤에 로그인한 위치가 붙음)라는 이름과 에이전트 로그인 라벨로 표시됩니다. 언제든 그곳에서 삭제할 수 있습니다.

키가 만료되면 호출이 실패하고, opencode auth login https://synthorai.io를 다시 실행하라는 메시지가 표시됩니다.

보안

직접 시작한 로그인의 코드만 승인하세요. 로그인 요청이 브라우저와 다른 네트워크에서 왔다면 확인 페이지에 경고가 표시됩니다.
워크스페이스에서 새 IP 승인 필요(설정 › 보안)가 켜져 있으면, 같은 네트워크에서 로그인을 허용할 때 로그인한 주소가 새 키의 신뢰할 수 있는 주소로 자동 등록되고, 다른 주소에서 온 호출은 승인을 기다립니다. 다른 네트워크에서 허용했다면 주소가 신뢰되지 않으니, 첫 호출이 보류되면 승인하세요. 꺼져 있다면 켜는 것을 고려해 보세요.

로컬 설정이 우선

로컬 opencode.json에 synthorai라는 프로바이더를 정의해 두었다면, OpenCode는 게이트웨이에서 받은 것 대신 그것을 사용합니다. 로컬 설정이 원격 설정보다 우선하기 때문입니다.

수동 설정(sh가 없는 Windows)

콘솔의 API 키 페이지에서 키를 만들어 환경 변수 SYNTHORAI_API_KEY에 넣고, 아래 프로바이더를 opencode.json에 추가합니다.

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "synthorai": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Synthorai",
      "options": {
        "baseURL": "https://synthorai.io/v1",
        "apiKey": "{env:SYNTHORAI_API_KEY}"
      },
      "models": {
        "claude-sonnet-5-5": { "name": "Claude Sonnet 5.5" }
      }
    }
  }
}

OpenCode에서 고를 모델을 models 아래에 나열합니다. 모델 ID는 모델 페이지에서 확인할 수 있습니다.

문제 해결

Failed to load auth provider metadata 주소를 확인하세요. https://synthorai.io 뒤에는 경로를 붙이지 않습니다.

Sign-in did not complete: the login was declined in the console 확인 페이지에서 요청이 거부되었습니다. 명령을 다시 실행해 처음부터 진행하세요.

코드가 만료됨 코드는 10분 동안 유효합니다. opencode auth login https://synthorai.io를 다시 실행하면 새 코드가 발급됩니다.

키 한도, 유효 기간, 삭제 방법은 API 키 문서를 참고하세요.