안드로이드 AI 모델 API 설정: 연결·이미지·도구 호출 확인하기
FoneClaw의 기본 모델 또는 호환 API를 설정하고 제공자 사전 설정, 기본 URL, API 키, 모델 ID와 이미지·도구 지원을 확인합니다. 모델 종료와 Android 권한 오류도 구분하세요.
- FoneClaw는 무료 기본 모델로 시작하거나 호환되는 온라인 모델 API를 설정해 사용할 수 있습니다. 챗봇 앱의 유료 구독과 API 계정·이용 권한·과금은 별도로 확인해야 합니다.
- 제공자 사전 설정, API 기본 URL, API 키, 모델 ID는 서로 다른 역할을 합니다. 이미지·도구 지원 옵션도 선택한 모델과 엔드포인트가 실제로 제공하는 기능에 맞춰 설정해야 합니다.
- 연결 검증은 무해한 텍스트 요청, 직접 선택한 이미지 해석, 낮은 위험의 Android 도구 실행 순서로 나눕니다. 텍스트 응답 성공만으로 이미지 이해나 도구 호출까지 확인된 것은 아닙니다.
- 모델 지원 종료와 Android 권한 오류는 별개입니다. 모델을 바꾼 뒤에는 세 단계 검증을 다시 하고, 중단된 작업을 재시도하기 전에 대상 앱에 이미 남은 결과부터 확인하세요.
기본 모델을 쓸지, 내 API를 연결할지 먼저 정하기
안드로이드 AI 모델 API 설정은 먼저 기본 모델과 사용자 API 중 어느 경로를 쓸지 정하는 데서 시작합니다. FoneClaw에는 무료 기본 모델이 있어 별도 API 자격 증명 없이 시작할 수 있습니다. 익숙한 모델이나 업무에 맞춘 모델을 쓰고 싶다면 호환되는 온라인 제공자의 API를 설정하세요. 이 설정은 FoneClaw 안에서 요청을 해석하고 계획할 모델을 선택하는 과정입니다. 소비자용 챗봇 앱을 유료로 구독하고 있더라도 API 사용 권한이나 결제가 함께 제공된다고 가정해서는 안 됩니다.
모델은 사용자의 요청을 이해하고 계획을 세우며, 실제 휴대폰 작업은 FoneClaw의 활성화된 Android 도구가 필요한 권한과 실제 승인 정책 안에서 처리합니다. 따라서 모델 연결이 성공해도 모든 Android 작업이 자동으로 가능해지는 것은 아닙니다. 모델 설정은 시작점이고, 폰 작업은 별도의 실행 조건을 갖습니다.
| 선택지 | 필요한 준비 | 적합한 경우 | 확인할 점 |
|---|---|---|---|
| 무료 기본 모델 | 추가 API 자격 증명 없음 | 처음 시작하고 낮은 위험 작업을 확인할 때 | 지원되는 작업과 권한 안내 |
| 호환 온라인 모델 API | 호환 기본 URL, API 키, 정확한 모델 ID | 선호 모델이나 업무 계정의 API를 사용할 때 | 계정 접근, 과금, 프로토콜과 이미지·도구 지원 |
이 글은 텍스트 응답을 받는 것에서 멈추지 않고, 선택한 모델이 이미지와 지원 Android 도구를 필요한 조건 안에서 사용할 수 있는지 확인하는 순서까지 다룹니다.
제공자 사전 설정·기본 URL·API 키·모델 ID 구분하기
FoneClaw의 온라인 제공자 사전 설정은 연결값을 구성하는 데 도움을 줍니다. 하지만 사전 설정을 고른 것만으로 계정에 모델 접근 권한이 생기거나 모든 기능의 호환성이 확인되지는 않습니다. API 기본 URL은 요청을 보낼 서비스 주소이고, API 키는 계정이나 프로젝트의 요청을 인증하는 비밀 값입니다. 모델 ID는 그 엔드포인트에서 실제로 사용할 수 있는 모델의 정확한 식별자입니다.
| 설정 | 역할 | 확인할 점 |
|---|---|---|
| 제공자 사전 설정 | 제공자별 연결 설정을 돕는 선택지 | 현재 계정과 사용하는 API 경로에 맞는지 |
| API 기본 URL | 호환 서비스의 기본 요청 주소 | 홈페이지 주소가 아닌 문서화된 API 주소인지 |
| API 키 | 요청을 인증하는 비밀 값 | 유효한 키와 프로젝트 권한인지 |
| 모델 ID | 선택한 API에서 호출할 모델 식별자 | 표시 이름이 아닌 정확한 API용 이름인지 |
| 이미지·도구 지원 | 모델 요청에 사용할 기능을 설정 | 모델과 엔드포인트의 실제 지원 여부 |
기본 URL과 모델 이름은 제공자마다 다를 수 있습니다. Google의 Gemini API의 OpenAI 호환성 안내도 해당 제공자의 주소와 모델 이름을 함께 확인해야 하는 사례입니다. OpenAI 형식의 호환 경로와 다른 제공자의 고유 API는 같은 주소를 넣는 것으로 바꿔 쓸 수 있는 관계가 아닙니다. 사용하는 엔드포인트의 문서와 FoneClaw의 호환 조건을 함께 확인하세요.
API 키는 비밀번호처럼 다뤄야 합니다. OpenAI의 API 인증 문서처럼 키 인증을 사용하는 서비스에서는 실제 키를 채팅, 스크린샷, 공개 이슈나 문서 예시에 남기지 마세요. 노출이 의심되면 제공자 콘솔에서 폐기하고 새 키를 발급하세요. API 키는 모델 요청을 인증하지만 연락처, 위치, 알림 같은 Android 자원 접근을 허용하는 값은 아닙니다.
FoneClaw에서 제공자와 지원 기능 설정하기
설정 전에 제공자 쪽에서 호환 기본 URL, API 키, 사용 가능한 모델 ID, 이용 한도와 과금 방식을 확인합니다. 이어서 모델의 이미지 입력과 도구 호출 지원을 살펴보세요. 저희 FoneClaw에서는 온라인 제공자 사전 설정과 이미지·도구 지원 옵션을 사용할 수 있습니다. 이 옵션은 실제 지원 기능에 맞춰 요청을 구성하기 위한 설정이며, 지원하지 않는 모델에 이미지 이해나 도구 호출 능력을 추가하지는 않습니다.
- FoneClaw의 모델 설정에서 기본 모델과 사용자 온라인 모델 중 사용할 경로를 정합니다.
- 사용자 모델이라면 해당하는 제공자 사전 설정을 선택하고 연결값을 확인합니다.
- 기본 URL을 제공자의 문서화된 호환 엔드포인트에 맞춥니다.
- API 키를 필요한 설정 항목에만 입력하고 화면 공유에 노출하지 않습니다.
- 현재 계정으로 사용할 수 있는 정확한 모델 ID를 입력합니다.
- 이미지·도구 지원 옵션을 모델과 엔드포인트의 실제 기능에 맞춥니다.
- 설정을 저장하고 사용할 모델을 선택한 뒤 단계별 검증을 진행합니다.
FoneClaw는 사용자가 선택한 큰 이미지의 크기를 최적화하고 방향을 처리하지만, 내용을 이해하려면 이미지 입력을 지원하는 호환 모델이 필요합니다. 도구 호출도 모델의 지원과 FoneClaw에서 활성화한 Android 도구, 필요한 권한이 모두 맞아야 합니다.
실행 구조를 더 깊게 보려면 AI 에이전트 Android 휴대폰 제어: 의도에서 확인, 실행, 검증까지에서 요청이 도구와 실제 결과로 이어지는 과정을 확인하세요. FoneClaw Android 프로젝트도 공개 제품 경로를 확인하는 출처이며, 실제 설정은 앱에 표시된 현재 항목과 안내를 기준으로 진행하면 됩니다.
텍스트·이미지·Android 도구를 따로 검증하기
모델을 저장했다면 첫 요청은 휴대폰 상태를 바꾸지 않는 짧은 텍스트로 정하세요. “세 문장으로 할 일 목록을 정리하는 형식을 제안해 줘”처럼 외부 결과가 없는 요청이 적합합니다. 정상적인 답변을 받으면 기본 URL, 인증과 모델 선택이 텍스트 요청에서 작동했음을 확인할 수 있습니다. 아직 이미지나 도구 호출까지 검증된 것은 아닙니다.
다음은 민감한 정보가 없는 사진을 직접 선택해 짧게 설명하도록 요청합니다. 이미지 입력을 지원하는 모델과 호환 경로를 사용하고, 이미지 지원 설정도 확인하세요. 답변이 첨부한 사진의 실제 내용과 맞는지 대조합니다. 텍스트 대화가 이어진다는 사실이나 일반적인 이미지 설명만으로 사진이 전달됐다고 판단하지 마세요.
| 검증 단계 | 요청 예 | 완료 확인 |
|---|---|---|
| 텍스트 | 짧은 정리 형식 제안 | 오류 없이 요청에 맞는 답변을 받음 |
| 선택한 이미지 | 사진에 보이는 물건 설명 | 답변을 실제 이미지와 대조 |
| 지원 Android 도구 | 현재 미디어 볼륨 조회 | 도구 실행 결과와 기기 상태 확인 |
마지막으로 활성화한 낮은 위험 도구 하나를 확인합니다. 현재 미디어 볼륨이나 Bluetooth 상태 조회처럼 외부에 전송하거나 기록을 변경하지 않는 요청이 좋습니다. 모델이 요청을 설명하는 데서 끝났는지, 실제로 지원 도구를 호출했는지 구분하세요. 필요한 권한과 실제 승인 정책이 적용된 뒤 도구 결과를 확인해야 합니다. 답장 문구를 작성하는 텍스트 요청만으로는 Android 도구 실행을 검증할 수 없습니다.
실패한 단계부터 찾아 오류 해결하기
오류는 발생한 단계와 함께 읽어야 합니다. 텍스트 요청부터 실패하면 인증, 엔드포인트, 모델 접근과 네트워크를 먼저 봅니다. 텍스트만 성공하면 이미지·도구 지원과 요청 호환성을 확인하고, Android 도구 실행 중 막혔다면 권한, 앱 상태와 정책을 봅니다. 한 단계의 성공을 다른 단계의 성공으로 확대하지 않는 것이 진단의 핵심입니다.
| 증상 | 확인할 부분 | 다음 조치 |
|---|---|---|
| 401 또는 인증 실패 | 키, 프로젝트와 API 접근 권한 | 키 상태와 앞뒤 공백, 계정 권한 확인 |
| 404 또는 모델을 찾을 수 없음 | 기본 URL, API 경로와 모델 ID | 호환 경로와 현재 계정의 정확한 모델 이름 확인 |
| 모델 지원 중단 안내 | 사용 중단 예고와 실제 종료 상태 | 제공자·파트너의 일정과 대체 모델 확인 |
| 시간 초과 | 네트워크, 요청 크기와 제공자 상태 | 짧은 텍스트 요청으로 원인 좁히기 |
| 텍스트는 되지만 이미지 실패 | 이미지 지원 설정, 모델의 시각 입력과 엔드포인트 호환성 | 작은 비민감 이미지로 다시 확인 |
| 텍스트는 되지만 도구 호출 실패 | 모델의 도구 호출 지원과 요청 형식 | 호환 조건과 활성화된 도구 확인 |
| Android 도구 실행 중 차단 | 자원 권한, 앱 로그인·상태와 실제 승인 정책 | 해당 실행 조건을 확인한 뒤 필요한 단계만 재시도 |
401과 404의 세부 의미는 제공자마다 다를 수 있으므로 오류 코드와 응답 내용을 함께 확인하세요. 일시적인 제공자 장애가 의심된다면 Android AI 어시스턴트 모델 장애 복구: 안전 재시도와 모델 전환 가이드에서 재시도와 전환 기준을 살펴볼 수 있습니다.
올바른 API 키는 모델 요청을 인증하고, Android 권한은 휴대폰 자원 접근을 허용합니다. 둘을 혼동하면 모델 오류를 해결하려고 불필요한 권한을 바꾸게 됩니다. 모델과 실행의 차이는 DeepSeek AI agent가 Android 휴대폰을 직접 제어할 수 있을까?에서도 확인할 수 있습니다.
모델 선택과 지원 종료 일정 확인하기
Android 작업용 모델은 지시 이해, 도구 호출 지원, 필요한 맥락과 이미지 입력, 비용, 응답 지연을 함께 보고 고르세요. 짧은 상태 조회와 긴 메일 요약은 요구가 다릅니다. 작업별 선택을 더 살펴보려면 Kimi K3, DeepSeek V4, GLM-5.2: 폰 에이전트 모델 선택 기준을 참고할 수 있습니다. 특정 모델을 추론 계층으로 구성하는 예는 Grok이 Android 휴대폰을 제어할 수 있나: 전화, 비서 설정, FoneClaw 모델 구성에서 다룹니다.
모델 수명주기도 연결 설정의 유지 관리 항목입니다. Anthropic의 모델 지원 종료 문서는 공식 API의 claude-sonnet-4-5-20250929에 대해 2026년 9월 30일 사용 중단 예고, 2026년 11월 30일 종료 예정과 권장 대체 모델 claude-sonnet-5-5를 안내합니다. 사용 중단이 예고된 모델은 종료 전까지 작동할 수 있으며, 실제 종료된 모델의 요청은 실패합니다. 9월 30일 안내를 이미 호출이 종료됐다는 뜻으로 읽어서는 안 됩니다.
이 일정은 Anthropic이 운영하는 플랫폼 기준이며 파트너 플랫폼은 별도 일정을 정할 수 있습니다. 공식 권장 대체 모델이 있다는 사실도 FoneClaw에 구성한 엔드포인트의 호환성을 증명하지는 않습니다. 해당 계정의 모델 ID와 프로토콜을 확인하고, Anthropic 고유 Messages API 주소를 OpenAI 형식의 호환 설정에 그대로 넣지 마세요. 제공자나 모델을 바꿨다면 텍스트, 이미지, 도구 검증을 다시 해야 합니다.
설정을 다시 검증하고 미완료 작업 이어가기
모델 변경 뒤에는 짧은 텍스트 요청부터 확인하고, 필요한 경우 이미지 입력과 낮은 위험의 Android 상태 조회를 이어서 검증하세요. 선택한 모델은 FoneClaw 안에서 해석과 계획을 맡고, 활성화된 도구는 필요한 권한, 앱 상태와 실제 승인 정책 안에서 실행합니다. 모든 도구가 같은 방식으로 승인을 요청한다고 가정하지 말고 현재 정책을 확인하세요.
이전에 중단된 요청이 있다면 재실행 전에 대상 앱의 결과부터 봅니다. 메일 전송 결과가 불분명하면 의도한 계정의 발송 기록을, 일정 저장이 불분명하면 대상 캘린더의 실제 항목을 확인하세요. 모델을 바꾸는 것은 이미 완료된 외부 작업을 되돌리지 않습니다. 결과가 없음을 확인한 뒤 미완료 단계만 이어가야 중복 전송이나 저장을 줄일 수 있습니다. 단계별 복구는 휴대폰 AI 에이전트 실패 디버깅과 복구: 권한, 도구 단계, 재시도 실전 런북에서 자세히 다룹니다.
지원되는 설정과 Android 작업은 FoneClaw 기능 페이지에서, 설치 경로는 FoneClaw 다운로드 페이지에서 확인할 수 있습니다. 온라인 모델에는 사용자가 제공한 요청과 선택한 이미지 등 문맥이 전달될 수 있으므로 검증에 필요한 정보만 사용하세요. 최종 성공은 모델의 완료 문구가 아니라 도구 결과와 의도한 위치에 남은 실제 상태로 확인합니다.