Cấu hình API Key OpenClaw: Hướng dẫn chi tiết từ Claude đến GPT (2026)

API key là “chìa khóa” kết nối OpenClaw với model AI (Claude, GPT, Gemini…). Không có API key, OpenClaw không thể xử lý bất kỳ task nào. Bài viết này hướng dẫn bạn cách lấy API key từ từng provider, cấu hình đúng cách trong openclaw.json, dùng lệnh openclaw configure, thiết lập multi-model routing, và xử lý lỗi auth.

Chưa cài OpenClaw? Xem trước Hướng dẫn cài đặt OpenClaw từ A-Z.

---

Nên chọn model nào cho OpenClaw?

Trước khi lấy API key, bạn cần quyết định dùng model nào. OpenClaw hỗ trợ 50+ LLM provider — từ cloud lớn (Anthropic, OpenAI, Google) đến model local (Ollama) và router (OpenRouter, Groq).

Model	Provider	Điểm mạnh	Phù hợp với	Chi phí (ước tính)
Claude Sonnet	Anthropic	Cân bằng tốc độ-chất lượng	Đa số use case	~$3/1M token
Claude Opus	Anthropic	Chất lượng cao nhất	Task phức tạp, phân tích sâu	~$15/1M token
Claude Haiku	Anthropic	Nhanh, rẻ	Task đơn giản, chatbot	~$0.25/1M token
GPT-4o	OpenAI	Đa năng, hỗ trợ vision	Xử lý ảnh, đa phương tiện	~$5/1M token
GPT-4o mini	OpenAI	Rẻ, nhanh	Task cơ bản	~$0.15/1M token
Gemini Pro	Google	Free tier rộng rãi	Thử nghiệm, budget thấp	Free tier khá
DeepSeek V3	DeepSeek	Giá rẻ, chất lượng khá	Budget thấp, code	~$0.27/1M token
Grok	xAI	Nhanh, real-time data	Tin tức, trending	~$5/1M token
Local (Ollama)	Self-host	Miễn phí, riêng tư	Ai quan tâm privacy	Chi phí phần cứng

Khuyến nghị: Bắt đầu với Claude Sonnet nếu bạn muốn chất lượng tốt với chi phí hợp lý. Dùng Gemini nếu muốn free tier để thử nghiệm. Dùng GPT-4o nếu cần xử lý ảnh.

---

Cách 1: Cấu hình nhanh bằng openclaw configure

Đây là cách đơn giản nhất — OpenClaw hỏi từng bước và tự ghi vào config file.

openclaw configure

Wizard hỏi lần lượt: chọn provider → nhập API key → chọn model → test kết nối. Xong.

Cấu hình từng phần riêng:

openclaw configure --section models     # Chỉ cấu hình model/API key
openclaw configure --section gateway    # Chỉ cấu hình Gateway
openclaw configure --section channels   # Chỉ cấu hình channel

Kiểm tra model đang dùng:

openclaw models list          # Danh sách model có sẵn
openclaw models set <model>   # Đổi model nhanh

Hoặc trong chat OpenClaw, gõ /model để đổi model tại chỗ mà không cần terminal.

---

Cách 2: Cấu hình thủ công trong openclaw.json

File cấu hình nằm tại ~/.openclaw/openclaw.json (JSON5 format — hỗ trợ comments, trailing comma). Đây là cách cho ai muốn kiểm soát chi tiết.

Cấu trúc cơ bản

{
  // Model chính
  "agents": {
    "defaults": {
      "model": {
        "primary": "claude-sonnet-4-20250514",    // Model mặc định
        "fallbacks": ["gpt-4o-mini", "gemini-pro"] // Backup khi primary fail
      },
      "models": [                                   // Allowlist — chỉ model trong list mới được dùng
        "claude-sonnet-4-20250514",
        "claude-haiku-4-5-20251001",
        "gpt-4o",
        "gpt-4o-mini",
        "gemini-pro"
      ]
    }
  }
}

Giải thích:

• model.primary — model mặc định cho mọi task.
• model.fallbacks — nếu primary gặp lỗi (rate limit, timeout, outage), OpenClaw tự động chuyển sang model tiếp theo trong danh sách. Cooldown tự động trước khi thử lại primary.
• models — allowlist (danh sách trắng). Chỉ model nằm trong list mới được phép sử dụng. Nếu ai gõ /model gpt-4-turbo mà model đó không có trong allowlist → bị chặn.

API key qua environment variable

OpenClaw đọc API key từ biến môi trường theo convention:

# Anthropic (Claude)
export ANTHROPIC_API_KEY="sk-ant-api03-xxxxx..."

# OpenAI (GPT)
export OPENAI_API_KEY="sk-proj-xxxxx..."

# Google (Gemini)
export GOOGLE_API_KEY="AIzaSy..."

# xAI (Grok)
export XAI_API_KEY="xai-xxxxx..."

# DeepSeek
export DEEPSEEK_API_KEY="sk-xxxxx..."

# OpenRouter (50+ model qua 1 key)
export OPENROUTER_API_KEY="sk-or-xxxxx..."

Thêm vào ~/.bashrc (hoặc ~/.zshrc) để lưu vĩnh viễn. Trên Windows native, dùng Environment Variables trong System Properties.

Không muốn dùng env var? Chạy openclaw configure — wizard tự xử lý lưu key.

---

Lấy API Key từ Anthropic (Claude)

1. Truy cập console.anthropic.com
2. Đăng ký tài khoản bằng email
3. Vào Settings → Billing → thêm thẻ tín dụng/debit → nạp credit (tối thiểu $5)
4. Vào Settings → API Keys → nhấn Create Key
5. Đặt tên (ví dụ: “OpenClaw Production”) → copy key ngay lập tức

Key format: sk-ant-api03-xxxxx... — key chỉ hiển thị một lần, mất thì phải tạo mới.

export ANTHROPIC_API_KEY="sk-ant-api03-xxxxx..."
openclaw models set claude-sonnet-4-20250514

Hoặc dùng OAuth (không cần copy key):

openclaw models auth login --provider anthropic

Lệnh mở trình duyệt → đăng nhập Anthropic → cấp quyền → done. Token tự lưu và tự refresh.

---

Lấy API Key từ OpenAI (GPT)

1. Truy cập platform.openai.com
2. Đăng ký/đăng nhập → xác minh số điện thoại
3. Vào Settings → Billing → nạp credit (khuyến nghị $10)
4. Vào API Keys → nhấn Create new secret key → copy key

Key format: sk-proj-xxxxx...

export OPENAI_API_KEY="sk-proj-xxxxx..."
openclaw models set gpt-4o

Lưu ý: Một số model (GPT-4o, o1) yêu cầu tier 2+ trên OpenAI. Nếu gặp lỗi “model not found”, kiểm tra tier trong dashboard OpenAI.

---

Lấy API Key từ Google (Gemini)

1. Vào aistudio.google.com → đăng nhập Google
2. Nhấn Get API Key → chọn project (hoặc tạo mới) → copy key

Key format: AIzaSy...

export GOOGLE_API_KEY="AIzaSy..."
openclaw models set gemini-pro

Ưu điểm: Google cung cấp free tier khá rộng rãi — phù hợp để thử nghiệm trước khi chuyển sang Claude hoặc GPT.

---

Dùng model local với Ollama (không cần API key)

Nếu bạn muốn chạy OpenClaw mà không phụ thuộc API bên ngoài:

# Cài Ollama
curl -fsSL https://ollama.com/install.sh | sh

# Tải model
ollama pull llama3.1

# Cấu hình OpenClaw
openclaw configure --section models
# Chọn provider: ollama → model: llama3.1 → base URL: http://localhost:11434

Hoặc cấu hình thủ công trong openclaw.json:

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "ollama/llama3.1"
      }
    }
  }
}

Lưu ý: Model local cần phần cứng mạnh (tối thiểu 16 GB RAM, có GPU thì càng tốt). Chất lượng output thường thấp hơn Claude/GPT cho task phức tạp.

---

Dùng OpenRouter (50+ model qua 1 API key)

Nếu bạn muốn truy cập nhiều model từ nhiều provider mà chỉ cần 1 API key, OpenRouter là trung gian tốt nhất:

1. Vào openrouter.ai → đăng ký → nạp credit
2. Vào API Keys → tạo key

export OPENROUTER_API_KEY="sk-or-xxxxx..."

Trong openclaw.json:

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "anthropic/claude-sonnet-4",
        "fallbacks": ["openai/gpt-4o-mini", "google/gemini-pro"]
      }
    }
  }
}

Ưu điểm: 1 key, 50+ model, 1 billing. Nhược điểm: thêm 1 lớp trung gian → latency cao hơn một chút.

---

Multi-model routing: Dùng nhiều LLM thông minh

OpenClaw hỗ trợ multi-model routing với tự động failover:

Chiến lược 1: Primary + Fallback

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "claude-sonnet-4-20250514",
        "fallbacks": ["gpt-4o-mini", "gemini-pro"]
      }
    }
  }
}

Khi Claude bị rate limit (429) hoặc timeout → OpenClaw tự chuyển sang GPT-4o mini → nếu GPT cũng fail → Gemini. Cooldown tự động trước khi quay lại primary.

Chiến lược 2: Model theo task type

Dùng model mạnh cho task phức tạp, model rẻ cho task đơn giản — tiết kiệm 60-70% chi phí:

• Task chính (viết content, phân tích, code): Claude Sonnet
• Task đơn giản (tóm tắt, phân loại, chatbot): GPT-4o mini hoặc Claude Haiku
• Xử lý ảnh: GPT-4o (vision)

Đổi model nhanh trong chat: gõ /model claude-haiku-4-5-20251001 hoặc /model gpt-4o-mini.

Theo dõi chi phí

/status         # Xem model đang dùng, token count
/usage full     # Báo cáo chi phí chi tiết theo model, theo ngày

---

OAuth: Xác thực không cần copy key

Thay vì copy-paste API key, OpenClaw hỗ trợ OAuth (browser-based authentication) cho một số provider:

openclaw models auth login --provider anthropic
openclaw models auth login --provider openai
openclaw models auth login --provider google

Lệnh mở trình duyệt → đăng nhập provider → cấp quyền → token tự lưu vào config. Token tự refresh khi hết hạn.

Khi nào dùng OAuth thay API key?

• Bạn không muốn copy/paste key (rủi ro lộ key qua clipboard)
• Provider bắt buộc OAuth (một số tổ chức enforce OAuth cho security)
• Team dùng chung config nhưng mỗi người auth riêng

Kiểm tra trạng thái auth:

openclaw models auth status

---

Cấu hình trên TryOpenClaw.io

Nếu bạn dùng TryOpenClaw.io, quá trình cấu hình API key đơn giản hơn:

1. Vào Dashboard → Settings → Model
2. Chọn model (Claude/GPT/Gemini)
3. Dán API key vào ô tương ứng
4. Nhấn Save — không cần restart, không cần sửa config file

TryOpenClaw cũng hỗ trợ hệ thống credit trực tiếp — bạn không cần tạo API key riêng, dùng credit TryOpenClaw để trả phí LLM. Tiện hơn nếu bạn không muốn quản lý API key.

Chi tiết: Chạy OpenClaw trên Cloud — không cần cài đặt

---

Bảo mật API Key

API key = quyền truy cập vào tài khoản LLM provider của bạn. Nếu bị lộ, người khác có thể dùng credit của bạn.

Không bao giờ commit API key vào Git. OpenClaw config file (openclaw.json) không chứa key trực tiếp — key nằm trong environment variable hoặc được mã hóa bởi openclaw configure.

Rotate key định kỳ: Tạo key mới mỗi 3-6 tháng và revoke key cũ trên dashboard provider.

Set spending limit: Cả Anthropic và OpenAI đều cho phép đặt giới hạn chi tiêu hàng tháng. Thiết lập để tránh bị charge bất ngờ.

Dùng key riêng cho từng project: Không share API key giữa OpenClaw và các ứng dụng khác — nếu 1 key bị lộ, chỉ ảnh hưởng 1 project.

Config file permission: OpenClaw kiểm tra quyền file tự động. Nếu ~/.openclaw/openclaw.json có quyền quá mở (world-readable), OpenClaw cảnh báo:

chmod 600 ~/.openclaw/openclaw.json   # Chỉ user hiện tại đọc/ghi

---

Lỗi thường gặp khi cấu hình API Key

“Invalid API key” hoặc “401 Unauthorized”: Key copy thiếu ký tự, có khoảng trắng thừa, hoặc bị revoke. Thử: tạo key mới, copy chính xác, chạy openclaw configure --section models lại.

“Insufficient quota” hoặc “402 Payment Required”: Hết credit. Nạp thêm tiền vào tài khoản provider. Kiểm tra spending limit có quá thấp không.

“Model not found”: Tên model sai. Chạy openclaw models list để xem danh sách model khả dụng. Một số model yêu cầu tier cao hơn (GPT-4o cần tier 2+ trên OpenAI).

Response rất chậm: Đổi sang model nhẹ hơn: /model claude-haiku-4-5-20251001 hoặc /model gpt-4o-mini. Kiểm tra rate limit — bạn có thể đang ở tier thấp.

OAuth token hết hạn:

openclaw models auth login --provider <tên-provider>

Debug đầy đủ: Lỗi thường gặp khi cài OpenClaw và cách khắc phục

---

FAQ

API key có miễn phí không? Hầu hết provider tính phí theo lượng sử dụng (pay-as-you-go). Google Gemini có free tier khá rộng. OpenAI và Anthropic thường tặng $5-10 credit cho tài khoản mới.

Cần bao nhiêu credit để bắt đầu? $5-10 là đủ cho 1-2 tuần sử dụng cơ bản (vài trăm task đơn giản). Nếu dùng Haiku/GPT-4o-mini cho task nhẹ, có thể kéo dài gấp 10 lần.

API key có hết hạn không? Anthropic và OpenAI key không hết hạn (trừ khi bạn revoke). Google key cũng tương tự. Tuy nhiên, credit có thể hết — và key sẽ trả lỗi 402.

Có thể dùng nhiều provider cùng lúc không? Có. Cấu hình primary + fallbacks trong openclaw.json. OpenClaw tự chuyển đổi khi provider gặp lỗi.

OpenRouter hay key riêng cho từng provider? Key riêng: nhanh hơn (ít 1 hop), giá gốc. OpenRouter: tiện (1 key, 1 billing), linh hoạt chuyển model. Nếu chỉ dùng 1-2 provider → key riêng. Nếu hay đổi model/thử nghiệm → OpenRouter.

---

Tổng kết

Cấu hình API key là bước quyết định OpenClaw sẽ dùng “bộ não” nào. Cách nhanh nhất: chạy openclaw configure — wizard tự hỏi và ghi config. Cách chi tiết: sửa ~/.openclaw/openclaw.json trực tiếp.

Bắt đầu với Claude Sonnet (chất lượng-giá tốt nhất), thêm fallback model để đảm bảo uptime, và set spending limit để kiểm soát chi phí.

---