문제 해결

#설치

#‘aimz’ 명령을 찾을 수 없음

명령이 놓인 폴더가 PATH 에 없습니다. Windows 는 py -m pipx ensurepath, macOS·Linux 는 pipx ensurepath 를 실행하고 터미널을 새로 여세요. Windows 에서 pipx 자체를 못 찾으면 같은 PowerShell에서 py -m pipx install 을 사용할 수 있습니다. 운영체제별 PATH 설정은 설치 — PATH 설정에 있습니다.

#Python 버전 오류

Python 3.10 이상이 필요합니다. Windows 는 py --version, macOS·Linux 는 python3 --version 으로 확인하세요. macOS 에 기본으로 들어 있는 python3 는 3.9 라서 거절됩니다 — brew install python.

#error: externally-managed-environment

macOS(Homebrew Python)와 최근 Linux(Ubuntu 23.04 이후 등)는 시스템 Python 에 pip install --user 를 막습니다(PEP 668). 정상 동작입니다. pipx 나 venv 로 설치하세요.

#python: command not found (macOS·Linux)

macOS·Linux 의 명령 이름은 python 이 아니라 python3 입니다. 문서의 Windows 예시에 있는 py 도python3 로 바꿔 읽으세요.

#로그인

#브라우저가 열리지 않음

터미널에 출력된 주소를 직접 브라우저에 붙여 넣으세요. 서버나 원격 접속 환경이면 aimz login --no-browser.

#로그인했는데 터미널이 계속 기다림

• 브라우저가 “로그인 완료” 화면까지 갔는지 확인하세요. 회사 보안 프로그램이 127.0.0.1 접속을 막으면 돌아오지 못합니다.
• 그럴 땐 Ctrl+C 로 멈추고 aimz login --no-browser 로 코드를 붙여 넣으세요.
• 화면에 ‘앱 열기’ 단추가 보이면(데스크톱 앱용 화면) 그 링크 주소를 복사해 터미널에 붙여 넣어도 로그인됩니다.

#Linux: 브라우저가 안 열리거나 ‘xdg-open’ 오류

데스크톱 환경이 없는 서버·SSH·WSL 에서는 브라우저를 열 수 없습니다. aimz login --no-browser 로 주소를 받아 다른 기기에서 로그인하고 코드를 붙여 넣으세요.

#macOS: 키체인 접근을 묻는 창

토큰을 키체인에 저장하거나 읽을 때 “… 키체인에 저장된 기밀 정보를 사용하려고 합니다” 창이 뜰 수 있습니다. 로그인 암호를 넣고 항상 허용을 누르세요. CLI 를 다시 설치해 Python 경로가 바뀌면 한 번 더 물을 수 있습니다.

#자격 증명 저장소 오류 (Linux 키링 잠김·DBus 오류 등)

OS 저장소를 쓸 수 없는 환경(데스크톱 없는 Linux 서버 등)이면 자동으로 ~/.aimz/credentials.json(본인만 읽기) 에 저장합니다. 키링이 있는데 잠금 해제 창이 계속 뜨거나 DBus 오류가 나면 파일로 강제하세요:

$env:AIMZ_CREDENTIAL_STORE = "file"; aimz login

#에이전트(MCP)

#에이전트에 도구가 안 보임

• 설정을 바꾼 뒤 에이전트를 다시 시작했는지 확인하세요. Claude Desktop 은 창만 닫지 말고 완전히 종료(macOS 는 ⌘Q)해야 합니다.
• aimz mcp-config 가 알려 주는 전체 경로를 명령으로 넣어 보세요. macOS 에서 Dock 으로 연 앱은 터미널 PATH 를 모릅니다.
• Claude Code: claude mcp list 로 연결 상태를 확인합니다.

#도구가 “로그인 필요”를 돌려줌

터미널에서 aimz login 을 한 번 하면 됩니다. MCP 서버를 다시 켤 필요는 없습니다.

#승인 창이 안 뜨고 채팅으로 물어봄

클라이언트가 MCP 승인 창(elicitation)을 지원하지 않는 경우입니다. 정상 동작이며, 채팅에서 승인하면 에이전트가 일회용 확인 표로 다시 실행합니다. 매번 묻는 게 번거로우면 once 또는 yolo 모드를 쓰세요.

#생성

#계속 queued(대기) 상태임

실패가 아니라 차례를 기다리는 중입니다. aimz queue(MCP: queue_status)로 순번·예상 시간을 보세요. 다시 접수하면 크레딧이 두 번 듭니다 — 대기열과 동시 생성.

#영상이 오래 걸림

모델·길이에 따라 몇 분 걸립니다. --no-wait 로 접수만 하고 aimz jobs <id> --wait 로 이어서 받으세요. 진행 중인 작업은 aimz jobs, 실패 이유는 aimz failures.

#넣은 값이 반영되지 않음

모델 규격에 없는 키는 서버가 버립니다. aimz model <id> 로 받는 키와 선택지를 확인하세요.

#Windows 에서 한글이 깨짐

Windows Terminal·PowerShell 7 을 권합니다. 다른 프로그램으로 출력을 넘길 때는 --json 을 쓰면 UTF-8 JSON 으로 나옵니다.