Jiminbox Docs

OpenCode 설치 가이드

18 min read

OpenCode 설치 가이드

OpenCode는 프로젝트 파일을 읽고 수정하며 명령을 실행하는 오픈소스 코딩 에이전트입니다. 이 문서는 Windows, macOS, Linux에서 OpenCode를 설치하고 Jiminbox New API에 연결한 뒤 첫 요청과 사용량 기록까지 확인하는 순서로 설명합니다.

작업 폴더를 먼저 확인하세요

OpenCode는 사용자가 연 폴더의 파일을 수정할 수 있습니다. 처음에는 중요하지 않은 테스트 폴더에서 사용하고, 삭제·배포·외부 전송 작업은 실행 전에 내용을 확인하세요.

1. 시작 전 준비

운영체제 확인

아래 설치 방법에서 현재 사용 중인 운영체제에 해당하는 절차만 따릅니다.

  • Windows: Windows 10 또는 Windows 11에서 OpenCode 설치 파일이나 터미널을 사용합니다.
  • macOS: Apple Silicon(M 시리즈) 또는 Intel Mac에서 OpenCode 설치 파일이나 터미널을 사용합니다.
  • Linux: 사용 중인 배포판에 맞는 OpenCode 설치 방법이나 터미널을 사용합니다.

터미널 버전을 설치할 때는 운영체제와 관계없이 먼저 node.js 설치 가이드에서 자신의 운영체제 절차만 따라 Node.js와 npm을 준비합니다. Windows 절차는 다른 운영체제에 적용하지 않습니다. Desktop 앱만 사용할 예정이라면 Node.js 준비 단계를 건너뛸 수 있습니다.

New API Key와 현재 연결값 확인

  1. New API Key와 사용량 가이드에 따라 New API에 로그인하고 API Keys에서 키를 만듭니다.
  2. 발급 직후 표시되는 New API Key 전체 값을 비밀번호 관리자처럼 안전한 곳에 보관합니다. 문서, 메신저, Git 저장소와 화면 캡처에는 넣지 마세요.
  3. New API의 현재 모델 목록과 연결 안내 화면을 열어 다음 값을 확인합니다.
    • Base URL: 현재 화면에 표시된 OpenAI 호환 API 주소 전체
    • 모델 ID: 현재 계정과 플랜에서 사용할 수 있는 모델의 ID 전체
    • 모델 이름: 화면에 표시되는 모델 이름
  4. 메뉴 이름이나 위치가 이 문서와 다르면 문서의 고정된 예시보다 현재 New API 화면의 안내를 우선합니다. 모델과 주소는 바뀔 수 있으므로 기억해서 입력하지 마세요.

2. OpenCode 설치

Desktop 앱

  1. OpenCode 다운로드 페이지 또는 공식 설치 안내를 엽니다.
  2. Windows, macOS, Linux 중 현재 운영체제에 맞는 설치 항목을 선택합니다. 페이지에 표시되는 현재 설치 파일 형식과 안내를 따르세요.
  3. 내려받은 설치 파일을 실행하고 설치를 마칩니다.
  4. OpenCode를 한 번 실행해 앱이 열리는지 확인합니다. 아직 Jiminbox 설정을 입력하지 않았다면 공급사 연결이 완료되지 않은 것이 정상입니다.

터미널 버전

  1. 먼저 node.js 설치 가이드의 자신의 운영체제 절차를 완료합니다.

  2. 새 터미널을 엽니다. Windows에서는 PowerShell 또는 명령 프롬프트를, macOS·Linux에서는 터미널을 사용할 수 있습니다.

  3. Node.js와 npm이 준비되었는지 확인합니다.

    node --version
npm --version

    두 명령 모두 버전 숫자를 출력해야 합니다.

  4. 다음 명령으로 OpenCode를 설치합니다.

    npm install -g opencode-ai

  5. 설치가 끝나면 버전을 확인합니다.

    opencode --version

    버전 숫자가 출력되면 터미널 설치가 완료된 것입니다. command not found 또는 Windows의 명령을 찾을 수 없다는 오류가 나오면 새 터미널을 열고 다시 실행한 뒤 node.js 설치 가이드의 PATH 문제 해결 절차를 확인합니다.

3. 설정 파일 만들기와 경로 확인

OpenCode의 사용자 전역 설정 파일을 만들면 Desktop 앱과 터미널 버전에서 같은 설정을 사용할 수 있습니다. 아래 경로는 현재 사용자 계정의 설정 경로입니다.

운영체제사용자 전역 설정 파일 경로
Windows%USERPROFILE%\.config\opencode\opencode.json
macOS·Linux~/.config/opencode/opencode.json

~와 %USERPROFILE%는 현재 로그인한 사용자의 홈 폴더를 뜻합니다. 파일 이름이 opencode.json.txt가 되지 않도록 파일 확장명을 확인합니다.

설정 폴더와 파일 열기

운영체제에 맞는 방법 하나만 실행합니다.

Windows PowerShell

New-Item -ItemType Directory -Force "$HOME\.config\opencode" | Out-Null
notepad "$HOME\.config\opencode\opencode.json"

macOS·Linux 터미널

mkdir -p "$HOME/.config/opencode"
nano "$HOME/.config/opencode/opencode.json"

nano가 없으면 사용 중인 텍스트 편집기로 같은 경로의 파일을 만듭니다. 기존 opencode.json이 있다면 먼저 백업한 뒤 수정합니다.

Windows PowerShell 백업

if (Test-Path "$HOME\.config\opencode\opencode.json") { Copy-Item "$HOME\.config\opencode\opencode.json" "$HOME\.config\opencode\opencode.json.backup" -Force }

macOS·Linux 터미널 백업

if [ -f "$HOME/.config/opencode/opencode.json" ]; then cp "$HOME/.config/opencode/opencode.json" "$HOME/.config/opencode/opencode.json.backup"; fi

경로가 맞는지 확인

파일 내용을 출력하지 않고 파일이 존재하는지만 확인합니다.

Windows PowerShell

Test-Path "$HOME\.config\opencode\opencode.json"

macOS·Linux 터미널

test -f "$HOME/.config/opencode/opencode.json" && echo "설정 파일을 찾았습니다."

결과가 True 또는 설정 파일을 찾았습니다.이면 경로 확인이 끝난 것입니다.

프로젝트 설정이 전역 설정을 덮어쓸 수 있습니다

OpenCode는 프로젝트 폴더 안의 opencode.json을 전역 설정 파일보다 우선할 수 있습니다. 첫 연결은 별도의 테스트 폴더에서 실행하고, 그 폴더에 다른 opencode.json이 있는지 확인합니다. 프로젝트 설정을 사용하는 경우에도 아래의 현재 New API 값을 동일하게 입력해야 합니다.

4. Jiminbox 값 입력

  1. opencode.json 템플릿에서 JSON 구조를 복사해 opencode.json에 붙여 넣습니다.
  2. 템플릿의 apiKey 값은 실제 예시값으로 바꾸지 말고, 현재 New API에서 방금 발급한 자신의 New API Key 전체 값만 이 컴퓨터의 설정 파일에 입력합니다. 이 값은 문서나 캡처에 남기지 않습니다.
  3. options.baseURL은 템플릿에 적힌 주소를 그대로 믿지 말고, 현재 New API 화면의 Base URL 전체 값으로 맞춥니다. 주소의 앞뒤 공백을 제거하고 /v1 같은 경로를 임의로 추가하거나 삭제하지 마세요.
  4. models 아래의 모델 ID는 현재 New API 화면에 표시된 모델 ID를 그대로 사용합니다. 템플릿에 없는 모델을 사용하려면 현재 화면의 모델 ID를 객체 이름으로 추가하고, name에는 화면의 모델 이름을 입력합니다. 첫 요청에서는 현재 계정에서 사용 가능한 모델 하나만 남겨도 됩니다.
  5. 모델 ID의 대소문자, 숫자, 하이픈과 점을 확인합니다. 표시 이름과 모델 ID가 다를 수 있으므로 모델 이름을 ID로 대신 입력하지 마세요.
  6. JSON의 큰따옴표와 쉼표를 유지하고 저장합니다. apiKey, baseURL, 모델 ID에는 줄바꿈이나 앞뒤 공백을 넣지 않습니다.

아래 표는 입력할 위치를 확인하기 위한 안내이며, 실제 값은 문서에 적지 않습니다.

설정 항목입력할 값
provider의 options.apiKey현재 New API에서 발급한 본인의 New API Key 전체 값
provider의 options.baseURL현재 New API 화면에 표시된 Base URL 전체 값
provider의 models 객체 이름현재 New API 화면에 표시된 사용 가능한 모델 ID
models의 name현재 New API 화면의 모델 표시 이름

설정 파일 공개 금지

API Key를 입력한 opencode.json은 Git에 커밋하거나 다른 사람에게 전송하지 마세요. 설정 화면과 오류 로그를 캡처할 때도 키 전체, Authorization 헤더와 홈 경로의 개인 정보가 보이지 않는지 확인하세요. 키가 노출되었다면 연결 확인을 계속하지 말고 New API의 API Keys에서 해당 키를 폐기한 뒤 새 키를 발급하세요.

5. 설치와 설정 완료 확인

  1. OpenCode를 완전히 종료했다가 다시 실행합니다.
  2. 터미널 버전이라면 테스트 폴더에서 opencode --version을 실행해 명령이 동작하는지 확인합니다. Desktop 앱이라면 앱 창이 정상적으로 열리는지 확인합니다.
  3. opencode.json 템플릿과 비교해 apiKey, baseURL, 모델 ID가 비어 있지 않은지 확인합니다. 키의 실제 내용은 화면에 복사하거나 출력하지 마세요.
  4. 3단계의 운영체제별 경로에 설정 파일이 있는지 다시 확인합니다.
  5. OpenCode에서 /models를 입력합니다. Jiminbox 공급사와 현재 New API 화면에서 확인한 모델 ID가 목록에 보여야 합니다.

Jiminbox 또는 모델이 보이지 않으면 첫 요청을 보내기 전에 7단계의 오류 해결 순서를 따르세요. 목록에 보인다는 사실만으로 API 요청 성공을 확정하지 않습니다.

6. 첫 요청과 Usage Logs 교차 확인

OpenCode에서 첫 요청 보내기

  1. 중요하지 않은 빈 테스트 폴더를 열고 OpenCode를 실행합니다.

  2. /models에서 Jiminbox와 현재 New API 화면에서 확인한 모델 ID를 선택합니다.

  3. 도구 호출이나 긴 파일 내용을 포함하지 않는 짧은 요청을 한 번만 보냅니다. 예를 들면 다음과 같습니다.

    1+1의 답을 한 문장으로만 알려 줘.

  4. 모델의 답변이 오류 없이 표시되는지 확인하고, 요청을 보낸 시각과 선택한 모델 ID를 메모합니다. 첫 테스트에서는 같은 질문을 반복하지 않아야 Usage Logs에서 찾기 쉽습니다.

New API Usage Logs에서 교차 확인

  1. New API에서 Usage Logs를 엽니다.
  2. 방금 요청한 시각과 모델 ID에 해당하는 기록을 찾습니다. 입력·출력 토큰과 차감량이 표시되면 함께 확인합니다.
  3. 로그 반영이 늦으면 잠시 기다린 뒤 새로 고침합니다. OpenCode에 답변이 보였더라도 Usage Logs에 해당 요청이 없으면 연결 성공으로 단정하지 마세요.
  4. OpenCode의 응답과 Usage Logs의 시각·모델 ID가 모두 일치하면 첫 연결 검증이 완료된 것입니다.

OpenCode는 한 작업 중 여러 번 API를 호출할 수 있습니다. 따라서 이 검증에서는 짧은 요청을 한 번만 보내고, Usage Logs에 여러 기록이 보이면 같은 시각의 전체 요청 수를 함께 확인합니다.

7. 오류 해결과 롤백

먼저 확인할 항목

  • 인증 오류: 현재 New API 화면에서 발급한 키 전체를 다시 복사했는지 확인합니다. 키 앞뒤 공백을 제거하되 키의 접두사나 형식을 임의로 바꾸지 마세요.
  • Base URL 오류 또는 404: 현재 New API 화면의 Base URL을 다시 복사합니다. /v1을 임의로 더하거나 빼지 말고, 템플릿의 이전 값이 남아 있지 않은지 확인합니다.
  • 모델을 찾을 수 없음: 현재 New API 모델 목록에서 사용 가능한 모델 ID를 다시 확인합니다. 표시 이름이 아니라 모델 ID를 models 객체 이름에 입력해야 합니다.
  • Jiminbox가 /models에 보이지 않음: 설정 파일의 위치와 파일 확장명을 확인하고, 프로젝트 폴더에 전역 설정을 덮어쓰는 opencode.json이 있는지 확인합니다. 저장 후 OpenCode를 완전히 다시 실행합니다.
  • Usage Logs에 기록이 없음: 잠시 기다린 뒤 새로 고침하고, Base URL·API Key·모델 ID를 다시 확인합니다. 로그가 생기기 전에는 성공한 것으로 처리하지 않습니다.
  • 한도 초과: New API의 Wallet과 Dashboard에서 잔여 한도와 갱신 상태를 확인합니다. 모델마다 차감량이 다를 수 있으므로 같은 요청을 반복하지 마세요.

새 설정을 이전 상태로 되돌리기

설정 변경 뒤 OpenCode가 시작되지 않거나 연결 오류가 계속되면 다음 순서로 되돌립니다. 먼저 백업 파일이 실제로 있는지 확인하고, 파일이 있을 때만 복원 명령을 실행합니다.

Windows PowerShell

$backup = "$HOME\.config\opencode\opencode.json.backup"
if (Test-Path $backup) {
    Copy-Item $backup "$HOME\.config\opencode\opencode.json" -Force
} else {
    Write-Host "백업 파일이 없습니다. 아래의 백업이 없을 때 절차를 따르세요."
}

macOS·Linux 터미널

backup="$HOME/.config/opencode/opencode.json.backup"
if [ -f "$backup" ]; then
  cp "$backup" "$HOME/.config/opencode/opencode.json"
else
  printf '%s\n' '백업 파일이 없습니다. 아래의 백업이 없을 때 절차를 따르세요.'
fi

백업이 없다면 OpenCode를 종료한 뒤 현재 파일을 .failed와 같이 이름을 바꾸고, 새 파일을 처음부터 다시 만듭니다. 이때 오류 원인을 확인할 수 있도록 기존 파일을 바로 삭제하지 않고 보관합니다.

  1. 복원 또는 이름 변경을 마친 뒤 OpenCode를 다시 실행합니다.
  2. 이전 설정으로 앱이 정상 실행되는지 확인합니다.
  3. 새 키가 잘못된 파일에 입력되었거나 캡처·로그에 노출되었다면 New API의 API Keys에서 해당 키를 즉시 삭제하고 새 키를 발급합니다.
  4. 새 키와 현재 Base URL·모델 ID를 다시 입력한 뒤 5단계와 6단계의 검증을 처음부터 반복합니다.

문제가 계속되면 Jiminbox 문제 해결 가이드를 확인합니다. 오류 화면을 공유할 때는 API Key, Authorization 헤더, 이메일과 개인 파일 경로를 먼저 가리세요.

다음 단계: New API Key와 사용량 가이드 · Jiminbox 문제 해결 가이드 · Jiminbox 사용 정책

그래프 뷰

백링크