문제 해결

먼저 mu doctor를 실행하세요. 세션 안에서는 /doctor예요. 설치, 모델, 판정기, 연결 상태를 점검하고 무엇을 고칠지 알려 줘요. 데스크톱 앱에서는 설정 → 정보에서 클릭 한 번으로 로그를 볼 수 있어요.

그래도 해결되지 않으면 버전, 플랫폼, mu doctor 출력을 적어서 이슈를 열어 주세요.

설치와 시작

mu needs Node >= 22.19 (found v20…). 명령줄에는 Node.js 22.19 이상이 필요해요. nvm install 24를 실행하거나 시스템 패키지를 설치하세요. 데스크톱 앱은 자체 Node를 담고 있어서 아무것도 필요 없어요.

Windows에서 SmartScreen 경고가 떠요. Windows 빌드는 아직 코드 서명이 없어요. 추가 정보를 누른 다음 실행을 누르세요. 모든 다운로드의 체크섬은 릴리스 페이지의 SHA256SUMS에 있어요.

Windows: 대화에서 Git for Windows가 없다고 해요. mu는 Windows에서 POSIX 셸로 명령을 실행해요. Git for Windows를 설치하고 새 대화를 시작하세요.

C:\Program Files\mu에 설치한 앱이 mu를 시작하지 못해요. 0.1.5에서 고쳤어요. 최신 릴리스를 기존 설치 위에 설치하세요. 데이터는 그대로 남아요.

mu install, mu list, mu config가 대신 세션을 시작해요. 데스크톱 0.1.7 / mu-agent 0.1.8 이후에 고쳤고, 다음 릴리스에 들어가요.

모델과 네트워크

모델이 설정되어 있지 않아요. mu setup이나 앱의 설정 가이드를 실행하세요. API 키를 붙여 넣거나 구독으로 로그인하면 돼요.

터미널에서는 괜찮은데 앱에서만 "User location is not supported"가 뜨거나 요청이 시간 초과돼요. 모델 서비스가 여러분 네트워크의 지역을 거부하거나, 앱이 프록시를 보지 못하는 거예요. 0.1.5부터 앱은 HTTPS_PROXY가 설정되어 있지 않으면 시스템 프록시를 따라요. 프록시가 켜져 있는지 확인하거나, mu용으로 HTTPS_PROXY를 설정하세요.

판정기

판정기가 아무것도 하지 않는 것 같아요. 섀도 모드인 판정 지점은 판정을 기록만 하고 아무것도 바꾸지 않고, 꺼진 판정 지점은 묻지 않아요. /status가 판정 지점마다 모드를 보여 줘요. ~/.mu/agent/mu.json에 "default": "shadow"나 "off"가 있는지, 환경에 MU_JUDGE_MODE가 있는지 확인하세요.

"아직 사용할 수 있는 판정기가 없어 mu가 단계마다 사용자에게 묻습니다." Jev 승인 모드에서 판정기가 답할 수 없으면, mu는 승인이 필요한 단계를 모두 여러분에게 물어요. 키가 없고 무료 Jev도 쓸 수 없을 때, 계정 잔액이 바닥났을 때, 또는 승인을 맡기지 않는 로컬 판정기만 있을 때예요. Jev 키를 설정하거나(mu setup), /permissions로 모드를 바꾸세요.

무료 Jev가 답하지 않아요. OpenCode Zen의 기간 한정 제공이라서, 제공이 끝나면 mu가 알려 줘요. Jev 서비스 중 하나의 키를 설정하거나 다른 판정기를 고르세요.

판정이 느려요. 판정 지점마다 시간 제한이 있고, 시간이 지나면 mu는 판정 없이 계속해요. 오래 막히는 일은 없어요. mu ledger --json은 판정마다 지연 시간을 보여 줘요. 느리거나 먼 판정기는 routes로 판정 지점마다 바꿀 수 있어요.

로컬 판정기가 모델을 내려받으려고 해요. Laya의 모델은 수백 MB예요. mu는 여러분이 동의한 뒤에만 mu judge setup이나 앱에서 내려받아요.

터미널

서브 에이전트가 시작될 때 터미널 UI가 "Rendered line … exceeds terminal width"와 함께 비정상 종료돼요. mu-agent 0.1.8 이후에 고쳤고, 다음 릴리스에 들어가요. 그전까지는 터미널을 상태 표시줄보다 넓게 늘리세요.

처음부터 다시

mu setup은 바꾸는 파일을 모두 먼저 ~/.mu/backups/<time>/에 복사해 둬요. mu 자체 설정을 초기화하려면 ~/.mu/agent/mu.json을 다른 곳으로 옮기세요. mu가 기본값으로 시작해요. 세션, 로그인, 교훈은 별도 파일이라 그대로 남아요.