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

자주 묻는 질문

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