Claude Code + Apple Foundation Models 연동 가이드 (OS 27 베타, 2026)

"Claude를 Swift 앱에 붙이려면 또 별도 SDK를 깔아야 할까요?"

📌 핵심 3줄 요약

• Anthropic이 ClaudeForFoundationModels Swift 패키지를 공개해, Apple Foundation Models 프레임워크의 LanguageModelSession API로 Claude를 호출할 수 있게 됐다.
• 같은 코드에서 model: 인자만 바꾸면 Apple 온디바이스 모델 ↔ Claude 클라우드를 라우팅할 수 있다.
• 현재 OS 27 / Xcode 27 베타 한정, API 변경 가능성 있음.

1. 무엇이 새로 추가됐나

Apple Foundation Models 프레임워크는 macOS 26부터 ~3B 온디바이스 모델을 Swift API로 노출해왔다. OS 27 베타에서 서버사이드 LanguageModel 슬롯이 열렸고, Anthropic이 그 슬롯을 채우는 ClaudeForFoundationModels v0.1.0을 공개했다.

💡 핵심 한 줄

"Claude Code CLI에 로컬 모델을 끼우는" 게 아니라 "Apple Foundation Models 세션에서 Claude를 백엔드로 선택"하는 Swift 패키지다. 방향이 반대다.

2. 설치 요구사항과 셋업

공식 문서가 명시한 요구사항은 다음과 같다.

• iOS 27 / macOS 27 / visionOS 27 / watchOS 27 (모두 베타)
• Xcode 27 (베타)
• Anthropic Console에서 발급한 개발용 API 키

Package.swift · Swift

dependencies: [
  .package(
    url: "https://github.com/anthropics/ClaudeForFoundationModels.git",
    from: "0.1.0"
  )
]

Xcode에서는 File → Add Package Dependencies…에 같은 URL을 넣어도 된다. 이후 import FoundationModels와 import ClaudeForFoundationModels를 함께 선언한다.

3. 같은 코드로 Apple FM과 Claude 라우팅하기

LanguageModelSession 생성 시 model: 인자만 갈아끼우면 백엔드가 바뀐다.

Router.swift · Swift

import FoundationModels
import ClaudeForFoundationModels

let apiKey = ProcessInfo.processInfo.environment["ANTHROPIC_API_KEY"] ?? ""

// 클라우드: 복잡 추론·긴 문맥용
let claude = ClaudeLanguageModel(name: .sonnet4_6, auth: .apiKey(apiKey))

// 온디바이스: 프라이버시 민감 입력용
let onDevice = SystemLanguageModel.default

func session(forSensitive isSensitive: Bool) -> LanguageModelSession {
  let model: any LanguageModel = isSensitive ? onDevice : claude
  return LanguageModelSession(model: model)
}

요청은 앱에서 Claude API로 직접 가며 Apple 서버를 경유하지 않는다. 온디바이스 호출은 디바이스에 머문다.

4. 도구 호출·구조화 출력·MCP 호환성

• 클라이언트 툴: Tool 타입을 LanguageModelSession(tools:)에 그대로 전달.
• 서버 툴(웹 검색·웹 페치·코드 실행): ClaudeLanguageModel(serverTools:)로 모델 단위 설정.
• 구조화 출력: @Generable 타입을 respond(to:generating:)로 요청.

단, Messages API 일부는 프레임워크 프로토콜에 표현이 없어 노출되지 않는다 — 프롬프트 캐싱 제어·stop sequence·Batch·Files API·토큰 카운트. MCP 서버 연결도 Claude Code CLI 쪽 기능이라 이 패키지 범위 밖이다.

5. 온디바이스 vs 클라우드: 어떻게 나눌까

기준	Apple 온디바이스	Claude (클라우드)
모델 규모	~3B 파라미터	Sonnet 4.6 / Opus 4.8
실행 위치	Apple Silicon	Anthropic 인프라
비용	무료	표준 API 과금
오프라인	가능	불가
적합 작업	요약·분류·간단 추출	긴 문맥·복합 추론·툴

실용 기준은 단순하다. 개인정보·짧은 쿼리·오프라인은 온디바이스, 긴 문맥·코드 생성은 Claude. rateLimited나 contextSizeExceeded 발생 시 다른 모델로 폴백하는 패턴도 공식 문서가 권장한다.

⚠️ 단점과 주의할 점

• OS 27/Xcode 27 베타에서만 동작. 일반 배포 앱에 지금 넣으면 안 된다.
• .apiKey는 개발용. 출시 시 반드시 .proxied로 자체 백엔드를 경유시킨다.
• 베타 기간 동안 외부 PR을 받지 않고, 일부 Messages API 기능은 사용 불가.

🚀 지금 바로 할 일

1. Apple Developer에서 macOS 27 / Xcode 27 베타 프로파일 신청.
2. ClaudeForFoundationModels 레포의 Examples/ClaudeExample을 클론해 --search 플래그까지 실행.
3. 기존 Swift 앱에서 SystemLanguageModel.default를 쓰던 자리에 ClaudeLanguageModel을 분기로 끼워 응답 속도·품질을 측정.

💬 의견

Swift 앱에서 온디바이스 모델과 클라우드 LLM을 같은 API로 다뤄본 경험이 있다면, 어떤 기준으로 라우팅을 나눴는지 댓글로 공유 부탁드립니다.

✅ 핵심 정리

• Foundation Models 세션에 Claude를 끼우는 Swift 패키지(v0.1.0, Apache 2.0).
• OS 27 / Xcode 27 베타 한정. macOS 26에선 Apple 온디바이스 모델만 동작.
• model: 인자만 바꿔 라우팅. 트래픽은 Apple 서버를 경유하지 않는다.

참고 자료

• Anthropic — Apple Foundation Models 공식 가이드
• GitHub — anthropics/ClaudeForFoundationModels
• Apple Developer — Foundation Models 프레임워크 문서
• WWDC26 — Bring an LLM provider to the Foundation Models framework

---

작성자: AI·개발자 도구 도메인을 추적하는 기술 블로그 운영자. Anthropic·Apple 공식 문서를 1차 자료로 검증해 작성합니다. 본문 코드와 요구사항은 2026-06-15 기준 공식 문서(platform.claude.com/docs, github.com/anthropics/ClaudeForFoundationModels)를 인용했습니다.