English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiفارسیไทย

Gateway

Xác thực

OpenClaw hỗ trợ OAuth và khóa API cho các nhà cung cấp mô hình. Với các máy chủ Gateway luôn bật, khóa API thường là tùy chọn dễ dự đoán nhất. Các luồng đăng ký/OAuth cũng được hỗ trợ khi chúng phù hợp với mô hình tài khoản nhà cung cấp của bạn.

Xem /concepts/oauth để biết toàn bộ luồng OAuth và bố cục lưu trữ. Đối với xác thực dựa trên SecretRef (các nhà cung cấp env/file/exec), xem Quản lý bí mật. Để biết các quy tắc về tính đủ điều kiện thông tin xác thực/mã lý do được dùng bởi models status --probe, xem Ngữ nghĩa thông tin xác thực xác thực.

Thiết lập được khuyến nghị (khóa API, bất kỳ nhà cung cấp nào)

Nếu bạn đang chạy một Gateway tồn tại lâu dài, hãy bắt đầu bằng khóa API cho nhà cung cấp bạn chọn. Riêng với Anthropic, xác thực bằng khóa API vẫn là cách thiết lập máy chủ dễ dự đoán nhất, nhưng OpenClaw cũng hỗ trợ tái sử dụng đăng nhập Claude CLI cục bộ.

  1. Tạo khóa API trong bảng điều khiển nhà cung cấp của bạn.
  2. Đặt khóa đó trên máy chủ Gateway (máy chạy openclaw gateway).
export <PROVIDER>_API_KEY="..."
openclaw models status
  1. Nếu Gateway chạy dưới systemd/launchd, nên đặt khóa trong ~/.openclaw/.env để daemon có thể đọc:
cat >> ~/.openclaw/.env <<'EOF'
&lt;PROVIDER&gt;_API_KEY=...
EOF

Sau đó khởi động lại daemon (hoặc khởi động lại tiến trình Gateway của bạn) và kiểm tra lại:

openclaw models status
openclaw doctor

Nếu bạn không muốn tự quản lý biến môi trường, quy trình onboarding có thể lưu khóa API để daemon sử dụng: openclaw onboard.

Xem Trợ giúp để biết chi tiết về kế thừa môi trường (env.shellEnv, ~/.openclaw/.env, systemd/launchd).

Anthropic: Claude CLI và khả năng tương thích token

Xác thực setup-token của Anthropic vẫn có trong OpenClaw như một đường dẫn token được hỗ trợ. Nhân viên Anthropic sau đó đã cho chúng tôi biết rằng việc sử dụng Claude CLI kiểu OpenClaw được phép trở lại, nên 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 có thể tái sử dụng Claude CLI trên máy chủ, đó hiện là đường dẫn ưu tiên.

Với các máy chủ Gateway tồn tại lâu dài, khóa API Anthropic vẫn là cách thiết lập dễ dự đoán nhất. Nếu bạn muốn tái sử dụng đăng nhập Claude hiện có trên cùng máy chủ, hãy dùng đường dẫn Anthropic Claude CLI trong onboarding/configure.

Thiết lập máy chủ được khuyến nghị để tái sử dụng Claude CLI:

# Run on the gateway host
claude auth login
claude auth status --text
openclaw models auth login --provider anthropic --method cli --set-default

Đây là thiết lập gồm hai bước:

  1. Đăng nhập chính Claude Code vào Anthropic trên máy chủ Gateway.
  2. Cho OpenClaw biết cần chuyển lựa chọn mô hình Anthropic sang backend claude-cli cục bộ và lưu hồ sơ xác thực OpenClaw tương ứng.

Nếu claude không có trong PATH, hãy cài Claude Code trước hoặc đặt agents.defaults.cliBackends.claude-cli.command thành đường dẫn nhị phân thực.

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

openclaw models auth paste-token --provider openrouter

auth-profiles.json chỉ lưu thông tin xác thực. Hình dạng chuẩn là:

{
  "version": 1,
  "profiles": {
    "openrouter:default": {
      "type": "api_key",
      "provider": "openrouter",
      "key": "OPENROUTER_API_KEY"
    }
  }
}

OpenClaw mong đợi hình dạng chuẩn version + profiles lúc chạy. Nếu một bản cài đặt cũ vẫn có tệp phẳng như { "openrouter": { "apiKey": "..." } }, hãy chạy openclaw doctor --fix để ghi lại nó thành hồ sơ khóa API openrouter:default; doctor giữ một bản sao .legacy-flat.*.bak bên cạnh bản gốc. Các chi tiết endpoint như baseUrl, api, id mô hình, header và timeout thuộc về models.providers.<id> trong openclaw.json hoặc models.json, không phải trong auth-profiles.json.

Các tuyến xác thực bên ngoài như Bedrock auth: "aws-sdk" cũng không phải là thông tin xác thực. Nếu bạn muốn một tuyến Bedrock có tên, hãy đặt auth.profiles.<id>.mode: "aws-sdk" trong openclaw.json; đừng ghi type: "aws-sdk" vào auth-profiles.json. openclaw doctor --fix di chuyển các dấu mốc AWS SDK cũ từ kho thông tin xác thực sang metadata cấu hình.

Tham chiếu hồ sơ xác thực cũng được hỗ trợ cho thông tin xác thực tĩnh:

  • Thông tin xác thực api_key có thể dùng keyRef: { source, provider, id }
  • Thông tin xác thực token có thể dùng tokenRef: { source, provider, id }
  • Hồ sơ ở chế độ OAuth không hỗ trợ thông tin xác thực SecretRef; nếu auth.profiles.<id>.mode được đặt thành "oauth", đầu vào keyRef/tokenRef dựa trên SecretRef cho hồ sơ đó sẽ bị từ chối.

Kiểm tra thân thiện với tự động hóa (thoát 1 khi hết hạn/thiếu, 2 khi sắp hết hạn):

openclaw models status --check

Probe xác thực trực tiếp:

openclaw models status --probe

Ghi chú:

  • Các hàng probe có thể đến từ hồ sơ xác thực, thông tin xác thực env hoặc models.json.
  • Nếu auth.order.<provider> tường minh bỏ qua một hồ sơ đã lưu, probe báo cáo excluded_by_auth_order cho hồ sơ đó thay vì thử dùng nó.
  • Nếu có xác thực nhưng OpenClaw không thể phân giải ứng viên mô hình có thể probe cho nhà cung cấp đó, probe báo cáo status: no_model.
  • Cooldown giới hạn tốc độ có thể được gắn theo mô hình. Một hồ sơ đang cooldown cho một mô hình vẫn có thể dùng được cho mô hình cùng cấp trên cùng nhà cung cấp.

Các script vận hành tùy chọn (systemd/Termux) được ghi tài liệu tại đây: Script giám sát xác thực

Ghi chú về Anthropic

Backend claude-cli của Anthropic được hỗ trợ trở lại.

  • Nhân viên Anthropic cho chúng tôi biết đường dẫn tích hợp OpenClaw này được phép trở lại.
  • 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 các lần chạy dựa trên Anthropic trừ khi Anthropic công bố chính sách mới.
  • Khóa API Anthropic vẫn là lựa chọn dễ dự đoán nhất cho các máy chủ Gateway tồn tại lâu dài và kiểm soát thanh toán phía máy chủ tường minh.

Kiểm tra trạng thái xác thực mô hình

openclaw models status
openclaw doctor

Hành vi xoay vòng khóa API (gateway)

Một số nhà cung cấp hỗ trợ thử lại yêu cầu bằng khóa thay thế khi một lệnh gọi API gặp giới hạn tốc độ của nhà cung cấp.

  • Thứ tự ưu tiên:
    • OPENCLAW_LIVE_&lt;PROVIDER&gt;_KEY (ghi đè đơn)
    • &lt;PROVIDER&gt;_API_KEYS
    • &lt;PROVIDER&gt;_API_KEY
    • &lt;PROVIDER&gt;_API_KEY_*
  • Các nhà cung cấp Google cũng bao gồm GOOGLE_API_KEY như một fallback bổ sung.
  • Cùng danh sách khóa được khử trùng lặp trước khi sử dụng.
  • OpenClaw chỉ thử lại bằng khóa tiếp theo đối với lỗi giới hạn tốc độ (ví dụ 429, rate_limit, quota, resource exhausted, Too many concurrent requests, ThrottlingException, concurrency limit reached hoặc workers_ai ... quota limit exceeded).
  • Các lỗi không phải giới hạn tốc độ sẽ không được thử lại bằng khóa thay thế.
  • Nếu tất cả khóa đều thất bại, lỗi cuối cùng từ lần thử cuối được trả về.

Kiểm soát thông tin xác thực được sử dụng

Theo phiên (lệnh trò chuyện)

Dùng /model <alias-or-id>@<profileId> để ghim một thông tin xác thực nhà cung cấp cụ thể cho phiên hiện tại (ví dụ id hồ sơ: anthropic:default, anthropic:work).

Dùng /model (hoặc /model list) cho bộ chọn gọn; dùng /model status để xem đầy đủ (ứng viên + hồ sơ xác thực tiếp theo, cùng chi tiết endpoint nhà cung cấp khi đã cấu hình).

Theo agent (ghi đè CLI)

Đặt ghi đè thứ tự hồ sơ xác thực tường minh cho một agent (được lưu trong auth-state.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> để nhắm đến một agent cụ thể; bỏ qua nó để dùng agent mặc định đã cấu hình. Khi bạn gỡ lỗi vấn đề thứ tự, openclaw models status --probe hiển thị các hồ sơ đã lưu bị bỏ qua là excluded_by_auth_order thay vì âm thầm bỏ qua chúng. Khi bạn gỡ lỗi vấn đề cooldown, hãy nhớ rằng cooldown giới hạn tốc độ có thể được gắn với một id mô hình thay vì toàn bộ hồ sơ nhà cung cấp.

Khắc phục sự cố

"Không tìm thấy thông tin xác thực"

Nếu thiếu hồ sơ Anthropic, hãy cấu hình khóa API Anthropic trên máy chủ Gateway hoặc thiết lập đường dẫn setup-token của Anthropic, rồi 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 hồ sơ nào sắp hết hạn. Nếu một hồ sơ token Anthropic bị thiếu hoặc đã hết hạn, hãy làm mới thiết lập đó qua setup-token hoặc chuyển sang khóa API Anthropic.

Liên quan