Source: https://aiprimetech.io/ko/learn/use-claude-api-with-factory-droid/

[홈](/ko/) / [학습](/ko/learn/) / Claude로 Factory Droid 실행하기 

# Claude로 Factory Droid 실행하기 

Factory의 Droid는 Claude Code와 같은 계열의 에이전트형 CLI로, 설정 파일을 통해 원하는 모델을 직접 연결할 수 있습니다. AI Prime Tech 게이트웨이를 연결하면 게이트웨이가 제공하는 다른 모델들과 함께 Claude를 사용해 Droid의 에이전트 루프를 실행할 수 있습니다. 

## 설정 파일 편집 

Droid는 ~/.factory/settings.json을 읽습니다. 사용할 모델마다 항목을 정의하는 customModels 배열을 추가하세요. 이것이 현재 사용하는 설정 경로입니다. 이전 config.json은 레거시 파일이며 settings.json의 모든 기능을 지원하지는 않습니다. 

파일 하나로 Droid 설정 전체를 관리하므로, 하나의 customModels 목록에서 CLI가 전환할 수 있는 모든 모델을 정의합니다. 프로젝트별로 두지 말고 사용자 수준에서 관리하세요. 

settings.json이 현재 사용하는 파일이라는 점을 알면 혼동을 크게 줄일 수 있습니다. 예전 안내와 토론에서는 여전히 config.json을 참조하며, 일부 기능은 두 파일에서 다르게 동작하기 때문입니다. 한쪽에서는 작동하고 다른 쪽에서는 작동하지 않는다면, 거의 항상 settings.json을 기준으로 판단하면 됩니다. 안내가 서로 충돌할 때 config.json보다 settings.json을 우선하면 대부분 해결됩니다. Factory가 적극적으로 지원하는 것은 새 파일이며, 변수 구문도 이 파일에서 실제로 작동합니다. 

## 모델 정의 

각 customModels 항목에는 모델 ID, baseUrl, apiKey, provider, maxOutputTokens가 들어갑니다. model은 claude-sonnet-4-5 같은 게이트웨이 ID로, baseUrl은 게이트웨이 호스트로 설정하세요. 

이 필드들은 함께 Droid가 모델에 접근하는 정확한 방법을 지정합니다. Droid는 특정 공급자를 전제로 하지 않으므로 각 요소를 명시해야 하며, 덕분에 게이트웨이를 대상으로 유연하게 설정할 수 있습니다. 

이처럼 명시적으로 설정하기 때문에 하나의 Droid 설치에서 같은 게이트웨이의 여러 Claude 모델을 사용할 수 있습니다. 각 모델은 baseUrl과 키를 공유하는 별도의 customModels 항목으로 정의됩니다. 모두 동일한 업스트림 엔드포인트로 연결되더라도 CLI에서는 각각 선택 가능한 별도 모델로 취급합니다. 하나의 설치에서 하나의 엔드포인트를 통해 여러 Claude 모델을 사용하는 구성을 가능하게 하는 것이 바로 이 명시적 필드들입니다. 각 항목은 baseUrl과 키를 공유하면서 고유한 모델 ID를 유지하므로, 라우팅은 게이트웨이가 처리하고 Droid는 이름만 선택합니다. 

## 공급자 모드 선택 

provider 필드는 통신 형식을 설정합니다. 게이트웨이의 네이티브 Messages 인터페이스에는 anthropic을, Responses 방식에는 openai를, OpenAI 형식의 /v1 채팅 엔드포인트에는 generic-chat-completion-api를 사용하세요. 게이트웨이에서 Claude를 사용한다면 anthropic이 자연스러운 선택입니다. 

provider를 게이트웨이의 실제 인터페이스와 일치시키면 첫 실행 시 오류를 방지할 수 있습니다. provider를 anthropic으로 설정하면 Droid는 게이트웨이가 Claude용으로 제공하는 네이티브 형식으로 통신합니다. 

세 가지 공급자 모드는 다중 모델 게이트웨이가 제공할 수 있는 인터페이스에도 잘 대응합니다. 따라서 같은 게이트웨이가 OpenAI 형식의 모델을 제공한다면 generic-chat-completion-api를 사용하는 별도 항목으로 추가하면 됩니다. 각 항목의 provider를 해당 인터페이스와 일치시키는 것이 혼합 구성에서 오류를 방지하는 원칙입니다. 모든 항목에서 provider와 인터페이스를 맞추는 것이 혼합 게이트웨이 구성을 깔끔하게 유지하는 원칙입니다. 네이티브 Claude 항목과 OpenAI 형식의 항목은 문제없이 함께 사용할 수 있습니다. 

## API 키 처리 

키를 apiKey에 넣으세요. 비밀 값이 파일 대신 환경에 유지되도록 ${AIPRIME_API_KEY} 같은 ${VAR} 참조를 사용하는 것이 좋습니다. ${VAR} 확장은 settings.json에서는 작동하지만 레거시 config.json에서는 작동하지 않습니다. 

기술적으로 익명 요청을 허용하는 게이트웨이에서도 apiKey 필드는 비워 둘 수 없습니다. Droid는 이 필드에 값이 있는지 검증하므로, 항상 키 또는 키가 들어 있는 변수를 제공하세요. 

이 두 가지 사실을 함께 보면 흔히 겪는 문제를 이해할 수 있습니다. 이전 config.json에 ${VAR}를 넣으면 확장되지 않아 Droid는 해석되지 않은 문자열을 그대로 읽습니다. 변수 형식에는 settings.json을 사용하고, Droid를 실행하는 셸에서 해당 변수가 실제로 export되어 있는지 확인하세요. 실행하는 셸에서 변수가 export되어 있는지 확인하는 단계는 사람들이 자주 놓치는 마지막 요소입니다. Droid는 자신을 시작한 환경에 있는 변수만 볼 수 있습니다. 

## 전환 및 실행 

Droid CLI 안에서 /model 명령으로 설정된 모델 간에 전환하세요. claude-opus-4-8에 대한 두 번째 항목을 추가하면 설정을 다시 수정하지 않고도 더 어려운 작업에 해당 모델을 사용할 수 있습니다. 

이후 Droid는 게이트웨이의 Claude를 대상으로 에이전트 루프를 실행합니다. 설정이 settings.json에 저장되므로 CLI를 시작할 때마다 같은 설정이 적용됩니다. 

Sonnet과 Opus 항목을 모두 준비해 두면 작업에 맞춰 즉시 모델을 선택할 수 있습니다. 꾸준한 구현 작업에는 Sonnet을, 더 깊은 추론이 필요한 문제에는 Opus를 사용하며, 모두 설정 변경 없이 게이트웨이를 통해 실행됩니다. /model 전환 명령을 사용하면 세션 도중 한 줄로 변경할 수 있습니다. 세션 도중 한 줄의 /model 명령으로 전환할 수 있기 때문에 작업에 맞는 모델을 손쉽게 선택할 수 있습니다. 세션을 떠나지 않고 Sonnet에서 Opus로 전환할 수 있습니다. 

복사

```
// ~/.factory/settings.json
{
  "customModels": [
    {
      "model": "claude-sonnet-4-5",
      "baseUrl": "https://aiprimetech.io",
      "apiKey": "${AIPRIME_API_KEY}",
      "provider": "anthropic",
      "maxOutputTokens": 8192
    }
  ]
}
// export AIPRIME_API_KEY=<key>   (apiKey must NOT be empty)
// Switch models in the CLI with /model
```

## 자주 묻는 질문 

 Claude로 Factory Droid를 실행하려면 어떻게 하나요?

~/.factory/settings.json에 provider anthropic, baseUrl https://aiprimetech.io,, 모델 ID, apiKey를 포함하는 customModels 항목을 추가하세요. /model로 전환하세요. Claude에는 어떤 provider 값을 사용하나요?

네이티브 Messages 인터페이스에는 anthropic을 사용합니다. openai 또는 generic-chat-completion-api는 OpenAI 형식의 엔드포인트를 대상으로 합니다. apiKey를 비워 둘 수 있나요?

아니요. Droid는 값을 요구합니다. ${AIPRIME_API_KEY} 같은 ${VAR} 참조를 사용하세요. 확장은 settings.json에서 작동하며, 레거시 config.json에서는 작동하지 않습니다. 모델은 어떻게 전환하나요?

Droid CLI에서 /model 명령을 사용하면 customModels 목록의 모든 항목 간에 전환할 수 있습니다.  

몇 분 만에 Claude 사용 시작하기

API 키를 발급받으세요 — Anthropic 계정이나 대기자 명단 등록이 필요하지 않습니다.[API 키 발급받기](/register) 

AI Prime Tech는 독립적인 API 게이트웨이입니다. Anthropic과 제휴 관계가 없으며, Anthropic의 보증을 받거나 Anthropic의 리셀러로 활동하지 않습니다. Claude 및 관련 모델 이름은 각 소유자의 상표입니다.    

## 더 많은 Claude API 가이드

[Claude API 키 발급 방법](/ko/learn/how-to-get-a-claude-api-key/)[Claude API 요금 해설](/ko/learn/claude-api-pricing-explained/)[Claude API를 가장 저렴하게 사용하는 방법](/ko/learn/cheapest-way-to-use-claude-api/)[Claude API로 Cursor 무제한 사용](/learn/use-claude-api-with-cursor/)[Claude Code 무제한 이용](/ko/learn/use-claude-api-with-claude-code/)[Claude API 게이트웨이와 Anthropic 직접 이용 비교](/ko/learn/claude-api-vs-anthropic-direct/)[OpenAI 호환 API를 통해 Claude 사용하기](/ko/learn/openai-compatible-claude-api/)[Claude 모델 해설: Claude Opus, Sonnet, Haiku, Fable 비교 — 모든 Claude API 모델, Anthropic 모델 이름 및 가격 (2026)](/ko/learn/claude-api-models-compared/)[암호화폐로 Claude API 요금 결제하기](/ko/learn/claude-api-with-crypto-payment/)[대기 명단 없이 Claude API 이용하기](/ko/learn/claude-api-without-waitlist/)[Claude 토큰 사용량을 줄이는 방법](/ko/learn/how-to-reduce-claude-token-usage/)[Claude API로 Cline 무제한 사용](/ko/learn/use-claude-api-with-cline/)[Claude API로 Roo Code 무제한 사용](/ko/learn/use-claude-api-with-roo-code/)[JetBrains IDE에서 Claude 무제한 사용](/ko/learn/use-claude-api-with-jetbrains/)[Claude API로 Aider 무제한 사용하기](/ko/learn/use-claude-api-with-aider/)[VS Code에서 Claude 무제한 사용](/ko/learn/use-claude-api-with-vscode/)[Claude용 OpenCode 구성: opencode.json 설정, 모델 및 일반적인 오류](/ko/learn/use-claude-api-with-opencode/)[Claude에서 Hermes 에이전트 무제한 실행하기](/ko/learn/run-hermes-agent-with-claude-api/)[Claude에서 OpenClaw 무제한 실행하기](/ko/learn/run-openclaw-with-claude-api/)[Anthropic 호환 API의 의미](/ko/learn/anthropic-compatible-api/)[Claude Code API 키 — ANTHROPIC_API_KEY: 발급 및 설정 방법과 대신 claude setup-token을 사용해야 하는 경우](/ko/learn/claude-code-api-key-setup/)[Claude Code API 비용 — 요금과 절감 방법](/ko/learn/claude-code-api-costs/)[Claude API 오류 설명: 서버 오류 500, 과부하 529, 사용량 제한 429, 잘못된 요청 400 — 각 오류의 해결 방법](/ko/learn/claude-api-errors-troubleshooting/)[Claude API 크레딧 구매 방법 — 그리고 Claude 크레딧이 어떤 "Claude 계정 구매" 상품보다 나은 이유](/ko/learn/buy-claude-api-credits/)[Claude 무료 API: 무료 Claude API 키가 있나요? 2026년에 실제로 무료인 것은 무엇인가요?](/ko/learn/claude-api-free-trial/)[Claude API와 Claude Pro/Max 구독 — 어떤 것을 선택할까요](/ko/learn/claude-api-vs-subscription/)[Claude에서 Codex CLI 실행하기](/ko/learn/use-claude-api-with-codex/)[Claude를 n8n에 연결하기](/ko/learn/use-claude-api-with-n8n/)[LiteLLM을 Claude로 라우팅하기](/ko/learn/use-claude-api-with-litellm/)[Kilo Code에서 Claude 사용하기](/ko/learn/use-claude-api-with-kilo-code/)[GitHub Copilot에 Claude 연결하기](/ko/learn/use-claude-api-with-github-copilot/)[게이트웨이를 통해 Zed를 Claude에 연결하기](/ko/learn/use-claude-api-with-zed/)[Cherry Studio를 Claude에 연결하기](/ko/learn/use-claude-api-with-cherry-studio/)[LangChain의 ChatAnthropic: 가져오기, base_url, 스트리밍, 도구 및 오류](/ko/learn/use-claude-api-with-langchain/)[Anthropic Python SDK: 설치, base_url 설정, 스트리밍 및 오류 처리](/ko/learn/anthropic-python-sdk/)[Vercel AI SDK로 Claude 사용하기: createAnthropic baseURL, 스트리밍 및 문제 해결](/ko/learn/use-claude-api-with-vercel-ai-sdk/)[Claude Code API 이해하기](/ko/learn/claude-code-api/)[애플리케이션에 Claude API 통합하기](/ko/learn/claude-api-integration/)[Claude를 무제한으로 사용하는 방법 — 그리고 "Claude Code 크랙 버전"이 없는 이유](/ko/learn/get-unlimited-claude-usage/)