OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Fundamentals

OAuth

OpenClaw hỗ trợ OAuth ("xác thực bằng gói thuê bao") cho các nhà cung cấp có cung cấp phương thức này, đáng chú ý là OpenAI Codex (ChatGPT OAuth) và tái sử dụng Anthropic Claude CLI. Đối với Anthropic, cách phân chia thực tế là:

  • Khóa API Anthropic: thanh toán API Anthropic thông thường.
  • Anthropic Claude CLI / xác thực bằng gói thuê bao bên trong OpenClaw: nhân viên Anthropic đã thông báo với chúng tôi rằng cách sử dụng này lại được cho phép, vì vậy OpenClaw xem việc tái sử dụng Claude CLI và sử dụng claude -p là được chấp thuận cho tích hợp này, trừ khi Anthropic công bố chính sách mới. Khi dùng Anthropic trong môi trường sản xuất, xác thực bằng khóa API vẫn là phương án an toàn hơn và được khuyến nghị.

OpenClaw lưu cả xác thực bằng khóa API OpenAI và ChatGPT/Codex OAuth dưới ID nhà cung cấp chuẩn openai. Các ID hồ sơ openai-codex:* cũ và mục auth.order.openai-codex là trạng thái cũ được openclaw doctor --fix sửa chữa; hãy sử dụng ID hồ sơ openai:* và auth.order.openai cho cấu hình mới.

Trang này trình bày:

  • cách trao đổi mã thông báo OAuth hoạt động (PKCE)
  • nơi lưu trữ mã thông báo (và lý do)
  • cách xử lý nhiều tài khoản (hồ sơ + ghi đè theo phiên)

Các Plugin nhà cung cấp có quy trình OAuth hoặc khóa API riêng đều chạy qua cùng một điểm vào:

bash
openclaw models auth login --provider <id>

Nơi tiếp nhận mã thông báo (lý do tồn tại)

Các nhà cung cấp OAuth thường tạo mã thông báo làm mới mới sau mỗi lần đăng nhập/làm mới. Một số nhà cung cấp vô hiệu hóa mã thông báo làm mới trước đó khi một mã mới được cấp cho cùng người dùng/ứng dụng. Biểu hiện thực tế: đăng nhập qua cả OpenClaw và Claude Code / Codex CLI, rồi sau đó một trong hai bị đăng xuất ngẫu nhiên.

Để giảm tình trạng này, OpenClaw xem kho hồ sơ xác thực là một nơi tiếp nhận mã thông báo:

  • môi trường chạy đọc thông tin xác thực từ một nơi cho mỗi tác nhân
  • nhiều hồ sơ có thể cùng tồn tại và được định tuyến theo cách xác định
  • việc tái sử dụng CLI bên ngoài phụ thuộc vào từng nhà cung cấp: sau khi OpenClaw sở hữu một hồ sơ OAuth cục bộ cho một nhà cung cấp, mã thông báo làm mới cục bộ là dữ liệu chuẩn. Nếu mã thông báo làm mới cục bộ đó bị từ chối, OpenClaw báo cáo hồ sơ cần xác thực lại thay vì dự phòng bằng dữ liệu mã thông báo từ CLI bên ngoài. Việc khởi tạo từ Codex CLI còn giới hạn hơn: nó chỉ có thể điền dữ liệu ban đầu vào một hồ sơ trống kiểu openai:default trước khi OpenClaw sở hữu OAuth cho nhà cung cấp đó; sau thời điểm này, các lần làm mới do OpenClaw sở hữu vẫn là dữ liệu chuẩn
  • các đường dẫn trạng thái/khởi động giới hạn việc phát hiện CLI bên ngoài trong tập hợp nhà cung cấp đã được cấu hình, vì vậy kho đăng nhập của một CLI không liên quan sẽ không bị thăm dò đối với thiết lập chỉ có một nhà cung cấp

Lưu trữ (nơi chứa mã thông báo)

Các bí mật được lưu riêng theo từng tác nhân, với tên logic auth-profiles.json (kho bên dưới là cơ sở dữ liệu SQLite của tác nhân; tên JSON được giữ lại để tương thích và hiển thị trong công cụ):

  • Hồ sơ xác thực (OAuth + khóa API + tham chiếu tùy chọn ở cấp giá trị): ~/.openclaw/agents/<agentId>/agent/auth-profiles.json
  • Tệp tương thích cũ: ~/.openclaw/agents/<agentId>/agent/auth.json (các mục api_key tĩnh sẽ bị xóa khi được phát hiện)

Tệp cũ chỉ dùng để nhập (vẫn được hỗ trợ nhưng không phải kho chính):

  • ~/.openclaw/credentials/oauth.json (được nhập vào kho hồ sơ xác thực trong lần sử dụng đầu tiên)

Tất cả các đường dẫn trên cũng tuân theo $OPENCLAW_STATE_DIR (ghi đè thư mục trạng thái). Tài liệu tham khảo đầy đủ: /gateway/configuration-reference#auth-storage

Để biết hành vi kích hoạt ảnh chụp nhanh môi trường chạy và tham chiếu bí mật tĩnh, hãy xem Quản lý bí mật.

Khi một tác nhân phụ không có hồ sơ xác thực cục bộ, OpenClaw sử dụng cơ chế kế thừa đọc xuyên từ kho của tác nhân mặc định/chính; hệ thống không sao chép kho của tác nhân chính khi đọc. Mã thông báo làm mới OAuth đặc biệt nhạy cảm: các quy trình sao chép thông thường mặc định bỏ qua chúng vì một số nhà cung cấp luân chuyển hoặc vô hiệu hóa mã thông báo làm mới sau khi sử dụng. Hãy cấu hình một lần đăng nhập OAuth riêng cho tác nhân khi tác nhân đó cần một tài khoản độc lập.

Tái sử dụng Anthropic Claude CLI

OpenClaw hỗ trợ tái sử dụng Anthropic Claude CLI và claude -p như một phương thức xác thực được chấp thuận. Nếu máy chủ đã có phiên đăng nhập Claude cục bộ, quy trình tiếp nhận/cấu hình có thể trực tiếp tái sử dụng phiên đó. Mã thông báo thiết lập Anthropic vẫn khả dụng như một phương thức xác thực bằng mã thông báo được hỗ trợ, nhưng OpenClaw ưu tiên tái sử dụng Claude CLI khi phương thức này khả dụng.

Trao đổi OAuth (cách đăng nhập hoạt động)

Các quy trình đăng nhập tương tác của OpenClaw được triển khai trong openclaw/plugin-sdk/llm.ts và kết nối với các trình hướng dẫn/lệnh.

Mã thông báo thiết lập Anthropic

Cấu trúc quy trình:

  1. bắt đầu quy trình mã thông báo thiết lập hoặc dán mã thông báo Anthropic từ OpenClaw
  2. OpenClaw lưu thông tin xác thực Anthropic thu được vào một hồ sơ xác thực
  3. lựa chọn mô hình vẫn là anthropic/...
  4. các hồ sơ xác thực Anthropic hiện có vẫn khả dụng để quay lui/kiểm soát thứ tự

OpenAI Codex (ChatGPT OAuth)

OpenAI Codex OAuth được hỗ trợ rõ ràng để sử dụng bên ngoài Codex CLI, bao gồm các quy trình làm việc của OpenClaw.

Lệnh đăng nhập sử dụng ID nhà cung cấp OpenAI chuẩn:

bash
openclaw models auth login --provider openai

Sử dụng --profile-id openai:<name> cho nhiều tài khoản ChatGPT/Codex OAuth trong một tác nhân. Không sử dụng openai-codex:<name> cho hồ sơ mới. Doctor di chuyển tiền tố cũ đó sang một ID hồ sơ openai:* không xung đột; hãy chạy openclaw models auth list --provider openai sau khi sửa chữa, trước khi sao chép ID hồ sơ vào auth.order hoặc /model ...@<profileId>.

Cấu trúc quy trình (PKCE):

  1. tạo bộ xác minh/thử thách PKCE và một state ngẫu nhiên
  2. mở https://auth.openai.com/oauth/authorize?... (phạm vi openid profile email offline_access)
  3. thử nhận lệnh gọi lại tại http://localhost:1455/auth/callback (máy chủ gọi lại mặc định là localhost và chỉ chấp nhận các máy chủ local loopback; ghi đè bằng OPENCLAW_OAUTH_CALLBACK_HOST)
  4. nếu bạn có thể dán mã trước khi lệnh gọi lại đến (hoặc đang ở môi trường từ xa/không giao diện và không thể liên kết lệnh gọi lại), hãy dán URL chuyển hướng/mã thay thế — thao tác dán thủ công sẽ chạy đua với lệnh gọi lại từ trình duyệt và thao tác nào hoàn tất trước sẽ thắng
  5. trao đổi mã tại https://auth.openai.com/oauth/token
  6. trích xuất accountId từ mã thông báo truy cập và lưu { access, refresh, expires, accountId }

Đường dẫn trình hướng dẫn là openclaw onboard → lựa chọn xác thực openai.

Làm mới + hết hạn

Các hồ sơ lưu dấu thời gian expires. Trong môi trường chạy:

  • nếu expires nằm trong tương lai, sử dụng mã thông báo truy cập đã lưu
  • nếu đã hết hạn, làm mới (dưới khóa tệp) và ghi đè thông tin xác thực đã lưu
  • nếu một tác nhân phụ đọc hồ sơ OAuth được kế thừa từ tác nhân chính, thao tác làm mới sẽ ghi ngược vào kho của tác nhân chính thay vì sao chép mã thông báo làm mới vào kho của tác nhân phụ
  • thông tin xác thực CLI được quản lý bên ngoài (Claude CLI, khởi tạo Codex CLI có giới hạn; xem Nơi tiếp nhận mã thông báo) sẽ được đọc lại thay vì sử dụng một mã thông báo làm mới đã sao chép. Nếu quá trình làm mới được quản lý thất bại, OpenClaw báo cáo hồ sơ bị ảnh hưởng cần xác thực lại thay vì trả về dữ liệu mã thông báo từ CLI bên ngoài.

Quy trình làm mới diễn ra tự động; thông thường bạn không cần quản lý mã thông báo theo cách thủ công.

Nhiều tài khoản (hồ sơ) + định tuyến

Hai mô hình:

1) Khuyến nghị: các tác nhân riêng biệt

Nếu bạn muốn tài khoản "cá nhân" và "công việc" không bao giờ tương tác, hãy sử dụng các tác nhân tách biệt (phiên + thông tin xác thực + không gian làm việc riêng):

bash
openclaw agents add workopenclaw agents add personal

Sau đó cấu hình xác thực cho từng tác nhân (trình hướng dẫn) và định tuyến cuộc trò chuyện đến đúng tác nhân.

2) Nâng cao: nhiều hồ sơ trong một tác nhân

Kho hồ sơ xác thực hỗ trợ nhiều ID hồ sơ cho cùng một nhà cung cấp. Chọn hồ sơ sẽ được sử dụng:

  • trên toàn cục thông qua thứ tự cấu hình (auth.order)
  • theo từng phiên thông qua /model ...@<profileId>

Ví dụ (ghi đè phiên):

  • /model Opus@anthropic:work

Liệt kê các ID hồ sơ hiện có bằng:

bash
openclaw models auth list --provider <id>

Tài liệu liên quan:

Liên quan

Was this useful?
On this page

On this page