Agentty/문서

문제 해결

흔히 어긋나는 것들과 그때 할 일.

문제점 자동진단#

Agentty가 흔한 문제를 자동으로 찾아내고 고칠 수 있습니다. 도움말 → 문제점 자동진단을 열거나, 설정 → 환경 점검에서 진단 시작을 누르세요.

점검하는 항목입니다.

  • Claude Code나 Codex가 설치돼 있는데 새 터미널에서 찾지 못하는 경우 — 설치 폴더를 셸 시작 파일의 PATH에 추가합니다.
  • 같은 CLI가 여러 개 설치된 경우 — Agentty는 항상 가장 최신 버전을 실행하고, 다른 터미널에서는 PATH 앞쪽의 오래된 버전이 실행되면 알려 줍니다.
  • 시작 직후 종료된 실행 때문에 Claude Code가 전체 화면 모드를 스스로 끈 경우 — Agentty 터미널은 영향을 받지 않습니다. 다른 터미널을 위해 그 기록을 지웁니다.
  • Claude Code의 settings.json, ~/.claude.json, Codex의 config.toml에 문법 오류가 있는 경우 — 마지막으로 정상이던 사본이 있으면 그것으로 되돌립니다.
  • 셸 시작 파일에서 CLAUDECODE, CLAUDE_CODE_CHILD_SESSION 같은 변수를 설정하는 경우 — 그 줄을 주석으로 바꿉니다.
  • Agentty 터미널 연동 파일이 없거나 오래된 경우 — 파일을 다시 만듭니다.

고칠 수 있는 문제에는 자동 해결 버튼이 있고 모두 해결을 누르면 한 번에 적용합니다. 파일을 고치기 전에는 항상 <파일>.agentty-<시각> 이름으로 사본을 남깁니다. 셸 시작 파일의 변경은 새로 여는 터미널부터 적용됩니다.

같은 폴더에서 다른 에이전트가 이미 작업 중이면 터미널에 입력한 claude/codex를 어디서 시작할지 묻습니다. 30초 안에 고르지 않으면 현재 폴더에서 바로 시작합니다.

에이전트가 목록에 없거나 시작되지 않습니다#

Agentty는 로그인 셸의 PATH에서 찾을 수 있는 에이전트 CLI만 제안합니다. 터미널에서는 되는데 여기서만 안 된다면 PATH가 대화형 셸만 읽는 파일(.zshrc, .bashrc)에 설정돼 있을 가능성이 큽니다. 그 설정을 로그인 셸이 읽는 파일로 옮기세요. 설정 → 환경 점검을 열어도 됩니다. 빠진 것을 나열하고 설치까지 해 줍니다.

페인 상태가 비어 있습니다#

상태는 페인이 시작할 때 Agentty가 에이전트에게 넘기는 훅에서 나옵니다.

  • Windows에서 Claude Code는 훅을 Git Bash로 실행합니다. Git for Windows를 설치하세요.
  • 이미 열린 셸 안에서 에이전트를 직접 실행했다면 훅이 없습니다. + 메뉴에서 여세요.

에이전트가 엉뚱한 파일을 고쳤습니다#

한 폴더에서 두 세션이 돌면 서로 부딪칩니다. 설정 → 일반 → 세션마다 워크트리를 켜면 두 번째 세션이 자기 git 워크트리와 브랜치를 갖습니다. 파일 패널에서 모든 워크트리와 각각의 변경 내용을 볼 수 있습니다.

탭을 닫았는데 개발 서버가 계속 돕니다#

설정 → 일반 → 닫을 때 서버 종료를 켜면 페인을 닫을 때 그 페인이 시작한 서버도 함께 끝냅니다. 아직 실행 중인 것은 모니터링 → 프로세스에서 확인할 수 있습니다.

사용량 숫자가 이상합니다#

디스크의 대화 파일로 계산한 값이고, 가격이 내장된 모델은 Claude뿐입니다. 다른 모델은 ~/.agentty/pricing.json에 가격을 추가하세요(설정 레퍼런스 참고). 이 수치는 추정치이며 정확한 금액은 제공자의 청구서를 따릅니다.

플러그인이 보이지 않거나 멈춥니다#

  • JavaScript 플러그인은 로그인 셸의 PATH에 Node.js 18 이상이 필요합니다.
  • 폴더 이름이 agentty-plugin.json의 id와 같아야 합니다. 복사해 넣은 뒤에는 새로 고침을 누르세요.
  • 플러그인 카드의 로그에 크래시를 포함한 실제 출력이 있습니다. 코드를 고친 뒤 재시작을 누르세요.

자세한 내용은 플러그인 사용하기에 있습니다.

agentty:// 링크가 동작하지 않습니다#

링크는 설치된 애플리케이션에서 동작하고 개발용으로 실행한 빌드에서는 동작하지 않습니다. 링크가 지정한 플러그인이 설치·활성화돼 있는지 확인하세요.

업데이트가 되지 않습니다#

업데이트는 GitHub에서 내려받고 쓰기 전에 검증합니다. 프록시나 차단된 호스트 때문에 내려받기가 실패하면 릴리스 페이지에서 직접 받으세요.

그래도 막혔다면#

이슈 트래커에 알려 주세요. Agentty 버전(설정 → Agentty 정보), 운영체제, 기대한 동작을 함께 적어 주시면 좋습니다. 로그나 화면을 붙여 넣기 전에 자격 증명은 가려 주세요.

보안 문제는 공개 이슈 대신 비공개로 신고해 주시기 바랍니다.