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

Gateway

Xác thực

OpenClaw hỗ trợ OAuth và khóa API cho các nhà cung cấp mô hình. Đối với máy chủ Gateway hoạt động liên tục, khóa API là lựa chọn dễ dự đoán nhất; các luồng đăng ký/OAuth cũng hoạt động khi phù hợp với mô hình tài khoản nhà cung cấp của bạn.

Thiết lập được khuyến nghị: khóa API (mọi nhà cung cấp)

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

openclaw onboard cũng có thể lưu khóa API để tiến trình nền sử dụng nếu bạn không muốn tự quản lý biến môi trường. Xem Biến môi trường để biết đầy đủ thứ tự ưu tiên khi nạp môi trường (env.shellEnv, ~/.openclaw/.env, systemd/launchd).

Anthropic: tái sử dụng Claude CLI

Xác thực bằng setup-token của Anthropic vẫn là một phương thức được hỗ trợ. Việc tái sử dụng Claude CLI (cách dùng kiểu claude -p) cũng được chấp thuận cho tích hợp này; khi thông tin đăng nhập Claude CLI có sẵn trên máy chủ, đây là phương thức ưu tiên cho việc sử dụng cục bộ/trên máy tính cá nhân. Đối với máy chủ Gateway hoạt động dài hạn, khóa API Anthropic vẫn là lựa chọn dễ dự đoán nhất, với khả năng kiểm soát thanh toán rõ ràng ở phía máy chủ.

Thiết lập trên máy chủ để tái sử dụng Claude CLI:

bash
# Chạy trên máy chủ Gatewayclaude auth loginclaude auth status --textopenclaw models auth login --provider anthropic --method cli --set-default

Quy trình này gồm hai bước: đăng nhập Claude Code vào Anthropic trên máy chủ, sau đó yêu cầu OpenClaw định tuyến việc lựa chọn mô hình Anthropic qua phần phụ trợ claude-cli cục bộ và lưu hồ sơ xác thực OpenClaw tương ứng.

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

Nhập token thủ công

Hoạt động với mọi nhà cung cấp; ghi vào kho xác thực SQLite theo từng tác nhân và cập nhật cấu hình:

bash
openclaw models auth paste-token --provider openrouter

OpenClaw đọc hồ sơ xác thực từ openclaw-agent.sqlite của từng tác nhân. Chi tiết điểm cuối (baseUrl, api, mã định danh mô hình, tiêu đề, thời gian chờ) thuộc models.providers.<id> trong openclaw.json hoặc models.json, không thuộc hồ sơ xác thực.

Nếu bản cài đặt cũ vẫn còn auth-profiles.json, auth-state.json hoặc cấu trúc phẳng như { "openrouter": { "apiKey": "..." } }, hãy chạy openclaw doctor --fix để nhập dữ liệu đó vào SQLite; doctor giữ các bản sao lưu có dấu thời gian bên cạnh các tệp JSON gốc.

Các tuyến xác thực bên ngoài như auth: "aws-sdk" của Bedrock không phải là thông tin xác thực. Đối với một tuyến Bedrock có tên, hãy đặt auth.profiles.<id>.mode: "aws-sdk" trong openclaw.json — không ghi type: "aws-sdk" vào kho hồ sơ xác thực. openclaw doctor --fix di chuyển các dấu hiệu AWS SDK cũ từ kho thông tin xác thực sang siêu dữ liệu cấu hình.

Thông tin xác thực dựa trên SecretRef

  • Thông tin xác thực api_key có thể sử dụng keyRef: { source, provider, id }
  • Thông tin xác thực token có thể sử dụng tokenRef: { source, provider, id }
  • Hồ sơ ở chế độ OAuth từ chối thông tin xác thực SecretRef: nếu auth.profiles.<id>.mode là "oauth", keyRef/tokenRef dựa trên SecretRef của hồ sơ đó sẽ bị từ chối.

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

bash
openclaw models statusopenclaw doctor

Kiểm tra phù hợp cho tự động hóa, thoát với mã 1 khi đã hết hạn/bị thiếu, 2 khi sắp hết hạn:

bash
openclaw models status --check

Thăm dò xác thực trực tiếp (thêm --probe-provider, --probe-profile, --probe-timeout, --probe-concurrency hoặc --probe-max-tokens để thu hẹp phạm vi):

bash
openclaw models status --probe

Lưu ý:

  • Các hàng 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.
  • Nếu auth.order.<provider> bỏ qua một hồ sơ đã lưu, thăm dò sẽ báo cáo excluded_by_auth_order cho hồ sơ đó thay vì thử sử dụng.
  • Nếu có thông tin xác thực nhưng OpenClaw không thể phân giải mô hình có thể thăm dò cho nhà cung cấp đó, thăm dò sẽ báo cáo status: no_model.
  • Thời gian chờ sau khi bị giới hạn tốc độ có thể áp dụng theo từng mô hình: hồ sơ đang trong thời gian chờ đối với một mô hình vẫn có thể phục vụ một mô hình cùng nhóm trên cùng nhà cung cấp.

Các tập lệnh vận hành tùy chọn (systemd/Termux): Tập lệnh giám sát xác thực.

Luân phiên khóa API (Gateway)

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

Thứ tự ưu tiên khóa theo từng nhà cung cấp:

  1. OPENCLAW_LIVE_&lt;PROVIDER&gt;_KEY (ghi đè đơn, cố định một khóa)
  2. &lt;PROVIDER&gt;_API_KEYS (danh sách phân tách bằng dấu phẩy/khoảng trắng/dấu chấm phẩy)
  3. &lt;PROVIDER&gt;_API_KEY
  4. &lt;PROVIDER&gt;_API_KEY_* (mọi biến môi trường có tiền tố này)

Các nhà cung cấp Google (google, google-vertex) còn dự phòng bằng GOOGLE_API_KEY. Danh sách kết hợp được loại bỏ mục trùng lặp trước khi sử dụng.

OpenClaw chỉ chuyển sang khóa tiếp theo khi thông báo lỗi khớp với: rate_limit, rate limit, 429, quota exceeded/quota_exceeded, resource exhausted/resource_exhausted hoặc too many requests. Các lỗi khác 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 sẽ được trả về.

Việc xóa thông tin xác thực đã lưu không thu hồi khóa tại nhà cung cấp — hãy luân phiên hoặc thu hồi khóa trong bảng điều khiển của nhà cung cấp khi bạn cần vô hiệu hóa ở phía nhà cung cấp.

Xóa thông tin xác thực của nhà cung cấp khi Gateway đang chạy

Khi bạn xóa thông tin xác thực của nhà cung cấp qua mặt phẳng điều khiển Gateway, OpenClaw sẽ xóa các hồ sơ xác thực đã lưu của nhà cung cấp đó và hủy các lượt chạy trò chuyện/tác nhân đang hoạt động có nhà cung cấp mô hình được chọn trùng với nhà cung cấp đã xóa. Các lượt chạy bị hủy sẽ phát ra các sự kiện hủy/vòng đời thông thường với stopReason: "auth-revoked", để các máy khách được kết nối có thể hiển thị rằng lượt chạy đã dừng do thông tin xác thực bị xóa.

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

OpenAI và mã định danh openai-codex cũ

Cả hồ sơ khóa API OpenAI và hồ sơ OAuth ChatGPT/Codex đều sử dụng mã định danh nhà cung cấp chuẩn openai. Hãy sử dụng mã định danh hồ sơ openai:* và auth.order.openai cho cấu hình mới.

Nếu bạn thấy openai-codex trong cấu hình cũ, mã định danh hồ sơ xác thực hoặc auth.order.openai-codex, hãy coi đó là dữ liệu đầu vào cho quá trình di chuyển cũ — không tạo hồ sơ openai-codex mới. Chạy:

bash
openclaw doctor --fixopenclaw models auth list --provider openai

Doctor ghi lại các mã định danh hồ sơ openai-codex:* cũ và các mục auth.order.openai-codex thành tuyến openai chuẩn. Để biết cách định tuyến mô hình/thời gian chạy riêng cho OpenAI, hãy xem OpenAI.

Trong khi đăng nhập (CLI)

bash
openclaw models auth login --provider openai --profile-id openai:ritsukoopenclaw models auth login --provider openai --profile-id openai:lain

--profile-id giữ nhiều thông tin đăng nhập OAuth cho cùng một nhà cung cấp tách biệt trong một tác nhân.

--force xóa các hồ sơ xác thực đã lưu của nhà cung cấp đó trong thư mục tác nhân được chọn, rồi chạy lại cùng một luồng xác thực. Hãy sử dụng tùy chọn này khi hồ sơ đã lưu bị kẹt, hết hạn hoặc gắn với sai tài khoản. Tùy chọn này không thu hồi thông tin xác thực tại nhà cung cấp.

bash
openclaw models auth login --provider anthropic --force

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

  • /model <alias-or-id>@<profileId> cố định một thông tin xác thực cụ thể của nhà cung cấp cho phiên hiện tại (ví dụ về mã định danh hồ sơ: anthropic:default, anthropic:work).
  • /model (hoặc /model list) hiển thị bộ chọn thu gọn; /model status hiển thị chế độ xem đầy đủ (các ứng viên + hồ sơ xác thực tiếp theo, cùng chi tiết điểm cuối của nhà cung cấp khi đã cấu hình).

Nếu bạn thay đổi thứ tự xác thực hoặc việc cố định hồ sơ cho một cuộc trò chuyện đang chạy, hãy gửi /new hoặc /reset để bắt đầu phiên mới — các phiên hiện có giữ nguyên lựa chọn mô hình/hồ sơ hiện tại cho đến khi được đặt lại.

Theo từng tác nhân (ghi đè bằng CLI)

Các ghi đè thứ tự xác thực được lưu trong trạng thái xác thực SQLite của tác nhân đó:

bash
openclaw models auth order get --provider anthropicopenclaw models auth order set --provider anthropic anthropic:defaultopenclaw models auth order clear --provider anthropic

Sử dụng --agent <id> để nhắm đến một tác nhân cụ thể; bỏ qua tùy chọn này để sử dụng tác nhân mặc định đã cấu hình. openclaw models status --probe hiển thị các hồ sơ đã lưu nhưng bị bỏ qua dưới dạng excluded_by_auth_order thay vì âm thầm bỏ qua chúng.

Khắc phục sự cố

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

Cấu hình khóa API Anthropic trên máy chủ Gateway, hoặc thiết lập phương thức setup-token của Anthropic, rồi kiểm tra lại:

bash
openclaw models status

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

Chạy openclaw models status để xem hồ sơ nào sắp hết hạn. Nếu hồ sơ token Anthropic bị thiếu hoặc đã hết hạn, hãy làm mới hồ sơ đó qua setup-token hoặc chuyển sang khóa API Anthropic.

Nội dung liên quan

Was this useful?
On this page

On this page