제한과 오류

도구 호출을 빠르고 예측 가능하게 유지하기 위한 제한과, 호출이 실패했을 때 AI 클라이언트가 받는 내용입니다.

호출당 제한

항목	제한
명령 출력(`exec`, `shell_run`)	32,000바이트. 이보다 긴 출력은 잘립니다
명령 제한 시간	기본 60초, 최대 900초. 더 오래 걸리는 작업에는 `job_start`를 사용합니다
`exec_many` 한 번에 대상 기기 수	8대. 기기마다 출력 제한은 절반입니다
`read_file`	호출당 기본 200,000바이트, 최대 4,000,000바이트. `next_offset`부터 이어서 읽습니다
`write_file`, `copy_between_hosts`	4,000,000바이트. 더 큰 파일에는 `transfer_start`를 사용합니다
`transfer_start`	크기 제한 없음. 연결당 동시에 2개, 각각 최대 10,000개 파일
작업 출력(`job_output`)	읽기 1회당 64,000바이트
호출당 터미널 출력	20,000자. 최대 600초까지 기다립니다
포트 포워딩 HTTP 본문(`tunnel_http`)	32 KB

열린 세션

항목	제한
셸 세션	기기당 4개. 30분 동안 사용하지 않으면 닫힙니다
터미널	연결당 8개. 30분 동안 사용하지 않으면 닫힙니다
터널	1시간 후 닫힙니다
예약 작업	계정당 200개
웹 공유	AI가 만들 때 기본 24시간, 최대 30일
대기 중인 승인	연결당 20개

10초 넘게 걸리는 호출은 클라이언트가 요청하면 10초마다 MCP 진행 상황 알림을 보냅니다. 따라서 명령, 전송, 승인이 진행 중인 동안 클라이언트에서 시간 초과가 발생하지 않습니다.

요금제 제한

요금제에 따라 계정의 기기 수와 멤버 수, 그리고 정책에서 사용할 수 있는 기능(폴더 단위 파일 규칙, 명령 규칙, 예약 작업, 웹 공유, 시크릿 환경 변수 등)이 정해집니다. 요금을 참고하십시오. 요금제에 포함되지 않은 기능이 필요한 호출은 그 사실을 알리는 메시지와 함께 실패합니다.

오류

거부되거나 실패한 호출은 isError: true가 설정된 MCP 도구 결과를 반환하며, 여기에는 무슨 일이 일어났고 다음에 무엇을 해야 하는지 AI에게 알려 주는 평이한 메시지가 담겨 있습니다. 가장 자주 보게 되는 메시지:

메시지 시작 부분	의미
`token lacks fleet.…`	이 도구에 필요한 스코프 없이 연결이 승인되었습니다. 다시 연결하고 해당 스코프를 승인하십시오.
`refused by this connection's command rules`	정책의 명령 규칙이 이 명령을 거부합니다.
`high-risk operation`	AI가 정확한 명령을 여러분에게 보여 준 다음, `confirm=true`로 다시 호출해야 합니다.
`refused by guardrail`	디스크 지우기처럼 LetKite가 절대 실행하지 않는 명령입니다.
`waiting for a person to approve this`	승인이 대기 중입니다. 메시지에 누구에게 언제까지 요청했는지 나와 있습니다.
`this connection's authorization is no longer valid`	연결이 해지되었습니다. 클라이언트를 다시 연결해 다시 로그인하십시오.

로그인 오류에는 표준 OAuth 오류 코드(invalid_grant, invalid_client, access_denied 등)를 사용합니다. 토큰이 없거나 만료되면 WWW-Authenticate 헤더와 함께 HTTP 401이 반환되며, 클라이언트가 스스로 다시 로그인하거나 토큰을 갱신합니다.