제약사항과 문제 해결
명령이 실패하면 접속 환경·로그인·조직·권한 순서로 확인합니다. 오류 메시지에 표시된 코드와 안내를 함께 참고하세요.
사용할 수 있는 명령 확인하기
aipctl --version
aipctl --help
aipctl skill --help작업에 필요한 명령과 옵션은 전체 명령 참조에서 확인할 수 있습니다. 사용할 수 있는 기능은 계정 권한과 접속 환경에 따라 달라질 수 있습니다.
| 작업 | 현재 사용할 방법 |
|---|---|
| Skill 파일 등록·다운로드, 조직 Skill GitHub 연동 | 이 매뉴얼의 Skill 명령 사용 |
| Agent 대화, Drive 전송, Agent 내보내기 | 해당 명령의 버전·서버 제공 조건 확인. 제한되면 웹 사용 |
| 연동 테스트·수정·삭제, 자동화 실행·취소, 키·주소 재발급 | 해당 명령의 버전·서버 제공 조건 확인. 제한되면 웹의 지원 작업 사용 |
| 새 일반 대화 메시지 전송·모델 실행·이미지 생성 | 웹에서 실행 |
| 연결 토큰 준비 | 웹의 PC 연결 안내 사용 |
CLI_OPERATION_NOT_ENABLED가 나오면 현재 버전과 조직의 기능 제공 여부를 확인하세요. 개발용 CLI 설치만으로 해결되지 않습니다.
브라우저 로그인이 완료되지 않아요
- 로그인 주소가 열리지 않으면 터미널에 출력된 주소를 같은 PC의 브라우저에서 여세요.
- 로그인 대기 시간이 지났다면
aipctl auth login을 다시 실행하세요. 8484포트를 사용 중이라는 오류가 나오면 다른 로그인·조직 선택 작업을 종료한 뒤 다시 시도하세요.- 로그인 중 접속 환경을 바꾸거나 다른 터미널에서 로그아웃하지 마세요.
aipctl config status
aipctl auth status
aipctl org currentCLI_AUTH_SESSION_CHANGED가 나오면 다른 작업에서 로그인·조직·환경이 바뀌었을 수 있습니다. 현재 상태를 확인한 뒤 의도한 환경에 다시 로그인합니다.
로그인했는데 조직에 접근할 수 없어요
org list에서 접근 가능한 조직을 확인하세요. 조직이 없다면 초대와 가입 상태를 확인합니다. IP 접근 제한이 있는 조직은 허용된 네트워크에서 사용해야 합니다.
aipctl org list
aipctl org use ORG_SLUG권한이 없거나 대상을 찾을 수 없어요
401: 로그인과 접속 주소를 확인하고 다시 로그인합니다.403: 조직 역할과 대상 리소스의 사용·관리 권한을 확인합니다.404: 현재 조직과 ID가 맞는지 목록에서 확인합니다. 기능이 해당 서버에서 제공되는지도 확인하세요.
명령에 admin이 있다고 모두 같은 권한을 요구하는 것은 아닙니다. 조직 공용 Skill·Agent 관리는 AI Operator 권한, 조직 사용량은 관리자 권한 등 작업별 조건이 적용됩니다.
요청이 너무 많다는 오류가 나와요
429는 요청 또는 실행 한도를 초과한 상태입니다. 오류의 대기 안내(Retry-After)가 있다면 기다린 뒤 조회 빈도를 낮추세요.
- 같은 목록을 짧은 간격으로 반복 조회하지 않습니다.
- 여러 스크립트가 동시에 실행 중이면 실행 수를 줄입니다.
- 개인 한도 외에 조직이 함께 쓰는 한도로 제한될 수도 있습니다.
- 일일 한도나 종료 확인 중인 실행은 잠시 기다리는 것만으로 해결되지 않을 수 있습니다. 계속 제한되면 조직 관리자나 지원 담당자에게 문의하세요.
503은 서비스를 일시적으로 사용할 수 없다는 뜻일 수 있습니다. 오류 메시지를 확인하고 잠시 후 다시 조회하거나 지원 담당자에게 문의하세요.
목록이나 메시지를 모두 볼 수 없어요
일반 조회는 응답 크기와 처리 시간에 제한이 있습니다. 큰 결과는 일부를 전체 결과처럼 반환하지 않고 오류로 종료할 수 있습니다.
| 상황 | 다음 행동 |
|---|---|
| 다음 페이지가 있는 목록 | 페이지 옵션으로 이어서 조회 |
| 검색·폴더 조건을 지원하는 목록 | 조회 범위를 좁혀 실행 |
| 대화 메시지가 잘리거나 조회 한도 초과 | 웹에서 전체 대화 확인 |
| 자동화가 50개보다 많음 | 웹에서 목록 확인 |
| 큰 폴더 삭제가 거절됨 | 하위 내용을 확인하고 범위를 나눠 정리 |
변경 중 연결이 끊겼어요
outcome=unknown, 시간 초과 또는 Ctrl+C 이후에는 변경이 서버에 반영되었을 수 있습니다.
- 생성·수정·삭제한 대상의 목록과 상세를 조회합니다.
- 실제 반영 상태를 확인합니다.
- 반영되지 않은 것이 확인된 경우에만 다시 실행합니다.
Ctrl+C와 로그아웃은 원격 실행 취소나 변경 취소를 보장하지 않습니다. 자동화 활성화·비활성화도 이미 실행 중인 작업의 취소 완료를 뜻하지 않습니다.
409가 나오면 대상 상태가 바뀌었거나 이름이 충돌했을 수 있습니다. 최신 상태를 다시 조회하고 수정 내용을 검토하세요. --force는 삭제 등의 실행 확인이며 권한·상태 충돌을 무시하는 옵션이 아닙니다.
지원 요청에 포함할 정보
aipctl --version결과, OS·CPU와 Node.js 버전- 실행한 명령과 발생 시각
- 오류 코드·메시지와 표시된 요청 ID
- 접속 환경과 작업 대상 종류, 변경 후 확인한 상태
토큰·PAT·인증 파일·비공개 자료 내용은 가리고 전달하세요. 스크린샷에 포함된 명령 인자도 확인합니다.