OpenClaw는 공급업체에 종속되지 않도록 설계되었으며, 이것이 바로 이 도구의 숨겨진 강점입니다. OpenAI나 Anthropic 같은 일반적인 업체는 물론, OpenAI와 호환되는 API라면 무엇이든 커스텀 공급업체로 추가할 수 있습니다(OpenClaw docs, 2026). 이러한 설계 덕분에 선호하는 에이전트를 그대로 유지하면서도, 토큰당 가격이 훨씬 저렴한 오픈 웨이트(open-weight) 모델로 전환하여 비용을 대폭 절감할 수 있습니다.
문제는 설정 과정에서 거의 누구나 실수하는 한 단계가 있다는 점입니다. 이를 잘못 설정하면 엉뚱한 오류 메시지가 발생하여 문제 해결에 어려움을 겪게 됩니다. 이 가이드에서는 올바른 OpenClaw 커스텀 API 설정 방법을 단계별로 안내합니다. 작동 원리, 정확한 설정값, 허용 목록(allowlist) 주의 사항, 그리고 연결 확인 방법까지 포함되어 있습니다. 약 5분 정도 소요됩니다.
OpenClaw 커스텀 API 설정이 필요한 이유
가장 큰 이유는 비용입니다. OpenClaw와 같은 에이전트 도구는 추론 단계마다 누적된 컨텍스트를 다시 전송하기 때문에, 동일한 작업을 수행하더라도 일반 채팅창보다 10배에서 100배 더 많은 토큰을 소모합니다(LeanOps, 2026). 이 배율 때문에 에이전트 사용료가 급격히 증가하며, 대규모 사용자의 경우 frontier 모델 사용 시 개발자 1인당 하루에 약 13달러의 비용이 발생하기도 합니다(CloudZero, 2026). OpenClaw 커스텀 API 설정은 바로 이 '토큰당 가격'을 공략합니다. 에이전트가 사용하는 모델을 비싼 frontier 모델 대신 오픈 웨이트 모델로 변경하면 단위 비용이 급격히 낮아지며, 일상적인 코딩 작업에서는 품질 차이가 거의 없음에도 비용을 70% 이상 절감할 수 있습니다. 기존의 OpenClaw 워크플로우를 그대로 유지하면서 요청을 처리하는 엔진만 바꾸면 되는 것입니다. 두 번째 이유는 특정 업체의 서비스를 직접 이용하기 어려운 지역의 팀들에게 중요합니다. 커스텀 공급업체를 사용하면 특정 업체의 결제 정책, 업데이트 일정, 지역적 제한에 의존하지 않고도 에이전트를 안정적이고 호환성 있게 운영할 수 있습니다.
OpenClaw 커스텀 API 설정 방식: 흔히 놓치는 두 단계
설정값을 입력하기 전에 OpenClaw가 사용하는 모델 방식을 이해해야 합니다. 그래야 모두가 겪는 오류를 방지할 수 있습니다. 커스텀 공급업체는 두 곳에서 정의되어야 하며, 두 과정 모두 필수입니다.
첫째, models.providers 섹션에서 공급업체 자체(기본 URL, API 키, 통신 프로토콜, 제공 모델 목록)를 정의합니다. (OpenAI 호환 엔드포인트는 openai-completions 사용) 둘째, 많은 사용자가 놓치는 부분인데, agents.defaults.models에서 provider-name/model-name과 같은 전체 식별자를 사용하여 해당 모델을 허용 목록에 추가해야 합니다(OpenClaw docs, 2026). 공급업체를 정의한다고 해서 모델이 자동으로 사용 가능한 것은 아닙니다. OpenClaw는 허용 목록에 없는 모델은 모두 거부합니다.
이는 의도된 설계입니다. 허용 목록을 통해 방대한 공급업체와 모델 카탈로그를 정의하더라도, 에이전트가 실제로 접근하기를 원하는 특정 모델만 노출할 수 있기 때문입니다. 공급업체 정의와 허용 목록이 별개의 계층이라는 점만 이해하면, 나머지 OpenClaw 커스텀 API 설정은 매우 간단합니다.
OpenClaw 커스텀 API 단계별 설정
아래 예시에서는 Atlas Cloud를 공급업체로 사용합니다. 하나의 OpenAI 호환 엔드포인트를 통해 주요 오픈 웨이트 모델들을 단일 키로 제공하기 때문입니다. 이를 통해 설정을 간결하게 유지하고, 나중에 새로운 등록 절차 없이도 모델을 쉽게 교체할 수 있습니다. 다른 호환 공급업체도 기본 URL과 키만 다를 뿐 설정 단계는 동일합니다.
1단계: 엔드포인트와 API 키 확보
이 단계가 끝나면 기본 URL과 키라는 두 가지 문자열을 얻게 됩니다.
- 공급업체 계정을 생성하고 API 키 섹션을 엽니다.
- 코딩용으로 범위가 제한된 키를 생성합니다. Atlas Cloud의 경우 키 유형으로 Coding Plan을 선택하면 일반적인 종량제 방식이 아닌 크레딧 기반의 코딩 할당량과 연결됩니다.
- 기본 URL을 확인합니다. OpenClaw와 같은 OpenAI 호환 클라이언트의 경우, Atlas Cloud는 https://api.atlascloud.ai/v1을 사용합니다 (여기서 /v1 접미사가 중요합니다).
2단계: 온보딩 마법사 실행 (가장 빠른 방법)
이 단계를 완료하면 연결이 바로 활성화됩니다. 터미널에서 다음 명령어로 가이드 마법사를 시작합니다.
Bash1openclaw onboard
안내에 따라 Yes, QuickStart, Custom Provider를 차례로 선택합니다. 마법사가 API 기본 URL(https://api.atlascloud.ai/v1), API 키, 모델 ID를 물어보면 입력합니다. 프로토콜 선택 시 OpenAI-compatible을 선택하세요. Verification successful 메시지가 뜨면 연결이 완료된 것입니다. 마지막으로 엔드포인트에 ID와 이름을 부여하면 끝납니다. 이 마법사의 숨겨진 장점은 공급업체 정의와 모델 허용 목록 입력을 자동으로 처리하고 게이트웨이를 재시작해 준다는 점입니다.
3단계: 설정 파일 직접 수정
이 단계를 통해 마법사가 어떤 내용을 설정했는지 이해하게 되며, 추후 모델을 추가할 때 유용합니다. 설정 파일은 ~/.openclaw/openclaw.json에 위치합니다(OpenClaw docs, 2026). 공급업체를 다음과 같이 정의하세요:
JSON1{ 2 "models": { 3 "mode": "merge", 4 "providers": { 5 "atlascloud": { 6 "baseUrl": "https://api.atlascloud.ai/v1", 7 "apiKey": "your-atlas-api-key", 8 "api": "openai-completions", 9 "models": [ 10 { "id": "zai-org/glm-5.1", "name": "glm-5.1", "contextWindow": 200000 } 11 ] 12 } 13 } 14 } 15}
"mode": "merge"는 기존 공급업체 설정을 덮어쓰지 않고 병합합니다. 커스텀 공급업체의 경우 reasoning, cost, maxTokens 등의 필드는 선택 사항이며 기본값이 적용되므로 처음부터 모두 채울 필요는 없습니다.
4단계: 모델 허용 목록 추가
이 단계를 거쳐야 OpenClaw가 해당 모델을 사용할 수 있습니다. 사람들이 가장 많이 놓치는 부분입니다. 허용 목록에 전체 식별자를 추가하세요:
JSON1{ 2 "agents": { 3 "defaults": { 4 "models": { 5 "atlascloud/zai-org/glm-5.1": { "alias": "glm" } 6 } 7 } 8 } 9}
키는 공급업체이름/모델ID 형식으로, 정의한 것과 정확히 일치해야 합니다. alias는 전체 경로 대신 입력할 수 있는 단축어입니다. 이 블록이 없으면 공급업체는 존재해도 모든 요청이 거부됩니다.
5단계: 설정 확인
이제 OpenClaw를 시작하고 모델(또는 별칭)을 선택한 뒤, 파일 설명과 같은 간단한 작업을 요청해 보세요. 정상적으로 응답한다면 연결이 성공한 것입니다. 만약 "model not allowed" 오류가 발생한다면 4단계를 다시 확인하세요. 허용 목록의 키가 공급업체 및 모델 이름과 정확히 일치하지 않을 가능성이 큽니다. 인증 오류가 발생하면 키가 잘못되었거나 공백이 포함되었을 수 있습니다. 연결 자체가 안 된다면 기본 URL과 /v1 접미사를 다시 체크하세요.
OpenClaw 설정에 적합한 모델 선택
모델 선택은 곧 비용 절감으로 이어집니다. 일상적인 작업에는 강력하면서도 저렴한 오픈 모델을 기본으로 사용하고, 고난도의 추론이 필요한 경우에만 더 비싼 모델을 사용하는 것이 현명합니다. SWE-Bench Pro 기준, 주요 오픈 모델은 상위 frontier 모델(약 91점)에 근접한 70점대 후반의 점수를 기록합니다(Codersera, 2026). 가장 어려운 문제에서는 차이가 있지만, 일상적인 기능 개발이나 리팩토링에서는 충분히 강력합니다. 크레딧 기반 게이트웨이에서는 모델별로 토큰 사용량에 따른 비용 배율이 적용되어 비교가 쉽습니다:
| 모델 ID | 컨텍스트 | 입력 배율 | 출력 배율 | 공식 대비 예상 절감액 |
|---|---|---|---|---|
| deepseek-ai/deepseek-v4-flash | 1M | 0.23 | 0.46 | ~50% |
| deepseek-ai/deepseek-v3.2 | 160K | 0.42 | 0.62 | ~55% |
| minimaxai/minimax-m2.5 | 200K | 0.65 | 2.18 | ~45% |
| moonshotai/kimi-k2.6 | 262K | 1.72 | 7.26 | ~45% |
| zai-org/glm-5.1 | 200K | 2.54 | 7.99 | ~45% |
출처: Atlas Cloud Coding Plan 크레딧 규정. 크레딧 비용 = 입력 토큰 × 입력 배율 + 출력 토큰 × 출력 배율. 합리적인 기본 설정은 대화형 코딩에는 GLM-5.1이나 Kimi K2.6을, 대량 작업이나 백그라운드 작업에는 DeepSeek V4 Flash를 사용하는 것입니다. 모든 모델이 한 공급업체 뒤에 있으므로 별칭만 한 줄 수정하면 쉽게 교체할 수 있습니다.
OpenClaw, Claude Code, Codex를 위한 단일 엔드포인트
OpenClaw 설정을 위한 엔드포인트는 OpenClaw 전용이 아닙니다. 여러 에이전트를 사용하는 개발자라면 각기 다른 공급업체 키, 대시보드, 청구서를 관리할 필요 없이 단일 OpenAI 호환 엔드포인트로 통합하여 관리할 수 있습니다.
Atlas Cloud는 여러 도구에 동일한 기본 URL을 제공하므로, 위에서 설정한 내용을 다른 곳에도 적용할 수 있습니다. Claude Code는 ~/.claude/settings.json에서 ANTHROPIC_BASE_URL을 https://api.atlascloud.ai로 설정하여 사용합니다 (단, Claude Code는 /v1 접미사를 붙이지 않습니다). Codex는 ~/.codex/config.toml의 base_url을 https://api.atlascloud.ai/v1으로 설정합니다. Cursor, OpenCode 등도 동일한 /v1 엔드포인트를 사용합니다. 하나의 키와 예산으로 모든 도구를 제어하세요.
또한, 통합 관리를 통해 지출 통제가 가능해집니다. 매일 자정에 갱신되는 고정 크레딧 요금제는 에이전트 루프가 멈추지 않고 돌아가는 상황을 방지하며, 필요 시 종량제 팩을 추가할 수 있습니다. Atlas Cloud 요금제는 월 10달러부터 시작하며, 종량제 팩은 41% 할인이 적용됩니다. 요금제 업그레이드 시 차액만 지불하면 되므로 부담이 없습니다.
OpenClaw 커스텀 API 설정 시 흔한 실수
대부분의 오류는 설정 파일 내의 사소한 실수에서 발생합니다. 허용 목록 누락: 가장 흔한 실수입니다. 공급업체 정의는 절반일 뿐입니다. "model not allowed" 메시지가 뜨면 모델이 agents.defaults.models에 누락되었거나 키가 일치하지 않는 경우입니다(haimaker, 2026). 허용 목록 키 불일치: 허용 목록 키는 정의한 대로 정확히 공급업체이름/모델이름 형태여야 합니다. 오타가 있으면 누락된 것과 똑같이 거부됩니다. 기본 URL 경로 오류: OpenClaw와 같은 도구는 /v1 경로를 기대합니다. 이를 빠뜨리거나 잘못 추가하면 연결 오류가 발생합니다. 병합 대신 덮어쓰기: "mode": "merge"를 사용하지 않고 파일을 수정하면 기존 설정이 삭제될 수 있습니다. 대체하려는 경우가 아니라면 항상 병합 모드를 유지하세요.
자주 묻는 질문(FAQ)
OpenClaw 커스텀 API 설정이 어려운가요?
아니요. openclaw onboard 마법사를 사용하면 5분 안에 공급업체 정의와 모델 허용 목록 설정이 자동으로 완료됩니다. 수동 설정 시에도 두 개의 작은 JSON 수정만 필요합니다.
가장 흔한 오류는 무엇인가요?
"model not allowed" 오류입니다. 대부분 모델이 허용 목록에 없거나, 키에 오타가 있는 경우입니다. 마법사를 사용하면 이를 방지할 수 있습니다.
어떤 모델을 선택해야 하나요?
대화형 코딩에는 GLM-5.1이나 Kimi K2.6을, 대량/백그라운드 작업에는 DeepSeek V4 Flash를 권장합니다. frontier 모델은 오픈 모델로 해결하기 어려운 작업에만 예비용으로 두세요.
비용을 얼마나 절감할 수 있나요?
DeepSeek V4 Flash는 100만 입력 토큰당 약 0.14달러로, frontier 모델의 수달러 대비 매우 저렴합니다. 일반적인 일상 업무를 오픈 모델로 전환하면 토큰 비용을 70% 이상 절감할 수 있습니다(Codersera, 2026).
나중에 원래 공급업체로 돌아갈 수 있나요?
네. "mode": "merge"를 유지하면 기존 공급업체 설정이 남아 있습니다. 필요에 따라 별칭을 바꾸거나 공급업체 블록을 삭제하기만 하면 됩니다.
결론
OpenClaw 커스텀 API 설정은 2026년에 개발자가 할 수 있는 가장 효율적인 5분 투자입니다. 에이전트는 그대로 유지하면서 백엔드와 비용만 최적화할 수 있습니다. 공급업체를 정의하고 모델을 허용 목록에 추가하여 오픈 웨이트 모델을 사용해 보세요. Claude Code나 Codex까지 통합하여 관리하고 싶다면 Atlas Cloud Coding Plan 콘솔을 통해 시작할 수 있습니다.
