Hướng dẫn cấu hình CLIProxyAPI vào OpenClaw (Chuyển đổi model trên giao diện chat được)

Nếu bạn đã có CLIProxyAPI endpoint và muốn OpenClaw gọi model qua proxy thay vì gọi trực tiếp provider, bài này là cấu hình copy-paste được ngay.

1) CLIProxyAPI được nối vào OpenClaw ở đâu?

Trong OpenClaw, phần quyết định route model nằm ở 2 lớp:

1. Provider layer (models.providers)
   Khai báo endpoint proxy + danh sách model mà OpenClaw có thể thấy.
2. Agent routing layer (agents.defaults.model và agents.list[].model)
   Chọn model chính (primary) và model dự phòng (fallbacks) theo định dạng:
3. provider/model-id
   Ví dụ: cliproxy/gpt-5-mini

2) Mẫu cấu hình tối thiểu cho models.providers.cliproxy

Mở file:

nano ~/.openclaw/openclaw.json

Thêm (hoặc cập nhật) block sau:

{
  "models": {
    "mode": "replace",
    "providers": {
      "cliproxy": {
        "baseUrl": "https://proxy.naai.studio/v1",
        "apiKey": "<YOUR_CLIPROXY_API_KEY>",
        "api": "openai-completions",
        "models": [
          {
            "id": "gpt-5-mini",
            "name": "GPT 5 Mini",
            "reasoning": false,
            "input": ["text"],
            "cost": { "input": 0, "output": 0 },
            "contextWindow": 1000000,
            "maxTokens": 8192
          },
          {
            "id": "claude-opus-4-6",
            "name": "Claude Opus 4.6",
            "reasoning": true,
            "input": ["text", "image"],
            "cost": { "input": 0, "output": 0 },
            "contextWindow": 1000000,
            "maxTokens": 8192
          }
        ]
      }
    }
  }
}

Giải thích nhanh các field quan trọng

• baseUrl: endpoint của CLIProxyAPI (phải có /v1 nếu proxy dùng chuẩn OpenAI-compatible).
• apiKey: key để OpenClaw auth vào proxy.
• api: trong cấu hình thực tế là openai-completions.
• models[].id: phải khớp chính xác model ID mà proxy đang expose.
• models.mode: "replace": dùng danh sách model bạn khai báo để thay thế list mặc định.

3) Set model primary + fallback cho agent mặc định

Sau khi có provider, set route model ở agents.defaults.model:

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "cliproxy/gpt-5-mini",
        "fallbacks": [
          "cliproxy/claude-opus-4-6",
          "anthropic/claude-opus-4-6",
          "openai-codex/gpt-5.3-codex"
        ]
      }
    }
  }
}

Nguyên tắc:
- primary đặt model rẻ/nhanh cho đa số tác vụ.
- fallbacks trộn nhiều provider để tăng độ sẵn sàng khi proxy hoặc quota gặp lỗi.

Lưu ý quan trọng: để có thể chọn thêm model khác trực tiếp trên giao diện chat, bạn cần khai báo danh sách model ở fallbacks trong cấu hình agent.

4) Override theo từng agent (nếu cần)

Nếu bạn có nhiều persona/workspace (ví dụ personal, work), có thể override model riêng ở agents.list[]:

{
  "agents": {
    "list": [
      {
        "id": "personal",
        "model": {
          "primary": "openai-codex/gpt-5.1-codex-mini",
          "fallbacks": [
            "cliproxy/claude-opus-4-6",
            "cliproxy/gemini-3-pro-preview"
          ]
        }
      }
    ]
  }
}

Điểm hay: bạn vẫn giữ cliproxy/* trong fallback để tự động “cứu phiên” khi model chính fail.

5) Checklist verify sau khi lưu cấu hình

1. Kiểm tra JSON hợp lệ (không thừa dấu phẩy, đóng ngoặc đúng).
2. Gọi thử endpoint models của proxy (đảm bảo key/URL đúng).
3. Khởi động lại OpenClaw.
4. Test prompt ngắn để xác nhận model primary hoạt động.
5. Test tình huống fallback (tạm disable primary hoặc dùng model sai ID để quan sát chuyển fallback).

6) Lỗi thường gặp và cách xử lý nhanh

Lỗi 401 Unauthorized

• Sai apiKey hoặc key đã bị revoke.
• Fix: tạo key mới, cập nhật lại models.providers.cliproxy.apiKey.

Lỗi 404 / model not found

• baseUrl sai path hoặc model id không tồn tại trên proxy.
• Fix: kiểm tra lại /v1 và đồng bộ model ID với danh sách proxy trả về.

Không fallback dù primary fail

• Sai format route model (thiếu prefix provider, ví dụ dùng gpt-5-mini thay vì cliproxy/gpt-5-mini).
• Fix: luôn dùng đủ định dạng provider/model-id.

7) Bảo mật khi làm việc với openclaw.json

• Không commit ~/.openclaw/openclaw.json lên git.
• Không paste token thật vào ticket/chat public.
• Nếu từng lộ key, rotate ngay (API key, bot token, gateway token).
• Khi chia sẻ cấu hình, thay toàn bộ secret bằng placeholder.

Kết luận

Muốn tích hợp CLIProxyAPI vào OpenClaw ổn định, chỉ cần nhớ 3 điểm:
1. Khai báo đúng models.providers.cliproxy.
2. Route đúng primary/fallback theo format provider/model-id.
3. Verify sau mỗi lần đổi cấu hình.

Làm đúng 3 bước này, bạn sẽ vừa tận dụng được tài khoản hiện có qua proxy, vừa giữ hệ thống agent chạy ổn định khi có lỗi provider.