Authentication

OpenClaw hỗ trợ OAuth và API key cho các model provider. Với tài khoản Anthropic, mình khuyên các bạn dùng API key. Còn nếu dùng gói đăng ký Claude, thì dùng token dài hạn được tạo bởi claude setup-token.

Xem /concepts/oauth để hiểu đầy đủ về OAuth flow và cách lưu trữ.

Cách setup Anthropic được khuyên dùng (API key)

Nếu các bạn dùng Anthropic trực tiếp, hãy dùng API key.

  1. Tạo API key trong Anthropic Console.
  2. Đặt nó trên gateway host (máy đang chạy openclaw gateway).
export ANTHROPIC_API_KEY="..."
openclaw models status
  1. Nếu Gateway chạy dưới systemd/launchd, nên đặt key vào ~/.openclaw/.env để daemon có thể đọc được:
cat >> ~/.openclaw/.env <<'EOF'
ANTHROPIC_API_KEY=...
EOF

Sau đó restart daemon (hoặc restart Gateway process) và kiểm tra lại:

openclaw models status
openclaw doctor

Nếu các bạn không muốn tự quản lý env vars, wizard onboarding có thể lưu API key cho daemon: openclaw onboard.

Xem Help để biết chi tiết về env inheritance (env.shellEnv, ~/.openclaw/.env, systemd/launchd).

Anthropic: setup-token (xác thực subscription)

Với Anthropic, cách được khuyên dùng là API key. Nếu các bạn đang dùng gói đăng ký Claude, setup-token flow cũng được hỗ trợ. Chạy lệnh này trên gateway host:

claude setup-token

Sau đó paste nó vào OpenClaw:

openclaw models auth setup-token --provider anthropic

Nếu token được tạo trên máy khác, paste thủ công:

openclaw models auth paste-token --provider anthropic

Nếu các bạn thấy lỗi Anthropic như này:

This credential is only authorized for use with Claude Code and cannot be used for other API requests.

…thì hãy dùng Anthropic API key thay thế.

Nhập token thủ công (bất kỳ provider nào; ghi vào auth-profiles.json + cập nhật config):

openclaw models auth paste-token --provider anthropic
openclaw models auth paste-token --provider openrouter

Kiểm tra thân thiện với automation (exit 1 khi expired/missing, 2 khi sắp hết hạn):

openclaw models status --check

Các script ops tùy chọn (systemd/Termux) được ghi ở đây: /automation/auth-monitoring

claude setup-token yêu cầu interactive TTY.

Kiểm tra trạng thái xác thực model

openclaw models status
openclaw doctor

Kiểm soát credential nào được sử dụng

Per-session (lệnh chat)

Dùng /model <alias-or-id>@<profileId> để ghim một provider credential cụ thể cho session hiện tại (ví dụ profile ids: anthropic:default, anthropic:work).

Dùng /model (hoặc /model list) để mở picker gọn; dùng /model status để xem đầy đủ (candidates + next auth profile, cộng thêm chi tiết provider endpoint khi đã config).

Per-agent (CLI override)

Đặt thứ tự auth profile override rõ ràng cho một agent (lưu trong auth-profiles.json của agent đó):

openclaw models auth order get --provider anthropic
openclaw models auth order set --provider anthropic anthropic:default
openclaw models auth order clear --provider anthropic

Dùng --agent <id> để target một agent cụ thể; bỏ qua nó để dùng default agent đã config.

Troubleshooting

”No credentials found”

Nếu Anthropic token profile bị thiếu, chạy claude setup-token trên gateway host, sau đó kiểm tra lại:

openclaw models status

Token sắp hết hạn/đã hết hạn

Chạy openclaw models status để xác nhận profile nào đang sắp hết hạn. Nếu profile bị thiếu, chạy lại claude setup-token và paste token lại.

Yêu cầu

  • Gói đăng ký Claude Max hoặc Pro (cho claude setup-token)
  • Claude Code CLI đã cài đặt (lệnh claude có sẵn)