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)

운영체제 보안 저장소(keyring)를 쓸 수 없는 PC에서는 API 키를 저장할 수 없고, 버튼 위에 그 이유가 나옵니다. keyring을 켜고 앱을 다시 시작하세요.

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

연결 테스트와 적용 단계에서 고른 모델을 실제로 쓸 수 있는지 확인하고, 쓸 수 없으면 적용을 멈춥니다. 목록에서 쓸 수 있는 모델을 다시 고르세요.

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

폴더 연결을 바꾼 뒤 예전 실행 프로필로 CLI를 띄우면 생길 수 있습니다. 도구 설정에서 그 연결을 다시 적용하고 CLI를 새로 시작하세요. 폴더에 Codex 설정은 있는데 폴더 연결 프로필만 사라졌다면, 앱이 저장된 설정으로 프로필을 다시 만듭니다.

「SECURE_STORAGE_BOOTSTRAP_FAILED」가 계속 나옵니다

  1. Agent Switchboard와 관련 프로세스가 모두 종료됐는지 확인합니다.
  2. 초기화 중에 강제로 종료돼 .secure-storage-bootstrap.lock 잠금 파일만 남았다면, 그 파일을 다른 곳에 복사해 둔 뒤 지우고 다시 실행합니다.
  3. Local State 파일이나 credentials 폴더는 지우거나 고치지 마세요. 원본을 그대로 둔 채 문의해 주세요.

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

지원 여부를 확인하지 못한 추론 강도는 도구 기본값으로 보내고 그 사실을 안내합니다. 이전 버전에서 이 문구 때문에 대화를 시작하지 못했다면 앱을 업데이트하세요.

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

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

문의할 때

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