문제 해결 가이드

문제 해결 순서: 먼저 tansr doctor(CLI) 또는 오류 코드(다른 형태)를 보고, 그다음 아래 표에서 처리를 찾습니다. 열에 아홉은 사람에게 연락할 필요가 없습니다.

첫 단계: `tansr doctor`

tansr doctor          # 人读报告
tansr doctor --json   # 机器可读

모델 호출 없음, 네트워크 없음, 읽기 전용(디렉터리를 전혀 만들지 않음). 종료 코드 0 = 사용 가능, 1 = 차단 문제 있음. 표시되는 것은 가장 최근 어셈블리 가져오기의 사실입니다. 콘솔에서 설정을 바꿨으면 CLI를 한 번 실행하면 새로 고쳐집니다. TUI 안의 /doctor는 별도의 더 짧은 어셈블리 상태 점검표이며(아래 참조) 종료 코드에 영향을 주지 않습니다.

무엇이 차단으로 계산되나

tansr doctor는 네 종류의 문제만 차단(종료 코드 1)으로 계산합니다: no_provider(사용 가능한 provider가 하나도 없음), unresolved_model(기본 별칭이 모델로 해석되지 않음), missing_credential(해석된 provider의 API key 환경 변수가 없음), session_store_unwritable(세션 저장소 디렉터리에 쓸 수 없음). --connectors를 명시적으로 붙여 배포 커넥터를 탐지하면 그 차단 문제도 같은 결론에 합쳐집니다. 나머지 섹션은 모두 귀속과 힌트이며 종료 코드를 바꾸지 않습니다.

보고서 섹션 대조표

섹션	정상일 때의 모습	이상할 때 어떻게 하나	차단?
설정 소스와 진단	5층 각각 loaded / absent, skipped 없음. error 수준 진단 0건	skipped = 그 층의 JSONC 구문 오류 또는 루트 노드가 객체가 아님. 파일을 고치거나 삭제. 진단은 건마다 층 / 키 경로 / 기대 타입을 제시하며, 잘못된 값은 이미 제거되어 더 낮은 층으로 폴백됨	아니요
provider / 모델 해석 / 자격 증명	기본 별칭 → provider / 모델. 자격 증명이 존재하며 `sk-...끝4자리` 형태로만 표시됨	“알 수 없는 모델 별칭 또는 ref”면 `modelAliases`와 `providers.models`를 대조. “API key 없음: 환경 변수 X가 설정되지 않음”이면 그 변수를 export	예(`no_provider` / `unresolved_model` / `missing_credential`)
`localProviders`(귀속)	플랫폼 모드: 로컬 providers가 프루닝되는 것은 예상된 동작. 이스케이프 해치: 배너 표시	“provider가 설정되지 않음”은 먼저 여기를 보고 설정이 안 된 것인지 프루닝된 것인지 구분	아니요
자격 증명 저장소(귀속)	키체인	평문 파일로 폴백되었으면 디렉터리 권한을 확인. `tansr init` 다시 실행	아니요
모델 선택 귀속	`model.selected` 값과 제공 층. 억제 상태	프로젝트 층이 `modelAliases.main`을 고정했을 때 사용자 층의 고착 선택이 억제되는 것은 예상된 동작	아니요
플랜	“개인(CLI만, 플랜 요금 없음)” 또는 “등급 이름 · 만료 · 상태”	개인 등급은 고장이 아님. 유예 / 회귀 상태는 콘솔에서 갱신	아니요
미디어 도구	네 면 `byo` / `platform` / `none`	전부 `none`이면 개통 안내가 붙음: 자체 엔드포인트 세 변수, 또는 관리자에게 미디어 풀 개방 요청	아니요
무인 기준선	`auto`이며 격리 흔적 있음	흔적이 없으면 눈에 띄게 안내. 격리를 확인했으면 `TANSR_ISOLATED=1`로 억제	아니요
컨텍스트 / memory	창 두 값과 클램프 쪽, 활성 스킴, 최근 7일 압축 통계. 메모리 디렉터리와 인덱스 점유량	창 알 수 없음 → 모델에 `maxContext`를 선언. production 아닌 스킴은 경고일 뿐	아니요
세션 저장소	세션 수, 바이트, sidecar-only 디렉터리, 손상 디렉터리. 쓰기 가능 프로브 통과	읽기만 하고 대신 삭제하지 않음. 정리는 `tansr sessions prune`. 디렉터리에 쓸 수 없으면 권한을 고치거나 `TANSR_STORAGE_ROOT`를 다른 곳으로 지정	쓰기 불가는 차단(`session_store_unwritable`)
작업 공간 신뢰	신뢰됨	신뢰되지 않음은 사용자의 명시적 선택이지 고장이 아님. 풀려면 TUI에서 `/trust grant`	아니요

TUI 안의 `/doctor`

TUI 안의 /doctor는 네트워크 없음, 자식 프로세스 없음의 별도 어셈블리 상태 자가 점검으로, 항목마다 ✓ / ✗를 표시합니다. 항목 목록은 실제 출력이 기준입니다(작성 시점 12개): node_version(≥ 22.19), config_sources(5층에 skipped 없음), config_diagnostics(error 수준 진단 없음), model_resolution, context_window, context_scheme(production 아닌 스킴에 경고 표시), custom_commands(명령 소스에 skipped 없음), mcp_connections(지연 연결의 미연결도 정상으로 봄. 실패한 서버는 오류 코드를 보고 /mcp reconnect), terminal(TTY와 크기), workspace_trust, output_style(스타일 이름이 없으면 정직하게 오류 보고), session_driver_state(현재 위상, 세대, 턴 수와 최근 전이. 위상 자체는 고장이 아니므로 이 항목은 항상 ✓). ✗는 힌트일 뿐이며 tansr doctor의 차단 문제와 같지 않습니다.

CLI에서 흔한 메시지

증상	처리
“대화형 UI를 시작할 수 없음: 현재 대화형 터미널(TTY)이 아님”	파이프 안에서 `tansr`를 시작했습니다. 스크립트 / 파이프 상황에서는 `tansr -p "<프롬프트>"`를 사용
“API token이 없습니다: –token <값>을 전달하거나 TANSR_SERVE_TOKEN을 설정하세요”	`tansr serve`는 fail-closed이며 인증 없는 서비스를 띄우지 않음
“서버 시작 실패” / “–port 값이 유효하지 않음”	포트가 사용 중이거나 잘못됨
“세션이 존재하지 않음” / “세션을 복구할 수 없음”	`--resume`의 id가 틀렸거나 디렉터리가 사용 중. 인자 없는 `tansr --resume`으로 선택기를 열어 확인
종료 코드 5이며 `tansr init` 안내	무인 형태가 초기화되지 않음. 먼저 로그인하거나 `TANSR_ESCAPE_LOCAL=1`을 설정해 로컬 모드로
종료 코드 3	상한 도달: `--max-turns` / 예산 / 도구 턴 수. 늘리거나 작업을 나눔
종료 코드 4	prompt가 너무 길고 압축을 사용할 수 없음. 더 큰 창의 모델로 바꿈
“동시 실행이 플랜 상한에 도달” 배너	새 세션만 거부. 30초 뒤 다시 보내거나 플랜 업그레이드

가장 흔한 오류 코드 열 개

모든 코드의 공식 표는 오류 코드 표에 있습니다. 여기서는 가장 자주 만나는 열 개와 첫 처리만 나열합니다.

코드	HTTP	어디에서 보게 되나	첫 처리
`unauthorized`	401	토큰이 만료되었거나 폐기됨. 세션 서비스 `authenticate`가 null 반환	CLI: `tansr init`으로 다시 로그인. SDK: 당신의 서버로 돌아가 토큰을 다시 발급. 모바일: 로그인 상태를 고친 뒤 명시적으로 재연결. 토큰이 잘못되었음을 나타내는 유일한 코드
`token_expired`	401	로그인 상태 token 만료	다시 로그인 / 새로 고침
`invalid_api_key`	401	PAT가 유효하지 않음	콘솔에서 PAT를 다시 만들고 `tansr init --fresh`
`rate_limited`	429	플랫폼 속도 제한, 또는 세션 서비스 호스트 속도 제한 / 플랜 할당량(`detail.scope: 'plan'`)	`Retry-After`의 초 단위로 기다린 뒤 재시도. 더 촘촘하게 다시 보내지 말 것
`plan_concurrency_exceeded`	429	플랜 동시 실행 하드 캡	새 세션만 거부. 30초 뒤 수동으로 다시 보냄. 등급 상향 고려
`insufficient_balance`	402	잔액 부족	충전. 재시도는 소용없음
`model_not_authorized`	403	모델이 앱 권한 범위에 없음	콘솔에서 앱에 그 모델 권한을 부여
`validation_failed`	400	요청 페이로드 형태가 잘못됨	`message`를 읽고 요청을 수정. 네트워크 문제가 아님
`payload_too_large`	413	크기 상한 초과(예: 음성 원시 오디오 > 24 MiB)	나누거나 압축. 재시도 불가
`session_archived`	410	플랫폼 세션이 보관 처리됨(30일 비활성)	새 세션 생성. 이것은 이어갈 수 없음

자주 보이지만 의미가 명확한 것 몇 개를 덧붙입니다: upstream_error(502, 업스트림 모델 장애, 백오프 후 재시도), upstream_timeout(504, 위와 같음), quota_exceeded(429, 일일 할당량), forbidden(403, 기능 플래그 꺼짐 또는 소속 불일치), context_window_exceeded(400, 먼저 압축).

각 형태의 문제 해결 첫 단계

SDK(Node / Electron): 어셈블리 단계인지 실행 단계인지 구분합니다. 어셈블리 단계의 TansrSdkError는 code를 읽습니다(invalid_options는 코드 수정. assembly_failed는 cause를 봄. capability_disabled는 콘솔에서 플래그를 켬). 실행 단계에서는 이벤트 스트림의 turn.error.recoverable을 봅니다. true는 자문이고, false가 실패입니다. 이벤트 스트림이 “멈춰서 움직이지 않음”은 거의 session.close()를 잊은 것이고, “도구가 모두 거부됨”은 거의 permission.askUser를 연결하지 않은 것입니다. 자세한 내용은 오류 처리와 재시도.

세션 서비스(@tansr/serve): 먼저 GET /readyz(503이면 reasons 포함)를 보고, 그다음 구조화 로그의 request.completed / store.commit_failed / session.rejected를 보며, 응답 헤더 x-request-id로 연관시킵니다. resume이 항상 409 resume_unavailable = store를 연결하지 않음. 500 store_corrupted는 공유 저장소 디렉터리(안전하지 않은 구성)에서 흔합니다. 세션 생성 시 503 upstream_unavailable은 플랫폼 쪽 토큰 발급 불가, 503 overloaded는 이 컴퓨터의 허용 상한, 503 draining은 정상 종료 진행 중입니다.

모바일(Android / iOS / HarmonyOS): 먼저 연결 상태를 봅니다. Android / iOS는 connectionState를 봅니다. Retrying은 정상적인 L1 재연결, Recovering은 L2 재구축. AuthExpired → Failed(Unauthorized)는 토큰을 2번 새로 받았는데도 여전히 401인 것으로, 로그인 상태를 고친 뒤 명시적으로 start()합니다. HarmonyOS는 session.onState의 retrying / recovering / failed를 봅니다. 연결하자마자 401은 보통 인증 헤더를 서버 쪽 authenticate가 인정하지 않는 것입니다. 에뮬레이터에서 연결이 안 되는 경우, Android는 10.0.2.2 대신 127.0.0.1을 쓴 경우가 많고, HarmonyOS 루프백은 로컬 디버그만이며 개발 머신 사설 주소에 닿으려면 allowPrivateNetworkHttp가 필요합니다.

이것을 가지고 지원팀에 문의

tansr doctor --json의 출력(키 값은 포함하지 않으며, 자격 증명은 지문 형태로 표시됨).
오류 코드와 완전한 message. 세션 서비스 쪽은 x-request-id도 첨부.
재현 단계와 시각. 과금과 관련되면 주문 번호 또는 청구 월.
가능하면 tansr sessions export <id>의 트랜스크립트(키는 이미 자동 마스킹됨).

진입점은 지원팀에 문의를 참고하세요.

문제 해결 가이드

첫 단계: tansr doctor