AI 코딩

OpenCode API Key와 인증 설정: Astra, Grok, 프록시, Web 비밀번호

OpenCode의 API Key, 사용자 지정 프로바이더, GPT-6 Astra, Grok 직접 인증, OpenCode Go, Astra Linux, 지역·사내 프록시, Web 비밀번호와 자주 발생하는 오류를 다루는 실전 가이드입니다.

BT

BetterToken

편집팀
9 분 분량
목차
OpenCode API Key와 인증 설정: Astra, Grok, 프록시, Web 비밀번호

OpenCode 인증 관련 질문은 서로 비슷해 보이지만 실제로는 다른 계층을 가리킵니다. 모델 프로바이더의 API Key, OpenCode Go 로그인, xAI OAuth 흐름, opencode web을 보호하는 비밀번호는 각각 역할이 다릅니다.

이 글에서는 이 네 가지를 구분하고 BetterToken을 사용자 지정 프로바이더로 연결하는 실제 설정을 제공합니다. gpt-6-astra를 위한 복사 가능한 예제, Linux와 Astra Linux의 지역 네트워크 설정, Grok 직접 인증, OpenCode Web 인터페이스를 안전하게 보호하는 방법까지 순서대로 설명합니다.

OpenCode는 빠르게 변경됩니다. 운영 환경에 적용하기 전에 아래 명령을 최신 OpenCode 공식 문서와 대조하고, 정확한 모델 ID를 BetterToken 모델 카탈로그에서 확인하세요.

빠른 답변

하려는 작업올바른 위치 또는 명령
프로바이더 API Key를 대화형으로 저장OpenCode 안에서 /connect 실행
저장된 프로바이더 확인opencode auth list 실행
사용자 지정 프로바이더, Base URL, 모델 정의opencode.json 또는 opencode.jsonc
BetterToken 사용Base URL: https://www.bettertoken.ai/v1
GPT-6 Astra 사용모델 ID: gpt-6-astra, 현재 계정에서 이용 가능한 경우
OpenCode Go 로그인/connect → OpenCode Go → https://opencode.ai/auth
xAI/Grok에 직접 인증/connect → xAI → OAuth 구독 또는 API Key
OpenCode Web 보호opencode web 실행 전에 OPENCODE_SERVER_PASSWORD 설정
지역 또는 사내 프록시 사용HTTP_PROXY, HTTPS_PROXY, NO_PROXY 설정

시작하기 전에

다음을 준비하세요.

  • 최신 버전의 OpenCode
  • 공유 운영 키가 아닌 테스트 전용 API Key
  • 프로바이더 카탈로그에 표시된 정확한 모델 ID
  • 에이전트가 중요한 파일을 수정하지 못하게 할 수 있는 작은 테스트 저장소
  • OpenCode 설치 파일과 API 엔드포인트에 접근할 수 있는 터미널 환경

API Key는 비밀번호처럼 취급하세요. 실제 키를 프롬프트, 스크린샷, 이슈, 문서 또는 Git 저장소에 붙여 넣지 마세요.

OpenCode 설치하기

공식 설치 스크립트는 macOS와 Linux에서 사용할 수 있습니다.

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

npm으로도 설치할 수 있습니다.

npm install -g opencode-ai

Windows에서는 호환성을 위해 WSL 사용이 권장됩니다. Chocolatey와 Scoop도 공식 문서에 안내되어 있습니다.

choco install opencode
scoop install opencode

설치를 확인합니다.

opencode --version

버전 번호가 출력되어야 합니다. 셸에서 command not found가 표시되면 터미널을 다시 열고 설치 디렉터리가 PATH에 포함되어 있는지 확인하세요.

네 가지 인증 계층 이해하기

1. 프로바이더 API Key

BetterToken, xAI, OpenAI 또는 다른 모델 프로바이더 호출을 승인하는 키입니다. OpenCode는 /connect를 통해 키를 저장하거나 설정 파일에서 참조한 환경 변수를 읽을 수 있습니다.

2. OpenCode Go 또는 OpenCode Zen 인증

OpenCode Go와 Zen은 OpenCode가 운영하는 모델 서비스입니다. 인증 과정에서 https://opencode.ai/auth가 열리며, 로그인하고 필요한 결제 설정을 완료한 뒤 발급된 API Key를 복사해 /connect로 돌아와 입력합니다.

이 키는 BetterToken 키와 별개입니다.

3. xAI/Grok 인증

현재 OpenCode의 프로바이더 흐름은 지원되는 xAI 구독의 디바이스 코드 OAuth 또는 사용량 기반 xAI API Key를 지원합니다. 이는 xAI에 직접 연결하는 방식이며 BetterToken 연결이 아닙니다.

4. OpenCode Web 비밀번호

OPENCODE_SERVER_PASSWORD는 로컬 OpenCode HTTP 서버와 브라우저 인터페이스를 Basic 인증으로 보호합니다. 모델 호출을 승인하지 않으며 프로바이더 API Key를 대신할 수 없습니다.

OpenCode에서 API Key를 설정하는 방법

OpenCode는 JSON과 JSONC를 모두 지원합니다. 공식 예제는 opencode.json을 자주 사용하며, 주석이 필요할 때는 JSONC가 편리합니다. 중요한 점은 자격 증명 저장과 프로바이더 정의가 서로 분리되어 있다는 것입니다.

방법 1: /connect로 키 저장하기

안전한 테스트 디렉터리에서 OpenCode를 시작합니다.

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

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

/connect

BetterToken을 연결할 때는 다음 순서로 진행합니다.

  1. Other를 선택합니다.
  2. 프로바이더 ID로 bettertoken을 입력합니다.
  3. 자격 증명 입력란에 BetterToken API Key를 붙여 넣습니다.
  4. 프로바이더 설정을 추가한 뒤 OpenCode를 종료하거나 다시 시작합니다.

/connect로 추가한 자격 증명은 다음 위치에 저장됩니다.

~/.local/share/opencode/auth.json

비밀 키를 출력하지 않고 프로바이더가 등록되었는지 확인합니다.

opencode auth list

/connect에서 사용한 프로바이더 ID는 설정 파일의 ID와 정확히 같아야 합니다. bettertoken을 입력했다면 설정의 프로바이더 키도 bettertoken이어야 합니다.

방법 2: opencode.json 또는 opencode.jsonc 설정하기

모든 프로젝트에서 프로바이더를 사용할 때는 전역 파일을 사용합니다.

~/.config/opencode/opencode.json

특정 저장소에만 전용 모델이나 엔드포인트가 필요하면 프로젝트 수준의 opencode.json 또는 opencode.jsonc를 사용합니다.

다음 예제는 BetterToken과 현재 API 모델 ID gpt-6-astra를 사용합니다.

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

사용하기 전에 gpt-6-astra가 현재 BetterToken 카탈로그와 계정의 접근 그룹에 표시되는지 확인하세요. 카탈로그에 다른 모델 ID가 표시되면 bettertoken/gpt-6-astra와 models 아래의 gpt-6-astra 키를 모두 교체해야 합니다.

Base URL 뒤에 /chat/completions를 추가하지 마세요. 요청 경로는 어댑터가 자동으로 구성합니다.

/connect 대신 환경 변수 사용하기

macOS 또는 Linux에서는 다음과 같이 설정합니다.

export BETTERTOKEN_API_KEY="YOUR_API_KEY"

PowerShell에서는 다음과 같습니다.

$env:BETTERTOKEN_API_KEY = "YOUR_API_KEY"

그다음 프로바이더 옵션에서 변수를 참조합니다.

{
  "$schema": "https://opencode.ai/config.json",
  "model": "bettertoken/gpt-6-astra",
  "provider": {
    "bettertoken": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "BetterToken",
      "options": {
        "baseURL": "https://www.bettertoken.ai/v1",
        "apiKey": "{env:BETTERTOKEN_API_KEY}"
      },
      "models": {
        "gpt-6-astra": {
          "name": "GPT-6 Astra"
        }
      }
    }
  }
}

JSON 파일에 비밀 값을 직접 쓰는 것보다 안전합니다. 환경 변수가 없으면 OpenCode는 빈 문자열로 치환하며, 일반적으로 401 오류가 발생합니다.

OpenCode가 설정을 무시하는 이유

OpenCode는 여러 설정 소스를 병합합니다. 같은 필드가 충돌하면 나중에 로드되는 소스가 앞선 값을 덮어씁니다. 중요한 우선순위는 다음과 같습니다.

  1. 조직의 원격 기본값
  2. ~/.config/opencode/opencode.json의 전역 설정
  3. OPENCODE_CONFIG가 가리키는 사용자 지정 파일
  4. 프로젝트의 opencode.json 또는 opencode.jsonc
  5. OPENCODE_CONFIG_CONTENT의 인라인 설정
  6. 사용자 파일을 덮어쓸 수 있는 관리자 관리 설정

OpenCode가 잘못된 모델이나 엔드포인트를 선택할 때 파일을 무작정 삭제하지 마세요. 활성 설정을 모두 찾아 다음 항목을 비교하세요.

  • 최상위 model 값
  • provider.bettertoken.options.baseURL
  • provider.bettertoken.models 아래의 모델 키
  • 현재 셸의 OPENCODE_CONFIG와 OPENCODE_CONFIG_CONTENT

프로바이더 설정을 변경한 뒤에는 OpenCode를 다시 시작하세요.

OpenCode Astra: 모델 이름인가, Astra Linux인가?

“OpenCode Astra”라는 검색어는 두 가지를 뜻할 수 있습니다.

OpenCode에서 GPT-6 Astra 사용하기

OpenAI 모델을 뜻한다면 정확한 API ID gpt-6-astra를 사용하세요. 위 BetterToken 프로바이더 설정에서는 다음 모델을 선택합니다.

bettertoken/gpt-6-astra

OpenCode 안에서 모델 선택기를 엽니다.

/models

모델이 표시되지 않으면 프로바이더 ID, models 맵, BetterToken 접근 그룹, 현재 카탈로그를 확인하세요. 표시 이름만 보고 모델 ID를 추측하지 마세요.

Astra Linux에서 OpenCode 실행하기

OpenCode 문서는 Linux 설치 방법을 제공하지만 Astra Linux 전용 지원을 별도로 보장하지는 않습니다. Astra Linux를 Linux 환경으로 보고, 호환된다고 가정하지 말고 실제 시스템에서 검증하세요.

아키텍처와 필요한 도구를 확인합니다.

uname -m
command -v curl
command -v bash

그다음 설치 경로와 API 경로를 따로 테스트하세요. 모델 API에 접속할 수 있다고 해서 OpenCode 설치 파일, npm 레지스트리, GitHub, 업데이트 서버에도 모두 접속할 수 있다는 뜻은 아닙니다.

일반 프록시는 다음과 같이 설정합니다.

export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080
export NO_PROXY=localhost,127.0.0.1,::1
opencode

NO_PROXY는 중요합니다. TUI가 로컬 OpenCode HTTP 서버와 통신하기 때문에 루프백 트래픽까지 프록시로 보내면 연결이 반복되거나 화면이 멈춘 것처럼 보일 수 있습니다.

조직에서 사설 인증 기관을 사용하는 경우 다음과 같이 설정합니다.

export NODE_EXTRA_CA_CERTS=/etc/company/ca.pem
opencode

실제 프록시 자격 증명을 공유 셸 스크립트에 직접 넣지 마세요. 조직의 비밀 관리 도구나 보호된 환경 설정을 사용하세요.

OpenCode Grok 인증: xAI 직접 연결 또는 게이트웨이

xAI에 직접 연결하기

다음을 실행합니다.

/connect

xAI를 선택합니다. 현재 OpenCode 문서는 두 가지 인증 방법을 안내합니다.

  • 지원되는 xAI 구독을 사용하는 디바이스 코드 OAuth
  • xAI 콘솔에서 발급받은 API Key 직접 입력

인증 후 다음을 실행합니다.

/models

사용 가능한 Grok 모델을 선택합니다.

BetterToken 또는 다른 게이트웨이로 Grok 사용하기

사용자 지정 게이트웨이는 해당 게이트웨이가 현재 유효한 Grok 모델과 올바른 프로토콜을 실제로 제공할 때만 동작합니다. Grok 모델 ID를 임의로 만들거나 모든 OpenAI 호환 게이트웨이가 xAI 모델을 제공한다고 가정하지 마세요.

먼저 현재 프로바이더 카탈로그를 확인하세요. Grok이 없다면 OpenCode의 xAI 프로바이더에 직접 연결합니다. Grok 인증 확장 같은 커뮤니티 플러그인은 공식 프로바이더 흐름과 별개입니다. 설치 전에 유지보수 상태, 요청 권한, 자격 증명 처리 방식을 검토하세요.

OpenCode Go 인증

OpenCode Go는 모든 프로바이더를 인증하는 명령이 아닙니다. OpenCode가 제공하는 구독형 서비스입니다.

연결 방법은 다음과 같습니다.

  1. /connect를 실행합니다.
  2. OpenCode Go를 선택합니다.
  3. https://opencode.ai/auth를 엽니다.
  4. 로그인하고 필요하면 결제 설정을 완료한 뒤 생성된 키를 복사합니다.
  5. 키를 OpenCode에 다시 붙여 넣습니다.
  6. /models를 실행해 요금제에 포함된 모델을 선택합니다.

OpenCode Go를 사용하려는 경우에만 이 흐름을 사용하세요. BetterToken은 프로바이더 ID와 키를 bettertoken으로 유지해야 합니다.

OpenCode Web 비밀번호: 환경 변수 사용하기

opencode web password는 자주 검색되는 표현이며, 일부 예제는 비밀번호 옵션으로 -p를 잘못 안내합니다. 공식 문서에 나온 방법은 OPENCODE_SERVER_PASSWORD 환경 변수입니다.

macOS 또는 Linux에서는 다음과 같이 실행합니다.

OPENCODE_SERVER_PASSWORD='replace-with-a-strong-password' opencode web

사용자 이름도 바꾸려면 다음과 같이 설정합니다.

OPENCODE_SERVER_USERNAME='developer' \
OPENCODE_SERVER_PASSWORD='replace-with-a-strong-password' \
opencode web

PowerShell에서는 다음과 같습니다.

$env:OPENCODE_SERVER_USERNAME = "developer"
$env:OPENCODE_SERVER_PASSWORD = "replace-with-a-strong-password"
opencode web

기본 사용자 이름은 opencode입니다. 127.0.0.1에서만 로컬로 사용할 때는 비밀번호가 없어도 허용 가능한 경우가 있지만, 네트워크 접근은 반드시 보호해야 합니다. 인증과 네트워크 제어를 준비하기 전에 서비스를 0.0.0.0에 바인딩하거나 터널로 외부에 노출하지 마세요.

Web 비밀번호는 OpenCode 서버를 보호합니다. 프로바이더 키가 다른 곳에서 유출된 경우 해당 프로바이더 계정을 보호해 주지는 않습니다.

첫 요청 확인하기

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

opencode

모델 선택기를 엽니다.

/models

bettertoken/gpt-6-astra를 선택하고 확인하기 쉬운 짧은 프롬프트를 보냅니다.

다음 JSON만 반환하고 어떤 파일도 수정하지 마세요: {"tool":"opencode","sum":4}

설정이 올바르면 다음 조건을 모두 만족해야 합니다.

  • OpenCode가 유효한 JSON을 반환한다
  • 프로젝트 파일이 변경되지 않는다
  • 선택된 모델이 bettertoken/gpt-6-astra이다
  • BetterToken 대시보드에 대응하는 요청이 나타난다
  • 모델, 상태, 입력 토큰, 출력 토큰, 비용이 합리적으로 보인다

OpenCode는 응답하지만 BetterToken에 요청이 표시되지 않는다면 더 높은 우선순위의 설정이 다른 프로바이더로 라우팅하고 있을 수 있습니다.

문제 해결

401 또는 자격 증명 오류

  • /connect를 다시 실행하고 프로바이더 ID로 bettertoken을 사용하세요.
  • opencode auth list를 실행하세요.
  • {env:BETTERTOKEN_API_KEY}를 사용하는 경우 비밀 값이 아니라 변수의 존재 여부만 확인하세요.
  • 키가 활성화되어 있고 충분한 잔액이나 권한이 있는지 확인하세요.

404 또는 API 경로 오류

BetterToken Base URL은 다음과 같아야 합니다.

https://www.bettertoken.ai/v1

/chat/completions를 직접 추가하지 마세요.

model not found

모델 카탈로그에서 현재의 정확한 ID를 확인하세요. 최상위 model 값과 models 아래의 키가 호출하려는 프로바이더와 모델에 맞아야 합니다.

잘못된 엔드포인트 또는 모델이 사용됨

전역, 사용자 지정, 프로젝트, 인라인, 관리자 관리 설정을 확인하세요. 그런 다음 OpenCode를 다시 시작하고 /models에서 모델을 다시 선택합니다.

프록시를 켜면 OpenCode가 멈춤

루프백 주소가 제외되었는지 확인하세요.

export NO_PROXY=localhost,127.0.0.1,::1

OpenCode Web에서 Unauthorized가 표시됨

브라우저가 설정한 사용자 이름과 비밀번호를 사용하는지 확인하세요. 셸 환경에 이전 OPENCODE_SERVER_PASSWORD 값이 남아 있거나 클라이언트 프로세스가 다른 값을 상속했는지도 확인합니다.

opencode: command not found

터미널을 다시 열고 PATH를 확인한 뒤 패키지 관리자의 전역 실행 파일 경로 확인 명령을 실행하세요. 어떤 실행 파일이 활성화되어 있는지 확인하기 전에는 여러 패키지 관리자로 같은 프로그램을 중복 설치하지 마세요.

자주 묻는 질문

OpenCode에 API Key를 어떻게 설정하나요?

권장되는 대화형 방법은 /connect입니다. 사용자 지정 프로바이더는 Other를 선택하고 프로바이더 ID와 키를 입력합니다. 별도로 opencode.json 또는 opencode.jsonc에 사용자 지정 프로바이더와 모델을 정의해야 합니다.

파일 이름은 opencode.json인가요, opencode.jsonc인가요?

OpenCode는 JSON과 JSONC를 모두 지원합니다. 주석이 필요하면 JSONC를 사용하세요. 여러 설정 소스가 어떻게 병합되는지 의도적으로 이해하고 사용하는 경우가 아니라면 프로젝트 설정은 하나만 활성화하세요.

OpenCode는 API Key를 어디에 저장하나요?

/connect로 추가한 자격 증명은 ~/.local/share/opencode/auth.json에 저장됩니다. 이 파일을 공개하거나 동기화하거나 커밋하지 마세요.

API Key를 설정 파일에 직접 넣어도 되나요?

OpenCode는 options.apiKey를 지원하지만 Git에서 추적되는 JSON 파일에 비밀 값을 그대로 쓰는 것은 위험합니다. /connect, {env:VARIABLE_NAME}, {file:path/to/secret}을 우선 사용하세요.

OpenCode Go 인증과 프로바이더 인증은 같은가요?

아닙니다. OpenCode Go는 별도의 OpenCode 서비스입니다. BetterToken, xAI 또는 다른 프로바이더 키와는 독립적입니다.

OpenCode Web 비밀번호는 어떻게 설정하나요?

opencode web을 실행하기 전에 OPENCODE_SERVER_PASSWORD를 설정하세요. 공식 방법은 환경 변수를 사용하는 것이며 범용 -p 비밀번호 플래그가 아닙니다.

OpenCode에서 Grok을 어떻게 인증하나요?

/connect를 실행하고 xAI를 선택한 뒤 지원되는 구독 OAuth 또는 xAI API Key 직접 입력 방식을 사용하세요. 게이트웨이는 실제로 Grok 모델을 제공할 때만 사용할 수 있습니다.

“OpenCode Astra”는 GPT-6 Astra인가요, Astra Linux인가요?

둘 다 의미할 수 있습니다. 모델이라면 gpt-6-astra를 사용하세요. Astra Linux라면 Linux 설치와 네트워크 확인 절차를 따르고 해당 배포판의 실제 빌드에서 검증해야 합니다.

러시아에서 OpenCode를 사용하려면 VPN이 필요한가요?

하나의 답으로 정리할 수 없습니다. 설치 다운로드, GitHub, npm, OpenCode 웹사이트, 모델 API는 서로 다른 네트워크 경로를 사용합니다. 각 경로를 따로 테스트하고 필요하면 규정에 맞는 지역 또는 사내 네트워크 설정을 사용하세요.

공식 참고 자료

BetterTokenAI MODEL APIs모든 모델을 하나의 API로GPTClaudeDeepSeekQwenGLMKimiMiniMaxAI API · 사용량 기반 요금BetterToken으로 개발 시작하기API 키를 만들고 첫 요청을 보내세요.시작하기bettertoken.ai
AI 코딩Cursor를 OpenRouter에 연결하는 방법: 설정, 기능 경계 및 오류 해결AI 코딩ZCode 사용 한도에 도달했을 때: GLM Coding Plan 할당량과 리셋 카드 확인법AI 코딩Kimi Code 한도: 5시간, 기존 요금제 주간, 월간, 429 오류 구분

LLM 워크플로를 최적화할 준비가 되셨나요?

하나의 API로 모델을 연결하고 키와 AI 비용을 관리하세요.

무료로 시작하기