한국어
문서
문제 해결

문제 해결

일반적인 문제와 해결 방법.

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 사이드카)를 실행합니다. 대부분의 문제는 오작동하는 플러그인, 손상된 캐시 또는 잘못된 서버 설정으로 인해 발생합니다.

빠른 확인

  • 앱을 완전히 종료하고 다시 실행하세요.
  • 앱에 오류 화면이 표시되면 Restart를 클릭하고 오류 세부 정보를 복사하세요.
  • macOS 전용: OpenCode 메뉴 -> Reload 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에 연결할 수 있습니다.

Connection Failed 대화 상자가 표시되거나 (앱이 스플래시 화면을 지나지 못하는 경우) 사용자 정의 서버 URL을 확인하세요.

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

홈 화면에서 서버 이름(상태 점이 있는)을 클릭하여 서버 선택기를 엽니다. Default server 섹션에서 Clear를 클릭하세요.

설정에서 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 Runtime이 필요합니다. 앱이 빈 창으로 열리거나 시작되지 않으면 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 (opens in a new tab)

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

  2. Discord 참여

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

    opencode.ai/discord (opens in a new tab)

일반적인 문제

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

OpenCode가 시작되지 않음

  • 로그에서 오류 메시지 확인
  • --print-logs로 실행하여 터미널에서 출력 확인
  • opencode upgrade로 최신 버전인지 확인

인증 문제

  • TUI에서 /connect 명령으로 재인증 시도
  • API 키가 유효한지 확인
  • 네트워크가 프로바이더의 API에 연결을 허용하는지 확인

모델 사용 불가

  • 프로바이더로 인증했는지 확인
  • 설정의 모델 이름이 올바른지 확인
  • 일부 모델은 특정 접근 권한이나 구독이 필요할 수 있음

ProviderModelNotFoundError가 발생하면 어딘가에서 모델을 잘못 참조하고 있을 가능성이 높습니다. 모델은 다음과 같이 참조해야 합니다: <providerId>/<modelId>

예:

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

접근 가능한 모델을 확인하려면 opencode models를 실행하세요

ProviderInitError

ProviderInitError가 발생하면 유효하지 않거나 손상된 설정이 있을 가능성이 높습니다.

해결하려면:

  1. 먼저 프로바이더 가이드를 따라 프로바이더가 올바르게 설정되었는지 확인하세요

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

    rm -rf ~/.local/share/opencode

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

  3. TUI에서 /connect 명령으로 프로바이더와 재인증하세요.

AI_APICallError 및 프로바이더 패키지 문제

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

프로바이더 패키지 문제를 해결하려면:

  1. 프로바이더 패키지 캐시 지우기:

    rm -rf ~/.cache/opencode

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

  2. opencode를 다시 시작하여 최신 프로바이더 패키지 재설치

이렇게 하면 opencode가 최신 버전의 프로바이더 패키지를 다운로드하도록 강제하여 모델 매개변수 및 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 순서로 클립보드 도구를 찾으려고 합니다.

엔터프라이즈Windows (WSL)