Ngữ nghĩa của thông tin xác thực xác thực danh tính

Các ngữ nghĩa này giúp hành vi xác thực tại thời điểm lựa chọn và khi chạy luôn nhất quán. Chúng được dùng chung bởi:

• resolveAuthProfileOrder (thứ tự hồ sơ)
• resolveApiKeyForProfile (phân giải thông tin xác thực khi chạy)
• openclaw models status --probe
• các bước kiểm tra xác thực của openclaw doctor (doctor-auth)

Mã lý do thăm dò ổn định

Kết quả thăm dò mang một nhóm status (ok, auth, rate_limit, billing, timeout, format, unknown, no_model) cùng một reasonCode ổn định khi quá trình thăm dò chưa bao giờ thực hiện được lệnh gọi mô hình:

Các bước kiểm tra tính đủ điều kiện báo cáo ok làm mã lý do cho thông tin xác thực có thể sử dụng.

Thông tin xác thực bằng token

Thông tin xác thực bằng token (type: "token") hỗ trợ token nội tuyến và/hoặc tokenRef.

Quy tắc về tính đủ điều kiện

1. Hồ sơ token không đủ điều kiện khi thiếu cả token lẫn tokenRef (missing_credential).
2. expires là tùy chọn. Khi có, giá trị này phải là số hữu hạn biểu thị mili giây kể từ Unix epoch, lớn hơn 0 và không vượt quá dấu thời gian Date tối đa của JavaScript (8640000000000000).
3. Nếu expires không hợp lệ (sai kiểu, NaN, 0, số âm, không hữu hạn hoặc vượt quá giá trị tối đa đó), hồ sơ không đủ điều kiện với invalid_expires.
4. Nếu expires nằm trong quá khứ, hồ sơ không đủ điều kiện với expired.
5. tokenRef không bỏ qua bước xác thực expires.

Quy tắc phân giải

1. Ngữ nghĩa của trình phân giải đối với expires khớp với ngữ nghĩa kiểm tra tính đủ điều kiện.
2. Với các hồ sơ đủ điều kiện, dữ liệu token có thể được phân giải từ giá trị nội tuyến hoặc tokenRef.
3. Các tham chiếu không thể phân giải tạo ra unresolved_ref trong đầu ra của models status --probe.

Khả năng di chuyển khi sao chép tác tử

Việc kế thừa xác thực của tác tử sử dụng cơ chế đọc xuyên. Khi một tác tử không có hồ sơ cục bộ, trong thời gian chạy nó phân giải hồ sơ từ kho của tác tử mặc định/chính mà không sao chép dữ liệu bí mật vào kho thông tin xác thực riêng (agents/<agentId>/agent/openclaw-agent.sqlite).

Các luồng sao chép tường minh, chẳng hạn như openclaw agents add, sử dụng chính sách di chuyển này:

• Các hồ sơ api_key và token có thể di chuyển, trừ khi đặt copyToAgents: false.
• Theo mặc định, hồ sơ oauth không thể di chuyển vì refresh token có thể chỉ dùng được một lần hoặc nhạy cảm với việc luân chuyển.
• Các luồng OAuth do nhà cung cấp sở hữu chỉ có thể chọn tham gia bằng copyToAgents: true khi đã biết việc sao chép dữ liệu làm mới giữa các tác tử là an toàn; lựa chọn tham gia này chỉ áp dụng khi hồ sơ chứa dữ liệu truy cập/làm mới nội tuyến.

Các hồ sơ không thể di chuyển vẫn khả dụng thông qua kế thừa đọc xuyên, trừ khi tác tử đích đăng nhập riêng và tạo hồ sơ cục bộ của chính nó.

Các tuyến xác thực chỉ dùng cấu hình

Các mục auth.profiles có mode: "aws-sdk" là siêu dữ liệu định tuyến, không phải thông tin xác thực được lưu trữ. Chúng hợp lệ khi nhà cung cấp đích sử dụng models.providers.<id>.auth: "aws-sdk", tức tuyến được quy trình thiết lập Amazon Bedrock do plugin sở hữu ghi vào. Các mã định danh hồ sơ này có thể xuất hiện trong auth.order và các giá trị ghi đè phiên ngay cả khi không có mục tương ứng trong kho thông tin xác thực.

Không ghi type: "aws-sdk" vào kho thông tin xác thực; thông tin xác thực được lưu trữ chỉ có thể là api_key, token hoặc oauth. Nếu một tệp auth-profiles.json cũ có dấu đánh dấu như vậy, openclaw doctor --fix sẽ chuyển nó sang auth.profiles và xóa dấu đánh dấu khỏi kho.

Lọc theo thứ tự xác thực tường minh

• Khi auth.order.<provider> hoặc giá trị ghi đè thứ tự của kho xác thực được đặt cho một nhà cung cấp, models status --probe chỉ thăm dò các mã định danh hồ sơ còn lại trong thứ tự xác thực đã phân giải của nhà cung cấp đó. Giá trị ghi đè đã lưu được ưu tiên hơn cấu hình auth.order.
• Hồ sơ đã lưu của nhà cung cấp đó nhưng bị loại khỏi thứ tự tường minh sẽ không được âm thầm thử lại sau đó. Đầu ra thăm dò báo cáo hồ sơ này với reasonCode: excluded_by_auth_order và chi tiết Excluded by auth.order for this provider.

Phân giải mục tiêu thăm dò

• Mục tiêu thăm dò có thể đến từ hồ sơ xác thực, thông tin xác thực trong môi trường hoặc models.json (source của kết quả: profile, env, models.json).
• Nếu một nhà cung cấp có thông tin xác thực nhưng OpenClaw không thể phân giải ứng viên mô hình có thể thăm dò, models status --probe báo cáo status: no_model với reasonCode: no_model.

Phát hiện thông tin xác thực của CLI bên ngoài

• Thông tin xác thực chỉ dùng khi chạy do các CLI bên ngoài sở hữu (Claude CLI cho claude-cli, Codex CLI cho openai, MiniMax CLI cho minimax-portal) chỉ được phát hiện khi nhà cung cấp, môi trường chạy hoặc hồ sơ xác thực nằm trong phạm vi của thao tác hiện tại, hoặc khi đã tồn tại hồ sơ cục bộ được lưu trữ cho nguồn bên ngoài đó.
• Các bên gọi kho xác thực chọn một chế độ phát hiện CLI bên ngoài tường minh: none để chỉ dùng xác thực được lưu bền vững/xác thực của plugin, existing để làm mới các hồ sơ CLI bên ngoài đã lưu, hoặc scoped cho một tập hợp nhà cung cấp/hồ sơ cụ thể.
• Các đường dẫn chỉ đọc/trạng thái truyền allowKeychainPrompt: false; chúng chỉ sử dụng thông tin xác thực của CLI bên ngoài được lưu trong tệp và không đọc hoặc tái sử dụng kết quả từ macOS Keychain.

Cơ chế bảo vệ chính sách SecretRef cho OAuth

Đầu vào SecretRef chỉ dành cho thông tin xác thực tĩnh. Thông tin xác thực OAuth có thể thay đổi khi chạy (các luồng làm mới lưu token đã luân chuyển), vì vậy dữ liệu OAuth dựa trên SecretRef sẽ chia trạng thái có thể thay đổi giữa nhiều kho.

• Nếu thông tin xác thực của hồ sơ có type: "oauth", các đối tượng SecretRef sẽ bị từ chối trong mọi trường dữ liệu thông tin xác thực của hồ sơ đó.
• Nếu auth.profiles.<id>.mode là "oauth", đầu vào keyRef/tokenRef dựa trên SecretRef cho hồ sơ đó sẽ bị từ chối.
• Các vi phạm là lỗi nghiêm trọng (ném lỗi) trong quá trình chuẩn bị bí mật khi khởi động/tải lại và trong các đường dẫn phân giải hồ sơ.

Thông báo tương thích với phiên bản cũ

Để bảo đảm khả năng tương thích với tập lệnh, lỗi thăm dò giữ nguyên dòng đầu tiên sau đây:

Auth profile credentials are missing or expired.

Chi tiết thân thiện với người dùng và mã lý do ổn định xuất hiện ở các dòng tiếp theo theo dạng ↳ Auth reason [code]: ....

Liên quan

• Quản lý bí mật
• Lưu trữ xác thực