1DesignTool의 대부분의 문제는 몇 가지 원인으로 귀결됩니다 — 없거나 로그아웃된 에이전트, 멈추는 실행, 렌더되지 않는 미리보기, 게이트 FAIL, 소진된 상한. 이 페이지는 각각에 대해 먼저 볼 곳입니다.
에이전트가 피커에 없음
앱은 지원되는 CLI를 PATH에서 찾습니다 — 터미널이 하는 것과 같은 방식입니다.
- 설치돼 있나요? 터미널에서 이름으로 CLI를 실행해 보세요(
claude,codex…) — 셸이 찾으면 앱도 찾아야 합니다. - 로그인돼 있나요? 피커가 로그인 상태를 보여줍니다; 없는 로그인은 앱이 아니라 CLI 자체의 인증입니다. CLI 쪽에서 로그인하고 다시 여세요.
- 로스터에 있나요? 16개 지원 CLI가 지원되는 코딩 에이전트에 나열돼 있습니다 — 목록에 없는 CLI는 꽂을 수 없습니다.
실행이 멈추거나 실패
- 에이전트의 쿼터 확인 — 턴은 CLI 계정에 과금됩니다; 소진되거나 만료된 계정은 트랜스크립트에서 실행을 가시적으로 실패시킵니다.
- 트랜스크립트 읽기 — 에이전트 자체의 출력이 거기 있습니다; CLI 쪽 오류는 제너릭 실패가 아니라 그 자체로 나타납니다.
- 한 번 재시도 — 일시적인 CLI 실패는 재시도에서 가끔 풀립니다. 지속되는 실패는 트랜스크립트가 이름을 짓는 원인이 있습니다.
미리보기가 렌더되지 않음
- 미리보기는 기본 거부 — 분류기가 서빙하지 않는 파일 타입은 안전하지 않게 렌더되는 대신 아무것도 렌더되지 않습니다. 이것은 안전 바닥이지 버그가 아닙니다.
- 오래된 워크트리 — 코드베이스 프로젝트에서 미리보기는
1design/<slug>워크트리를 읽습니다; 브랜치 상태가 이상해 보이면 렌더를 의심하기 전에 브랜치 바의 diff를 리뷰하세요. - 패널 새로고침 — 미리보기 레일의 리로드 버튼이 폴더를 다시 읽습니다; 절반만 쓰인 파일은 보통 다음 페인트에서 풀립니다.
게이트 FAIL이 풀리지 않음
- Fix at this width — FAIL 파인딩의 픽스 버튼이 정확히 그 이슈를 한 줄 브리프로 에이전트에게 돌려보냅니다; 파인딩이 너비와 요소를 이름짓므로 픽스는 보통 기계적입니다.
- 그 너비에서 확인 — 파인딩이 어느 뷰포트가 깨졌는지 말합니다; 규칙이 틀렸다고 가정하기 전에 거기서 결과를 보세요.
- 일부 파인딩은 의도적 — 알려진 트레이드오프는 받아들일 수 있습니다; 게이트는 조언하지 막지 않습니다. design-kit 게이트 참조.
상한이 실행을 거절
1design:limit: 거절은 소진된 상한을 이름짓습니다 — Free 티어의 턴, 렌더,
버전, 배리언트, 디자인 시스템. Settings → Usage가 미터를 전부 보여주고,
버전을 아카이브하면 라이선스 없이 슬롯이 비워집니다. 상한은 평생
카운터입니다; Pro가 그것들을 없앱니다. Free vs
Pro 참조.
Windows에서: EISDIR 오류 (알려진 이슈)
Windows의 1.7.0에서 design kit 스크립트가 EISDIR로 실패할 수 있습니다 —
Knowledge, 턴 후 체크, 비디오 익스포트, Build mode가 깨집니다. 알려진
버그이며 다음 릴리스에서 고쳐집니다; macOS에서는 같은 플로가 영향받지
않습니다.
MCP 클라이언트가 연결되지 않음
- 접근 패널 확인 — Settings → MCP access가 엔드포인트, 토큰, 허용 클라이언트 목록을 보여줍니다; 거절된 클라이언트는 보통 목록에 없습니다.
- 토큰 확인 — 패널의 토큰이 클라이언트가 보내는 것입니다; 오래되거나 틀린 토큰은 연결을 거절합니다.
- 액티비티 로그 확인 — 로그가 서버에 도달한 것과 도달하지 않은 것을 보여줍니다.
먼저 볼 곳
- 트랜스크립트 패널 — 에이전트의 출력, 그대로
- 브랜치 바 — 코드베이스 프로젝트에서 턴이 실제로 바꾼 것
- Settings → Usage — 어느 미터가 소진됐는지
- 액티비티 로그 — MCP 클라이언트가 실제로 한 일
Tip: 트랜스크립트가 항상 첫 읽기입니다 — 에이전트 자체의 출력이 일어난 일의 정직한 버전이고, 대부분의 "앱이 고장 났다"는 사실 "CLI가 뭔가 말했는데 UI가 너무 부드럽게 번역했다"입니다.