Cấu hình OpenClaw

OpenClaw là một AI agent framework cho phép bạn tạo và quản lý các AI agents với khả năng tùy chỉnh cao. Tài liệu này hướng dẫn cấu hình OpenClaw để dùng với ShopAIKey API.

Endpoint chính

OpenAI-compatible: https://api.shopaikey.com/v1
Anthropic-compatible: https://api.shopaikey.com
Google GenAI: https://api.shopaikey.com

Cấu trúc file cấu hình

File cấu hình OpenClaw sử dụng định dạng JSON với các phần chính sau:

1. Meta & Wizard

code

{
  "meta": {
    "lastTouchedVersion": "2026.3.13",
    "lastTouchedAt": "2026-03-17T13:15:30.244Z"
  },
  "wizard": {
    "lastRunAt": "2026-03-17T12:46:52.879Z",
    "lastRunVersion": "2026.3.13",
    "lastRunCommand": "onboard",
    "lastRunMode": "local"
  }
}

Phần này lưu thông tin về phiên bản và lịch sử chạy wizard.

2. Models - Cấu hình nhà cung cấp AI

Bạn có thể khai báo nhiều provider cùng trỏ về ShopAIKey với các loại API khác nhau (OpenAI-compatible, Anthropic, Google GenAI). Mỗi provider chứa danh sách model muốn dùng.

code

{
  "models": {
    "mode": "merge",
    "providers": {
      "shopaikey": {
        "baseUrl": "https://api.shopaikey.com/v1",
        "apiKey": "sk-xxx",
        "api": "openai-completions",
        "models": [
          {
            "id": "gpt-5",
            "name": "GPT-5 (ShopAIKey)",
            "api": "openai-completions",
            "reasoning": true,
            "input": ["text", "image"],
            "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },
            "contextWindow": 400000,
            "maxTokens": 16384
          },
          {
            "id": "gpt-5-mini",
            "name": "GPT-5 Mini (ShopAIKey)",
            "api": "openai-completions",
            "reasoning": true,
            "input": ["text", "image"],
            "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },
            "contextWindow": 400000,
            "maxTokens": 16384
          },
          {
            "id": "claude-opus-4-5",
            "name": "Claude Opus 4.5 (ShopAIKey)",
            "api": "openai-completions",
            "reasoning": true,
            "input": ["text", "image"],
            "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },
            "contextWindow": 200000,
            "maxTokens": 32000
          },
          {
            "id": "claude-sonnet-4-5",
            "name": "Claude Sonnet 4.5 (ShopAIKey)",
            "api": "openai-completions",
            "reasoning": true,
            "input": ["text", "image"],
            "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },
            "contextWindow": 200000,
            "maxTokens": 64000
          },
          {
            "id": "claude-haiku-4-5",
            "name": "Claude Haiku 4.5 (ShopAIKey)",
            "api": "openai-completions",
            "reasoning": false,
            "input": ["text", "image"],
            "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },
            "contextWindow": 200000,
            "maxTokens": 8192
          },
          {
            "id": "deepseek-v3.2",
            "name": "DeepSeek V3.2 (ShopAIKey)",
            "api": "openai-completions",
            "reasoning": false,
            "input": ["text"],
            "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },
            "contextWindow": 128000,
            "maxTokens": 8192
          },
          {
            "id": "qwen3-coder-plus",
            "name": "Qwen3 Coder Plus (ShopAIKey)",
            "api": "openai-completions",
            "reasoning": false,
            "input": ["text"],
            "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },
            "contextWindow": 128000,
            "maxTokens": 8192
          }
        ]
      },
      "shopaikey-anthropic": {
        "baseUrl": "https://api.shopaikey.com",
        "apiKey": "sk-xxx",
        "api": "anthropic-messages",
        "models": [
          {
            "id": "claude-opus-4-5",
            "name": "Claude Opus 4.5 (Anthropic native)",
            "api": "anthropic-messages",
            "reasoning": true,
            "input": ["text", "image"],
            "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },
            "contextWindow": 200000,
            "maxTokens": 32000
          },
          {
            "id": "claude-sonnet-4-5",
            "name": "Claude Sonnet 4.5 (Anthropic native)",
            "api": "anthropic-messages",
            "reasoning": true,
            "input": ["text", "image"],
            "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },
            "contextWindow": 200000,
            "maxTokens": 64000
          }
        ]
      },
      "shopaikey-gemini": {
        "baseUrl": "https://api.shopaikey.com",
        "apiKey": "sk-xxx",
        "api": "google-generative-ai",
        "models": [
          {
            "id": "gemini-3-pro-preview",
            "name": "Gemini 3 Pro (ShopAIKey)",
            "api": "google-generative-ai",
            "reasoning": true,
            "input": ["text", "image", "video", "audio"],
            "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },
            "contextWindow": 1000000,
            "maxTokens": 8192
          },
          {
            "id": "gemini-3-flash-preview",
            "name": "Gemini 3 Flash (ShopAIKey)",
            "api": "google-generative-ai",
            "reasoning": false,
            "input": ["text", "image", "video", "audio"],
            "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },
            "contextWindow": 1000000,
            "maxTokens": 8192
          }
        ]
      }
    }
  }
}

Các trường quan trọng:

mode: Chế độ merge providers ("merge")
baseUrl: URL API ShopAIKey - dùng /v1 cho openai-completions, không có /v1 cho anthropic-messages và google-generative-ai
apiKey: API key ShopAIKey của bạn (cùng key dùng được cho cả 3 loại API)
api: Loại API
- "openai-completions": Hỗ trợ các model OpenAI-compatible qua OpenAI format
- "anthropic-messages": Native Anthropic format, hỗ trợ extended thinking và prompt caching đầy đủ
- "google-generative-ai": Native Gemini format
models: Danh sách các model có sẵn
- id: ID của model (phải khớp với tên model trong Bảng giá Model)
- contextWindow: Số token tối đa trong context
- maxTokens: Số token tối đa trong response
- reasoning: Model có hỗ trợ reasoning / extended thinking hay không
- input: Các loại input model hỗ trợ ("text", "image", "video", "audio")

Tip: với Claude, dùng provider "anthropic-messages" sẽ được tận dụng đầy đủ extended thinking và prompt caching. Provider "openai-completions" với model Claude vẫn hoạt động nhưng một số tính năng nâng cao có thể bị giới hạn.

3. Agents - Cấu hình AI Agents

code

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "shopaikey-anthropic/claude-sonnet-4-5"
      },
      "models": {
        "shopaikey/gpt-5": { "alias": "gpt" },
        "shopaikey/gpt-5-mini": { "alias": "gpt-mini" },
        "shopaikey-anthropic/claude-opus-4-5": { "alias": "opus" },
        "shopaikey-anthropic/claude-sonnet-4-5": { "alias": "sonnet" },
        "shopaikey/claude-haiku-4-5": { "alias": "haiku" },
        "shopaikey-gemini/gemini-3-pro-preview": { "alias": "gemini" },
        "shopaikey-gemini/gemini-3-flash-preview": { "alias": "gemini-fast" },
        "shopaikey/deepseek-v3.2": { "alias": "deepseek" },
        "shopaikey/qwen3-coder-plus": { "alias": "qwen-coder" }
      },
      "workspace": "/Users/username/.openclaw/workspace"
    },
    "list": [
      { "id": "main", "model": "shopaikey-anthropic/claude-sonnet-4-5" },
      { "id": "fast", "model": "shopaikey-gemini/gemini-3-flash-preview" },
      { "id": "coder", "model": "shopaikey/qwen3-coder-plus" }
    ]
  }
}

Cấu hình agents:

defaults.model.primary: Model mặc định khi gọi agent
defaults.models: Alias để dùng tên ngắn gọn (vd @gpt, @sonnet, @gemini) thay vì gõ đầy đủ provider/model
defaults.workspace: Thư mục làm việc của agents
list: Danh sách agent cụ thể, mỗi agent có thể chọn model khác nhau theo mục đích sử dụng

4. Tools & Commands

code

{
  "tools": {
    "profile": "coding"
  },
  "commands": {
    "native": "auto",
    "nativeSkills": "auto",
    "restart": true,
    "ownerDisplay": "raw"
  }
}

tools.profile: Profile công cụ ("coding" cho lập trình)
commands: Cấu hình các lệnh hệ thống

5. Gateway - Cấu hình server

code

{
  "gateway": {
    "port": 18789,
    "mode": "local",
    "bind": "loopback",
    "auth": {
      "mode": "token",
      "token": "your-secure-token",
      "password": "your-secure-password"
    },
    "tailscale": {
      "mode": "off",
      "resetOnExit": false
    },
    "nodes": {
      "denyCommands": [
        "camera.snap",
        "camera.clip",
        "screen.record",
        "contacts.add",
        "calendar.add",
        "reminders.add",
        "sms.send"
      ]
    }
  }
}

Cấu hình gateway:

port: Cổng server (mặc định 18789)
mode: Chế độ chạy ("local" hoặc "remote")
bind: Bind address ("loopback" chỉ localhost)
auth: Xác thực với token/password
nodes.denyCommands: Danh sách lệnh bị cấm

Ví dụ cấu hình hoàn chỉnh

code

{
  "meta": {
    "lastTouchedVersion": "2026.3.13",
    "lastTouchedAt": "2026-03-17T13:15:30.244Z"
  },
  "models": {
    "mode": "merge",
    "providers": {
      "shopaikey": {
        "baseUrl": "https://api.shopaikey.com/v1",
        "apiKey": "sk-xxx",
        "api": "openai-completions",
        "models": [
          {
            "id": "gpt-5",
            "name": "GPT-5",
            "api": "openai-completions",
            "reasoning": true,
            "input": ["text", "image"],
            "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },
            "contextWindow": 400000,
            "maxTokens": 16384
          },
          {
            "id": "deepseek-v3.2",
            "name": "DeepSeek V3.2",
            "api": "openai-completions",
            "reasoning": false,
            "input": ["text"],
            "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },
            "contextWindow": 128000,
            "maxTokens": 8192
          }
        ]
      },
      "shopaikey-anthropic": {
        "baseUrl": "https://api.shopaikey.com",
        "apiKey": "sk-xxx",
        "api": "anthropic-messages",
        "models": [
          {
            "id": "claude-sonnet-4-5",
            "name": "Claude Sonnet 4.5",
            "api": "anthropic-messages",
            "reasoning": true,
            "input": ["text", "image"],
            "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },
            "contextWindow": 200000,
            "maxTokens": 64000
          }
        ]
      },
      "shopaikey-gemini": {
        "baseUrl": "https://api.shopaikey.com",
        "apiKey": "sk-xxx",
        "api": "google-generative-ai",
        "models": [
          {
            "id": "gemini-3-pro-preview",
            "name": "Gemini 3 Pro",
            "api": "google-generative-ai",
            "reasoning": true,
            "input": ["text", "image", "video", "audio"],
            "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },
            "contextWindow": 1000000,
            "maxTokens": 8192
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": { "primary": "shopaikey-anthropic/claude-sonnet-4-5" },
      "models": {
        "shopaikey/gpt-5": { "alias": "gpt" },
        "shopaikey-anthropic/claude-sonnet-4-5": { "alias": "sonnet" },
        "shopaikey-gemini/gemini-3-pro-preview": { "alias": "gemini" }
      },
      "workspace": "/Users/username/.openclaw/workspace"
    },
    "list": [
      { "id": "main", "model": "shopaikey-anthropic/claude-sonnet-4-5" }
    ]
  },
  "tools": { "profile": "coding" },
  "gateway": {
    "port": 18789,
    "mode": "local",
    "bind": "loopback",
    "auth": {
      "mode": "token",
      "token": "your-secure-token",
      "password": "your-secure-password"
    }
  }
}

Hướng dẫn sử dụng

Tạo file cấu hình: Tạo file openclaw.json với nội dung như trên
Cấu hình API keys: Thay thế sk-xxx bằng API key thực của bạn (lấy từ tài khoản ShopAIKey)
Chọn models: Chỉ giữ những model bạn thực sự dùng để config gọn gàng. Tham khảo danh sách đầy đủ tại Bảng giá Model
Bảo mật: Đổi token và password gateway mặc định trước khi chạy
Khởi chạy: Chạy OpenClaw với file cấu hình này

Lưu ý bảo mật

Không commit API keys vào git - dùng biến môi trường hoặc file .gitignore
Sử dụng token/password mạnh cho gateway
Cân nhắc sử dụng mode: "local" nếu chỉ dùng trên máy cá nhân
Kiểm tra denyCommands để hạn chế quyền truy cập của agent
Khi chia sẻ config qua Tailscale hoặc remote, đảm bảo bind không phải "0.0.0.0" trừ khi thực sự cần

Hỗ trợ

Mua key & tra cứu đơn: @shopaikey_bot
Hỗ trợ kỹ thuật: @shopaikey_support

Bài cùng nhóm · Công cụ & IDE

Cấu hình DeepSeek Harness

Bài trướcCấu hình Gemini CLI Bài sau Cấu hình OpenCode