컨텐츠로 건너뛰기
쇼케이스 생태계 소스 코드 문서

문제 해결

OpenCode 관련 문제를 디버깅하려면 먼저 로그와 디스크에 저장된 로컬 데이터를 확인하세요.

로그

로그 파일은 다음 위치에 작성됩니다.

  • macOS/Linux: ~/.local/share/opencode/log/
  • Windows: WIN+R을 누르고 %USERPROFILE%\.local\share\opencode\log를 붙여넣으세요.

로그 파일은 타임스탬프 형식으로 명명되며 (예: 2025-01-09T123456.log), 가장 최근 10개의 로그 파일이 유지됩니다.

--log-level 명령줄 옵션으로 로그 레벨을 설정해 더 자세한 디버그 정보를 얻을 수 있습니다. 예를 들어 opencode --log-level DEBUG와 같이 실행합니다.

저장소

opencode는 세션 데이터와 기타 애플리케이션 데이터를 디스크의 다음 위치에 저장합니다.

  • macOS/Linux: ~/.local/share/opencode/
  • Windows: WIN+R을 누르고 %USERPROFILE%\.local\share\opencode를 붙여넣으세요.

이 디렉터리에는 다음이 포함되어 있습니다.

  • auth.json - API 키, OAuth 토큰 등 인증 데이터
  • log/ - 애플리케이션 로그
  • project/ - 세션 및 메시지 데이터 등 프로젝트별 데이터
    • 프로젝트가 Git 저장소 내부에 있으면 ./<project-slug>/storage/에 저장됩니다.
    • Git 저장소가 아니면 ./global/storage/에 저장됩니다.

데스크톱 앱

OpenCode Desktop은 로컬 OpenCode 서버 (opencode-cli 사이드카)를 백그라운드에서 실행합니다. 대부분의 문제는 잘못 동작하는 플러그인, 손상된 캐시, 잘못된 서버 설정 때문에 발생합니다.

빠른 점검

  • 앱을 완전히 종료한 후 다시 실행하세요.
  • 앱이 오류 화면을 표시하면 다시 시작을 클릭하고 오류 세부 정보를 복사하세요.
  • macOS 전용: OpenCode 메뉴 -> Webview 다시 불러오기 (UI가 비어 있거나 멈춰 있을 때 유용).

플러그인 비활성화

데스크톱 앱이 실행 시 충돌하거나 멈추거나 비정상적으로 동작한다면 먼저 플러그인을 비활성화하세요.

전역 설정 확인

전역 설정 파일을 열어 plugin 키를 확인하세요.

  • macOS/Linux: ~/.config/opencode/opencode.jsonc (또는 ~/.config/opencode/opencode.json)
  • macOS/Linux (이전 버전 설치): ~/.local/share/opencode/opencode.jsonc
  • Windows: WIN+R을 누르고 %USERPROFILE%\.config\opencode\opencode.jsonc를 붙여넣으세요.

설정한 플러그인이 있다면 키를 제거하거나 빈 배열로 설정해 일시적으로 비활성화하세요.

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": [],
}

플러그인 디렉터리 확인

OpenCode는 디스크에서 로컬 플러그인을 로드할 수도 있습니다. 다음 위치들을 일시적으로 다른 곳으로 옮기거나 (또는 폴더 이름을 변경) 데스크톱 앱을 재시작하세요.

  • 전역 플러그인
    • macOS/Linux: ~/.config/opencode/plugins/
    • Windows: WIN+R을 누르고 %USERPROFILE%\.config\opencode\plugins를 붙여넣으세요.
  • 프로젝트 플러그인 (프로젝트별 설정을 사용하는 경우에만 해당)
    • <your-project>/.opencode/plugins/

앱이 다시 정상 동작하면 플러그인을 하나씩 다시 활성화해 어떤 플러그인이 문제의 원인인지 찾으세요.

캐시 지우기

플러그인 비활성화로 해결되지 않거나 (또는 플러그인 설치가 멈춘 경우) 캐시를 지워 OpenCode가 다시 빌드할 수 있게 하세요.

  1. OpenCode Desktop을 완전히 종료하세요.
  2. 캐시 디렉터리를 삭제하세요.
  • macOS: Finder -> Cmd+Shift+G -> ~/.cache/opencode를 붙여넣기
  • Linux: ~/.cache/opencode 삭제 (또는 rm -rf ~/.cache/opencode 실행)
  • Windows: WIN+R을 누르고 %USERPROFILE%\.cache\opencode를 붙여넣으세요.
  1. OpenCode Desktop을 다시 시작하세요.

서버 연결 문제 해결

OpenCode Desktop은 자체 로컬 서버를 시작하거나 (기본값) 사용자가 설정한 서버 URL에 연결할 수 있습니다.

“연결 실패” 대화 상자가 표시되거나 (또는 앱이 시작 화면을 지나지 못하는 경우) 사용자 지정 서버 URL이 있는지 확인하세요.

데스크톱 기본 서버 URL 지우기

홈 화면에서 서버 이름 (상태 점이 있는 항목)을 클릭해 서버 선택기를 엽니다. 기본 서버 섹션에서 지우기를 클릭하세요.

설정에서 server.port / server.hostname 제거

opencode.json(c)에 server 섹션이 있다면 일시적으로 제거한 후 데스크톱 앱을 재시작하세요.

환경 변수 확인

환경에 OPENCODE_PORT가 설정되어 있으면 데스크톱 앱은 로컬 서버에 해당 포트를 사용하려고 시도합니다.

  • OPENCODE_PORT를 해제하거나 (또는 사용 가능한 포트를 선택) 재시작하세요.

Linux: Wayland / X11 문제

Linux에서 일부 Wayland 설정은 빈 창이나 컴포지터 오류를 일으킬 수 있습니다.

  • Wayland를 사용 중인데 앱이 비어 있거나 충돌한다면 OC_ALLOW_WAYLAND=1을 설정해 실행해 보세요.
  • 오히려 더 나빠지면 해당 옵션을 제거하고 X11 세션에서 실행해 보세요.

Windows: WebView2 런타임

Windows에서 OpenCode Desktop은 Microsoft Edge WebView2 런타임이 필요합니다. 앱이 빈 창으로 열리거나 시작되지 않으면 WebView2를 설치/업데이트한 후 다시 시도하세요.

Windows: 일반적인 성능 문제

Windows에서 성능이 느리거나 파일 접근, 터미널 문제가 발생한다면 WSL (Windows Subsystem for Linux)을 사용해 보세요. WSL은 OpenCode의 기능과 더 원활하게 동작하는 Linux 환경을 제공합니다.

알림이 표시되지 않음

OpenCode Desktop은 다음 조건이 모두 충족될 때만 시스템 알림을 표시합니다.

  • OS 설정에서 OpenCode의 알림이 활성화되어 있어야 합니다.
  • 앱 창이 포커스되어 있지 않아야 합니다.

데스크톱 앱 저장소 초기화 (최후의 수단)

앱이 시작되지 않고 UI 안에서 설정을 지울 수 없다면 데스크톱 앱의 저장된 상태를 초기화하세요.

  1. OpenCode Desktop을 종료하세요.
  2. 다음 파일을 찾아 삭제하세요 (OpenCode Desktop 앱 데이터 디렉터리에 있습니다).
  • opencode.settings.dat (데스크톱 기본 서버 URL)
  • opencode.global.dat 및 opencode.workspace.*.dat (최근 서버/프로젝트 등 UI 상태)

디렉터리를 빠르게 찾으려면 다음을 참고하세요.

  • macOS: Finder -> Cmd+Shift+G -> ~/Library/Application Support (그런 다음 위 파일명을 검색)
  • Linux: ~/.local/share 아래에서 위 파일명을 검색
  • Windows: WIN+R -> %APPDATA% (그런 다음 위 파일명을 검색)

도움 받기

OpenCode 관련 문제가 발생했다면 다음을 시도해 보세요.

  1. GitHub에 이슈 보고

    버그를 보고하거나 기능을 요청하는 가장 좋은 방법은 GitHub 저장소를 이용하는 것입니다.

    github.com/anomalyco/opencode/issues

    새 이슈를 만들기 전에 기존 이슈를 검색해 같은 문제가 이미 보고되었는지 확인하세요.

  2. Discord 참여

    실시간 도움과 커뮤니티 토론을 위해 Discord 서버에 참여하세요.

    opencode.ai/discord

일반적인 문제

다음은 일반적인 문제와 해결 방법입니다.

OpenCode가 시작되지 않음

  1. 로그에서 오류 메시지 확인
  2. --print-logs 옵션으로 터미널에서 출력 확인
  3. opencode upgrade로 최신 버전인지 확인

인증 문제

  1. TUI에서 /connect 명령으로 다시 인증 시도
  2. API 키가 유효한지 확인
  3. 네트워크가 provider의 API에 연결을 허용하는지 확인

모델을 사용할 수 없음

  1. 해당 provider로 인증했는지 확인
  2. 설정의 모델 이름이 올바른지 확인
  3. 일부 모델은 특정 접근 권한이나 구독이 필요할 수 있음

ProviderModelNotFoundError가 발생한다면 어딘가에서 모델을 잘못 참조하고 있을 가능성이 큽니다. 모델은 <providerId>/<modelId> 형식으로 참조해야 합니다.

예시:

  • openai/gpt-4.1
  • openrouter/google/gemini-2.5-flash
  • opencode/kimi-k2

사용 가능한 모델을 확인하려면 opencode models를 실행하세요.

ProviderInitError

ProviderInitError가 발생한다면 설정이 잘못되었거나 손상되었을 가능성이 큽니다.

해결 방법:

  1. 먼저 providers 가이드에 따라 provider가 올바르게 설정되어 있는지 확인하세요.

  2. 문제가 지속되면 저장된 설정을 지워보세요.

    rm -rf ~/.local/share/opencode

    Windows에서는 WIN+R을 누르고 %USERPROFILE%\.local\share\opencode를 삭제하세요.

  3. TUI에서 /connect 명령으로 provider에 다시 인증하세요.

AI_APICallError 및 provider 패키지 문제

API 호출 오류가 발생한다면 provider 패키지가 오래되었기 때문일 수 있습니다. opencode는 필요에 따라 provider 패키지(OpenAI, Anthropic, Google 등)를 동적으로 설치하고 로컬에 캐시합니다.

provider 패키지 문제를 해결하려면 다음을 시도하세요.

  1. provider 패키지 캐시를 지웁니다.

    rm -rf ~/.cache/opencode

    Windows에서는 WIN+R을 누르고 %USERPROFILE%\.cache\opencode를 삭제하세요.

  2. opencode를 재시작해 최신 provider 패키지를 다시 설치합니다.

이렇게 하면 opencode가 provider 패키지의 최신 버전을 다운로드하며, 이는 모델 파라미터 및 API 변경 사항과의 호환성 문제를 해결하는 경우가 많습니다.

Linux에서 복사/붙여넣기가 동작하지 않음

Linux 사용자는 복사/붙여넣기 기능이 동작하려면 다음 클립보드 유틸리티 중 하나를 설치해야 합니다.

X11 시스템:

apt install -y xclip
# 또는
apt install -y xsel

Wayland 시스템:

apt install -y wl-clipboard

헤드리스 환경:

apt install -y xvfb
# 그리고 다음을 실행:
Xvfb :99 -screen 0 1024x768x24 > /dev/null 2>&1 &
export DISPLAY=:99.0

opencode는 Wayland 사용 여부를 감지해 wl-clipboard를 우선 시도하며, 그렇지 않으면 xclip, xsel 순으로 클립보드 도구를 찾습니다.