OAuth

OpenClaw hỗ trợ “subscription auth” qua OAuth cho các provider có cung cấp (đặc biệt là OpenAI Codex (ChatGPT OAuth)). Với Anthropic subscriptions, các bạn dùng flow setup-token. Trang này sẽ giải thích:

  • OAuth token exchange hoạt động như thế nào (PKCE)
  • Token được lưu trữ ở đâu (và tại sao)
  • Cách xử lý nhiều tài khoản (profiles + per-session overrides)

OpenClaw cũng hỗ trợ provider plugins có OAuth hoặc API‑key flows riêng. Chạy chúng qua:

openclaw models auth login --provider <id>

Token sink (tại sao cần nó)

Các OAuth provider thường tạo refresh token mới trong quá trình login/refresh. Một số provider (hoặc OAuth clients) có thể vô hiệu hóa refresh token cũ khi token mới được tạo cho cùng user/app.

Triệu chứng thực tế:

  • các bạn đăng nhập qua OpenClaw và qua Claude Code / Codex CLI → một trong số đó bị “logged out” ngẫu nhiên sau đó

Để giảm vấn đề này, OpenClaw coi auth-profiles.json như một token sink:

  • runtime đọc credentials từ một nơi duy nhất
  • mình có thể giữ nhiều profiles và route chúng một cách xác định

Storage (nơi lưu token)

Secrets được lưu theo từng agent:

  • Auth profiles (OAuth + API keys): ~/.openclaw/agents/<agentId>/agent/auth-profiles.json
  • Runtime cache (tự động quản lý; đừng edit): ~/.openclaw/agents/<agentId>/agent/auth.json

File legacy chỉ dùng để import (vẫn được hỗ trợ, nhưng không phải nơi lưu chính):

  • ~/.openclaw/credentials/oauth.json (được import vào auth-profiles.json lần đầu sử dụng)

Tất cả các file trên cũng tuân theo $OPENCLAW_STATE_DIR (state dir override). Tham khảo đầy đủ: /gateway/configuration

Anthropic setup-token (subscription auth)

Chạy claude setup-token trên bất kỳ máy nào, sau đó paste vào OpenClaw:

openclaw models auth setup-token --provider anthropic

Nếu các bạn đã tạo token ở nơi khác, paste thủ công:

openclaw models auth paste-token --provider anthropic

Kiểm tra:

openclaw models status

OAuth exchange (cách login hoạt động)

Các interactive login flows của OpenClaw được implement trong @mariozechner/pi-ai và kết nối vào wizards/commands.

Anthropic (Claude Pro/Max) setup-token

Flow shape:

  1. chạy claude setup-token
  2. paste token vào OpenClaw
  3. lưu dưới dạng token auth profile (không refresh)

Wizard path là openclaw onboard → auth choice setup-token (Anthropic).

OpenAI Codex (ChatGPT OAuth)

Flow shape (PKCE):

  1. tạo PKCE verifier/challenge + random state
  2. mở https://auth.openai.com/oauth/authorize?...
  3. thử capture callback trên http://127.0.0.1:1455/auth/callback
  4. nếu callback không bind được (hoặc các bạn đang remote/headless), paste redirect URL/code
  5. exchange tại https://auth.openai.com/oauth/token
  6. extract accountId từ access token và lưu { access, refresh, expires, accountId }

Wizard path là openclaw onboard → auth choice openai-codex.

Refresh + expiry

Profiles lưu trữ timestamp expires.

Khi runtime:

  • nếu expires còn trong tương lai → dùng access token đã lưu
  • nếu hết hạn → refresh (dưới file lock) và ghi đè credentials đã lưu

Flow refresh là tự động; các bạn thường không cần quản lý token thủ công.

Nhiều tài khoản (profiles) + routing

Hai pattern:

1) Khuyên dùng: tách riêng agents

Nếu các bạn muốn “personal” và “work” không bao giờ tương tác với nhau, dùng isolated agents (sessions + credentials + workspace riêng biệt):

openclaw agents add work
openclaw agents add personal

Sau đó config auth cho từng agent (wizard) và route chats đến đúng agent.

2) Nâng cao: nhiều profiles trong một agent

auth-profiles.json hỗ trợ nhiều profile IDs cho cùng một provider.

Chọn profile nào được dùng:

  • globally qua config ordering (auth.order)
  • per-session qua /model ...@<profileId>

Ví dụ (session override):

  • /model Opus@anthropic:work

Cách xem profile IDs nào tồn tại:

  • openclaw channels list --json (hiển thị auth[])

Tài liệu liên quan: