도움말 센터

계정과 결제, 문제 해결, 지원팀에 문의. 답을 찾지 못했나요? 먼저 검색해 보고, 그다음 연락해 주세요.

자주 묻는 질문 그룹

계정, 키, 플랜 및 결제
- 로그인과 조직
- API 키 생성, 교체, 폐기
- 플랜 한도와 사용량
- 청구서와 결제
문제 해결
- doctor 출력 읽는 법
- 자주 보는 오류 코드와 대처
- 네트워크와 프록시 문제
- 세션을 재개할 수 없을 때
지원 문의
- WeChat 지원 그룹
- 이메일 지원
- 문의 시 함께 보낼 정보

여기는 tansr 도움말 센터입니다. 개발자 문서 구역은 “어떻게 쓰는가”를 설명하고, 여기서는 “무슨 일이 생겼고, 누구를 찾아야 하는가”에 답합니다. 먼저 아래 그룹에서 질문을 찾아보세요. 찾지 못하면 하단의 세 진입점으로 가세요.

세 가지 진입점

해결하려는 것	갈 곳
로그인이 안 됨, 키를 잃음, 잔액과 플랜, 인보이스	계정과 결제
오류가 났음, `tansr doctor` 출력을 이해할 수 없음, 어떤 오류 코드의 의미	문제 해결 가이드
위로도 해결되지 않았거나, 문제를 제보하고 싶음	지원팀에 문의

시작과 설치

어느 문서부터 시작해야 하나요? 에이전트를 어디에서 실행할지에 따라 다릅니다. 터미널에서 직접 쓰려면 CLI, Node / Electron 프로그램에 내장하려면 SDK, 자신의 사용자에게 에이전트를 제공하려면 세션 서비스, 모바일은 세션 서비스를 거쳐 Android / iOS SDK를 연결합니다. 경로 선택표는 빠른 시작에 있습니다.

어떤 실행 환경이 필요한가요? CLI npm 패키지와 두 npm 라이브러리는 모두 Node.js ≥ 22.19가 필요합니다. 단일 파일 실행 파일은 런타임을 내장합니다. Android minSdk 26, iOS 16+.

npm i -g @tansr/cli 뒤에 명령 이름은 무엇인가요? 패키지 이름은 @tansr/cli, 명령 이름은 tansr입니다. tansr --version으로 설치를 확인합니다.

어떻게 업데이트하나요? tansr update로 확인하고, --install을 붙여야 설치합니다. TUI 안에서는 /update. 시작 시 자동 확인은 절대 하지 않습니다. 조직은 TANSR_UPDATE_PINNED_VERSION으로 버전을 고정할 수 있습니다.

플랫폼을 쓰지 않고 자체 모델 key만 쓰고 싶은데 가능한가요? 가능합니다. TANSR_ESCAPE_LOCAL=1을 설정해 완전 로컬 모드로 들어가고, .tansr/settings.json에 provider를 선언합니다(API key는 환경 변수 이름만 기록). 플랫폼 기능(원격 모델, 사용량, 잔액)은 전체가 비활성화됩니다.

계정과 키

PAT, 앱 키, 최종 사용자 토큰은 무엇이 다른가요? PAT는 당신 본인을 나타내며, tansr init으로 이 컴퓨터에 로그인할 때만 씁니다. 앱 키(appid / appkey)는 당신의 앱을 나타내며 서버 쪽에만 둡니다. 최종 사용자 토큰은 서버가 appkey로 어느 사용자를 위해 발급한 단기 자격 증명입니다. 자세한 내용은 계정과 결제와 보안과 개인정보를 참고하세요.

tansr init이 PAT가 유효하지 않거나 만료되었다고 하면? 콘솔에서 PAT를 새로 만들고, tansr init --fresh로 다시 로그인합니다.

컴퓨터를 바꾸면 다시 로그인해야 하나요? 네. 각 기기가 자기 파생 키를 가지며, tansr init을 다시 실행하면 됩니다. 이전 기기의 키는 영향을 받지 않으며 콘솔에서 비활성화할 수 있습니다.

tansr logout이 내 PAT를 폐기하나요? 아니요. 이 컴퓨터의 자격 증명만 지우고 이 컴퓨터의 파생 키를 비활성화합니다. PAT는 콘솔에서 직접 관리합니다.

플랜과 과금

개인이 CLI를 쓰면 플랜 요금을 내야 하나요? 아니요. 개인 등급에는 플랜 요금이 없으며, 모델은 정가로 잔액에서 차감됩니다. tansr doctor가 “플랜: 개인(CLI만, 플랜 요금 없음)“을 표시하는 것은 고장이 아닙니다.

잔액은 어디에서 보나요? tansr init 요약 카드, TUI 상태 표시줄(1위안 미만이면 항상 보이는 경고로 바뀜), 콘솔. 잔액이 소진되면 플랫폼 모델 호출은 과금 게이트가 거부하며, 로컬 기능에는 영향이 없습니다.

왜 새 세션은 429인데 기존 세션은 계속 쓸 수 있나요? 플랜 동시 실행 상한 도달(plan_concurrency_exceeded)은 새 세션만 거부하며, 실행 중인 세션은 끊지 않습니다. 30초 뒤 다시 시도하거나 플랜을 업그레이드하세요. 자세한 내용은 계정과 결제.

한 번 호출에 얼마가 들었나요? TUI /cost는 모델별로 줄을 나눠 집계합니다. /usage로 token 상세를, /context로 컨텍스트의 어느 부분에 돈이 쓰였는지 봅니다.

세션과 데이터

세션은 어디에 저장되나요? 업로드되나요? CLI 세션은 이 컴퓨터의 ~/.tansr에 저장됩니다(로그인 후 계정별로 격리). 플랫폼은 단말 세션 내용을 저장하지 않고 계량만 합니다. 자세한 내용은 보안과 개인정보.

지난 세션을 어떻게 재개하나요? TUI에서 tansr --resume으로 선택기를 열거나 /resume. 스크립트는 --resume <id> / --continue.

세션 디렉터리가 계속 커지는데 어떻게 정리하나요? tansr sessions prune(기본값은 목록만 나열하고, --apply를 붙여야 삭제. 오늘의 세션과 사용 중인 세션은 절대 삭제하지 않음).

컨텍스트가 가득 차면 어떻게 되나요? 턴 사이에 수위에 따라 자동으로 압축됩니다. /compact로도 할 수 있습니다. 압축 요약 끝에는 압축 전 전체 트랜스크립트의 경로가 붙어 있어 세부 내용을 다시 확인할 수 있습니다.

대화 하나를 내보내고 싶어요. tansr sessions export <id> [--format md|json] [--out 경로]. 키는 자동으로 마스킹됩니다.

오류와 문제 해결

첫 단계로 무엇을 하나요? tansr doctor. 네트워크 없이 설정, 모델 해석, 자격 증명 위치, 플랫폼 모드 귀속, 플랜, 미디어 도구 출처를 출력합니다. 종료 코드 1만 차단입니다. 읽는 법은 문제 해결 가이드를 참고하세요.

오류 코드는 어디에서 찾나요? 오류 코드 표에 모든 기계 코드, HTTP 상태, 재시도 가능 여부가 나열되어 있습니다.

“모델 provider가 설정되지 않음”이라는데 이미 로그인했어요. tansr doctor의 localProviders 섹션을 보세요. 플랫폼 모드에서는 로컬 providers가 기본적으로 프루닝되는데, 이것은 예상된 동작입니다. 또는 이스케이프 해치에 있을 수 있습니다.

모델이 이미지 / 음성 도구가 없다고 해요. tansr doctor의 미디어 도구 줄을 보세요. none은 보통 관리자가 아직 계정에 해당 미디어 풀을 열지 않았거나, 이 컴퓨터가 아직 새 설정을 받지 않은 것입니다(세션을 한 번 재시작).

권한이 항상 거부돼요. 헤드리스 / 서비스 형태에는 질문 채널이 없어 “질문”은 일괄 거부로 폴백합니다. --allowedTools 또는 --permission-mode로 권한을 열고, 환경 격리를 함께 적용하세요. SDK 쪽은 permission.askUser를 연결해야 합니다.

개발자 연동

SDK 모델 출처 세 등급 중 어느 것을 골라야 하나요? 단말 배포는 토큰 방식 { token, baseUrl }, 자신의 서버 스크립트는 관리형 방식 model: '별칭', 테스트는 주입 방식. 세 방식은 상호 배타적입니다.

세션 서비스에 store를 연결하지 않으면 어떻게 되나요? 프로세스가 재시작되면 모든 활성 세션 컨텍스트가 사라지고, resume은 항상 409 resume_unavailable입니다. 프로덕션에서는 반드시 연결하세요.

모바일에서 네트워크가 끊기면 세션을 잃나요? 아니요. SDK는 Last-Event-ID로 재연결하고, gap이 있으면 /history에서 재구축하고, 서버 재시작 후에는 store에서 resume합니다. 3단계 복구 체인은 전부 자동입니다.

푸시 웨이크업은 무엇을 연결해야 하나요? 세션 서비스는 webhook 연결점만 남기고, 푸시 채널(FCM / APNs / 제조사)은 당신이 직접 연결합니다. v2 프로토콜과 webhook을 참고하세요.

appkey가 유출되면 어떻게 하나요? 즉시 콘솔에서 교체하고, 서버 환경 변수를 업데이트한 뒤 재시작합니다. 이전 appkey는 즉시 무효화됩니다.

아직 해결되지 않았나요?

tansr doctor의 출력(키 값은 포함하지 않음)과 만난 오류 코드를 가지고 지원팀에 문의하세요.