러시아에서 OpenCode 사용하기: 설치, API 설정, 첫 요청

러시아에서 OpenCode를 시작하기 위해 필요한 것

OpenCode는 터미널에서 동작하는 코딩 에이전트입니다. 프로젝트 파일을 읽고 선택한 모델과 작업하며, 저장소 안에서 작업을 수행할 수 있습니다. 첫 실행에는 다음을 준비합니다.

• 공식 설치 방법을 사용할 수 있는 macOS, Linux 또는 Windows
• 본인의 BetterToken API Key
• BetterToken의 현재 모델 목록에서 확인한 Model ID
• 에이전트의 응답을 안전하게 시험할 수 있는 테스트 디렉터리

이 구성에서 BetterToken은 외부 API 요청을 처리합니다. OpenCode 웹사이트, 설치 파일, GitHub 또는 업데이트 서비스의 가용성을 보장하는 것은 아닙니다. 러시아에서 BetterToken API Endpoint에 연결할 때는 VPN이 필요하지 않지만, 이 조건은 제3자 사이트 접속이나 다운로드에는 적용되지 않습니다.

공식 소스에서 OpenCode 설치하기

아래 방법 중 하나를 선택합니다. Node.js는 npm으로 설치할 때만 필요합니다. 같은 환경에 여러 설치 방법을 겹쳐 쓰기 전에, 하나의 방법으로 opencode --version이 작동하는지 먼저 확인하는 편이 좋습니다.

macOS와 Linux: 공식 설치 프로그램

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

설치가 끝나면 새 터미널을 열거나 셸 설정을 다시 읽은 다음 명령을 확인합니다. 설치 출력에 오류가 있다면 다른 설치 방법으로 넘어가기 전에 오류 내용과 실제 설치 위치부터 확인합니다.

npm

npm install -g opencode-ai

npm 전역 실행 파일 디렉터리가 PATH에 없으면 패키지 설치가 성공해도 명령을 찾을 수 없습니다. 다시 설치하기 전에 npm이 실행 파일을 어느 경로에 넣었는지 확인합니다.

Homebrew

brew install anomalyco/tap/opencode

OpenCode는 전용 tap 사용을 안내합니다. Homebrew 팀이 관리하는 brew install opencode formula는 이후에 변경될 수 있으므로, 여기서는 전용 tap 명령을 사용합니다. 설치 방식을 바꾼다고 설정 파일의 우선순위가 바뀌는 것은 아닙니다.

Windows

공식 문서는 Chocolatey 또는 Scoop을 제시합니다.

choco install opencode

또는 다음을 사용합니다.

scoop install opencode

어느 운영체제에서든 설치 직후 아래 명령을 실행합니다.

opencode --version

command not found 같은 오류 없이 버전이 출력되면 명령을 사용할 수 있습니다. 정확한 버전 번호는 릴리스마다 바뀌므로 문서에 고정하지 않습니다.

/connect와 opencode.json의 동작 방식

OpenCode는 인증 정보와 provider 설정을 분리해 저장할 수 있습니다. 일반 설정에서 /connect는 API Key를 ~/.local/share/opencode/auth.json에 저장합니다. 사용자 전체의 provider와 모델은 ~/.config/opencode/opencode.json에서 지정하고, 프로젝트 루트의 opencode.json은 해당 저장소에만 적용되는 설정을 바꿉니다.

설정 파일은 병합되며, 충돌하면 나중에 읽힌 소스가 앞선 값을 덮어씁니다. 일반 로컬 설정에서는 전역 설정 → OPENCODE_CONFIG가 가리키는 파일 → 프로젝트 opencode.json 순서가 중요합니다. 조직이 관리하는 설정은 이와 별도로 가장 높은 우선순위를 가질 수 있습니다.

1. /connect로 API Key 저장하기

실제 저장소가 아니라 테스트 디렉터리에서 OpenCode를 먼저 시작합니다.

mkdir opencode-first-test
cd opencode-first-test
opencode

TUI에서 다음을 실행합니다.

/connect

Other를 선택하고 provider id에 bettertoken을 입력한 뒤 credential 입력란에 본인의 API Key를 붙여 넣습니다. 실제 Key를 프롬프트, opencode.json, 스크린샷 또는 Git에 넣으면 안 됩니다.

저장한 뒤 OpenCode를 종료하고 provider가 등록됐는지 확인합니다.

opencode auth list

이 명령에는 provider가 표시되지만 Key 값 자체는 드러나지 않아야 합니다.

2. BetterToken provider 추가하기

모든 프로젝트에서 사용하려면 아래 파일을 만들거나 업데이트합니다.

~/.config/opencode/opencode.json

한 저장소에서만 provider가 필요하다면 그 루트에 opencode.json을 둡니다. 최소 설정은 다음과 같습니다.

{
  "$schema": "https://opencode.ai/config.json",
  "model": "bettertoken/YOUR_MODEL_ID",
  "provider": {
    "bettertoken": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "BetterToken",
      "options": {
        "baseURL": "https://www.bettertoken.ai/v1"
      },
      "models": {
        "YOUR_MODEL_ID": {
          "name": "YOUR_MODEL_ID"
        }
      }
    }
  }
}

YOUR_MODEL_ID는 BetterToken의 현재 모델 목록에 있는 정확한 ID로 바꿉니다. 같은 값을 최상위 model, models 객체의 키, 그 안의 name에 사용해야 합니다. Base URL 뒤에 /chat/completions를 붙이지 마세요. OpenCode와 @ai-sdk/openai-compatible 패키지가 요청 경로를 만듭니다. 자동 설정 명령과 현재 모델 그룹의 제한은 BetterToken OpenCode 문서에서 확인합니다. 모델 목록은 바뀔 수 있으므로 이 글에서는 특정 ID를 고정하지 않습니다.

3. 어떤 설정 파일이 우선하는지 확인하기

프로젝트의 opencode.json은 전역 모델이나 provider를 덮어쓸 수 있습니다. 예상과 다른 endpoint 또는 모델이 선택되면 다음 순서로 확인합니다.

1. ~/.config/opencode/opencode.json
2. 설정돼 있다면 OPENCODE_CONFIG 값
3. 현재 프로젝트 또는 Git 루트까지의 가장 가까운 상위 디렉터리에 있는 opencode.json

파일을 추측으로 삭제하지 마세요. 찾은 모든 설정에서 model, provider.bettertoken.options.baseURL, provider.bettertoken.models 값을 비교합니다. 일반 파일 사이에서는 프로젝트 설정의 우선순위가 높으므로 전역 파일만 고쳐서는 결과가 바뀌지 않을 수 있습니다.

첫 요청 실행 및 검증하기

JSON을 수정한 뒤 OpenCode를 다시 시작합니다.

opencode

모델 선택을 엽니다.

/models

bettertoken/YOUR_MODEL_ID를 선택하고, 파일을 바꾸지 않는 짧은 요청을 보냅니다. 예를 들면 다음과 같습니다.

JSON만 반환하세요: {"tool":"opencode","sum":4}. 파일은 변경하지 마세요.

첫 요청은 아래 네 가지가 모두 맞을 때 확인된 것으로 봅니다.

• OpenCode가 유효한 JSON을 반환했고 파일을 바꾸지 않았다.
• TUI에서 bettertoken/YOUR_MODEL_ID가 선택돼 있다.
• BetterToken Dashboard에 예상한 모델과 상태의 요청이 기록됐다.
• Dashboard에 input, output, 해당되는 cache Token 및 그에 대응하는 소비가 표시된다.

Dashboard를 전체 프롬프트나 응답 본문을 보관하는 곳으로 사용할 필요는 없습니다. 여기서 확인하는 것은 Token 사용량과 소비 기록입니다. 기록이 나타나지 않는다면 설정 덮어쓰기 때문에 다른 provider가 응답했을 수 있습니다. 우선순위 확인 단계로 돌아가 짧은 요청으로 다시 검증합니다.

자주 발생하는 오류 고치기

opencode: command not found

터미널을 닫고 다시 엽니다. npm으로 설치했다면 npm 전역 실행 파일 디렉터리가 PATH에 들어 있는지 확인합니다. 첫 번째 바이너리가 어디에 설치됐는지 알기 전에는 다른 설치 프로그램을 실행하지 마세요. 여러 설치 경로를 겹치면 실제로 어떤 실행 파일을 쓰는지 추적하기 어려워집니다.

401 또는 credential 오류

/connect를 다시 실행하고 provider id로 bettertoken을 선택합니다. 결과는 opencode auth list로 확인합니다. 빠른 확인을 위해서라도 Key를 명령줄이나 JSON에 직접 붙여 넣지 마세요. 인증 정보는 /connect의 저장 위치에 맡기고 설정 파일에는 provider 구조만 둡니다.

404 또는 API 오류

provider.bettertoken.options.baseURL에는 다음 Base URL이 있어야 합니다.

https://www.bettertoken.ai/v1

끝에 /chat/completions를 추가하지 않습니다. URL을 고친 후 OpenCode를 재시작하고, 긴 작업 대신 앞의 짧은 요청을 다시 실행합니다. URL이 맞는데도 오류가 계속되면 현재 Model ID와 설정 덮어쓰기를 확인합니다.

model not found

현재 문서와 모델 목록에서 Model ID 철자를 확인합니다. 최상위 model은 bettertoken/YOUR_MODEL_ID 형식이어야 하고, provider.bettertoken.models에는 같은 YOUR_MODEL_ID를 키로 둬야 합니다. 오래된 글이나 다른 provider의 모델 이름을 복사해도 현재 목록에 없는 ID는 선택할 수 없습니다.

OpenCode가 다른 모델 또는 endpoint를 사용함

대부분 설정 덮어쓰기가 원인입니다. 전역 설정, OPENCODE_CONFIG, 프로젝트 설정 파일을 비교합니다. 표준 설정 파일 사이에서는 프로젝트 파일이 우선합니다. 수정한 뒤 OpenCode를 완전히 재시작하고 /models와 Dashboard 모두에서 선택한 모델과 실제 요청을 확인합니다.

FAQ

API Key를 opencode.json에 저장해야 하나요?

그럴 필요가 없습니다. 일반 설정에서는 /connect를 사용합니다. OpenCode가 credential을 ~/.local/share/opencode/auth.json에 저장하므로 설정 파일에 실제 Key를 넣지 않아도 됩니다. 저장소에 두는 opencode.json은 실수로 커밋하지 않도록 내용을 확인하세요.

OpenCode에 필요한 Base URL은 무엇인가요?

BetterToken의 OpenAI-compatible provider에는 https://www.bettertoken.ai/v1을 사용합니다. 이것은 Base URL이므로 /chat/completions를 직접 추가하지 않습니다. www가 붙은 다른 URL이나 Claude Code용 Base URL을 섞지 마세요.

전역과 프로젝트 opencode.json 중 무엇을 선택해야 하나요?

하나의 provider와 모델을 많은 저장소에서 공통으로 쓴다면 전역 파일이 편리합니다. 특정 저장소에만 다른 Model ID나 권한이 필요하면 프로젝트 파일을 사용합니다. 충돌 시 프로젝트 설정이 덮어쓰므로, 문제가 생기면 두 위치를 함께 확인합니다.

BetterToken provider에 OpenCode 계정이 필요한가요?

custom provider는 선택한 API 서비스의 credential을 사용합니다. BetterToken은 사용자의 API Key를 제공하지만 OpenCode 웹사이트, 계정 또는 그 밖의 서비스를 대체하지는 않습니다. OpenCode 자체에 현재 필요한 계정 조건은 OpenCode 공식 문서에서 확인하세요.