iOS 앱 클로드 연동 — 키 없이 앱 증명·온디바이스와 같은 코드

아이폰 앱에 AI를 붙이려면 보통 둘 중 하나를 포기해야 했습니다. 기기 안 모델을 쓰면 무거운 일을 못 시키고, 바깥 모델을 쓰면 열쇠를 어디에 둘지부터 골치가 아팠으니까요.

애플 프레임워크에 클로드를 꽂아 주는 스위프트 꾸러미가 나왔습니다. 기기 안 모델과 코드가 똑같고, 앱에 열쇠를 안 싣고도 중계 서버 없이 출시할 수 있습니다.

📌 30초 요약

• 기기 안 모델과 같은 세션 코드로 돌아갑니다. 인자만 바꾸면 됩니다.
• 요청은 앱에서 곧바로 갑니다. 애플은 경로에 없습니다.
• 앱 증명을 쓰면 열쇠도 중계 서버도 없이 출시됩니다.
• 속도 제한에 걸린 턴만 기기 안 모델로 되돌리는 방식이 권장됩니다.

1. 기기 안 모델과 같은 코드로

이 꾸러미가 하는 일은 클로드를 애플 프레임워크의 언어 모델 규약에 맞춰 주는 것입니다. 그래서 기기 안 모델을 쓰던 그 세션 방식 그대로 굴립니다. 한 번에 답받기, 흘려 받기, 정해진 형태로 받기, 도구 호출까지 전부 같은 방법으로 돌아갑니다.

그러니 갈아타는 비용이 거의 없습니다. 세션에 넘기는 모델 인자만 바꾸면 끝이니까요. 문서는 기준을 이렇게 줍니다 — 기기 안 모델은 빠르고, 사적이고, 통신 없이도 되지만 가벼운 일에 맞춰진 크기입니다. 맥락이 크거나, 어려운 추론이 필요하거나, 웹 검색·코드 실행 같은 바깥 도구가 필요할 때 올려 보내라는 것입니다.

경로 이야기도 분명합니다. 요청은 앱에서 클로드로 곧장 갑니다. 애플은 그 경로에 끼지 않고 프롬프트도 응답도 보지 못합니다. 대신 사용량은 내 계정으로 청구되니 잔액이나 결제 수단이 살아 있어야 하고요. 기기 안 처리와 바깥 처리의 경계를 어떻게 알리느냐는 애플 인텔리전스가 스위치 대신 리포트를 택한 이야기와 나란히 놓고 볼 만합니다.

2. 열쇠를 안 싣고 출시하는 법

가장 반가운 대목입니다. 앱 증명을 쓰면 설치본 하나하나가 애플 서비스를 통해 「내가 등록한 그 앱이 맞고 손대지 않았다」는 것을 증명합니다. 그러면 앤트로픽이 그 기기에 한 시간짜리 임시 출입증을 내주고, 사용량은 내 작업공간으로 달립니다.

핵심은 앱이 아무 열쇠도 품지 않는다는 것입니다. 돌려야 할 중계 서버도 없고요. 증명을 주고받는 절차는 꾸러미가 알아서 하고 만료되면 다시 받아 옵니다. 개발자가 쓸 증명 코드가 아예 없습니다. 자격을 앱에 넘기지 않고 바깥에서 붙이는 이 발상은 에이전트에게 비밀값을 안 보여 주는 금고와 같은 계열입니다.

⚠️ 개발용 열쇠를 그대로 내보내면 안 됩니다

시뮬레이터에서는 앱 증명이 안 됩니다. 보안 장치가 있는 실제 기기가 필요하거든요. 그래서 개발 중에는 열쇠를 직접 넣고 돌리게 되는데, 그 상태로 출시하면 바이너리에서 열쇠를 뽑아낼 수 있습니다. 뽑아낸 사람의 요청이 전부 내 계정으로 청구됩니다.

그리고 사고가 났을 때 앱 연결을 취소하면 발급된 출입증이 전부 무효가 되고 등록된 기기도 새로 받지 못합니다. 다만 취소는 되돌릴 수 없어서 다시 쓰려면 연결을 새로 만들어야 합니다.

3. 인증 세 갈래

방식	쓸 자리와 조건
앱 증명	뒷단 없이 출시 · 실제 기기만 · 클로드를 직접 부를 때만
중계 서버	내 서버가 자격을 붙여 전달 · 머리글로 호출자 확인 가능
열쇠 직접	개발 중에만 · 출시본에 넣으면 추출됨

주의할 단서가 하나 있습니다. 앱 증명은 클로드를 직접 부를 때만 됩니다. 세 곳의 큰 클라우드를 거쳐 쓰는 구성에서는 못 씁니다. 그리고 출입증은 메시지 호출만 할 수 있게 범위가 잘려 있고, 등록할 수 있는 앱 묶음 이름은 서른두 개까지입니다. 설정하려면 애플 개발자 팀 식별자와 조직 관리자 권한이 필요하고요.

4. 모델마다 받는 것이 다릅니다

꾸러미가 유난히 깐깐한 지점입니다. 모델마다 받아 주는 요청 항목이 다르고, 안 받는 항목을 보내면 그 자리에서 오류가 납니다. 그래서 미리 담긴 모델 상수들은 각자 무엇을 받는지 달고 다닙니다. 아직 안 담긴 새 모델을 쓰려면 내가 직접 적어 줘야 하는데, 알아서 추측해 주는 지름길은 일부러 만들지 않았다고 적혀 있습니다. 조용히 틀리느니 시끄럽게 멈추자는 쪽입니다.

생각의 깊이를 정하는 노력 수준에도 어긋남이 있습니다. 애플 프레임워크가 이름 붙여 둔 추론 단계는 높음까지가 끝인데 클로드 쪽은 그 위로 두 단계가 더 있습니다. 그래서 더 세게 돌리려면 그 이름을 사용자 지정 값으로 직접 적어 넘겨야 합니다. 아무것도 안 보내면 높음으로 도는데, 지출을 묶고 싶다면 노력 수준에 상한을 걸어 두는 설정을 같이 보세요.

같은 태도가 정해진 형태로 받기에서도 나옵니다. 그 기능을 못 받는 모델을 골랐다면 모양을 슬쩍 포기하고 아무 글이나 돌려주는 대신 오류를 던집니다. 흘려 받을 때도 한 번 짚어 둘 게 있는데, 조각조각 오는 것이 아니라 매번 지금까지의 답 전체가 통째로 옵니다. 앞의 것에 이어 붙이는 코드를 짜 두면 같은 문장이 겹쳐 쌓입니다. 이미지를 넣는 것은 받아 주는 모델에 한해 프레임워크의 표준 방식 그대로 되고, 꾸러미가 알아서 형식을 바꿔 보냅니다.

이 길로는 못 쓰는 것	사정
캐시 조절	캐시는 알아서 걸리지만 유지 시간·끊는 지점은 못 정함
토큰 세기 · 묶음 처리	애플 규약에 자리가 없어 아예 노출되지 않음
정지 문구 · 파일 올리기	같은 이유로 빠짐 · 필요하면 따로 부르는 수밖에

대신 오류를 애플 쪽 형태로 바꿔 줍니다. 맥락이 넘치면 맥락 초과로, 호출이 몰리면 속도 제한으로, 시간이 지나면 시간 초과로 떨어집니다. 여기서 문서가 알려 주는 실전 패턴 하나가 값집니다 — 속도 제한이 잡히면 그 턴만 기기 안 모델로 되돌려 답하게 하라는 것입니다. 같은 세션 방식을 쓰니 가능한 일이고요. 앱에 AI를 붙이는 순서를 잡는 중이라면 AI 도입 한 바퀴를 모아 둔 글도 같이 보시면 좋습니다.

자주 묻는 질문 (FAQ)

Q. 애플이 제 앱의 대화를 들여다보나요?

아닙니다. 요청은 앱에서 클로드로 곧장 가고 애플은 그 경로에 끼지 않습니다. 프롬프트도 응답도 애플을 거치지 않습니다. 다만 사용량이 내 계정으로 청구된다는 점은 기기 안 모델과 결정적으로 다릅니다. 기기 안 모델은 공짜지만 이쪽은 쓴 만큼 냅니다.

Q. 사용자마다 구분해서 관리할 수 있나요?

출입증만으로는 안 됩니다. 문서가 못 박아 뒀습니다 — 앱 증명은 앱을 식별하지 사람을 식별하지 않습니다. 발급된 출입증에는 최종 사용자의 신원이 담기지 않습니다. 그래서 사용자별 한도나 구독 상태 같은 것은 앱 쪽에서 따로 처리해야 합니다. 그게 부담이면 중계 서버 방식이 낫습니다.

Q. 웹 검색 같은 기능도 앱에서 되나요?

됩니다. 웹 검색·웹 가져오기·코드 실행은 앤트로픽 쪽에서 한 번의 왕복 안에 처리하고 돌아옵니다. 기기에서 실행할 게 없다는 뜻입니다. 허용·차단할 도메인과 최대 사용 횟수도 정할 수 있고요. 다만 대화별로 다른 도구 묶음을 쓰려면 모델 객체를 여러 개 만들어야 합니다.

Q. 지금 바로 실무에 써도 되나요?

아직은 이릅니다. 운영체제도 개발 도구도 베타 단계인 버전이 필요하고, 문서 스스로 베타 동안 방식이 바뀔 수 있다고 적어 뒀습니다. 공개 저장소에 예제가 함께 올라와 있어 미리 만져 보기에는 충분하지만, 베타 기간에는 외부 기여를 받지 않는다는 점도 같이 적혀 있습니다.

정리하면

• 기기 안 모델과 코드가 같습니다. 인자만 바꾸세요.
• 출시본에는 앱 증명이나 중계 서버를, 열쇠는 개발용으로만.
• 사용자 구분이 필요하면 앱에서 따로 하세요.
• 속도 제한이 나면 그 턴만 기기 안 모델로 돌리면 됩니다.

※ 공개된 안내 문서를 읽고 정리했습니다. 형식 이름·설정 항목·메뉴는 우리말로 풀어 적었고, 직접 앱에 붙여 빌드해 보지는 않았습니다.

※ 운영체제·개발 도구·이 꾸러미 모두 베타 단계라 방식이 바뀔 수 있습니다. 등록 개수·출입증 유지 시간·지원 범위는 열람 시점 기준입니다. 요금은 표준 요금제로 내 계정에 청구되므로, 기기 안 모델로 충분한 일까지 올려 보내지 않도록 경계를 먼저 정하세요.