빠른 답변
- 설치 직후 "opencode: command not found"가 뜨나요? 설치기의 bin 폴더가 PATH에 없는 것입니다 — 셸 프로필에 export로 추가하고(영상에서는 Git Bash용으로 .opencode/bin 경로를 넣습니다) 새 터미널을 열면 해결됩니다.
- 설치 스크립트가 에러를 뱉나요? Bash 스크립트라서 PowerShell에서 실행하면 -fsSL 플래그에서 실패합니다. 먼저 VS Code 기본 터미널 프로필을 Git Bash로 바꾸고, curl -fsSL https://opencode.ai/install | bash를 다시 실행하세요.
- 터미널이나 데스크톱 창이 검게 열리나요? .local/share/opencode 아래 손상된 데이터 폴더를 지우고(Windows는 AppData\Local\share\opencode) 멈춘 프로세스를 끝낸 뒤 다시 실행하세요 — 녹화에서는 1분 안에 TUI가 다시 그려집니다.
- "Free usage exceeded"나 프로바이더 오류가 뜨나요? /models로 모델 피커를 열어 다른 모델로 바꾸거나, /connect로 재인증하세요. opencode auth list를 실행하면 자격 증명이 등록됐는지 확인됩니다.
- 모델 목록이 덜 보이나요? 연결된 프로바이더만 표시됩니다. /connect로 프로바이더를 추가하거나, opencode.json의 model·disabled_providers·프로바이더별 허용/차단 목록 키로 목록을 정리하세요.
Fix OpenCode Error in Antigravity Terminal (Git Bash + PATH Solution)
채널:teacher account5:52
OpenCode docs — install, config & troubleshooting
문서:opencode.ai/docs
장면은 세 개의 화면 녹화에서 가져왔습니다: 위의 PATH 수정, Windows 검은 화면 수리(xiXPoY2d4iw, Vũ Văn Hà), 무료 한도 도달 후 모델 전환(DX8MZFuu1BM, Free Code). 각 단계에서 해당 영상 지점으로 바로 이동합니다.
영상 장면의 저작권은 제작자에게 있으며, 출처와 딥 링크를 밝혀 단계별 문서로 삽입했습니다.
OpenCode 한 단계씩 고치기
설치와 PATH — "명령을 찾을 수 없음" 단계
- 1
공식 설치 명령어 확보하기
opencode.ai를 열어 설치 박스에서 명령어를 복사하세요 — curl -fsSL https://opencode.ai/install | bash — 또는 탭을 npm·bun·brew로 바꿔도 됩니다. OpenCode가 "안 되는" 이유가 애초에 설치가 끝까지 안 된 것이라면, 절반만 복사한 명령어를 디버깅하는 것보다 이 공식 명령어로 다시 시작하는 게 빠릅니다.
curl·npm·bun·brew 탭이 있는 opencode.ai 설치 박스0:08에 보기 - 2
PowerShell이 아니라 Bash 셸에서 설치기 실행하기
설치 스크립트는 Bash용입니다. PowerShell에 붙여 넣으면 녹화에 그대로 잡힌 것처럼 Invoke-WebRequest: A parameter cannot be found that matches parameter name 'fsSL' 오류가 납니다. 화면에서 보여준 해결책: IDE의 settings.json에서 terminal.integrated.defaultProfile.windows를 Git Bash로 바꿔 명령어가 Bash 셸에 닿게 하는 것입니다.
PowerShell이 던진 -fsSL 오류와 기본 프로필 설정1:32에 보기 - 3
PATH를 늘려 "opencode: command not found" 해결하기
설치는 끝났는데 터미널이 여전히 bash: opencode: command not found라고 한다면 바이너리 폴더가 PATH에 못 들어간 것입니다. 녹화에서는 Git Bash에서 export PATH=/c/Users/<you>/.opencode/bin:$PATH로 .opencode/bin 디렉터리를 추가하고 opencode를 다시 실행합니다 — 같은 export를 ~/.bashrc에 넣으면 계속 유지됩니다.
command not found, PATH export, 그리고 성공하는 재시도4:32에 보기 - 4
Git Bash에서 설치기 재실행 후 확인하기
Git Bash가 기본 프로필이 된 상태에서 curl -fsSL https://opencode.ai/install | bash를 다시 끝까지 실행하세요. npm으로는 npm install -g opencode-ai로 설치할 수 있고, Windows에서는 choco와 scoop도 됩니다. 끝나면 터미널을 다시 열어 갱신된 PATH를 반영하세요.
기본 프로필이 Git Bash인 채 설치 명령어가 다시 실행되는 장면2:30에 보기
검은 화면과 시작 시 크래시
- 5
검은 화면으로 시작되는 증상 알아보기
두 번째 고장 양상: opencode를 입력하면 창 제목은 바뀌는데 본문은 계속 검정 — 배너도 프롬프트도 없습니다. 녹화는 Windows 11에서 바로 이 죽은 창을 보여줍니다. 입력이 문제가 아니라, 디스크의 상태나 멈춘 프로세스가 TUI 렌더링을 막고 있는 것입니다.
opencode 실행 직후 깜깜한 명령 프롬프트 창0:09에 보기 - 6
손상된 데이터 폴더 정리하기
녹화에서 보여준 해결책: OpenCode를 닫고 작업 관리자에서 멈춘 인스턴스를 끝낸 뒤, AppData\Local\share\opencode 데이터 폴더를 삭제합니다(macOS·Linux는 ~/.local/share/opencode). 여기에는 auth.json과 로그, 프로젝트 상태가 들어 있어 이후 다시 인증해야 합니다 — 돌아가는 TUI를 위한 작은 대가입니다.
삭제 전 AppData\Local\share 아래의 opencode 데이터 폴더0:28에 보기 - 7
다시 실행해 TUI가 그려지는지 확인하기
opencode를 다시 실행하세요. 녹화의 다음 장면은 건강한 터미널 UI — 배너, Ask anything 프롬프트, "Run /connect to add an AI provider and start coding" 팁까지. 창이 여전히 어두우면 opencode --print-logs로 실행해 log/ 폴더의 가장 최근 파일에서 실패한 줄을 확인하세요.
상태 정리 후 복원된 OpenCode TUI1:09에 보기
프로바이더·모델·IDE 문제
- 8
전환 전에 무료 한도 메시지 읽기
내장 모델의 쿼터가 바닥나면 세션에 빨간 "Free usage exceeded, subscribe to Go [retrying…]" 배너가 뜨고 반응이 멈춥니다. 크래시가 아닙니다 — 녹화에서는 다른 모델을 고르는 순간 세션이 돌아오므로, 이 메시지를 '9단계로 가라'는 신호로 읽으면 됩니다.
Free usage exceeded 배너와 현재 모델 줄0:36에 보기 - 9
모델 피커를 열어 다른 모델 고르기
세션에서 /models를 실행하거나(셸에서는 opencode models) 연결된 프로바이더가 제공하는 모델을 모두 나열하세요. 녹화에서는 OpenCode Zen 카탈로그에서 Free 표시가 붙은 다른 모델을 고릅니다. /connect로 연결돼 있다면 Claude·GPT·Gemini처럼 자격 증명이 있는 모델은 무엇이든 됩니다.
Free 표시 모델과 프로바이더가 담긴 Select model 피커0:12에 보기 - 10
제안되면 추론 강도 변형도 고르기
일부 모델은 녹화처럼 Default·minimal·medium·high·xhigh 옵션을 담은 두 번째 Select variant 대화상자를 엽니다. 낮은 강도는 더 빠르고 저렴하게 답하고, 까다로운 리팩터링은 high로. 선택은 현재 세션에만 적용되니 부담 없이 실험해 볼 수 있습니다.
minimal부터 xhigh까지 추론 옵션이 담긴 Select variant0:20에 보기 - 11
상태 표시줄에서 전환 확인하기
프롬프트 아래 상태 표시줄은 활성 모델을 알려줍니다 — 녹화에서는 전환 후 Build · Muse Spark 1.2 Free · OpenCode Zen · xhigh로 표시되고, 컨텍스트 패널에는 사용한 토큰과 $0.00 지출이 보입니다. 새 모델에서도 오류가 사라지지 않으면 /connect로 재인증하고 opencode auth list로 확인하세요.
바뀐 모델과 추론 강도를 확인하는 상태 표시줄0:30에 보기 - 12
OpenCode를 VS Code에 연결하기
"VS Code에서 안 됨" 케이스용: 통합 터미널을 열고 opencode를 실행하면 OpenCode 확장이 자동 설치됩니다 — 녹화의 Installed 목록에 opencode for VS Code by SST가 보입니다. 이후 Ctrl+Esc가 분할 터미널에서 OpenCode를 열고, 안 되면 확장 마켓플레이스에서 "OpenCode"를 검색해 수동 설치하세요.
설치된 opencode 확장과 설치기 실행 안내3:02에 보기
그래도 고장이라면? 체크리스트 돌기
위 세 단계에서 증상이 잡히지 않았다면, 남은 고장 패턴들이 여기 있습니다 — 각 항목이 공식 문서와 연결돼 증상이 아니라 원인을 고칠 수 있습니다.
- 1설치 후에도 "인식되지 않음" — 열어 둔 터미널마다 옛 PATH를 갖고 있습니다. 셸을 닫았다 다시 열고, export 줄을 ~/.bashrc에 넣거나(Windows는 시스템 속성에서 PATH 설정) 재시작 후에도 남게 하세요. npm 사용자는 npm의 전역 bin 폴더도 PATH에 있는지 확인하세요.
- 2아예 시작이 안 됨 — opencode --print-logs로 실패를 실시간으로 보고, ~/.local/share/opencode/log/(Windows는 %USERPROFILE%\.local\share\opencode\log)의 최근 로그를 읽으세요. 로그는 최근 10개만 유지되며, 해당되는 건 가장 최근 것입니다. 바이너리가 오래됐다고 의심되면 opencode upgrade를 시도하세요.
- 3ProviderInitError 또는 "invalid or corrupted configuration" — 공식 문서의 처방은 데이터 디렉터리 삭제(rm -rf ~/.local/share/opencode)와 /connect 재인증입니다. 6단계 검은 화면 수리와 같은 처방을 오류 메시지 쪽에서 접근한 것입니다.
- 4세션 중 AI_APICallError — rm -rf ~/.cache/opencode로 프로바이더 패키지 캐시를 지우고 재시작하면 프로바이더 SDK가 다시 설치됩니다. 이후 opencode auth list를 확인하세요. 자격 증명 만료·누락이 두 번째로 흔한 원인입니다.
- 5Windows 데스크톱 앱이 죽음 — WebView2 런타임을 업데이트하고 완전히 종료 후 재실행하며, 커스텀 server.port / OPENCODE_PORT 재정의를 지우세요. 공식 문서는 Windows에서 가장 매끄러운 경험을 위해 WSL을 권하며, 이는 터미널 프로필 문제 대부분도 피해 줍니다.
- 6모델이 전부 안 보임 — /models는 연결한 프로바이더만 나열합니다. /connect로 추가하고 opencode.json에서 카탈로그를 정리하세요: "model": "provider/model-id"를 기본으로 두고, disabled_providers로 프로바이더 전체를 숨기거나, 프로바이더별 허용/차단 목록으로 범위를 좁히세요.
목록을 순서대로 돌면 "opencode 안 됨" 신고 대부분이 해결됩니다: 먼저 PATH, 다음 상태, 마지막으로 프로바이더와 모델. 그래도 안 되면 가장 최근 로그 파일을 준비해 OpenCode 저장소에 이슈를 열어 주세요 — 유지보수자가 원하는 건 로그지 스크린샷이 아닙니다.