Lỗi '401 Invalid bearer token' OpenClaw là gì?

Token Anthropic API key của bạn sai format hoặc đã hết hạn. Format đúng là sk-ant-api03-[...]. Kiểm tra lại key trong Anthropic Console và đảm bảo copy đủ không bị cắt.

'All in cooldown' trong OpenClaw nghĩa là gì?

OpenClaw tạm block requests vì nhiều request liên tiếp fail. Đợi 5-10 phút hoặc restart gateway bằng lệnh 'openclaw gateway restart'.

OpenClaw 429 rate limit fix như thế nào?

Lỗi 429 nghĩa là API key của bạn đang bị throttle bởi provider (Anthropic/OpenAI). Đợi 1 phút rồi thử lại. Nếu liên tục, kiểm tra billing tier — free tier có rate limit thấp hơn nhiều so với paid tier.

Troubleshooting

OpenClaw API Key Không Hoạt Động: 6 Lỗi Phổ Biến Nhất Và Cách Xử Lý

Q: Cách kiểm tra API key OpenClaw đang hoạt động hay không?

Chạy lệnh 'openclaw models status' — nếu thấy danh sách models với status 'available' là key đang hoạt động tốt. Nếu thấy 'cooldown' hoặc lỗi là có vấn đề cần xử lý.

Đội ngũ NOVA • Tháng 3, 2026 • 8 phút đọc

💬 Trả Lời Nhanh

Khi OpenClaw báo lỗi API key, có 3 nguồn gốc khác nhau: (1) sai format key — Anthropic Claude cần format sk-ant-api03-..., (2) đặt key sai chỗ trong file config (~/.openclaw/openclaw.json), (3) billing/quota chưa active trên tài khoản provider. Thử lệnh openclaw doctor --fix trước — xử lý được khoảng 60% lỗi cấu hình thông thường. Nếu vẫn lỗi, đọc tiếp để xác định đúng nguyên nhân.

📋 Điểm Chính Cần Nhớ

OpenClaw có 3 lớp authentication — lỗi ở lớp nào cũng hiện là "API key error"
Format key Anthropic: sk-ant-api03-[...] | OpenAI: sk-[...]
API key đặt đúng chỗ nhưng billing chưa active vẫn báo 401
Lỗi 429 (rate limit) và 401 (auth) cần fix khác nhau — đừng nhầm

Tại sao lỗi API key OpenClaw phức tạp hơn bình thường?

Đây là điều làm nhiều người bối rối nhất: cùng một thông báo lỗi nhưng có thể đến từ 3 chỗ khác nhau hoàn toàn.

OpenClaw có kiến trúc 3 lớp authentication:

Lớp 1 — Config cục bộ: File ~/.openclaw/openclaw.json trên máy/VPS của anh/chị
Lớp 2 — Gateway token: Token để OpenClaw gateway giao tiếp với các services
Lớp 3 — Upstream provider: API key thật của Anthropic hoặc OpenAI

Lỗi ở bất kỳ lớp nào cũng có thể hiện lên màn hình là "authentication error" hoặc "invalid key." Đây là lý do nhiều người thử đổi API key nhiều lần nhưng vẫn không fix được — vì vấn đề không phải ở key.

💡 Tip đầu tiên: Trước khi làm bất cứ gì, chạy openclaw doctor --fix. Lệnh này tự động scan và fix nhiều lỗi config thông thường. Nếu xong mà vẫn lỗi — lúc đó mới cần đọc tiếp.

6 lỗi phổ biến nhất kèm cách xử lý

Lỗi 1: 401 authentication_error — Invalid bearer token

Nguyên nhân: API key sai format hoặc đã bị thu hồi. Đây là lỗi dễ fix nhất.
Fix: Vào Anthropic Console (console.anthropic.com) hoặc OpenAI Platform, tạo key mới, copy toàn bộ (không cắt). Anthropic key bắt đầu bằng sk-ant-api03-, OpenAI key bắt đầu bằng sk-.

Lỗi 2: "No API key found" hoặc "Key not configured"

Nguyên nhân: Key chưa được đặt trong file config, hoặc đặt sai chỗ.
Fix: Kiểm tra vị trí key trong openclaw.json (xem mục dưới).

Lỗi 3: 429 rate_limit_error

Nguyên nhân: API key đang bị throttle — gọi quá nhiều trong thời gian ngắn, hoặc đang dùng free tier có rate limit thấp.
Fix: Đợi 1–2 phút. Nếu thường xuyên gặp, nâng billing tier của tài khoản Anthropic/OpenAI lên paid.

Lỗi 4: 502 Bad Gateway hoặc WebSocket error 1008

Nguyên nhân: Gateway token mismatch — token trong config không khớp với gateway đang chạy.
Fix: Restart gateway: openclaw gateway restart. Nếu vẫn lỗi, kiểm tra gatewayToken trong config.

Lỗi 5: "All models in cooldown"

Nguyên nhân: OpenClaw đã tạm block tất cả request vì nhiều lần fail liên tiếp (auto-protection).
Fix: Đợi 5–10 phút để cooldown hết, hoặc restart gateway.

Lỗi 6: "Billing not active" hoặc key hợp lệ nhưng fail silent

Nguyên nhân: Tài khoản Anthropic/OpenAI chưa add billing method, hoặc credit đã hết.
Fix: Vào console của provider, add payment method và nạp credit tối thiểu ($5 là đủ để test).

File config đúng trông như thế nào?

Đây là điểm dễ sai nhất. API key phải đặt ở đúng vị trí trong file cấu hình:

// ~/.openclaw/openclaw.json — Cấu trúc đúng
{
  "model": "claude-sonnet-4-5",
  // API key phải ở root level, trong mục này:
  "anthropic": {
    "apiKey": "sk-ant-api03-YOUR_KEY_HERE"
  },
  // KHÔNG đặt key trong skills.entries hay chỗ khác
  "gateway": {
    "port": 18789
  }
}
    

Lỗi phổ biến nhất mình thấy: key được copy vào đúng file nhưng đặt trong một block lồng nhau (ví dụ trong skills hay plugins) thay vì root level. App vẫn khởi động bình thường, không báo lỗi syntax — chỉ đến khi gọi API mới báo "key not found."

Sau khi fix xong, làm sao biết API key đang hoạt động?

Chạy lệnh này để kiểm tra nhanh:

openclaw models status

Kết quả đúng sẽ hiện danh sách models với status "available". Nếu thấy "cooldown," "error," hay không thấy model nào — là vẫn còn vấn đề cần xử lý tiếp.

Muốn hiểu chi tiết hơn về chi phí API key mỗi model tốn bao nhiêu? Xem bài OpenClaw tốn bao nhiêu tiền thật sự?

Đã thử hết mà vẫn lỗi — lúc này nên làm gì?

Mình hoàn toàn hiểu cảm giác này. Đọc docs, làm đúng từng bước, nhưng màn hình vẫn đỏ.

Vấn đề thật sự không phải anh/chị làm sai. Vấn đề là những lỗi này đòi hỏi phải hiểu cả 3 lớp authentication của OpenClaw mới có thể diagnose chính xác. Không phải thứ có thể học nhanh qua Google.

Mình đã debug lỗi API key OpenClaw hàng chục lần cho các khách hàng khác nhau. Trong hầu hết trường hợp, 15 phút nhìn vào setup của anh/chị là đủ để tìm ra nguyên nhân thật — và fix ngay trong buổi đó.

Nếu anh/chị đang stuck với bot Telegram thay vì lỗi API key — đọc bài OpenClaw bot Telegram không trả lời: 5 nguyên nhân phổ biến để xem đó có phải vấn đề khác không.

Những vấn đề phổ biến khác sau khi fix được API key

Theo dữ liệu thực tế từ người dùng VN (tuần 9–10/03/2026), sau khi fix xong lỗi API key, nhu cầu tiếp theo thường là:

Tối ưu model: Dùng Claude Sonnet hay Opus? Cho task nào? Tốn bao nhiêu? — Nhiều người setup xong nhưng không biết cấu hình model cho từng loại task.
Kết nối Google Workspace: Đọc Google Sheets, gửi email qua Gmail, cập nhật Google Docs — đây là integration được hỏi nhiều nhất sau setup cơ bản.
Mở rộng cho team: Từ 1 người dùng → cả team dùng chung — cần setup allowlist và permissions đúng cách.

Đây không phải setup 1 lần là xong. Anh/chị cần người đồng hành liên tục — đó là lý do gói Basic 2M/tháng cover cả ongoing support, không chỉ lần đầu.

Đặt Lịch Debug 15 Phút Miễn Phí

Mình nhìn qua setup của anh/chị, xác định đúng nguyên nhân lỗi, và fix ngay trong buổi đó. Không cần anh/chị biết terminal hay đọc log.

📅 Đặt Lịch Ngay

Miễn phí hoàn toàn. Sau 15 phút anh/chị biết vấn đề ở đâu.

Câu Hỏi Thường Gặp

Lỗi "authentication_error: Invalid bearer token" là gì?

Token Anthropic API key của bạn sai format hoặc đã hết hạn. Kiểm tra lại key trong Anthropic Console — đảm bảo key bắt đầu bằng sk-ant-api03- và copy đủ, không bị cắt cụt.

Tại sao API key đúng nhưng vẫn lỗi 401?

Có thể key đặt sai vị trí trong file config. Key phải ở root level của openclaw.json trong mục "anthropic" hoặc "openai", không phải trong skills.entries hay cấu trúc lồng nhau khác. Đây là lỗi thường gặp nhất mà khó phát hiện nhất.

"All models in cooldown" nghĩa là gì?

OpenClaw tạm block tất cả requests vì nhiều request liên tiếp bị fail — đây là cơ chế tự bảo vệ để tránh tốn credit khi có lỗi. Đợi 5–10 phút hoặc chạy "openclaw gateway restart" để reset.

Làm sao kiểm tra API key OpenClaw đang hoạt động không?

Chạy lệnh "openclaw models status" trong terminal. Nếu thấy danh sách models với status "available" là key đang hoạt động bình thường. Nếu thấy "cooldown" hoặc lỗi là cần xử lý thêm.

API key Anthropic và OpenClaw gateway token khác nhau như thế nào?

Đây là 2 thứ khác nhau hoàn toàn. API key Anthropic là key để gọi Claude AI — lấy từ console.anthropic.com. Gateway token là token nội bộ của OpenClaw để bảo vệ gateway — tự sinh ra khi cài. Nhầm 2 cái này với nhau là lỗi phổ biến nhất.