Clawdbot (Moltbot/OpenClaw) Gemini API 연동 튜토리얼

Clawdbot(Moltbot/OpenClaw)에서 Gemini 3 Flash를 통합하는 전체 튜토리얼 (defapi.org 프록시 사용)

Clawdbot은 기본적으로 Anthropic Claude의 tool use를 가장 완벽하게 지원하지만, Gemini 시리즈(특히 속도가 빠르고 컨텍스트가 매우 긴 Gemini 3 Flash)는 검색, 빠른 응답, 멀티모달 작업에서 뛰어난 성능을 보입니다. Google 공식 Gemini API를 Clawdbot에 직접 연결하려면 일반적으로 복잡한 형식 변환 레이어(예: litellm 또는 커스텀 relay)가 필요하지만, defapi.org는 거의 수정 없이 바로 실행할 수 있는 솔루션을 제공합니다. 이 서비스는 Gemini를 Anthropic/OpenAI 스타일의 인터페이스와 호환되도록 패키징하며, 특히 tool calling에 대한 투과성이 뛰어납니다.

최대 장점: defapi.org를 통해 Gemini 3 Flash를 사용하면 실제 비용이 Google 공식 API보다 약 50% 저렴합니다 (2026년 커뮤니티 실측 및 상위 공급업체 가격 비교 기준: 공식 Gemini 3 Flash 입력 ≈ $0.50–$1.00 / 1M tokens, 출력 $3.00+; defapi 프록시 레이어는 보통 40–60% 할인이 적용되어, 헤비 유저의 경우 절반 이상의 비용을 절약할 수 있습니다. 특히 Clawdbot과 같이 tool call 빈도가 높은 agent 시나리오에 적합합니다).

다음은 2026년 최신 버전의 가장 안정적인 연동 단계입니다.

1. 사전 준비

Clawdbot 설치 완료 (이번 테스트에 사용된 버전: 2026.1.24-3 (885167d)). 새 서버인 경우 다음 명령어를 참고하여 빠르게 설치할 수 있습니다:
```
# fnm 및 Node.js 24 설치
curl -o- https://fnm.vercel.app/install | bash
source ~/.bashrc
fnm install 24

# clawdbot 설치
npm install -g clawdbot
```
defapi.org 계정 가입 ( https://defapi.org ), 충전 완료 (Alipay/WeChat/신용카드 지원).
API Key 획득: 대시보드에서 defapi API Key를 가져옵니다 (보통 dk-로 시작하는 형식).

2. 왜 공식 API나 다른 프록시가 아닌 defapi를 선택해야 하나요?

항목	defapi.org (gemini-3-flash)	Google 공식 Gemini API	OpenRouter / LiteLLM 등 기타 프록시
연동 난이도	매우 낮음 (설정 3줄 수정)	높음 (형식 변환 레이어 필요)	보통 (호환 모델 선택 필요)
Tool calling 호환성	우수 (function/tool role 지원)	추가 어댑터 필요	프록시에 따라 다름
컨텍스트 길이	1M tokens 네이티브 지원	1M tokens	일반적으로 지원
멀티모달 (이미지)	지원 (Clawdbot 이미지 업로드 가능)	지원	일부 지원
비용 (공식 대비)	약 50% 저렴	기준 가격	20–40% 저렴
지연 시간 (Latency)	공식보다 약간 높지만 수용 가능	가장 낮음	보통

한 줄 요약: 예산에 민감하면서 Gemini 3 Flash를 Clawdbot에서 빠르게 사용하고 싶은 사용자에게 defapi는 현재 가장 매력적인 선택지입니다.

3. 상세 설정 단계

Clawdbot의 최신 버전(2026.1.24-3 (885167d))은 JSON 형식의 설정 파일을 통한 관리를 권장합니다.

설정 파일 생성

사용자 디렉토리에 ~/.clawdbot/clawdbot.json 파일을 생성하거나 편집합니다:
```
mkdir -p ~/.clawdbot
vi ~/.clawdbot/clawdbot.json
```

설정 내용 작성

다음 내용을 clawdbot.json에 입력합니다. apiKey 부분을 실제 defapi 키로 교체해야 합니다:

{
    "gateway": {
        "mode": "local",
        "bind": "loopback",
        "port": 18789
    },
    "agents": {
        "defaults": {
            "model": {
                "primary": "gemini/gemini-3-flash"
            },
            "elevatedDefault": "full",
            "workspace": "/myworkspace",
            "compaction": {
                "mode": "safeguard"
            },
            "maxConcurrent": 4,
            "subagents": {
                "maxConcurrent": 8
            }
        }
    },
    "models": {
        "mode": "merge",
        "providers": {
            "gemini": {
                "baseUrl": "https://api.defapi.org/v1",
                "apiKey": "defapi API key, dk-* 로 시작",
                "api": "openai-completions",
                "models": [
                    {
                        "id": "gemini-3-flash",
                        "name": "gemini-3-flash"
                    }
                ]
            }
        }
    },
    "channels": {
        "telegram": {
            "botToken": "당신의 TG Token, 비워둘 수 있음"
        }
    },
    "plugins": {
        "entries": {
            "telegram": {
                "enabled": true
            }
        }
    }
}

주요 포인트 설명:

baseUrl: 반드시 https://api.defapi.org/v1이어야 합니다.
api: openai-completions를 입력합니다. defapi의 Gemini 인터페이스는 OpenAI 형식과 완벽하게 호환됩니다.
primary model: 참조 형식은 provider/model_id 즉, gemini/gemini-3-flash입니다.

테스트 결과 확인

clawdbot agent --message "hi" --agent main

예상 출력:

root@iZ6wefjkouvkogu7drkjvfZ:~# clawdbot agent --message "hi" --agent main

🦞 Clawdbot 2026.1.24-3 (885167d) — Pairing codes exist because even bots believe in consent—and good security hygiene.

│
◇
Gateway agent failed; falling back to embedded: Error: gateway closed (1006 abnormal closure (no close frame)): no close reason
Gateway target: ws://127.0.0.1:18789
Source: local loopback
Config: /root/.clawdbot/clawdbot.json
Bind: loopback
Hey. I just came online.

Who am I? Who are you?

The `BOOTSTRAP.md` file tells me this is a fresh workspace, which means we get to figure this out from scratch. I've got plenty of tools and potential, but I'm missing a name, a vibe, and a sense of who I'm helping.

What should we call me? And what's your name?