본문으로 건너뛰기

문제 해결

준비 실패, 진단 복사, doctor 점검을 다룹니다.

이 페이지

어느 단계에서 문제가 생겼는지 먼저 확인하고, 해결되지 않으면 진단 정보를 모아 보고합니다.

Butler Agent를 준비하지 못할 때

첫 실행의 설치 단계에서 Butler Agent를 준비하지 못했습니다. 메시지가 표시되면 다음 순서로 시도합니다.

  1. 다시 시도를 누릅니다. Agent 상태를 처음부터 다시 확인합니다.
  2. 같은 오류가 반복되면 복구를 누릅니다. 앱에 포함된 Agent를 멈췄다가 다시 시작한 뒤 상태를 확인합니다.
  3. 그래도 실패하면 진단 복사를 눌러 진단 정보를 클립보드에 복사합니다. 문제를 보고할 때 이 내용을 붙여 넣습니다.
  4. 지금 해결하기 어렵다면 종료로 앱을 닫습니다.

진단 정보 읽기

복사한 진단 정보는 JSON 형식이며 checks에 점검 항목이 순서대로 들어 있습니다. 상태가 failed인 첫 항목이 준비가 멈춘 지점입니다.

  • Butler Agent 실행
  • Butler Agent 연결
  • Agent 버전 확인
  • 로컬 인증 확인
  • 상태 확인
  • 프로토콜 확인
  • Electron 연결 확인

errors의 code가 bundled_agent_version_missing이면 앱 패키지에서 Agent 버전을 읽지 못했다는 뜻입니다. GitHub Releases에서 네이티브 Agent가 포함된 최신 DMG를 받아 앱을 다시 설치합니다.

진단 정보에서는 토큰, 비밀값, 사용자 경로가 가려지고 스택 트레이스와 표준 출력 원문은 빠집니다.

앱이 열리지 않을 때

Butler 앱은 Apple 공증을 거치지 않아 처음 열 때 macOS가 실행을 막을 수 있습니다. 시스템 설정 → 개인정보 보호 및 보안에서 그래도 열기를 선택합니다.

모델 연결 문제

모델 목록을 불러오지 못할 때

  • 첫 실행의 모델 단계에서 모델 목록을 불러오지 못했습니다. 메시지가 나오면 다시 불러오기를 누릅니다.
  • 입력창의 모델 선택에 모델 상태 오류가 표시되면 설정 → 모델에서 기본 모델과 연결 상태를 확인합니다.
  • 선택한 모델 사용 불가가 표시되면 다른 모델을 고릅니다.

응답이 실패할 때

대화에 응답 처리 중 문제가 발생했습니다. 메시지가 표시되면 아래 버튼으로 다시 시도합니다.

  • 원래 설정으로 다시 시도: 실패한 요청을 원래 모델과 설정으로 다시 보냅니다.
  • 현재 설정으로 새로 시도: 지금 선택한 모델과 설정으로 새로 보냅니다. 모델을 바꾼 뒤에 씁니다.

같은 모델이 자주 응답하지 않으면 설정 → 모델의 예비·정리 모델에서 예비 모델 사용을 켜고 예비 모델 추가로 이어받을 모델을 등록합니다. 자세한 내용은 예비 모델을 참고합니다.

OAuth 로그인이 끝나지 않을 때

설정 → 모델 → 모델 관리에서 OAuth로 모델을 추가할 때 로그인이 끝나지 않으면 다음 순서로 확인합니다.

  1. 브라우저가 열리지 않으면 링크 복사를 눌러 브라우저에 직접 붙여 넣습니다.
  2. 브라우저에서 인증을 마친 뒤 Butler로 돌아와 인증 완료 확인을 누릅니다.
  3. OAuth 인증이 완료되지 않았습니다. 메시지가 표시되면 다시 인증을 누릅니다.

OAuth 로그인은 http://localhost:1455/auth/callback으로 결과를 받습니다. 다른 프로그램이 1455번 포트를 쓰고 있으면 로그인을 마칠 수 없으므로, 그 프로그램을 종료한 뒤 다시 인증합니다.

연결이 끊겼다고 표시될 때

실시간 연결이 끊겨 다시 연결하고 있습니다. 표시된 작업 상태는 최신이 아닐 수 있습니다. 안내가 표시되면 Butler가 자동으로 다시 연결합니다. 오래 지속되면 Butler를 종료하고 다시 엽니다.

앱에 포함된 Agent는 Butler가 열려 있는 동안에만 실행됩니다.

화면에 오류가 표시될 때

버틀러 화면에 오류가 발생했습니다. 메시지가 표시되면 창을 새로고침하거나 Butler를 다시 엽니다.

Git 안내가 표시될 때

입력창에 Git이 설치되어 있지 않습니다 안내가 표시되면 Butler는 계속 쓸 수 있지만 브랜치, 커밋, Ledger 커밋 증거 기능은 쓸 수 없습니다. Git 설치 안내를 눌러 Git을 설치합니다.

업데이트 문제

macOS에서는 앱 업데이트가 자동으로 설치되지 않습니다. 새 버전의 DMG를 받아 직접 설치합니다.

  1. 설정 → 업데이트에서 확인을 누릅니다.
  2. 새 버전이 있으면 버틀러 항목에 현재 버전과 새 버전이 표시됩니다. 업데이트를 누르면 새 버전의 DMG를 내려받아 엽니다.
  3. Butler를 종료하고, 열린 DMG에서 Butler.app을 응용 프로그램 폴더로 끌어다 놓아 기존 앱을 바꿉니다.
  4. 업데이트 확인 실패나 업데이트 적용 실패가 반복되면 GitHub Releases에서 최신 DMG를 받아 다시 설치합니다.

버틀러 항목 아래에는 앱에 포함된 Agent 버전(Butler Agent <버전>)도 표시됩니다.

standalone Agent는 butler update --check로 새 버전을 확인합니다. butler update --apply --yes는 아카이브를 데이터 폴더에 내려받아 두기만 하므로, 설치는 Butler Agent CLI의 절차대로 직접 합니다.

알림이 오지 않을 때

  1. 설정 → 일반 → 알림 권한에서 OS 알림 상태를 확인합니다.
  2. 테스트를 눌러 테스트 알림을 보냅니다.
  3. 알림이 보이지 않으면 macOS 알림 설정을 눌러 시스템 설정에서 Butler 알림을 허용합니다.

로그 확인

앱의 개발자 로그

개발자 로그에서는 모델 요청 컨텍스트 조립 결과와 응답 원문을 모델 턴 단위로 볼 수 있습니다.

  1. 설정 → 정보의 개발자 영역에서 개발자 모드를 켭니다.
  2. 설정 목록의 앱 및 시스템 그룹에 로그가 나타나면 엽니다.
  3. 필터에서 실패한 모델 턴을 고르면 실패한 요청만 볼 수 있습니다.
  4. 항목을 열어 컨텍스트, 요청, 응답, 메타데이터 탭을 확인합니다.

검색창으로 모델, 세션, 섹션, 응답 내용을 찾거나 세션 ID로 걸러 볼 수 있습니다. 개발자 모드를 켜면 이 앱 창에서 Chrome DevTools도 열 수 있습니다.

개발자 로그는 설정 → 개인정보의 진단이 켜져 있을 때만 기록되며, 데이터 폴더의 app/developer-logs/model-turns.jsonl에 저장됩니다. 진단을 끄면 로그 항목도 사라집니다.

개발자 로그에는 대화 내용이 담긴 요청과 응답 원문이 포함될 수 있습니다. 다른 사람에게 공유하기 전에 내용을 확인합니다.

standalone Agent의 서비스 로그

butler start로 실행한 서비스의 로그는 데이터 폴더(기본값 ~/.butler)의 logs/butler-agent-service.stdout.log와 logs/butler-agent-service.stderr.log에 기록됩니다.

bash
butler logs --lines 200
butler logs --follow

doctor로 설치 점검

standalone Agent는 butler doctor로 설치 상태를 점검합니다. 읽기 전용이며 문제를 고치지는 않습니다. 점검 범위는 Butler Agent CLI를 참고합니다.

bash
butler doctor
butler doctor --check installation

결과가 degraded이면 FAIL이나 WARN으로 표시된 항목을 확인합니다. 서비스가 실행 중이 아니면 서비스 항목이 WARN이 되므로, 설치만 확인할 때는 --check installation을 씁니다.

자주 보는 오류와 해결 방법입니다.

  • butler_data_overlaps_installation: 데이터 폴더가 설치 폴더와 겹칩니다. 설치 폴더 밖의 다른 폴더를 --data로 지정합니다.
  • --home is unsupported: --home 대신 --data를 씁니다.
  • native_home_unavailable: HOME 환경 변수가 비어 있습니다. MCP 클라이언트에서 실행할 때 자주 생깁니다.
  • update --apply requires --yes: 업데이트 적용에는 --yes를 함께 붙입니다.

다시 설치하기

앱

  1. Butler를 종료합니다.
  2. GitHub Releases에서 최신 butler-app-<버전>-darwin-arm64.dmg를 내려받습니다.
  3. DMG를 열고 Butler.app을 응용 프로그램 폴더로 끌어다 놓아 기존 앱을 바꿉니다.

대화와 기억, Agent 설정은 앱이 아니라 데이터 폴더(~/.butler)에 저장되므로 앱을 다시 설치해도 유지됩니다.

standalone Agent

새 버전 폴더에 다시 설치합니다. 기존 설치 폴더는 수정하지 않습니다. 기존 데이터와 분리된 상태로 확인하려면 --data로 비어 있는 새 폴더를 지정해 실행합니다. 기존 DATA 폴더는 그대로 남습니다.

문제 보고

해결되지 않는 문제는 GitHub Issues에 새 이슈로 보고합니다. Butler 저장소는 설정 → 정보의 GitHub 저장소에서도 열 수 있습니다. 보고할 때 다음을 함께 적으면 원인을 찾기 쉽습니다.

  • 설정 → 정보의 버전
  • macOS 버전과 Mac 칩 종류
  • 문제가 생기기까지의 순서
  • 첫 실행 준비 실패라면 진단 복사 결과
  • standalone Agent라면 butler version --json과 butler doctor --json 출력

진단 복사와 doctor 출력은 비밀값을 가리지만, 로그나 대화 내용을 첨부할 때는 올리기 전에 직접 확인합니다.

자주 묻는 질문

창을 닫으면 Agent도 멈추나요?

앱에 포함된 Agent는 Butler가 열려 있는 동안에만 실행됩니다. 설정 → 일반의 트레이 및 메뉴바에 표시를 켜면 창을 닫아도 앱이 메뉴바에 남습니다.

데이터는 어디에 저장되나요?

데이터 폴더인 ~/.butler에 저장됩니다. 설정은 butler.config.json, 클라우드 모델 API 키는 auth/model-provider-credentials.json, 웹 검색 API 키 같은 그 밖의 비밀값은 .env에 있습니다. 자세한 위치는 클라우드 모델을 참고합니다.

대화 내용이 외부로 전송되나요?

클라우드 모델을 쓰거나 사용자 정보 분석을 켜면 요청에 필요한 프롬프트, 컨텍스트, 프로필 후보 텍스트가 설정한 모델 제공자로 전송될 수 있습니다. 처리 내용을 기기 안에만 두려면 로컬 모델을 Custom 모델로 연결해 씁니다.

Windows나 Linux에서 쓸 수 있나요?

현재 릴리스는 Apple Silicon Mac용으로만 패키징하고 검증합니다. Windows와 Linux용 네이티브 Agent 번들은 아직 지원하지 않습니다.

이전 버전을 설치했는데 준비가 계속 실패합니다.

이전 릴리스에는 지금은 쓰지 않는 TypeScript/Bun Agent가 들어 있을 수 있습니다. 네이티브 Agent가 포함된 최신 릴리스로 다시 설치합니다.

관련 문서

설치GitHub Releases에서 Butler 앱을 내려받아 설치하고 처음 실행합니다.Butler Agent CLI앱 없이 헤드리스 런타임을 설치하고 명령줄로 다룹니다.예비 모델기본 모델을 쓸 수 없을 때 이어받을 모델의 순서를 정합니다.