GigaChat Skill

Integrate GigaChat (Sber AI) with OpenClaw via gpt2giga proxy.

Features

• Three models: GigaChat, GigaChat-Pro, GigaChat-Max
• OpenAI API compatibility via gpt2giga proxy
• Automatic token management (gpt2giga handles OAuth internally)
• Credentials passed via environment variables only (never on CLI)

Prerequisites

1. GigaChat API Access:

   • Register at https://developers.sber.ru/
   • Create a GigaChat API application
   • Note your Client ID and Client Secret
   • Choose scope: GIGACHAT_API_PERS (free tier) or GIGACHAT_API_CORP (paid)

2. Python & gpt2giga:

   pip3 install gpt2giga
   

3. Environment File: Create ~/.openclaw/gigachat-new.env:

   CLIENT_ID="your-client-id-here"
   CLIENT_SECRET="your-client-secret-here"
   
   # Auto-generate credentials (base64 of CLIENT_ID:CLIENT_SECRET)
   GIGACHAT_CREDENTIALS=$(echo -n "$CLIENT_ID:$CLIENT_SECRET" | base64)
   GIGACHAT_SCOPE="GIGACHAT_API_PERS"
   

Quick Start

1. Start the proxy

/openclaw/skills/gigachat/scripts/start-proxy.sh

Output:

Starting gpt2giga proxy on port 8443...
✅ gpt2giga started successfully (PID: 12345)
   Log: ~/.openclaw/gpt2giga.log
   Endpoint: http://localhost:8443/v1/chat/completions

gpt2giga handles OAuth token generation and refresh internally using the GIGACHAT_CREDENTIALS environment variable.

2. Configure OpenClaw

Run the patch script (backs up your config first):

/openclaw/skills/gigachat/scripts/patch-config.sh

Or add manually to openclaw.json:

{
  "models": {
    "providers": {
      "gigachat": {
        "baseUrl": "http://127.0.0.1:8443",
        "apiKey": "not-needed",
        "api": "openai-completions",
        "models": [
          {
            "id": "GigaChat-Max",
            "name": "GigaChat MAX",
            "contextWindow": 32768,
            "maxTokens": 8192
          },
          {
            "id": "GigaChat-Pro",
            "name": "GigaChat Pro",
            "contextWindow": 32768,
            "maxTokens": 4096
          },
          {
            "id": "GigaChat",
            "name": "GigaChat Lite",
            "contextWindow": 8192,
            "maxTokens": 2048
          }
        ]
      }
    }
  }
}

3. Test

curl -s -X POST http://localhost:8443/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "GigaChat-Max",
    "messages": [{"role": "user", "content": "Привет!"}]
  }' | jq -r '.choices[0].message.content'

Expected output:

Привет! Как дела?

Creating an Agent

Add a GigaChat-powered agent to openclaw.json:

{
  "agents": {
    "list": [
      {
        "id": "ruslan",
        "name": "Ruslan",
        "emoji": "🐻",
        "model": "gigachat/GigaChat-Pro",
        "workspace": "/root/.openclaw/agents/ruslan/workspace"
      }
    ]
  }
}

Create agent workspace:

mkdir -p /root/.openclaw/agents/ruslan/workspace

IDENTITY.md:

# IDENTITY.md

- Name: Ruslan
- Creature: Российский AI-ассистент
- Vibe: Дружелюбный, знает русский контекст
- Emoji: 🐻

SOUL.md:

# SOUL.md — Кто ты

Ты Руслан. Российский AI-ассистент на базе GigaChat.

Говоришь на русском, знаешь русский контекст (кухня, культура, реалии).
Отвечаешь кратко и по делу. Без лишней вежливости.

Token Management

gpt2giga handles OAuth token generation and refresh automatically using the GIGACHAT_CREDENTIALS environment variable. No manual token management is needed.

If the proxy loses its token (e.g. after a long idle period), restart it:

/openclaw/skills/gigachat/scripts/start-proxy.sh

Troubleshooting

Issue: 401 Unauthorized

Cause: Token expired or invalid credentials
Fix: Restart proxy script (generates fresh token)

Issue: 402 Payment Required

Cause: Quota exhausted for that model
Fix: Try a different model or wait for quota reset

• Free tier: Limits per model
• Strategy: Rotate between Max → Pro → Lite

Issue: Process defunct / zombie

Cause: gpt2giga crashes but holds port
Fix:

fuser -k 8443/tcp
/openclaw/skills/gigachat/scripts/start-proxy.sh

Architecture

OpenClaw → http://localhost:8443/v1/chat/completions
           ↓
       gpt2giga (proxy, env-var auth)
           ↓
   Sber GigaChat API (OAuth token auto-managed)

Flow:

1. Startup script exports credentials as environment variables
2. gpt2giga starts and handles OAuth token generation internally
3. OpenClaw sends OpenAI-format requests to localhost:8443
4. gpt2giga translates to GigaChat format and manages auth
5. Responses translated back to OpenAI format

Files

• scripts/start-proxy.sh — Start proxy with env-var credentials
• scripts/start.sh — Alternative start (nohup)
• scripts/stop.sh — Stop proxy
• scripts/status.sh — Check proxy status
• scripts/setup.sh — Install gpt2giga from PyPI
• scripts/patch-config.sh — Add GigaChat provider to openclaw.json (backs up config first)
• SKILL.md — This file

Limitations

• Free Tier Quotas: Limited tokens per model
• SSL Verification: Disabled by default due to Sber's custom CA; install Sber root CA to /etc/ssl/certs/sber-ca.crt to enable
• Credentials: Passed via environment variables only (never on the command line); protect ~/.openclaw/gigachat-new.env with chmod 600

References

• GigaChat Docs: https://developers.sber.ru/docs/ru/gigachat/overview
• gpt2giga: https://pypi.org/project/gpt2giga/
• OpenClaw: https://openclaw.ai