문제 해결 — 가이드 — Agent Switchboard

먼저 확인할 것

앱을 최신 버전으로 업데이트합니다. 많은 문제가 새 버전에서 고쳐졌습니다. 휴대폰이나 다른 PC와 함께 쓰는 기능은 연결한 PC도 최신 버전이어야 합니다.
오류 문구를 그대로 확인합니다. 앱은 원인별로 다른 안내를 보여 줍니다.

설치와 업데이트

Windows에서 SmartScreen 경고가 나옵니다

Windows 설치 파일에 아직 Authenticode 코드 서명이 없어서 생기는 경고입니다. 공식 다운로드 페이지에서 받은 파일인지 확인한 뒤 추가 정보 → 실행을 누릅니다. 자세한 내용은 설치·첫 실행을 참고하세요.

Portable 버전이 스스로 업데이트되지 않습니다

Windows Portable은 앱 안 자동 설치를 지원하지 않습니다. 다운로드 페이지에서 새 파일을 받아 교체합니다. 자동 업데이트가 필요하면 Setup 버전을 쓰세요.

업데이트 서버에 연결하지 못합니다

앱이 업데이트 주소에 닿지 못하면 기본 브라우저에서 릴리스 페이지를 엽니다. 거기서 설치 파일을 직접 받을 수 있습니다. 업데이트에는 계정이나 액세스 토큰이 필요하지 않습니다.

업데이트 알림이 오지 않습니다

나중에를 골랐다면 그 실행 동안 4시간은 다시 알리지 않습니다.
이번 버전 건너뛰기를 골랐다면 그 버전은 자동으로 알리지 않습니다.
상단의 다운로드 아이콘으로 직접 확인하면 보류한 버전과 건너뛴 버전도 다시 보여 줍니다.

업데이트 설치가 실패합니다

실패 이유는 업데이트 창과 재시작 확인 창에 표시됩니다.

macOS: 설치 검증 중 오류나 120초 시간 초과가 나면 다시 시도할 수 있습니다.
Linux .deb: 설치할 때 관리자 권한 창이 떠야 합니다. 3분 안에 권한 창이 뜨지 않으면 설치를 멈추고, 터미널에서 직접 설치하는 명령을 알려 줍니다. 권한 창에서 취소한 경우와 권한을 받지 못한 경우를 구분해 안내합니다.
Linux, 샌드박스 셸에서 앱을 띄운 경우: NoNewPrivs 제한 때문에 권한 상승이 막힐 수 있습니다. 앱은 사용자 systemd로 인증 창을 띄우고, 그래도 안 되면 앱 밖 터미널에서 sudo로 설치하는 방법을 안내합니다.

휴대폰 연결과 QR

「연결 QR 만들기」를 누를 수 없습니다

QR은 PC가 중계 서버에 연결된 뒤에만 만들 수 있습니다. 환경 설정 › 휴대폰에서 휴대폰 연결 켜기가 켜져 있는지, 상태가 연결됨인지 확인하세요.

휴대폰 연결을 켤 수 없습니다

PC가 운영체제 보안 저장소를 쓸 수 없으면 휴대폰 연결을 켤 수 없습니다. 평문으로 대신 저장하지 않습니다. Linux라면 Secret Service 같은 keyring을 켜고 앱을 다시 시작하세요.

QR이 만료됐거나 이미 사용했다고 나옵니다

QR은 5분 동안만 유효하고 한 번만 쓸 수 있습니다. PC에서 새 QR을 만들어 다시 연결하세요.

「연결 시도가 너무 잦습니다」가 나옵니다

인증에 실패한 연결은 PC가 중계 서버를 통해 잠시(약 1분) 막습니다. 1분쯤 기다린 뒤 새 QR로 다시 시도하세요.

「연결이 해제되었습니다」가 나옵니다

PC에서 이 휴대폰의 연결을 끊었거나 데스크톱 신원을 새로 만든 경우입니다. PC에서 새 QR을 만들어 다시 연결하세요. Google 계정으로 연결했다면 PC의 승인 창에서 다시 허용하면 됩니다.

PC가 꺼져 있다고 나옵니다

PC가 켜져 있고 Agent Switchboard가 실행 중인지 확인하세요. PC가 켜지면 자동으로 다시 연결됩니다.

Android 앱이 「네트워크 연결을 확인하세요」만 보여 줍니다

배포 키로 서명한 Android 앱(0.6.0 이상)은 PC 0.65.2 이상에서만 Google 계정 연결을 받습니다. PC 앱을 업데이트하세요.

「Google 계정을 확인하지 못했습니다」가 나옵니다

PC 시계가 늦으면 Google 로그인 증명 확인에 실패할 수 있습니다. PC 0.65.3에서 시계가 조금 늦은 경우를 고쳤습니다. PC 앱을 업데이트하고, 운영체제의 시간 자동 동기화를 켜 두세요.

PC에 「Google에 다시 로그인해 주세요」가 뜹니다

PC의 Google 로그인이 만료된 경우입니다. 환경 설정 › 휴대폰의 Google 다시 로그인을 누르세요. 다시 로그인하기 전에는 다른 기기의 새 연결을 받을 수 없습니다.

Android 앱을 새로 설치할 수 없습니다

예전에 다른 서명으로 만든 APK를 설치했다면 새 APK로 덮어 설치되지 않습니다. 기존 앱을 지우고 새 APK를 설치한 뒤 PC 연결과 Google 로그인을 다시 하세요.

웹 앱 주소가 바뀐 뒤 PC 목록이 비었습니다

휴대폰 웹 앱은 https://app.switchboard.twentyoz.kr에서 제공합니다. 예전 주소에서 쓰던 연결 정보는 새 주소로 옮겨지지 않습니다. QR로 다시 연결하거나, Google 계정을 쓰고 있었다면 다시 로그인해 PC 목록을 불러오세요.

키와 인증

「저장 후 적용」이 꺼져 있습니다(Linux)

OS 보안 저장소(keyring)를 쓸 수 없는 PC에서는 API 키를 저장할 수 없습니다. 버튼 위에 이유가 표시됩니다. keyring을 켜고 앱을 다시 시작하세요.

선택한 모델로 적용되지 않습니다

연결 테스트와 적용 때 선택한 모델을 실제로 쓸 수 있는지 확인합니다. 쓸 수 없으면 적용을 멈춥니다. 목록에서 사용할 수 있는 모델을 다시 고르세요.

CLI가 「credential is not configured」 오류를 냅니다

폴더 연결이 바뀐 뒤 오래된 실행 프로필로 CLI를 띄웠을 때 생길 수 있습니다. 해당 연결을 도구 설정에서 다시 적용하고 CLI를 새로 시작하세요. 폴더에 Codex 설정은 있는데 폴더 연결 프로필이 사라진 경우에는 앱이 저장된 설정으로 프로필을 다시 만듭니다.

「SECURE_STORAGE_BOOTSTRAP_FAILED」가 계속 나옵니다

Agent Switchboard와 관련 프로세스가 모두 종료됐는지 확인합니다.
초기화 도중 강제 종료로 .secure-storage-bootstrap.lock 잠금 파일만 남았다면, 그 파일을 따로 보관한 뒤 지우고 다시 실행합니다.
Local State 파일이나 credentials 폴더는 지우거나 바꾸지 마세요. 원본을 보존한 채 문의해 주세요.

추론 강도를 지원하는지 확인하지 못했다고 나옵니다

지원이 확인되지 않은 추론 강도는 도구 기본값으로 보내고 안내를 남깁니다. 이전 버전에서 이 문구로 대화를 시작하지 못했다면 앱을 업데이트하세요.

Windows에서 OAuth 로그인 창이 빈 터미널로만 열립니다

사용자 PowerShell 시작 프로필이 로그인 명령을 막던 문제입니다. 0.61.2부터 인증 창은 시작 프로필을 건너뜁니다. 앱을 업데이트하세요.

문의할 때

보안과 관련된 문제를 알릴 때는 API 키, OAuth 토큰, 인증 파일, 설정 파일 전체를 첨부하지 마세요. 연결 주소, 운영체제, 앱 버전, 재현 단계, 민감한 값을 가린 오류 문구만 보내 주세요. 문의는 hello@twentyoz.kr로 받습니다.