Integrasi: OpenClaw dengan Lunos

Panduan ini menjelaskan cara menghubungkan OpenClaw ke Lunos dengan menjadikan Lunos sebagai custom provider. Karena Lunos kompatibel OpenAI, OpenClaw bisa memakai ID model Lunos melalui satu endpoint di https://api.lunos.tech/v1.

Prasyarat

OpenClaw terpasang di perangkat Anda
Akun Lunos dan Lunos API key
ID model yang tersedia di dashboard Lunos Anda

Instruksi simple (CLI onboard)

Onboard Lunos via CLI

Jalankan perintah berikut secara berurutan. Setiap langkah memetakan proses konfigurasi manual.

Step 1 — Set API key

export LUNOS_API_KEY="lns-sk-your-key-here"

Ganti lns-sk-your-key-here dengan key dari Lunos Dashboard.

Step 2 — Register Lunos sebagai provider

openclaw onboard \
  --auth-choice apiKey \
  --token-provider lunos \
  --token "$LUNOS_API_KEY"

--token-provider adalah nama provider yang akan muncul di config (lunos).
--token mengambil key dari Step 1.

Step 3 — Set default model

openclaw models set lunos/openai/gpt-4o

Ganti openai/gpt-4o dengan model primary yang Anda inginkan.
Format lengkap: lunos/<provider>/<model-id> — cek ID yang tersedia di lunos.tech/models.

Step 4 — Restart gateway

openclaw gateway restart

Wajib setelah perubahan provider. Config tidak akan berlaku sebelum restart.

Step 5 — Verifikasi

openclaw models list
openclaw models status

list harus menampilkan model lunos/*.
status memastikan autentikasi sehat.

Instruksi detail (konfigurasi manual)

Ikuti langkah berikut dalam urutan yang benar.

1) Ambil Lunos API key Anda

Buat secret key di Lunos Dashboard. Simpan dengan aman dan anggap seperti password.

Anda juga bisa memverifikasi konektivitas dengan pengecekan balance:

curl -X GET "https://api.lunos.tech/v1/balance" \
  -H "Authorization: Bearer YOUR_LUNOS_API_KEY" \
  -H "Content-Type: application/json"

2) Simpan API key sebagai environment variable

Tujuannya agar secret tidak tersimpan/ter-commit ke git.

macOS / Linux (zsh/bash)

export LUNOS_API_KEY="lns-sk-your-key-here"

Windows (PowerShell)

$env:LUNOS_API_KEY = "lns-sk-your-key-here"

3) Buka konfigurasi `openclaw.json`

Lokasi config Anda biasanya:

~/.openclaw/openclaw.json

Beberapa instalasi lama bisa menggunakan:

~/.openclaw/clawdbot.json

Buat file ini jika belum ada.

4) Tambahkan Lunos sebagai custom provider

Tambahkan block lunos di dalam models.providers. Field api: "openai-completions" itu penting karena memberitahu OpenClaw untuk memakai protokol OpenAI saat routing request ke Lunos.

{
  "models": {
    "mode": "merge",
    "providers": {
      "lunos": {
        "baseUrl": "https://api.lunos.tech/v1",
        "apiKey": "${LUNOS_API_KEY}",
        "api": "openai-completions",
        "models": [
          {
            "id": "openai/gpt-4o",
            "name": "GPT-4o via Lunos",
            "contextWindow": 128000,
            "maxTokens": 4096
          },
          {
            "id": "anthropic/claude-sonnet-4",
            "name": "Claude Sonnet 4 via Lunos",
            "contextWindow": 200000,
            "maxTokens": 8192
          },
          {
            "id": "google/gemini-2.0-flash",
            "name": "Gemini 2.0 Flash via Lunos",
            "contextWindow": 1000000,
            "maxTokens": 8192
          }
        ]
      }
    }
  }
}

5) Allowlist model dan set alias (aturan dua langkah)

OpenClaw memakai referensi model yang sudah fully-qualified dengan format provider/model-id. Selain mendefinisikan provider di providers.lunos.models, Anda juga wajib allowlist model di agents.defaults.models (serta mengisi agents.defaults.model.primary dan fallbacks).

Gunakan contoh openclaw.json lengkap berikut:

{
  "models": {
    "mode": "merge",
    "providers": {
      "lunos": {
        "baseUrl": "https://api.lunos.tech/v1",
        "apiKey": "${LUNOS_API_KEY}",
        "api": "openai-completions",
        "models": [
          {
            "id": "openai/gpt-4o",
            "name": "GPT-4o via Lunos",
            "contextWindow": 128000,
            "maxTokens": 4096
          },
          {
            "id": "anthropic/claude-sonnet-4",
            "name": "Claude Sonnet 4 via Lunos",
            "contextWindow": 200000,
            "maxTokens": 8192
          },
          {
            "id": "google/gemini-2.0-flash",
            "name": "Gemini 2.0 Flash via Lunos",
            "contextWindow": 1000000,
            "maxTokens": 8192
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "lunos/openai/gpt-4o",
        "fallbacks": [
          "lunos/anthropic/claude-sonnet-4",
          "lunos/google/gemini-2.0-flash"
        ]
      },
      "models": {
        "lunos/openai/gpt-4o": {
          "alias": "gpt-4o"
        },
        "lunos/anthropic/claude-sonnet-4": {
          "alias": "sonnet"
        },
        "lunos/google/gemini-2.0-flash": {
          "alias": "gemini-flash"
        }
      }
    }
  }
}

6) Restart gateway dan verifikasi

Setiap perubahan config membutuhkan restart gateway. Lalu jalankan perintah untuk memastikan entri Lunos muncul di daftar model:

openclaw gateway restart
openclaw models list
openclaw models status

Jika masih muncul error model not allowed, pastikan nilai id di providers.lunos.models[].id benar-benar sama dengan referensi allowlist di agents.defaults.models (misalnya lunos/openai/gpt-4o).

7) Ganti model saat sesi berjalan

Setelah provider terpasang, Anda bisa mengganti model saat sesi berjalan menggunakan referensi fully-qualified atau alias yang sudah dibuat:

openclaw models set lunos/openai/gpt-4o
openclaw models set gpt-4o
openclaw models set gemini-flash

Power move: track usage per project dengan X-App-ID

Lunos mendukung header untuk menandai aplikasi/proyek. Saat OpenClaw meroute request lewat Lunos, Anda bisa menambahkan header ini di konfigurasi provider.

{
  "models": {
    "providers": {
      "lunos": {
        "baseUrl": "https://api.lunos.tech/v1",
        "apiKey": "${LUNOS_API_KEY}",
        "api": "openai-completions",
        "headers": {
          "X-App-ID": "my-openclaw-agent"
        },
        "models": []
      }
    }
  }
}

Setelah ini, setiap request akan ditag, sehingga Anda bisa memecah analitik token dan biaya berdasarkan app ID di dashboard Lunos.

Troubleshooting

Error `model not allowed`

Biasanya terjadi karena model sudah didefinisikan di providers.lunos.models, tetapi belum ditambahkan juga ke agents.defaults.models. Pastikan kedua bagian diisi, lalu restart gateway setelah melakukan perubahan pada openclaw.json.

Request 401 Unauthorized

OpenClaw kemungkinan tidak membaca API key Anda. Pastikan LUNOS_API_KEY diexport di shell tempat Anda menjalankan OpenClaw:

echo $LUNOS_API_KEY

Jika output kosong, export ulang variabel tersebut atau buat agar permanen di profil shell Anda.

Model lama masih muncul setelah perubahan config

Setelah mengubah openclaw.json:

Jalankan openclaw gateway restart
Buka sesi baru
Verifikasi dengan openclaw models list

Rate limiting (error 429)

Jika Anda mengisi agents.defaults.model.fallbacks, OpenClaw bisa mencoba fallback model saat model gagal. Lunos rate limiting bisa mengirim header seperti:

X-RateLimit-Limit
X-RateLimit-Remaining
X-RateLimit-Reset

Jalankan openclaw models status setelah perubahan konfigurasi untuk memastikan model mana yang aktif.

Keamanan

Jangan commit API key ke repository.
Gunakan environment variable (misalnya LUNOS_API_KEY) dan referensikan di openclaw.json sebagai ${LUNOS_API_KEY}.
Pisahkan key untuk dev/staging/prod jika memungkinkan.

Referensi

Dokumentasi Lunos: https://lunos.tech/docs
Model Providers OpenClaw: https://docs.openclaw.ai/concepts/model-providers

Di halaman ini

Tidak ada judul di halaman ini.