10. 자주 만나는 오류와 해결법

연동은 한 번 성공하는 것보다, 문제가 생겼을 때 다시 복구할 수 있는 상태를 만드는 것이 더 중요합니다. 처음에는 오류가 나면 전부 비슷해 보입니다. 로그인도 안 되는 것 같고, 모델도 안 보이는 것 같고, 설정도 다 틀린 것 같고, 캐시도 뭔가 수상합니다.

하지만 실제로는 대부분의 문제를 네 갈래로 나눌 수 있습니다. 인증 문제인지, 모델 지정 문제인지, 설정 병합 문제인지, 아니면 캐시·버전 문제인지만 먼저 가르면 절반은 끝난 셈입니다.¹²

이번 장에서는 초보자가 가장 자주 만나는 대표 이슈를, "증상 → 원인 후보 → 확인 명령 → 해결 순서"로 정리해 보겠습니다. 목표는 단순합니다. 당황하지 않고, 원인 후보를 한 단계씩 줄여 가는 습관을 만드는 것입니다.

문제를 만나면 먼저 어디를 의심해야 할까

오류가 났을 때 가장 먼저 할 일은 설정 파일을 무작정 갈아엎는 것이 아닙니다. 우선 지금 어디서 막혔는지를 잡아야 합니다.

아래 표처럼 생각하면 훨씬 편합니다.

이 표를 머릿속에 넣고 나면 오류 메시지가 더 이상 괴물처럼 보이지 않습니다. 그냥 "어느 칸에 들어가는 문제인가?"를 고르는 퍼즐처럼 보이기 시작합니다.

가장 먼저 해 두면 좋은 3분 진단

문제가 생기면 아래 네 가지를 먼저 확인해 보세요. 이 네 줄만으로도 원인이 꽤 많이 좁혀집니다.¹³

opencode --version
opencode auth ls
opencode models openai
opencode --print-logs --log-level DEBUG

첫 번째 명령은 현재 OpenCode 버전을 보여 줍니다. 버전 호환성 문제를 볼 때 출발점이 됩니다.

두 번째 명령은 인증 정보가 OpenCode 쪽에 저장되어 있는지 확인합니다. openai가 아예 안 보이면, 브라우저에서는 로그인한 것 같아도 실제 저장은 실패했을 가능성이 있습니다.³

세 번째 명령은 OpenCode가 지금 인식하는 OpenAI 모델 이름을 보여 줍니다. 내가 입력한 모델 이름이 틀렸는지 확인할 때 가장 믿을 만한 기준입니다.¹³

네 번째 명령은 화면에 로그를 바로 뿌려 줍니다. 초보자에게 로그는 무서운 검은 벽처럼 느껴지지만, 사실 핵심 단어만 찾으면 됩니다. 403, 401, Model not found, ProviderInitError, Waiting for authorization 같은 문구만 봐도 방향이 잡힙니다.¹

공식 문서 기준으로 OpenCode 로그는 보통 ~/.local/share/opencode/log/에 저장되고, 인증 정보는 ~/.local/share/opencode/auth.json에 저장됩니다.¹³

코드 실습: 내 환경 상태를 한 번에 보는 진단 스크립트

초보자라면 매번 명령을 따로 치는 대신, 작은 진단 스크립트 하나를 만들어 두면 좋습니다. 아래 코드를 opencode-doctor.sh로 저장해 보세요.

#!/usr/bin/env bash
set -e

echo "== OpenCode Doctor =="

echo
printf "[1] Versionn"
opencode --version || true

echo
printf "[2] Auth Providersn"
opencode auth ls || true

echo
printf "[3] OpenAI Models (first 30 lines)n"
opencode models openai 2>/dev/null | head -n 30 || true

echo
printf "[4] Port 1455 Checkn"
if command -v lsof >/dev/null 2>&1; then
  lsof -i :1455 || echo "Nothing is listening on 1455"
else
  echo "lsof not installed; skip port check"
fi

echo
printf "[5] OpenCode Pathsn"
echo "Auth file: $HOME/.local/share/opencode/auth.json"
echo "Logs dir : $HOME/.local/share/opencode/log/"
echo "Cache dir: $HOME/.cache/opencode"

실행 권한을 주고 실행합니다.

chmod +x opencode-doctor.sh
./opencode-doctor.sh

이 스크립트는 화려하진 않지만 꽤 든든합니다. 적어도 "버전이 뭔지, 인증이 있는지, 모델이 보이는지, 1455 포트가 이상한지"는 한 번에 확인할 수 있습니다. 디버깅의 절반은 사실 대단한 기술이 아니라 현재 상태를 잘 보는 것입니다.

오류 1. 브라우저에서는 성공처럼 보이는데 터미널은 계속 기다린다

이 증상은 초보자가 가장 당황하는 장면 중 하나입니다. 브라우저에서는 승인도 끝났고 화면도 그럴듯합니다. 그런데 터미널은 여전히 기다리는 상태입니다. 특히 원격 환경이나 콜백이 꼬인 상황에서 자주 보입니다.²

이럴 때는 보통 세 가지를 먼저 의심하면 됩니다.

첫째는 브라우저와 OpenCode가 같은 컴퓨터에서 돌고 있는지입니다. 로컬 PC에서는 자동 콜백이 잘 되지만, SSH·WSL·원격 서버에서는 브라우저와 터미널이 서로 다른 곳에 있기 때문에 자동 복귀가 실패하기 쉽습니다. 이런 환경에서는 Manual URL Paste 방식이 더 안정적입니다.²

둘째는 오래된 로그인 링크를 다시 쓴 경우입니다. OAuth 승인 세션은 계속 유지되지 않습니다. 새로 opencode auth login을 다시 실행해서 새 링크를 받아야 할 때가 많습니다.²

셋째는 로컬 콜백 포트 충돌입니다. 플러그인 문서 기준으로 OAuth 콜백에 localhost:1455가 사용되며, 다른 프로세스가 같은 포트를 쓰고 있으면 흐름이 꼬일 수 있습니다.²

해결 순서는 이렇게 가면 됩니다.

1. 원격 환경이면 자동 콜백을 고집하지 말고 Manual URL Paste로 바꿉니다.

2. opencode auth login을 새로 시작해 새 URL을 받습니다.

3. 아래 명령으로 1455 포트를 누가 쓰는지 확인합니다.

lsof -i :1455

중요한 것은 "로그인 흐름 중에 이상한 다른 프로세스가 계속 붙어 있지 않은지"를 확인하는 것입니다.

오류 2. 토큰 교환 단계에서 403이 나온다

이 메시지는 꽤 얄밉습니다. 브라우저 로그인까지는 멀쩡해 보이는데, 마지막 토큰 교환 단계에서 갑자기 실패하기 때문입니다.²

이 오류를 보면 흔히 "내 컴퓨터 문제인가?"부터 떠올리지만, 꼭 그렇지는 않습니다. 오히려 아래 순서로 보는 편이 현실적입니다.

먼저 ChatGPT Plus 또는 Pro 구독 상태를 확인하세요. 이 플러그인은 해당 구독을 전제로 동작합니다. 구독 만료, 결제 문제, 계정 제한이 있으면 브라우저 인증 화면은 끝났더라도 실제 토큰 발급에서 막힐 수 있습니다.²

그다음은 승인 세션이 이미 오래되었는지를 봐야 합니다. 브라우저 탭을 오래 열어 둔 뒤 나중에 다시 승인하면, 마지막 교환 단계에서 실패하는 경우가 있습니다. 새로 opencode auth login을 시작하고 새 링크로 다시 진행해 보세요.²

간단한 해결 순서는 이렇습니다.

opencode auth logout
opencode auth login
opencode auth ls

여기서 중요한 포인트는 "브라우저에 성공 문구가 떴다"와 "토큰 교환이 실제로 성공했다"는 같은 말이 아니라는 점입니다.

오류 3. 처음엔 됐는데 나중에 401 또는 refresh 실패가 난다

이 오류는 "처음 로그인은 됐는데, 조금 쓰다 보니 갑자기 죽는" 타입입니다. 보통 저장된 인증 정보가 만료된 뒤 자동 갱신에 실패한 상황으로 이해하면 됩니다.²

초보자 입장에서는 너무 깊게 파고들기보다 재인증이 가장 빠른 복구법이라고 기억하는 편이 좋습니다.

아래 순서로 정리해 보세요.

opencode auth logout
opencode auth login
opencode auth ls

그리고 인증 저장소가 실제로 있는지도 가볍게 확인합니다.

ls -l ~/.local/share/opencode/auth.json

핵심은 토큰 내용을 읽는 것이 아니라, 재로그인 후 OpenCode가 인증 상태를 다시 인식하는지를 확인하는 것입니다.

오류 4. Model not found, ProviderModelNotFoundError

이 오류는 생각보다 단순한 실수에서 많이 나옵니다. 공식 트러블슈팅 문서도 모델을 항상 <providerId>/<modelId> 형식으로 적어야 한다고 설명합니다. 즉, gpt-5.2가 아니라 openai/gpt-5.2처럼 써야 합니다.¹

또 하나 자주 틀리는 부분은 표시 이름과 실제 모델 키를 혼동하는 것입니다. CLI와 내부 조회에 중요한 것은 보기 좋은 이름이 아니라 모델 key입니다.²

여기에 modern/legacy 혼동이 겹치면 더 헷갈립니다. 예를 들어 modern 환경에서는 openai/gpt-5.2 --variant=medium처럼 쓰는데, legacy 환경에서는 openai/gpt-5.2-medium처럼 모델 이름 자체가 달라질 수 있습니다. 둘을 섞어 쓰면 모델이 없는 것처럼 보입니다.²

이럴 때는 기억을 믿지 말고, 아래 명령을 믿으세요.

opencode models openai

필요하면 모델 캐시를 새로고침합니다.

opencode models --refresh

그리고 내가 쓰려는 문자열이 목록에 정확히 있는지 확인합니다. 철자 하나, 하이픈 하나 차이로도 실패합니다.

오류 5. 설정 파일이 맞는 것 같은데 반영이 안 된다

이 문제는 초보자에게 특히 교묘합니다. 파일을 분명히 고쳤는데도 OpenCode가 말을 안 듣습니다. 이럴 때는 "왜 설정이 무시되지?"라고 생각하기 쉬운데, 실제로는 무시된 것이 아니라 다른 설정이 위에서 덮어쓴 것일 수 있습니다.⁴

OpenCode 설정은 하나만 읽지 않고, 여러 위치의 설정을 병합합니다. 전역 설정, 사용자 지정 경로, 프로젝트 설정, 인라인 설정 등이 순서대로 합쳐지고, 나중 레이어가 앞 레이어를 override합니다.⁴

이 문제를 볼 때는 아래를 차례로 확인하세요.

첫째, 파일 경로가 맞는지 봅니다. 전역 설정은 보통 ~/.config/opencode/opencode.json 또는 .jsonc입니다.⁴

둘째, JSON 문법이 맞는지 봅니다. 주석을 쓰고 싶다면 .jsonc를 써야 합니다. .json 파일에 주석을 넣으면 파싱 단계에서 문제를 만들 수 있습니다.

셋째, 프로젝트 루트에 opencode.json이 있는지 확인합니다. 있으면 그 파일이 전역보다 강합니다.⁴

넷째, provider나 plugin 관련 변경은 완전 재시작이 필요한 경우가 많습니다. 파일만 저장하고 열린 세션을 그대로 두면 "왜 안 바뀌지?"라는 착시가 생깁니다.¹⁵

아래 스크립트는 현재 흔히 쓰이는 설정 위치를 빠르게 훑어봅니다. inspect-opencode-configs.mjs로 저장해 보세요.

import fs from "node:fs";
import os from "node:os";
import path from "node:path";

const home = os.homedir();
const files = [
  path.join(home, ".config", "opencode", "opencode.jsonc"),
  path.join(home, ".config", "opencode", "opencode.json"),
  path.join(process.cwd(), "opencode.json"),
];

for (const file of files) {
  if (!fs.existsSync(file)) continue;
  const text = fs.readFileSync(file, "utf8");
  console.log(`n== ${file} ==`);
  console.log("plugin key:", text.includes("\"plugin\"") ? "yes" : "no");
  console.log("openai key:", text.includes("\"openai\"") ? "yes" : "no");
  console.log("model key:", text.includes("\"model\"") ? "yes" : "no");
}

실행합니다.

node inspect-opencode-configs.mjs

이 스크립트는 완벽한 파서는 아니지만, 최소한 "어디에 설정 파일이 있고, 어느 파일이 OpenAI나 model 키를 들고 있는지"는 빨리 보여 줍니다.

오류 6. 플러그인 캐시가 꼬였거나 패키지가 오래됐다

OpenCode는 플러그인과 provider 관련 패키지를 캐시에 저장합니다. 공식 트러블슈팅 문서도 이상한 API 호출 오류나 플러그인 문제를 의심할 때 ~/.cache/opencode 삭제 후 재시작을 권장합니다.¹

이 문제의 특징은 이렇습니다. 설정은 맞는 것 같고, 인증도 있는 것 같은데, 요청만 이상하게 실패합니다. 어제는 됐는데 오늘 갑자기 안 되기도 합니다. 이럴 때는 캐시를 한번 비워 보는 편이 좋습니다.

rm -rf ~/.cache/opencode

그다음 OpenCode를 완전히 종료하고 다시 시작합니다.

opencode

플러그인 자체를 잠시 의심해 보고 싶다면, 전역 설정의 plugin 배열을 잠깐 비우거나 문제의 플러그인만 제거해 재시작해 볼 수 있습니다. 또 로컬 플러그인 디렉터리인 ~/.config/opencode/plugins/ 또는 프로젝트의 .opencode/plugins/ 안에 실험용 파일이 남아 있지 않은지도 같이 확인하세요.¹⁵

코드 실습: 캐시 초기화 전에 안전하게 현재 상태 백업하기

캐시 삭제 자체는 비교적 안전하지만, 초보자라면 로그와 설정 정도는 먼저 남겨 두는 습관이 좋습니다.

아래를 backup-before-reset.sh로 저장하세요.

#!/usr/bin/env bash
set -e
STAMP=$(date +%Y%m%d-%H%M%S)
OUT="$HOME/opencode-debug-backup-$STAMP"
mkdir -p "$OUT"

cp -R "$HOME/.config/opencode" "$OUT/config" 2>/dev/null || true
cp -R "$HOME/.local/share/opencode/log" "$OUT/log" 2>/dev/null || true
cp "$HOME/.local/share/opencode/auth.json" "$OUT/auth.json" 2>/dev/null || true

echo "Backup saved to: $OUT"
echo "주의: auth.json에는 민감한 정보가 있을 수 있으니 외부 공유 전 반드시 마스킹하세요."

실행합니다.

chmod +x backup-before-reset.sh
./backup-before-reset.sh

그다음에 캐시를 지워도 됩니다.

rm -rf ~/.cache/opencode

오류 7. 버전 호환성 문제

이 문제는 은근히 흔합니다. 특히 이 책처럼 OpenCode 본체와 외부 플러그인이 함께 움직이는 구조에서는, 둘 중 하나만 앞서가거나 뒤처져도 이상한 현상이 생길 수 있습니다.

대표적인 체크 포인트는 두 가지입니다.

하나는 내 OpenCode 버전에 맞는 설정 형식을 쓰고 있는지입니다. 앞 장에서 본 것처럼 modern과 legacy 구성은 다릅니다. 버전에 맞지 않는 Full Config를 쓰면 모델 인식이나 옵션 적용이 미묘하게 꼬일 수 있습니다.²⁴

다른 하나는 플러그인 자체가 최신 상태인지입니다. 이미 고쳐진 버그를 예전 버전에서 계속 겪고 있을 수도 있기 때문입니다.

그래서 버전 문제는 아래 순서가 좋습니다.

opencode --version
opencode upgrade
npx -y opencode-openai-codex-auth@latest

업데이트 후에는 반드시 OpenCode를 완전히 종료하고 다시 시작하세요. 특히 플러그인, provider, config 관련 변경은 재시작이 빠지면 효과가 반쯤만 보일 수 있습니다.¹⁵

오류 8. 사용량 제한 메시지, rate limit, context 초과

연동이 제대로 됐는데도 요청이 막힐 수 있습니다. 이때는 "연결 실패"가 아니라 "사용량 또는 요청 조건 문제"일 가능성이 큽니다.²

이 세 경우는 각각 다르게 보면 됩니다.

사용량 제한 메시지는 계정 사용량 창이 리셋될 때까지 기다리는 수밖에 없는 경우가 많습니다. 이건 설정 문제가 아닙니다.

rate limit은 일시적일 수 있으므로, 잠시 기다렸다가 다시 시도하거나 더 가벼운 모델로 바꾸는 편이 좋습니다.

context 초과는 대화가 너무 길어진 경우가 많으니, 새 세션을 시작하거나 더 짧은 작업 단위로 나눠 요청하는 편이 좋습니다. reasoning 강도와 설명 길이를 낮추는 것도 토큰 사용량을 줄이는 데 도움이 됩니다.²

예를 들어 아래처럼 가볍게 바꿔 볼 수 있습니다.

{
  "provider": {
    "openai": {
      "options": {
        "reasoningEffort": "low",
        "textVerbosity": "medium",
        "store": false
      }
    }
  }
}

물론 이 설정도 기존 Full Config 구조 안에서 신중하게 override해야 합니다. 핵심은 "오류가 났으니 아무 옵션이나 바꾸자"가 아니라, 토큰을 많이 먹는 축을 줄여 보자는 방향입니다.

로그를 읽을 때 꼭 봐야 하는 두 군데

문제가 계속되면 결국 로그를 봐야 합니다. 다행히 모든 로그를 이해할 필요는 없습니다. 초보자는 두 군데만 보면 충분합니다.

하나는 OpenCode 기본 로그입니다. 공식 문서 기준으로 ~/.local/share/opencode/log/에 저장됩니다.¹

다른 하나는 플러그인 디버그 로그입니다. 플러그인 문서 기준으로 DEBUG_CODEX_PLUGIN=1을 켜면 콘솔에서 모델 해석과 설정 적용 상태를 더 자세히 볼 수 있습니다.²

예를 들어 이렇게 실행해 볼 수 있습니다.

DEBUG_CODEX_PLUGIN=1 opencode run "test" --model=openai/gpt-5.2

더 자세한 요청 로그가 필요하면 플러그인 문서에서 안내하는 환경 변수를 함께 사용할 수 있습니다.²

DEBUG_CODEX_PLUGIN=1 ENABLE_PLUGIN_REQUEST_LOGGING=1 opencode run "test" --model=openai/gpt-5.2

여기서 보고 싶은 핵심은 많지 않습니다. 모델 이름이 어떻게 해석됐는지, 모델별 옵션이 실제로 잡혔는지, 요청 직전에 무슨 에러가 터졌는지만 보면 됩니다.

그래도 안 풀릴 때: 문제 제보용 체크리스트

정말 안 풀릴 때는 GitHub 이슈나 커뮤니티에 질문해야 할 수 있습니다. 이때 "안 돼요" 한 줄만 올리면 답을 받기 어렵습니다. 대신 아래 정보가 있으면 훨씬 빨리 도움을 받을 수 있습니다.¹²

• OpenCode 버전

• 플러그인 버전

• 운영체제

• 정확한 오류 문구

• 재현 순서

• 민감 정보를 지운 config 일부

• 로그 일부

특히 auth.json이나 실제 토큰, API 키는 절대 그대로 올리면 안 됩니다. 디버깅은 중요하지만, 계정은 더 중요합니다.

초보자를 위한 실전 복구 루틴

이제 마지막으로, 실제 현장에서 가장 쓸모 있는 순서를 정리해 보겠습니다. 문제를 만나면 아래처럼만 움직여도 훨씬 덜 흔들립니다.

먼저 opencode --version, opencode auth ls, opencode models openai로 현재 상태를 확인합니다.¹³

그다음 증상이 인증 쪽이면 opencode auth logout 후 opencode auth login으로 재인증합니다. 원격 환경이라면 자동 콜백 대신 Manual URL Paste를 우선 고려합니다.²

모델 오류면 provider/model 형식과 실제 model key를 다시 확인합니다. modern/legacy 혼용도 같이 점검합니다.¹²

설정 문제 같으면 전역 파일과 프로젝트 파일이 병합되고 있는지, .json에 주석을 넣지 않았는지, 재시작을 했는지 확인합니다.⁴

그래도 이상하면 ~/.cache/opencode를 지우고 재시작합니다. 필요하면 플러그인도 최신으로 다시 설치합니다.¹⁵

마지막으로, 정말 애매한 경우에는 디버그 로그를 켜서 모델 해석과 요청 직전 에러를 확인합니다.²

이 순서가 좋은 이유는 간단합니다. 가장 값싼 확인부터 시작해서, 가장 무거운 초기화는 뒤로 미루기 때문입니다. 디버깅도 결국 체력전이라, 순서가 곧 실력입니다.

이번 장에서 꼭 기억할 것

문제가 생겼을 때 가장 중요한 것은 "무엇이든 많이 해보는 것"이 아니라, 원인 후보를 줄이는 순서를 지키는 것입니다. 로그인 문제는 브라우저 성공 화면만 보지 말고 실제 인증 저장과 콜백 흐름을 봐야 합니다.² 모델 오류는 이름을 감으로 쓰지 말고 opencode models openai 결과를 기준으로 봐야 합니다.¹³ 설정 문제는 파일 하나가 아니라 병합 구조 전체를 봐야 하고, 이상한 API 오류는 캐시와 버전 호환성도 함께 의심해야 합니다.⁴⁵

초보자에게 가장 강력한 무기는 천재적인 직감이 아닙니다. 같은 순서로 점검하는 습관입니다. 그 습관이 생기면, 연동은 한 번 성공하는 이벤트가 아니라 오래 굴러가는 작업 환경이 됩니다.

참고

¹문제 해결 | OpenCode

²Troubleshooting Guide | OpenCode Codex Auth Plugin

³CLI | OpenCode

⁴Config | OpenCode

⁵플러그인 | OpenCode