> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tokenlab.sh/llms.txt
> Use this file to discover all available pages before exploring further.
# TokenLab Provider 설정
> OpenAI, Responses, Anthropic 및 Gemini 호환 경로를 사용하여 OpenClaw에 TokenLab를 커스텀 프로바이더로 구성하는 방법
이 가이드는 TokenLab를 AI 프로바이더로 연결하려는 **self-hosted OpenClaw** 사용자를 위한 것입니다.
## 권장: 플러그인 설치
일반적인 OpenClaw 에이전트 실행에는 TokenLab 프로바이더 플러그인을 설치하세요.
```bash theme={null}
openclaw plugins install @tokenlabai/openclaw-provider
openclaw onboard --tokenlab-api-key "$TOKENLAB_API_KEY"
```
플러그인은 TokenLab의 실시간 채팅 모델 카탈로그를 가져오며, 오프라인 검색을 위한 18개의 폴백 모델도 유지합니다. 모델은 `tokenlab/` 형식을 사용합니다.
[npm 패키지](https://www.npmjs.com/package/@tokenlabai/openclaw-provider) · [ClawHub 목록](https://clawhub.ai/tokenlabai/plugins/openclaw-provider) · [소스 코드](https://github.com/hedging8563/tokenlab-openclaw-provider)
## 수동 프로바이더 구성
별도의 **Responses API**, **Claude native**, **Gemini native** 또는 **MiniMax native** 경로가 명시적으로 필요한 경우에만 아래의 `models.providers` 수동 구성을 사용하세요.
수동 구성을 선택한다면 `tokenlab`만 구성하는 것으로 충분합니다. **Responses API**, **Claude native**, **Gemini native**, 또는 **MiniMax native** 동작이 명시적으로 필요할 때만 다른 프로바이더를 추가하세요.
| 제공업체 | OpenClaw `api` | 적합한 용도 | baseUrl |
| -------------------- | ---------------------- | ------------------------------------------------ | ---------------------------- |
| `tokenlab` | `openai-completions` | GPT, DeepSeek, Qwen 및 대부분의 OpenAI 호환 호출 | `https://api.tokenlab.sh/v1` |
| `tokenlab-responses` | `openai-responses` | `/v1/responses` 의미론을 기대하는 OpenAI Responses 워크플로우 | `https://api.tokenlab.sh/v1` |
| `tokenlab-claude` | `anthropic-messages` | Claude Messages 네이티브 API | `https://api.tokenlab.sh` |
| `tokenlab-gemini` | `google-generative-ai` | Gemini 네이티브 API 형식 | `https://api.tokenlab.sh` |
| `tokenlab-minimax` | `anthropic-messages` | MiniMax 네이티브 라우팅 | `https://api.tokenlab.sh` |
`/v1` 접미사는 `openai-completions` 및 `openai-responses`에만 사용하세요.
`anthropic-messages` 및 `google-generative-ai`와 같은 네이티브 프로바이더는 `/v1` 없이 `https://api.tokenlab.sh`를 사용해야 하며, 그렇지 않으면 OpenClaw가 잘못된 업스트림 경로를 구성할 수 있습니다.
## 사전 요구사항
* self-hosted OpenClaw 인스턴스
* TokenLab API Key — [Get one here](https://tokenlab.sh/dashboard)
## 구성
OpenClaw 구성 파일을 편집하세요:
* **셀프 호스트**: `~/.openclaw/openclaw.json`
`models.providers` 아래에 TokenLab 프로바이더를 추가합니다:
```json5 theme={null}
{
agents: {
defaults: {
model: {
primary: "tokenlab-claude/claude-sonnet-4-6"
}
}
},
models: {
mode: "merge",
providers: {
tokenlab: {
api: "openai-completions",
baseUrl: "https://api.tokenlab.sh/v1",
apiKey: "sk-your-tokenlab-key",
models: [
{ id: "gpt-4o", name: "GPT-4o" },
{ id: "deepseek-r1", name: "DeepSeek R1" },
{ id: "qwen3-coder-flash", name: "Qwen 3 Coder Flash" }
]
},
"tokenlab-responses": {
api: "openai-responses",
baseUrl: "https://api.tokenlab.sh/v1",
apiKey: "sk-your-tokenlab-key",
models: [
{ id: "gpt-4o", name: "GPT-4o (Responses)" },
{ id: "gpt-5.2", name: "GPT-5.2 (Responses)" }
]
},
"tokenlab-claude": {
api: "anthropic-messages",
baseUrl: "https://api.tokenlab.sh",
apiKey: "sk-your-tokenlab-key",
models: [
{ id: "claude-sonnet-4-6", name: "Claude Sonnet 4.6" },
{ id: "claude-opus-4-6", name: "Claude Opus 4.6" }
]
},
"tokenlab-gemini": {
api: "google-generative-ai",
baseUrl: "https://api.tokenlab.sh",
apiKey: "sk-your-tokenlab-key",
models: [
{ id: "gemini-3.5-flash", name: "Gemini 3.5 Flash" },
{ id: "gemini-2.5-pro", name: "Gemini 2.5 Pro" }
]
},
"tokenlab-minimax": {
api: "anthropic-messages",
baseUrl: "https://api.tokenlab.sh",
apiKey: "sk-your-tokenlab-key",
models: [
{ id: "minimax-m3", name: "MiniMax M3" }
]
}
}
}
}
```
모든 5개 프로바이더는 **같은 API Key**를 사용합니다. TokenLab 계정은 하나만 있으면 됩니다.
위의 `models` 배열은 일반적인 예시만 보여줍니다. 필요에 따라 각 프로바이더에 더 많은 모델 ID를 추가하세요.
## 모델 사용 방법
OpenClaw은 여전히 `provider/model` 형식으로 모델을 참조합니다:
```json5 theme={null}
{
agents: {
defaults: {
model: {
primary: "tokenlab-gemini/gemini-3.5-flash"
}
}
}
}
```
### 모델 예시
| 제공업체 | 모델 참조 | 설명 |
| -------------------- | ----------------------------------- | ----------------------- |
| `tokenlab` | `tokenlab/gpt-4o` | OpenAI 호환 경로 |
| `tokenlab` | `tokenlab/deepseek-r1` | DeepSeek 추론 모델 |
| `tokenlab-responses` | `tokenlab-responses/gpt-4o` | Responses API 경로 |
| `tokenlab-claude` | `tokenlab-claude/claude-sonnet-4-6` | Claude Messages 네이티브 경로 |
| `tokenlab-gemini` | `tokenlab-gemini/gemini-3.5-flash` | Gemini 네이티브 경로 |
| `tokenlab-minimax` | `tokenlab-minimax/minimax-m3` | MiniMax 네이티브 경로 |
사용 가능한 모든 모델은 [tokenlab.sh/models](https://tokenlab.sh/ko/models)에서 확인하세요.
## 어떤 프로바이더를 언제 사용해야 하나요
* `tokenlab`: 대부분의 범용 에이전트 및 채팅 사용 사례에 대한 기본 선택입니다.
* `tokenlab-responses`: OpenClaw 워크플로우가 명시적으로 OpenAI Responses 의미론에 의존할 때 사용하세요.
* `tokenlab-claude`: Claude의 네이티브 Messages 동작이 필요할 때 사용하세요.
* `tokenlab-gemini`: Gemini 네이티브 요청/응답 포맷이나 기존 Gemini 스타일 통합을 사용하고자 할 때 사용하세요.
* `tokenlab-minimax`: MiniMax의 네이티브 경로를 사용하고자 할 때 사용하세요.
Gemini 네이티브 동작이 필요하지 않다면 OpenAI 호환 경로를 통해 `tokenlab/gemini-*`로 Gemini 모델을 호출할 수 있습니다.
## 흔한 실수
현재 OpenClaw 문서는 `models.providers`를 사용합니다. 이전의 최상위 `providers` 배열 형식을 유지하면 OpenClaw가 구성을 무시하거나 프로바이더 접두사를 예상대로 해결하지 못할 수 있습니다.
`openai-responses`는 TokenLab의 `/v1/responses` 경로에 매핑되므로 `tokenlab-responses`는 반드시 `https://api.tokenlab.sh/v1`을 사용해야 합니다.
`anthropic-messages` 및 `google-generative-ai`는 `/v1` 없이 `https://api.tokenlab.sh`를 사용해야 합니다. `/v1`을 추가하면 잘못된 요청 경로가 생성될 수 있습니다.
예. 현재 OpenClaw 문서에는 내장된 `google` 프로바이더가 포함되어 있으며 `api: "google-generative-ai"`를 사용하는 커스텀 프로바이더도 지원합니다. 따라서 `tokenlab-gemini`는 OpenClaw 사용자를 위한 유효한 네이티브 Gemini 경로로 남아 있습니다.
## 설정 확인
구성 파일을 저장한 후 OpenClaw 인스턴스를 재시작하고 간단한 메시지로 테스트하세요. 응답을 받으면 프로바이더가 올바르게 구성된 것입니다.
```bash theme={null}
# 셀프 호스트: 서비스를 다시 시작
systemctl --user restart openclaw # Linux
launchctl stop cc.tokenlab.openclaw && launchctl start cc.tokenlab.openclaw # macOS
```
## 다음 단계
OpenClaw가 연결된 후, 다음 가이드들이 TokenLab를 보다 효과적으로 사용하는 데 도움이 됩니다:
* [API 형식](/guides/api-formats) — OpenAI, Responses, Anthropic, Gemini 경로 간 차이 이해
* [IDE / SDK Compatibility](/guides/ide-sdk-compatibility) — 언제 `/v1/responses`가 더 적합한지 확인
* [오류 처리](/guides/error-handling) — 일반적인 실패 모드 및 복구 패턴 학습
* [모델 개요](https://tokenlab.sh/ko/models) — 에이전트에 연결하기 전에 모델 ID를 살펴보세요