OpenClaw 설정 가이드
OpenClaw는 프로그래밍 환경에 특화된 터미널/웹 UI 도구입니다. 다양한 모델 프로토콜을 지원하므로 단순한 주소 입력뿐만 아니라 baseUrl과 api 필드를 올바른 쌍으로 매칭하는 것이 설정의 핵심입니다.
공식 정보 다운로드 및 문서는 공식 사이트를 기준으로 합니다.
이 도구의 개요 및 용도
먼저 프로토콜 선택 기준 확인하기
| 사용 시나리오 | Base URL 확인 방법 | API 필드 선택 방법 |
|---|---|---|
| OpenAI 네이티브 | 중계 사이트에서 제공하는 OpenAI / OpenAI 호환 API 주소 사용 (/v1 포함 여부는 백엔드에 따라 다름) | openai-responses |
| Claude 네이티브 | 중계 사이트에서 제공하는 Anthropic / Claude 인터페이스 주소 사용 | anthropic-messages |
| Gemini 네이티브 | 중계 사이트에서 제공하는 Google / Gemini 인터페이스 주소 사용 | google-generative-ai |
| 호환 모드 | 중계 사이트의 OpenAI 호환 인터페이스 주소 | openai-completions |
중계 사이트 관리자 페이지에서 OpenAI, Claude, Gemini 인터페이스 주소를 구분하여 제공하는 경우, 도메인만 복사하지 말고 해당 프로토콜에 맞는 전체 주소를 복사하세요.
설정 코드 스니펫 참조
설정 파일은 일반적으로 ~/. openclaw/openclaw.json에 위치합니다. 초기화 마법사에서 중계 사이트 주소를 올바르게 입력하기 어려운 경우, 먼저 모델 선택 단계를 건너뛴 후 설정 파일을 직접 수정할 수 있습니다.
OpenClaw 단일 중계 사이트 설정 예시 스니펫
"models": { "providers": { "mz-openai": { "baseUrl": "https://YOUR_PROVIDER_API_URL", "apiKey": "YOUR_KEY", "auth": "api-key", "api": "openai-responses", "models": [ { "id": "MODEL_ID_FROM_PROVIDER_DASHBOARD", "name": "DISPLAY_NAME", "reasoning": false, "input": [], "contextWindow": 128000, "maxTokens": 32000 } ] } } }저장 후 확인 방법
- 먼저 하나의 중계 사이트만 설정하고, 한 번에 여러 모델을 추가하지 마세요.
- 테스트 프로젝트로 이동하여 새로 추가한 모델을 선택합니다.
- '설정 성공이라고만 답해줘'와 같은 가장 간단한 질문을 전송해 봅니다.
- 프로토콜 오류가 발생하면 api 필드와 Base URL이 동일한 유형의 인터페이스 규격인지 먼저 확인하세요.
초보자를 위한 자주 묻는 질문
| 증상 | 우선 점검 사항 | 해결 방법 |
|---|---|---|
| 프로토콜 관련 오류 | api 필드가 Base URL과 일치하는지 여부 | OpenAI, Claude, Gemini 프로토콜을 혼용하지 말고 중계 사이트의 해당 프로토콜에 맞춰 입력하세요. |
| 모델 목록이 비어 있음 | 중계 사이트에서 모델 목록 조회를 지원하는지 여부 | 목록 조회가 실패할 경우 관리자 페이지에 명시된 모델 ID/모델명을 직접 수동으로 입력하세요. |
| 설정 파일을 수정했으나 적용되지 않음 | OpenClaw가 실제로 읽는 설정 파일을 수정한 것이 맞는지 확인 | OpenClaw를 재시작한 후 다시 테스트하세요. 한 번에 여러 설정을 동시에 변경하지 마세요. |
| API 키가 올바른데도 오류가 발생함 | 현재 Provider의 auth 및 apiKey 필드 설정 | 해당 API 키가 현재 선택한 프로토콜 및 중계 사이트에 유효한 키인지 확인하세요. |
OpenClaw 공식 웹사이트 도구 소개 및 시작 페이지 확인
OpenClaw AI 중계 사이트 설정 참조 다양한 프로토콜 환경에서 baseUrl과 api 필드를 쌍으로 설정하는 방법 참조