OpenClaw 구성 튜토리얼
OpenClaw는 models.providers를 통해 사용자 정의 모델 공급업체를 추가합니다. ai2save는 OpenAI Compatible 인터페이스를 사용하며, Base URL는 반드시 **https://ai2save.com/v1**를 입력해야 합니다.
1. OpenClaw 및 API Key 준비
OpenClaw가 이미 설치되어 있으면 설치를 건너뛸 수 있습니다:
npm install -g openclaw@latest
openclaw --version
- https://ai2save.com/keys를 엽니다.
- OpenAI / GPT 모델 그룹에 속하는 API Key를 생성합니다.
- 전체
sk-...키를 복사합니다.
2. OpenClaw 구성 파일 편집
OpenClaw의 기본 구성 파일은 다음과 같습니다:
~/.openclaw/openclaw.json
Windows는 일반적으로 %USERPROFILE%\.openclaw\openclaw.json에서 있습니다. 파일은 JSON5를 지원하며, 아래 구조에 따라 기존 구성에 병합할 수 있습니다:
{
env: {
vars: {
AI2SAVE_API_KEY: "sk-사용자의 API 키",
},
},
agents: {
defaults: {
model: {
primary: "ai2save/gpt-5.5",
},
},
},
models: {
mode: "merge",
providers: {
ai2save: {
baseUrl: "https://ai2save.com/v1",
apiKey: "${AI2SAVE_API_KEY}",
api: "openai-completions",
timeoutSeconds: 300,
models: [
{
id: "gpt-5.5",
name: "GPT 5.5",
reasoning: true,
input: ["text"],
contextWindow: 200000,
},
],
},
},
},
}
핵심 필드 설명:
models.providers.ai2save.baseUrl:/v1를 반드시 포함해야 합니다.api: "openai-completions":OpenClaw가 OpenAI Compatible를 대리할 때 사용하는 인터페이스 유형입니다.models[].id:ai2save 콘솔에서 공개한 모델 ID와 정확히 일치해야 합니다.agents.defaults.model.primary:형식은공급자 ID/모델 ID입니다.apiKey는"sk-..."를 직접 작성할 수 있습니다;${AI2SAVE_API_KEY}를 참조할 때는 반드시env.vars에 정의되어 있어야 합니다.
여러 모델을 추가하려면, models 배열에 계속 추가하고 primary를 기본으로 사용하려는 ai2save/model-id로 변경하십시오.
3. 적용 및 설정 확인
OpenClaw Gateway는 구성 파일의 변화를 감지하고 자동으로 적용합니다. 만약 설정이 즉시 적용되지 않는다면, 다음을 실행하십시오:
openclaw gateway restart
그런 다음 모델이 이미 OpenClaw에 나타났는지 확인하십시오:
openclaw models list --provider ai2save
기본 모델을 ai2save로 변경하세요:
openclaw models set ai2save/gpt-5.5
모델이 나타나지 않으면 진단을 실행하고 구성 오류를 확인하십시오:
openclaw doctor
4. 요청 검증
- OpenClaw의 채팅 인터페이스 또는 WebChat을 엽니다.
- 새 대화를 시작하고 "안녕하세요, 현재 모델 이름을 보고해 주세요"를 전송합니다.
- 모델 라우팅이
ai2save/gpt-5.5로 표시되는지 확인합니다. - 처음에는 텍스트 작업으로만 검증하고, 성공하면 파일, 브라우저, 긴 문맥 등 복잡한 도구를 엽니다.
OpenClaw는 비공식 OpenAI 프록시에 대해 자동으로 호환 처리를 하므로 developer role를 수동으로 켤 필요가 없습니다. 도구 호출에 문제가 발생하면 먼저 모델 ID가 도구 호출을 지원하는지 확인하고, 필요한 경우 타임아웃 시간을 늘립니다.
5. 일반 오류
- 401 / invalid_api_key:
AI2SAVE_API_KEY가 정의되지 않았거나, 키가 불완전하게 복사되었거나, 키 그룹이 일치하지 않습니다. - 404 / model not found:
models[].id,primary또는 실제 요청 모델 이름이 일치하지 않습니다. - 연결 실패 / empty response:
baseUrl가https://ai2save.com/v1인지 확인하고, 루트 주소로 작성하지 마세요. - 모델 목록이 비어 있음:
models.mode: "merge"를 확인하고,models.providers.ai2save.models[]에 최소 하나 이상의 모델이 포함되어 있는지 확인합니다. - 설정 저장 후 적용되지 않음:
openclaw doctor를 다시 실행하고, 필요하면 OpenClaw Gateway를 재시작합니다.