Chuyển đến nội dung chính

​
FAQ

Câu trả lời nhanh và hướng dẫn khắc phục sự cố cho các thiết lập thực tế (phát triển cục bộ, VPS, multi-agent, OAuth/API keys, chuyển đổi mô hình). Để chẩn đoán runtime, xem Troubleshooting. Để tham khảo cấu hình đầy đủ, xem Configuration.

​
60 giây đầu tiên nếu có sự cố

  1. Kiểm tra trạng thái nhanh (kiểm tra đầu tiên) 
    openclaw status
    Tóm tắt nhanh cục bộ: Hệ điều hành + cập nhật, khả năng truy cập gateway/dịch vụ, agents/sessions, cấu hình provider + vấn đề runtime (khi gateway có thể truy cập).
  2. Báo cáo có thể chia sẻ (an toàn để chia sẻ) 
    openclaw status --all
    Chẩn đoán chỉ đọc với log tail (tokens đã được ẩn).
  3. Trạng thái Daemon + cổng 
    openclaw gateway status
    Hiển thị runtime của supervisor so với khả năng truy cập RPC, URL mục tiêu probe và cấu hình dịch vụ có thể đã sử dụng.
  4. Kiểm tra sâu 
    openclaw status --deep
    Chạy kiểm tra sức khỏe gateway + kiểm tra provider (yêu cầu gateway có thể truy cập). Xem Health.
  5. Theo dõi log mới nhất 
    openclaw logs --follow
    Nếu RPC không hoạt động, sử dụng: 
    tail -f "$(ls -t /tmp/openclaw/openclaw-*.log | head -1)"
    File logs tách biệt với logs dịch vụ; xem Logging và Troubleshooting.
  6. Chạy doctor (sửa chữa) 
    openclaw doctor
    Sửa chữa/di chuyển cấu hình/trạng thái + chạy kiểm tra sức khỏe. Xem Doctor.
  7. Snapshot Gateway 
    openclaw health --json
openclaw health --verbose   # hiển thị URL mục tiêu + đường dẫn cấu hình khi có lỗi
    Yêu cầu gateway đang chạy cho một snapshot đầy đủ (chỉ WS). Xem Health.

​
Bắt đầu nhanh và thiết lập lần đầu

Sử dụng một agent AI cục bộ có thể xem máy của bạn. Điều này hiệu quả hơn nhiều so với hỏi trên Discord, vì hầu hết các trường hợp “tôi bị kẹt” là vấn đề cấu hình cục bộ hoặc môi trường mà người hỗ trợ từ xa không thể kiểm tra.Các công cụ này có thể đọc repo, chạy lệnh, kiểm tra logs và giúp sửa thiết lập cấp máy của bạn (PATH, dịch vụ, quyền, file xác thực). Cung cấp cho chúng toàn bộ source checkout thông qua cài đặt hackable (git):
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git
Điều này cài đặt OpenClaw từ một git checkout, vì vậy agent có thể đọc mã + tài liệu và suy luận về phiên bản chính xác bạn đang chạy. Bạn luôn có thể chuyển lại sang phiên bản ổn định sau bằng cách chạy lại trình cài đặt mà không có --install-method git.Mẹo: yêu cầu agent lên kế hoạch và giám sát việc sửa chữa (từng bước), sau đó chỉ thực hiện các lệnh cần thiết. Điều đó giữ cho các thay đổi nhỏ và dễ kiểm tra.Nếu bạn phát hiện ra lỗi thực sự hoặc sửa chữa, vui lòng gửi vấn đề trên GitHub hoặc gửi PR: https://github.com/openclaw/openclaw/issues https://github.com/openclaw/openclaw/pullsBắt đầu với các lệnh này (chia sẻ đầu ra khi yêu cầu trợ giúp):
openclaw status
openclaw models status
openclaw doctor
Chúng làm gì:
  • openclaw status: snapshot nhanh về sức khỏe gateway/agent + cấu hình cơ bản.
  • openclaw models status: kiểm tra xác thực provider + khả dụng mô hình.
  • openclaw doctor: xác thực và sửa chữa các vấn đề cấu hình/trạng thái phổ biến.
Các kiểm tra CLI hữu ích khác: openclaw status --all, openclaw logs --follow, openclaw gateway status, openclaw health --verbose.Vòng lặp gỡ lỗi nhanh: 60 giây đầu tiên nếu có sự cố. Tài liệu cài đặt: Install, Installer flags, Updating.
Repo khuyến nghị chạy từ source và sử dụng onboarding:
curl -fsSL https://openclaw.ai/install.sh | bash
openclaw onboard --install-daemon
Trình hướng dẫn cũng có thể tự động xây dựng tài sản UI. Sau khi onboarding, bạn thường chạy Gateway trên cổng 18789.Từ source (người đóng góp/dev):
git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install
pnpm build
pnpm ui:build # tự động cài đặt các phụ thuộc UI lần đầu chạy
openclaw onboard
Nếu bạn chưa có cài đặt toàn cầu, chạy nó qua pnpm openclaw onboard.
Trình hướng dẫn mở trình duyệt của bạn với một URL dashboard sạch (không có token) ngay sau khi onboarding và cũng in liên kết trong tóm tắt. Giữ tab đó mở; nếu nó không khởi chạy, sao chép/dán URL đã in trên cùng máy.
Localhost (cùng máy):
  • Mở http://127.0.0.1:18789/.
  • Nếu yêu cầu xác thực, dán token từ gateway.auth.token (hoặc OPENCLAW_GATEWAY_TOKEN) vào cài đặt Control UI.
  • Lấy nó từ máy chủ gateway: openclaw config get gateway.auth.token (hoặc tạo một cái: openclaw doctor --generate-gateway-token).
Không trên localhost:
  • Tailscale Serve (khuyến nghị): giữ bind loopback, chạy openclaw gateway --tailscale serve, mở https://<magicdns>/. Nếu gateway.auth.allowTailscale là true, các header nhận dạng thỏa mãn xác thực Control UI/WebSocket (không cần token, giả định máy chủ gateway đáng tin cậy); HTTP APIs vẫn yêu cầu token/mật khẩu.
  • Tailnet bind: chạy openclaw gateway --bind tailnet --token "<token>", mở http://<tailscale-ip>:18789/, dán token vào cài đặt dashboard.
  • SSH tunnel: ssh -N -L 18789:127.0.0.1:18789 user@host sau đó mở http://127.0.0.1:18789/ và dán token vào cài đặt Control UI.
Xem Dashboard và Web surfaces để biết các chế độ bind và chi tiết xác thực.
Node >= 22 là bắt buộc. pnpm được khuyến nghị. Bun không được khuyến nghị cho Gateway.
Có. Gateway nhẹ - tài liệu liệt kê 512MB-1GB RAM, 1 core, và khoảng 500MB đĩa là đủ cho sử dụng cá nhân, và lưu ý rằng Raspberry Pi 4 có thể chạy nó.Nếu bạn muốn thêm không gian (logs, media, dịch vụ khác), 2GB được khuyến nghị, nhưng không phải là yêu cầu tối thiểu.Mẹo: một Pi/VPS nhỏ có thể lưu trữ Gateway, và bạn có thể ghép nối nodes trên laptop/điện thoại của bạn để sử dụng màn hình/camera/canvas cục bộ hoặc thực thi lệnh. Xem Nodes.
Phiên bản ngắn: nó hoạt động, nhưng mong đợi có những khó khăn.
  • Sử dụng hệ điều hành 64-bit và giữ Node >= 22.
  • Ưu tiên cài đặt hackable (git) để bạn có thể xem logs và cập nhật nhanh chóng.
  • Bắt đầu mà không có channels/skills, sau đó thêm từng cái một.
  • Nếu bạn gặp vấn đề nhị phân kỳ lạ, thường là vấn đề tương thích ARM.
Tài liệu: Linux, Install.
Màn hình đó phụ thuộc vào việc Gateway có thể truy cập và xác thực. TUI cũng tự động gửi “Wake up, my friend!” khi hatch lần đầu. Nếu bạn thấy dòng đó mà không có phản hồi và tokens vẫn ở 0, agent chưa bao giờ chạy.
  1. Khởi động lại Gateway:
openclaw gateway restart
  1. Kiểm tra trạng thái + xác thực:
openclaw status
openclaw models status
openclaw logs --follow
  1. Nếu nó vẫn bị treo, chạy:
openclaw doctor
Nếu Gateway là từ xa, đảm bảo kết nối tunnel/Tailscale đang hoạt động và UI đang chỉ vào Gateway đúng. Xem Remote access.
Có. Sao chép thư mục trạng thái và workspace, sau đó chạy Doctor một lần. Điều này giữ cho bot của bạn “hoàn toàn giống nhau” (bộ nhớ, lịch sử phiên, xác thực và trạng thái kênh) miễn là bạn sao chép cả hai vị trí:
  1. Cài đặt OpenClaw trên máy mới.
  2. Sao chép $OPENCLAW_STATE_DIR (mặc định: ~/.openclaw) từ máy cũ.
  3. Sao chép workspace của bạn (mặc định: ~/.openclaw/workspace).
  4. Chạy openclaw doctor và khởi động lại dịch vụ Gateway.
Điều này bảo toàn cấu hình, hồ sơ xác thực, thông tin đăng nhập WhatsApp, phiên và bộ nhớ. Nếu bạn đang ở chế độ từ xa, nhớ rằng máy chủ gateway sở hữu kho lưu trữ phiên và workspace.Quan trọng: nếu bạn chỉ commit/push workspace của mình lên GitHub, bạn đang sao lưu bộ nhớ + file bootstrap, nhưng không phải lịch sử phiên hoặc xác thực. Những thứ đó nằm dưới ~/.openclaw/ (ví dụ ~/.openclaw/agents/<agentId>/sessions/).Liên quan: Migrating, Nơi lưu trữ trên đĩa, Agent workspace, Doctor, Remote mode.
Kiểm tra changelog trên GitHub: https://github.com/openclaw/openclaw/blob/main/CHANGELOG.mdCác mục mới nhất nằm ở đầu. Nếu phần trên cùng được đánh dấu Unreleased, phần có ngày tiếp theo là phiên bản mới nhất đã phát hành. Các mục được nhóm theo Highlights, Changes, và Fixes (cộng với các phần docs/khác khi cần thiết).
Một số kết nối Comcast/Xfinity chặn docs.openclaw.ai không chính xác thông qua Xfinity Advanced Security. Vô hiệu hóa nó hoặc cho phép docs.openclaw.ai, sau đó thử lại. Chi tiết thêm: Troubleshooting. Vui lòng giúp chúng tôi mở khóa nó bằng cách báo cáo tại đây: https://spa.xfinity.com/check_url_status.Nếu bạn vẫn không thể truy cập trang web, tài liệu được sao lưu trên GitHub: https://github.com/openclaw/openclaw/tree/main/docs
Stable và beta là npm dist-tags, không phải các dòng mã riêng biệt:
  • latest = stable
  • beta = bản dựng sớm để thử nghiệm
Chúng tôi phát hành các bản dựng cho beta, thử nghiệm chúng, và khi một bản dựng ổn định, chúng tôi thăng cấp phiên bản đó lên latest. Đó là lý do tại sao beta và stable có thể chỉ vào cùng một phiên bản.Xem những gì đã thay đổi: https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md
Beta là npm dist-tag beta (có thể khớp với latest). Dev là đầu di chuyển của main (git); khi được phát hành, nó sử dụng npm dist-tag dev.Một dòng lệnh (macOS/Linux):
curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --beta

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --install-method git
Trình cài đặt Windows (PowerShell): https://openclaw.ai/install.ps1Chi tiết thêm: Development channels và Installer flags.
Hai lựa chọn:
  1. Kênh Dev (git checkout):
openclaw update --channel dev
Điều này chuyển sang nhánh main và cập nhật từ source.
  1. Cài đặt hackable (từ trang cài đặt):
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git
Điều đó cung cấp cho bạn một repo cục bộ bạn có thể chỉnh sửa, sau đó cập nhật qua git.Nếu bạn thích một clone sạch thủ công, sử dụng:
git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install
pnpm build
Tài liệu: Update, Development channels, Install.
Hướng dẫn sơ bộ:
  • Cài đặt: 2-5 phút
  • Onboarding: 5-15 phút tùy thuộc vào số lượng kênh/mô hình bạn cấu hình
Nếu nó bị treo, sử dụng Installer stuck và vòng lặp gỡ lỗi nhanh trong I am stuck.
Chạy lại trình cài đặt với đầu ra chi tiết:
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --verbose
Cài đặt beta với chi tiết:
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --beta --verbose
Đối với cài đặt hackable (git):
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git --verbose
Tương đương Windows (PowerShell):
# install.ps1 chưa có flag -Verbose riêng.
Set-PSDebug -Trace 1
& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -NoOnboard
Set-PSDebug -Trace 0
Nhiều tùy chọn hơn: Installer flags.
Hai vấn đề phổ biến trên Windows:1) npm error spawn git / không tìm thấy git
  • Cài đặt Git for Windows và đảm bảo git có trong PATH của bạn.
  • Đóng và mở lại PowerShell, sau đó chạy lại trình cài đặt.
2) openclaw không được nhận diện sau khi cài đặt
  • Thư mục bin toàn cầu npm của bạn không có trong PATH.
  • Kiểm tra đường dẫn: 
    npm config get prefix
  • Thêm thư mục đó vào PATH người dùng của bạn (không cần hậu tố \bin trên Windows; trên hầu hết các hệ thống là %AppData%\npm).
  • Đóng và mở lại PowerShell sau khi cập nhật PATH.
Nếu bạn muốn thiết lập Windows mượt mà nhất, sử dụng WSL2 thay vì Windows gốc. Tài liệu: Windows.
Đây thường là sự không khớp mã trang console trên các shell Windows gốc.Triệu chứng:
  • Đầu ra system.run/exec hiển thị tiếng Trung dưới dạng mojibake
  • Lệnh tương tự trông ổn trong một profile terminal khác
Giải pháp nhanh trong PowerShell:
chcp 65001
[Console]::InputEncoding = [System.Text.UTF8Encoding]::new($false)
[Console]::OutputEncoding = [System.Text.UTF8Encoding]::new($false)
$OutputEncoding = [System.Text.UTF8Encoding]::new($false)
Sau đó khởi động lại Gateway và thử lại lệnh của bạn:
openclaw gateway restart
Nếu bạn vẫn gặp phải điều này trên OpenClaw mới nhất, theo dõi/báo cáo nó trong:
Sử dụng cài đặt hackable (git) để bạn có toàn bộ source và tài liệu cục bộ, sau đó hỏi bot của bạn (hoặc Claude/Codex) từ thư mục đó để nó có thể đọc repo và trả lời chính xác.
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git
Chi tiết thêm: Install và Installer flags.
Câu trả lời ngắn: theo hướng dẫn Linux, sau đó chạy onboarding.
Bất kỳ VPS Linux nào cũng hoạt động. Cài đặt trên máy chủ, sau đó sử dụng SSH/Tailscale để truy cập Gateway.Hướng dẫn: exe.dev, Hetzner, Fly.io. Truy cập từ xa: Gateway remote.
Chúng tôi giữ một trung tâm lưu trữ với các nhà cung cấp phổ biến. Chọn một và làm theo hướng dẫn:Cách hoạt động trên cloud: Gateway chạy trên máy chủ, và bạn truy cập nó từ laptop/điện thoại của bạn qua Control UI (hoặc Tailscale/SSH). Trạng thái + workspace của bạn sống trên máy chủ, vì vậy hãy coi máy chủ là nguồn gốc và sao lưu nó.Bạn có thể ghép nối nodes (Mac/iOS/Android/headless) với Gateway trên cloud để truy cập màn hình/camera/canvas cục bộ hoặc chạy lệnh trên laptop của bạn trong khi giữ Gateway trên cloud.Trung tâm: Platforms. Truy cập từ xa: Gateway remote. Nodes: Nodes, Nodes CLI.
Câu trả lời ngắn: có thể, nhưng không khuyến nghị. Quy trình cập nhật có thể khởi động lại Gateway (dẫn đến mất phiên hoạt động), có thể cần một git checkout sạch, và có thể yêu cầu xác nhận. An toàn hơn: chạy cập nhật từ shell với tư cách là người vận hành.Sử dụng CLI:
openclaw update
openclaw update status
openclaw update --channel stable|beta|dev
openclaw update --tag <dist-tag|version>
openclaw update --no-restart
Nếu bạn phải tự động hóa từ một agent:
openclaw update --yes --no-restart
openclaw gateway restart
Tài liệu: Update, Updating.
openclaw onboard là con đường thiết lập được khuyến nghị. Trong chế độ cục bộ, nó hướng dẫn bạn qua:
  • Thiết lập mô hình/xác thực (hỗ trợ các luồng OAuth/setup-token của provider và API keys, cùng với các tùy chọn mô hình cục bộ như LM Studio)
  • Vị trí Workspace + file bootstrap
  • Cài đặt Gateway (bind/port/auth/tailscale)
  • Providers (WhatsApp, Telegram, Discord, Mattermost (plugin), Signal, iMessage)
  • Cài đặt Daemon (LaunchAgent trên macOS; systemd user unit trên Linux/WSL2)
  • Kiểm tra sức khỏe và lựa chọn skills
Nó cũng cảnh báo nếu mô hình bạn cấu hình không xác định hoặc thiếu xác thực.
Không. Bạn có thể chạy OpenClaw với API keys (Anthropic/OpenAI/khác) hoặc với mô hình chỉ cục bộ để dữ liệu của bạn ở lại trên thiết bị của bạn. Đăng ký (Claude Pro/Max hoặc OpenAI Codex) là các cách tùy chọn để xác thực các provider đó.Nếu bạn chọn xác thực đăng ký Anthropic, tự quyết định xem có sử dụng nó không: Anthropic đã chặn một số sử dụng đăng ký ngoài Claude Code trong quá khứ. OpenAI Codex OAuth được hỗ trợ rõ ràng cho các công cụ bên ngoài như OpenClaw.Tài liệu: Anthropic, OpenAI, Local models, Models.
Có. Bạn có thể xác thực bằng setup-token thay vì API key. Đây là con đường đăng ký.Đăng ký Claude Pro/Max không bao gồm API key, vì vậy đây là con đường kỹ thuật cho các tài khoản đăng ký. Nhưng đây là quyết định của bạn: Anthropic đã chặn một số sử dụng đăng ký ngoài Claude Code trong quá khứ. Nếu bạn muốn con đường rõ ràng và an toàn nhất cho sản xuất, sử dụng một Anthropic API key.
claude setup-token tạo ra một chuỗi token thông qua Claude Code CLI (nó không có sẵn trong web console). Bạn có thể chạy nó trên bất kỳ máy nào. Chọn Anthropic token (paste setup-token) trong onboarding hoặc dán nó với openclaw models auth paste-token --provider anthropic. Token được lưu trữ dưới dạng hồ sơ xác thực cho provider anthropic và được sử dụng như một API key (không tự động làm mới). Chi tiết thêm: OAuth.
Nó không có trong Anthropic Console. Setup-token được tạo ra bởi Claude Code CLI trên bất kỳ máy nào:
claude setup-token
Sao chép token mà nó in ra, sau đó chọn Anthropic token (paste setup-token) trong onboarding. Nếu bạn muốn chạy nó trên máy chủ gateway, sử dụng openclaw models auth setup-token --provider anthropic. Nếu bạn đã chạy claude setup-token ở nơi khác, dán nó trên máy chủ gateway với openclaw models auth paste-token --provider anthropic. Xem Anthropic.
Có - thông qua setup-token. OpenClaw không còn tái sử dụng các token OAuth của Claude Code CLI; sử dụng setup-token hoặc một Anthropic API key. Tạo token ở bất kỳ đâu và dán nó trên máy chủ gateway. Xem Anthropic và OAuth.Quan trọng: đây là khả năng tương thích kỹ thuật, không phải là đảm bảo chính sách. Anthropic đã chặn một số sử dụng đăng ký ngoài Claude Code trong quá khứ. Bạn cần quyết định xem có sử dụng nó không và xác minh các điều khoản hiện tại của Anthropic. Đối với sản xuất hoặc khối lượng công việc nhiều người dùng, xác thực API key của Anthropic là lựa chọn an toàn và được khuyến nghị.
Điều đó có nghĩa là hạn ngạch/tốc độ giới hạn của Anthropic của bạn đã hết cho cửa sổ hiện tại. Nếu bạn sử dụng một đăng ký Claude (setup-token), chờ cửa sổ đặt lại hoặc nâng cấp gói của bạn. Nếu bạn sử dụng một Anthropic API key, kiểm tra Anthropic Console để biết sử dụng/thanh toán và tăng giới hạn khi cần.Nếu thông báo cụ thể là: Extra usage is required for long context requests, yêu cầu đang cố gắng sử dụng Anthropic’s 1M context beta (context1m: true). Điều đó chỉ hoạt động khi thông tin xác thực của bạn đủ điều kiện cho thanh toán long-context (API key billing hoặc đăng ký với Extra Usage được bật).Mẹo: đặt một mô hình dự phòng để OpenClaw có thể tiếp tục trả lời trong khi một provider bị giới hạn tốc độ. Xem Models, OAuth, và /gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context.
Có - thông qua provider Amazon Bedrock (Converse) của pi-ai với cấu hình thủ công. Bạn phải cung cấp thông tin xác thực AWS/khu vực trên máy chủ gateway và thêm một mục provider Bedrock trong cấu hình mô hình của bạn. Xem Amazon Bedrock và Model providers. Nếu bạn thích một luồng khóa quản lý, một proxy tương thích OpenAI trước Bedrock vẫn là một lựa chọn hợp lệ.
OpenClaw hỗ trợ OpenAI Code (Codex) thông qua OAuth (đăng nhập ChatGPT). Onboarding có thể chạy luồng OAuth và sẽ đặt mô hình mặc định thành openai-codex/gpt-5.4 khi thích hợp. Xem Model providers và Onboarding (CLI).
Có. OpenClaw hoàn toàn hỗ trợ OpenAI Code (Codex) subscription OAuth. OpenAI cho phép rõ ràng việc sử dụng subscription OAuth trong các công cụ/quy trình làm việc bên ngoài như OpenClaw. Onboarding có thể chạy luồng OAuth cho bạn.Xem OAuth, Model providers, và Onboarding (CLI).
Gemini CLI sử dụng một luồng xác thực plugin, không phải một client id hoặc secret trong openclaw.json.Các bước:
  1. Kích hoạt plugin: openclaw plugins enable google
  2. Đăng nhập: openclaw models auth login --provider google-gemini-cli --set-default
Điều này lưu trữ các token OAuth trong hồ sơ xác thực trên máy chủ gateway. Chi tiết: Model providers.
Thường thì không. OpenClaw cần ngữ cảnh lớn + an toàn mạnh; các thẻ nhỏ cắt ngắn và rò rỉ. Nếu bạn phải, chạy bản dựng lớn nhất MiniMax M2.5 mà bạn có thể cục bộ (LM Studio) và xem /gateway/local-models. Các mô hình nhỏ hơn/được lượng hóa tăng nguy cơ tiêm nhiễm prompt - xem Security.
Chọn các điểm cuối được ghim theo khu vực. OpenRouter cung cấp các tùy chọn lưu trữ tại Mỹ cho MiniMax, Kimi, và GLM; chọn biến thể lưu trữ tại Mỹ để giữ dữ liệu trong khu vực. Bạn vẫn có thể liệt kê Anthropic/OpenAI cùng với những cái này bằng cách sử dụng models.mode: "merge" để các dự phòng vẫn có sẵn trong khi tôn trọng provider theo khu vực bạn chọn.
Không. OpenClaw chạy trên macOS hoặc Linux (Windows qua WSL2). Một Mac mini là tùy chọn - một số người mua một cái như một máy chủ luôn bật, nhưng một VPS nhỏ, máy chủ tại nhà, hoặc hộp Raspberry Pi-class cũng hoạt động.Bạn chỉ cần một Mac cho các công cụ chỉ dành cho macOS. Đối với iMessage, sử dụng BlueBubbles (khuyến nghị) - máy chủ BlueBubbles chạy trên bất kỳ Mac nào, và Gateway có thể chạy trên Linux hoặc nơi khác. Nếu bạn muốn các công cụ chỉ dành cho macOS khác, chạy Gateway trên một Mac hoặc ghép nối một node macOS.Tài liệu: BlueBubbles, Nodes, Mac remote mode.
Bạn cần một thiết bị macOS nào đó đã đăng nhập vào Messages. Nó không phải là một Mac mini - bất kỳ Mac nào cũng được. Sử dụng BlueBubbles (khuyến nghị) cho iMessage - máy chủ BlueBubbles chạy trên macOS, trong khi Gateway có thể chạy trên Linux hoặc nơi khác.Các thiết lập phổ biến:
  • Chạy Gateway trên Linux/VPS, và chạy máy chủ BlueBubbles trên bất kỳ Mac nào đã đăng nhập vào Messages.
  • Chạy mọi thứ trên Mac nếu bạn muốn thiết lập đơn giản nhất trên một máy.
Tài liệu: BlueBubbles, Nodes, Mac remote mode.
Có. Mac mini có thể chạy Gateway, và MacBook Pro của bạn có thể kết nối như một node (thiết bị đồng hành). Nodes không chạy Gateway - chúng cung cấp các khả năng bổ sung như màn hình/camera/canvas và system.run trên thiết bị đó.Mẫu phổ biến:
  • Gateway trên Mac mini (luôn bật).
  • MacBook Pro chạy ứng dụng macOS hoặc một node host và ghép nối với Gateway.
  • Sử dụng openclaw nodes status / openclaw nodes list để xem nó.
Tài liệu: Nodes, Nodes CLI.
Bun không được khuyến nghị. Chúng tôi thấy các lỗi runtime, đặc biệt với WhatsApp và Telegram. Sử dụng Node cho các gateways ổn định.Nếu bạn vẫn muốn thử nghiệm với Bun, hãy làm điều đó trên một gateway không phải sản xuất mà không có WhatsApp/Telegram.
channels.telegram.allowFrom là ID người dùng Telegram của người gửi (số). Nó không phải là tên người dùng bot.Onboarding chấp nhận đầu vào @username và chuyển đổi nó thành một ID số, nhưng xác thực OpenClaw chỉ sử dụng ID số.An toàn hơn (không có bot bên thứ ba):
  • DM bot của bạn, sau đó chạy openclaw logs --follow và đọc from.id.
API Bot chính thức:
  • DM bot của bạn, sau đó gọi https://api.telegram.org/bot<bot_token>/getUpdates và đọc message.from.id.
Bên thứ ba (ít riêng tư hơn):
  • DM @userinfobot hoặc @getidsbot.
Xem /channels/telegram.
Có, thông qua multi-agent routing. Liên kết mỗi DM người gửi WhatsApp (peer kind: "direct", người gửi E.164 như +15551234567) với một agentId khác nhau, để mỗi người có workspace và kho lưu trữ phiên riêng. Phản hồi vẫn đến từ cùng một tài khoản WhatsApp, và kiểm soát truy cập DM (channels.whatsapp.dmPolicy / channels.whatsapp.allowFrom) là toàn cầu cho mỗi tài khoản WhatsApp. Xem Multi-Agent Routing và WhatsApp.
Có. Sử dụng multi-agent routing: cung cấp cho mỗi agent mô hình mặc định riêng, sau đó liên kết các tuyến inbound (tài khoản provider hoặc peers cụ thể) với mỗi agent. Cấu hình ví dụ nằm trong Multi-Agent Routing. Xem thêm Models và Configuration.
Có. Homebrew hỗ trợ Linux (Linuxbrew). Thiết lập nhanh:
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
echo 'eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)"' >> ~/.profile
eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)"
brew install <formula>
Nếu bạn chạy OpenClaw qua systemd, đảm bảo PATH dịch vụ bao gồm /home/linuxbrew/.linuxbrew/bin (hoặc prefix brew của bạn) để các công cụ cài đặt qua brew được giải quyết trong các shell không đăng nhập. Các bản dựng gần đây cũng thêm các thư mục bin người dùng phổ biến trên các dịch vụ systemd Linux (ví dụ ~/.local/bin, ~/.npm-global/bin, ~/.local/share/pnpm, ~/.bun/bin) và tôn trọng PNPM_HOME, NPM_CONFIG_PREFIX, BUN_INSTALL, VOLTA_HOME, ASDF_DATA_DIR, NVM_DIR, và FNM_DIR khi được thiết lập.
  • Cài đặt hackable (git): toàn bộ source checkout, có thể chỉnh sửa, tốt nhất cho người đóng góp. Bạn chạy các bản dựng cục bộ và có thể vá mã/tài liệu.
  • npm install: cài đặt CLI toàn cầu, không có repo, tốt nhất cho “chỉ cần chạy nó.” Cập nhật đến từ npm dist-tags.
Tài liệu: Getting started, Updating.
Có. Cài đặt hương vị khác, sau đó chạy Doctor để dịch vụ gateway chỉ vào điểm đầu vào mới. Điều này không xóa dữ liệu của bạn - nó chỉ thay đổi cài đặt mã OpenClaw. Trạng thái của bạn (~/.openclaw) và workspace (~/.openclaw/workspace) vẫn không bị ảnh hưởng.Từ npm sang git:
git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install
pnpm build
openclaw doctor
openclaw gateway restart
Từ git sang npm:
npm install -g openclaw@latest
openclaw doctor
openclaw gateway restart
Doctor phát hiện sự không khớp điểm đầu vào dịch vụ gateway và đề nghị viết lại cấu hình dịch vụ để khớp với cài đặt hiện tại (sử dụng --repair trong tự động hóa).Mẹo sao lưu: xem Backup strategy.
Câu trả lời ngắn: nếu bạn muốn độ tin cậy 24/7, sử dụng VPS. Nếu bạn muốn ít ma sát nhất và bạn ổn với việc ngủ/khởi động lại, chạy nó cục bộ.Laptop (Gateway cục bộ)
  • Ưu điểm: không tốn chi phí máy chủ, truy cập trực tiếp vào file cục bộ, cửa sổ trình duyệt trực tiếp.
  • Nhược điểm: ngủ/mất kết nối mạng = ngắt kết nối, cập nhật/hệ điều hành khởi động lại gián đoạn, phải luôn thức.
VPS / cloud
  • Ưu điểm: luôn bật, mạng ổn định, không có vấn đề ngủ laptop, dễ dàng giữ cho nó chạy.
  • Nhược điểm: thường chạy headless (sử dụng ảnh chụp màn hình), chỉ truy cập file từ xa, bạn phải SSH để cập nhật.
Lưu ý cụ thể của OpenClaw: WhatsApp/Telegram/Slack/Mattermost (plugin)/Discord đều hoạt động tốt từ VPS. Sự khác biệt thực sự duy nhất là trình duyệt headless so với một cửa sổ có thể nhìn thấy. Xem Browser.Mặc định khuyến nghị: VPS nếu bạn đã gặp ngắt kết nối gateway trước đó. Cục bộ là tuyệt vời khi bạn đang sử dụng Mac tích cực và muốn truy cập file cục bộ hoặc tự động hóa UI với một trình duyệt có thể nhìn thấy.
Không bắt buộc, nhưng khuyến nghị cho độ tin cậy và cách ly.
  • Máy chủ chuyên dụng (VPS/Mac mini/Pi): luôn bật, ít gián đoạn ngủ/khởi động lại, quyền sạch hơn, dễ dàng giữ cho nó chạy.
  • Laptop/desktop chia sẻ: hoàn toàn ổn cho thử nghiệm và sử dụng tích cực, nhưng mong đợi tạm dừng khi máy ngủ hoặc cập nhật.
Nếu bạn muốn có cả hai thế giới, giữ Gateway trên một máy chủ chuyên dụng và ghép nối laptop của bạn như một node cho các công cụ màn hình/camera/exec cục bộ. Xem Nodes. Để biết hướng dẫn bảo mật, đọc Security.
OpenClaw nhẹ. Đối với một Gateway cơ bản + một kênh chat:
  • Tối thiểu tuyệt đối: 1 vCPU, 1GB RAM, ~500MB đĩa.
  • Khuyến nghị: 1-2 vCPU, 2GB RAM hoặc nhiều hơn để có không gian (logs, media, nhiều kênh). Các công cụ Node và tự động hóa trình duyệt có thể tiêu tốn tài nguyên.
Hệ điều hành: sử dụng Ubuntu LTS (hoặc bất kỳ Debian/Ubuntu hiện đại nào). Đường dẫn cài đặt Linux được thử nghiệm tốt nhất ở đó.Tài liệu: Linux, VPS hosting.
Có. Đối xử với một VM giống như một VPS: nó cần luôn bật, có thể truy cập, và có đủ RAM cho Gateway và bất kỳ kênh nào bạn kích hoạt.Hướng dẫn cơ bản:
  • Tối thiểu tuyệt đối: 1 vCPU, 1GB RAM.
  • Khuyến nghị: 2GB RAM hoặc nhiều hơn nếu bạn chạy nhiều kênh, tự động hóa trình duyệt, hoặc công cụ media.
  • Hệ điều hành: Ubuntu LTS hoặc một Debian/Ubuntu hiện đại khác.
Nếu bạn đang sử dụng Windows, WSL2 là thiết lập kiểu VM dễ nhất và có công cụ tương thích tốt nhất. Xem Windows, VPS hosting. Nếu bạn đang chạy macOS trong một VM, xem macOS VM.

​
OpenClaw là gì?

OpenClaw là một trợ lý AI cá nhân bạn chạy trên các thiết bị của riêng bạn. Nó trả lời trên các nền tảng nhắn tin bạn đã sử dụng (WhatsApp, Telegram, Slack, Mattermost (plugin), Discord, Google Chat, Signal, iMessage, WebChat) và cũng có thể thực hiện giọng nói + Canvas trực tiếp trên các nền tảng được hỗ trợ. Gateway là mặt phẳng điều khiển luôn bật; trợ lý là sản phẩm.
OpenClaw không chỉ là “một lớp bọc Claude.” Nó là một mặt phẳng điều khiển ưu tiên cục bộ cho phép bạn chạy một trợ lý mạnh mẽ trên phần cứng của riêng bạn, có thể truy cập từ các ứng dụng chat bạn đã sử dụng, với các phiên có trạng thái, bộ nhớ và công cụ - mà không cần giao quyền kiểm soát quy trình làm việc của bạn cho một SaaS được lưu trữ.Điểm nổi bật:
  • Thiết bị của bạn, dữ liệu của bạn: chạy Gateway ở bất kỳ đâu bạn muốn (Mac, Linux, VPS) và giữ workspace + lịch sử phiên cục bộ.
  • Kênh thực, không phải sandbox web: WhatsApp/Telegram/Slack/Discord/Signal/iMessage/etc, cộng với giọng nói di động và Canvas trên các nền tảng được hỗ trợ.
  • Không phụ thuộc mô hình: sử dụng Anthropic, OpenAI, MiniMax, OpenRouter, v.v., với định tuyến và chuyển đổi dự phòng theo agent.
  • Tùy chọn chỉ cục bộ: chạy các mô hình cục bộ để tất cả dữ liệu có thể ở lại trên thiết bị của bạn nếu bạn muốn.
  • Định tuyến multi-agent: tách các agent theo kênh, tài khoản, hoặc nhiệm vụ, mỗi cái có workspace và mặc định riêng.
  • Mã nguồn mở và có thể hack: kiểm tra, mở rộng, và tự lưu trữ mà không bị khóa nhà cung cấp.
Tài liệu: Gateway, Channels, Multi-agent, Memory.
Dự án đầu tiên tốt:
  • Xây dựng một trang web (WordPress, Shopify, hoặc một trang tĩnh đơn giản).
  • Tạo mẫu một ứng dụng di động (phác thảo, màn hình, kế hoạch API).
  • Tổ chức file và thư mục (dọn dẹp, đặt tên, gắn thẻ).
  • Kết nối Gmail và tự động hóa tóm tắt hoặc theo dõi.
Nó có thể xử lý các nhiệm vụ lớn, nhưng nó hoạt động tốt nhất khi bạn chia chúng thành các giai đoạn và sử dụng các sub agent cho công việc song song.
Những chiến thắng hàng ngày thường trông như:
  • Tóm tắt cá nhân: tóm tắt hộp thư đến, lịch, và tin tức bạn quan tâm.
  • Nghiên cứu và soạn thảo: nghiên cứu nhanh, tóm tắt, và bản thảo đầu tiên cho email hoặc tài liệu.
  • Nhắc nhở và theo dõi: nhắc nhở và danh sách kiểm tra dựa trên cron hoặc heartbeat.
  • Tự động hóa trình duyệt: điền vào biểu mẫu, thu thập dữ liệu, và lặp lại các nhiệm vụ web.
  • Phối hợp thiết bị chéo: gửi một nhiệm vụ từ điện thoại của bạn, để Gateway chạy nó trên máy chủ, và nhận kết quả trở lại trong chat.
Có cho nghiên cứu, đủ điều kiện, và soạn thảo. Nó có thể quét các trang web, xây dựng danh sách ngắn, tóm tắt khách hàng tiềm năng, và viết bản thảo tiếp cận hoặc quảng cáo.Đối với tiếp cận hoặc chạy quảng cáo, giữ một người trong vòng lặp. Tránh spam, tuân thủ luật pháp địa phương và chính sách nền tảng, và xem xét mọi thứ trước khi gửi. Mẫu an toàn nhất là để OpenClaw soạn thảo và bạn phê duyệt.Tài liệu: Security.
OpenClaw là một trợ lý cá nhân và lớp điều phối, không phải là một thay thế IDE. Sử dụng Claude Code hoặc Codex cho vòng lặp mã hóa trực tiếp nhanh nhất trong một repo. Sử dụng OpenClaw khi bạn muốn bộ nhớ bền vững, truy cập đa thiết bị, và điều phối công cụ.Lợi thế:
  • Bộ nhớ + workspace bền vững qua các phiên
  • Truy cập đa nền tảng (WhatsApp, Telegram, TUI, WebChat)
  • Điều phối công cụ (trình duyệt, file, lập lịch, hooks)
  • Gateway luôn bật (chạy trên VPS, tương tác từ bất kỳ đâu)
  • Nodes cho trình duyệt/màn hình/camera/exec cục bộ
Showcase: https://openclaw.ai/showcase

​
Kỹ năng và tự động hóa

Sử dụng managed overrides thay vì chỉnh sửa bản sao của repo. Đặt các thay đổi vào ~/.openclaw/skills/<name>/SKILL.md (hoặc thêm thư mục qua skills.load.extraDirs trong ~/.openclaw/openclaw.json). Thứ tự ưu tiên là <workspace>/skills > ~/.openclaw/skills > bundled, vì vậy managed overrides sẽ được ưu tiên mà không cần chạm vào git. Chỉ những chỉnh sửa đáng giá upstream mới nên tồn tại trong repo và được gửi đi dưới dạng PR.
Có. Thêm các thư mục bổ sung qua skills.load.extraDirs trong ~/.openclaw/openclaw.json (ưu tiên thấp nhất). Thứ tự ưu tiên mặc định vẫn là: <workspace>/skills → ~/.openclaw/skills → bundled → skills.load.extraDirs. clawhub cài đặt vào ./skills theo mặc định, mà OpenClaw coi là <workspace>/skills trong phiên tiếp theo.
Hiện tại các mẫu hỗ trợ là:
  • Cron jobs: các công việc độc lập có thể đặt một model override cho mỗi công việc.
  • Sub-agents: định tuyến nhiệm vụ đến các agent riêng biệt với các mô hình mặc định khác nhau.
  • Chuyển đổi theo yêu cầu: sử dụng /model để chuyển đổi mô hình phiên hiện tại bất cứ lúc nào.
Xem Cron jobs, Multi-Agent Routing, và Slash commands.
Sử dụng sub-agents cho các nhiệm vụ dài hoặc song song. Sub-agents chạy trong phiên riêng của chúng, trả về một bản tóm tắt và giữ cho cuộc trò chuyện chính của bạn luôn phản hồi.Yêu cầu bot “spawn a sub-agent for this task” hoặc sử dụng /subagents. Sử dụng /status trong chat để xem Gateway đang làm gì ngay bây giờ (và liệu nó có bận không).Mẹo về token: các nhiệm vụ dài và sub-agents đều tiêu thụ token. Nếu chi phí là một mối quan tâm, hãy đặt một mô hình rẻ hơn cho sub-agents qua agents.defaults.subagents.model.Tài liệu: Sub-agents.
Sử dụng thread bindings. Bạn có thể ràng buộc một thread Discord vào một subagent hoặc mục tiêu phiên để các tin nhắn tiếp theo trong thread đó duy trì trên phiên đã ràng buộc.Quy trình cơ bản:
  • Spawn với sessions_spawn sử dụng thread: true (và tùy chọn mode: "session" cho theo dõi liên tục).
  • Hoặc ràng buộc thủ công với /focus <target>.
  • Sử dụng /agents để kiểm tra trạng thái ràng buộc.
  • Sử dụng /session idle <duration|off> và /session max-age <duration|off> để kiểm soát tự động unfocus.
  • Sử dụng /unfocus để tách thread.
Cấu hình yêu cầu:
  • Mặc định toàn cầu: session.threadBindings.enabled, session.threadBindings.idleHours, session.threadBindings.maxAgeHours.
  • Ghi đè Discord: channels.discord.threadBindings.enabled, channels.discord.threadBindings.idleHours, channels.discord.threadBindings.maxAgeHours.
  • Tự động ràng buộc khi spawn: đặt channels.discord.threadBindings.spawnSubagentSessions: true.
Tài liệu: Sub-agents, Discord, Configuration Reference, Slash commands.
Cron chạy bên trong quá trình Gateway. Nếu Gateway không chạy liên tục, các công việc đã lên lịch sẽ không chạy.Danh sách kiểm tra:
  • Xác nhận cron được bật (cron.enabled) và OPENCLAW_SKIP_CRON không được đặt.
  • Kiểm tra Gateway đang chạy 24/7 (không ngủ/khởi động lại).
  • Xác minh cài đặt múi giờ cho công việc (--tz so với múi giờ máy chủ).
Gỡ lỗi:
openclaw cron run <jobId> --force
openclaw cron runs --id <jobId> --limit 50
Tài liệu: Cron jobs, Cron vs Heartbeat.
Sử dụng ClawHub (CLI) hoặc thả kỹ năng vào workspace của bạn. Giao diện người dùng Skills trên macOS không có sẵn trên Linux. Duyệt kỹ năng tại https://clawhub.com.Cài đặt ClawHub CLI (chọn một trình quản lý gói):
npm i -g clawhub

pnpm add -g clawhub
Có. Sử dụng bộ lập lịch Gateway:
  • Cron jobs cho các nhiệm vụ theo lịch trình hoặc định kỳ (duy trì qua các lần khởi động lại).
  • Heartbeat cho các kiểm tra định kỳ “main session”.
  • Isolated jobs cho các agent tự động đăng tóm tắt hoặc gửi đến các cuộc trò chuyện.
Tài liệu: Cron jobs, Cron vs Heartbeat, Heartbeat.
Không trực tiếp. Các kỹ năng macOS bị giới hạn bởi metadata.openclaw.os cùng với các binary cần thiết, và các kỹ năng chỉ xuất hiện trong prompt hệ thống khi chúng đủ điều kiện trên Gateway host. Trên Linux, các kỹ năng chỉ dành cho darwin (như apple-notes, apple-reminders, things-mac) sẽ không tải trừ khi bạn ghi đè giới hạn.Bạn có ba mẫu hỗ trợ:Tùy chọn A - chạy Gateway trên Mac (đơn giản nhất). Chạy Gateway nơi các binary macOS tồn tại, sau đó kết nối từ Linux trong remote mode hoặc qua Tailscale. Các kỹ năng tải bình thường vì Gateway host là macOS.Tùy chọn B - sử dụng một node macOS (không SSH). Chạy Gateway trên Linux, ghép nối một node macOS (ứng dụng menubar), và đặt Node Run Commands thành “Always Ask” hoặc “Always Allow” trên Mac. OpenClaw có thể coi các kỹ năng chỉ dành cho macOS là đủ điều kiện khi các binary cần thiết tồn tại trên node. Agent chạy các kỹ năng đó qua công cụ nodes. Nếu bạn chọn “Always Ask”, việc phê duyệt “Always Allow” trong prompt sẽ thêm lệnh đó vào danh sách cho phép.Tùy chọn C - proxy các binary macOS qua SSH (nâng cao). Giữ Gateway trên Linux, nhưng làm cho các binary CLI cần thiết giải quyết thành các wrapper SSH chạy trên Mac. Sau đó ghi đè kỹ năng để cho phép Linux để nó vẫn đủ điều kiện.
  1. Tạo một wrapper SSH cho binary (ví dụ: memo cho Apple Notes): 
    #!/usr/bin/env bash
set -euo pipefail
exec ssh -T user@mac-host /opt/homebrew/bin/memo "$@"
  2. Đặt wrapper trên PATH trên host Linux (ví dụ ~/bin/memo).
  3. Ghi đè metadata kỹ năng (workspace hoặc ~/.openclaw/skills) để cho phép Linux: 
    ---
name: apple-notes
description: Quản lý Apple Notes qua memo CLI trên macOS.
metadata: { "openclaw": { "os": ["darwin", "linux"], "requires": { "bins": ["memo"] } } }
---
  4. Bắt đầu một phiên mới để snapshot kỹ năng được làm mới.
Hiện tại chưa có sẵn.Các tùy chọn:
  • Kỹ năng tùy chỉnh / plugin: tốt nhất cho truy cập API đáng tin cậy (cả Notion và HeyGen đều có API).
  • Tự động hóa trình duyệt: hoạt động mà không cần mã nhưng chậm hơn và dễ bị lỗi hơn.
Nếu bạn muốn giữ ngữ cảnh cho mỗi khách hàng (quy trình làm việc của agency), một mẫu đơn giản là:
  • Một trang Notion cho mỗi khách hàng (ngữ cảnh + sở thích + công việc đang hoạt động).
  • Yêu cầu agent lấy trang đó khi bắt đầu một phiên.
Nếu bạn muốn tích hợp gốc, mở một yêu cầu tính năng hoặc xây dựng một kỹ năng nhắm mục tiêu vào các API đó.Cài đặt kỹ năng:
clawhub install <skill-slug>
clawhub update --all
ClawHub cài đặt vào ./skills dưới thư mục hiện tại của bạn (hoặc quay lại workspace OpenClaw đã cấu hình); OpenClaw coi đó là <workspace>/skills trong phiên tiếp theo. Để chia sẻ kỹ năng giữa các agent, đặt chúng vào ~/.openclaw/skills/<name>/SKILL.md. Một số kỹ năng yêu cầu các binary được cài đặt qua Homebrew; trên Linux điều đó có nghĩa là Linuxbrew (xem mục FAQ Homebrew Linux ở trên). Xem Skills và ClawHub.
Sử dụng hồ sơ trình duyệt user tích hợp sẵn, kết nối qua Chrome DevTools MCP:
openclaw browser --browser-profile user tabs
openclaw browser --browser-profile user snapshot
Nếu bạn muốn một tên tùy chỉnh, tạo một hồ sơ MCP rõ ràng:
openclaw browser create-profile --name chrome-live --driver existing-session
openclaw browser --browser-profile chrome-live tabs
Đường dẫn này là host-local. Nếu Gateway chạy ở nơi khác, hãy chạy một node host trên máy trình duyệt hoặc sử dụng CDP từ xa thay thế.

​
Sandboxing và bộ nhớ

Có. Xem Sandboxing. Đối với thiết lập Docker cụ thể (gateway đầy đủ trong Docker hoặc sandbox images), xem Docker.
Hình ảnh mặc định ưu tiên bảo mật và chạy dưới dạng người dùng node, vì vậy nó không bao gồm các gói hệ thống, Homebrew, hoặc trình duyệt đi kèm. Để có một thiết lập đầy đủ hơn:
  • Duy trì /home/node với OPENCLAW_HOME_VOLUME để các bộ nhớ cache tồn tại.
  • Nướng các phụ thuộc hệ thống vào hình ảnh với OPENCLAW_DOCKER_APT_PACKAGES.
  • Cài đặt trình duyệt Playwright qua CLI đi kèm: node /app/node_modules/playwright-core/cli.js install chromium
  • Đặt PLAYWRIGHT_BROWSERS_PATH và đảm bảo đường dẫn được duy trì.
Tài liệu: Docker, Browser.
Có - nếu lưu lượng riêng tư của bạn là DMs và lưu lượng công khai của bạn là groups.Sử dụng agents.defaults.sandbox.mode: "non-main" để các phiên nhóm/kênh (không phải khóa chính) chạy trong Docker, trong khi phiên DM chính vẫn ở trên host. Sau đó hạn chế những công cụ nào có sẵn trong các phiên sandboxed qua tools.sandbox.tools.Hướng dẫn thiết lập + cấu hình ví dụ: Groups: personal DMs + public groupsTham khảo cấu hình chính: Gateway configuration
Đặt agents.defaults.sandbox.docker.binds thành ["host:path:mode"] (ví dụ, "/home/user/src:/src:ro"). Các bind toàn cầu + per-agent hợp nhất; các bind per-agent bị bỏ qua khi scope: "shared". Sử dụng :ro cho bất kỳ thứ gì nhạy cảm và nhớ rằng các bind bỏ qua các tường lửa hệ thống tệp sandbox. Xem Sandboxing và Sandbox vs Tool Policy vs Elevated để biết ví dụ và ghi chú an toàn.
Bộ nhớ OpenClaw chỉ là các tệp Markdown trong workspace của agent:
  • Ghi chú hàng ngày trong memory/YYYY-MM-DD.md
  • Ghi chú dài hạn được chọn lọc trong MEMORY.md (chỉ các phiên chính/riêng tư)
OpenClaw cũng chạy một silent pre-compaction memory flush để nhắc mô hình viết các ghi chú bền vững trước khi tự động nén. Điều này chỉ chạy khi workspace có thể ghi (sandbox chỉ đọc bỏ qua nó). Xem Memory.
Yêu cầu bot ghi nhớ thông tin vào bộ nhớ. Ghi chú dài hạn thuộc về MEMORY.md, ngữ cảnh ngắn hạn đi vào memory/YYYY-MM-DD.md.Đây vẫn là một lĩnh vực chúng tôi đang cải thiện. Nó giúp nhắc mô hình lưu trữ ký ức; nó sẽ biết phải làm gì. Nếu nó cứ quên, hãy xác minh Gateway đang sử dụng cùng một workspace trong mỗi lần chạy.Tài liệu: Memory, Agent workspace.
Các tệp bộ nhớ tồn tại trên đĩa và tồn tại cho đến khi bạn xóa chúng. Giới hạn là dung lượng lưu trữ của bạn, không phải mô hình. Ngữ cảnh phiên vẫn bị giới hạn bởi cửa sổ ngữ cảnh của mô hình, vì vậy các cuộc trò chuyện dài có thể nén hoặc cắt ngắn. Đó là lý do tại sao tìm kiếm bộ nhớ tồn tại - nó chỉ kéo các phần liên quan trở lại ngữ cảnh.Tài liệu: Memory, Context.
Chỉ khi bạn sử dụng OpenAI embeddings. Codex OAuth bao gồm chat/completions và không cấp quyền truy cập embeddings, vì vậy đăng nhập bằng Codex (OAuth hoặc Codex CLI login) không giúp ích cho tìm kiếm bộ nhớ ngữ nghĩa. OpenAI embeddings vẫn cần một khóa API thực (OPENAI_API_KEY hoặc models.providers.openai.apiKey).Nếu bạn không đặt một nhà cung cấp rõ ràng, OpenClaw tự động chọn một nhà cung cấp khi nó có thể giải quyết một khóa API (auth profiles, models.providers.*.apiKey, hoặc env vars). Nó ưu tiên OpenAI nếu một khóa OpenAI được giải quyết, nếu không thì Gemini nếu một khóa Gemini được giải quyết, sau đó là Voyage, rồi Mistral. Nếu không có khóa từ xa nào có sẵn, tìm kiếm bộ nhớ sẽ bị vô hiệu hóa cho đến khi bạn cấu hình nó. Nếu bạn có một đường dẫn mô hình cục bộ được cấu hình và có mặt, OpenClaw ưu tiên local. Ollama được hỗ trợ khi bạn đặt rõ ràng memorySearch.provider = "ollama".Nếu bạn muốn giữ cục bộ, đặt memorySearch.provider = "local" (và tùy chọn memorySearch.fallback = "none"). Nếu bạn muốn Gemini embeddings, đặt memorySearch.provider = "gemini" và cung cấp GEMINI_API_KEY (hoặc memorySearch.remote.apiKey). Chúng tôi hỗ trợ OpenAI, Gemini, Voyage, Mistral, Ollama, hoặc local embedding models - xem Memory để biết chi tiết thiết lập.

​
Nơi lưu trữ dữ liệu trên đĩa

Không - trạng thái của OpenClaw là cục bộ, nhưng các dịch vụ bên ngoài vẫn thấy những gì bạn gửi cho chúng.
  • Cục bộ theo mặc định: các phiên, tệp bộ nhớ, cấu hình, và workspace sống trên Gateway host (~/.openclaw + thư mục workspace của bạn).
  • Từ xa khi cần thiết: các tin nhắn bạn gửi đến các nhà cung cấp mô hình (Anthropic/OpenAI/etc.) đi đến API của họ, và các nền tảng chat (WhatsApp/Telegram/Slack/etc.) lưu trữ dữ liệu tin nhắn trên máy chủ của họ.
  • Bạn kiểm soát dấu chân: sử dụng các mô hình cục bộ giữ các prompt trên máy của bạn, nhưng lưu lượng kênh vẫn đi qua máy chủ của kênh.
Liên quan: Agent workspace, Memory.
Mọi thứ sống dưới $OPENCLAW_STATE_DIR (mặc định: ~/.openclaw):
Đường dẫnMục đích
$OPENCLAW_STATE_DIR/openclaw.jsonCấu hình chính (JSON5)
$OPENCLAW_STATE_DIR/credentials/oauth.jsonNhập OAuth cũ (sao chép vào hồ sơ xác thực khi sử dụng lần đầu)
$OPENCLAW_STATE_DIR/agents/<agentId>/agent/auth-profiles.jsonHồ sơ xác thực (OAuth, API keys, và tùy chọn keyRef/tokenRef)
$OPENCLAW_STATE_DIR/secrets.jsonTệp tải bí mật dựa trên tệp tùy chọn cho các nhà cung cấp SecretRef file
$OPENCLAW_STATE_DIR/agents/<agentId>/agent/auth.jsonTệp tương thích cũ (các mục api_key tĩnh đã được xóa)
$OPENCLAW_STATE_DIR/credentials/Trạng thái nhà cung cấp (ví dụ whatsapp/<accountId>/creds.json)
$OPENCLAW_STATE_DIR/agents/Trạng thái per-agent (agentDir + sessions)
$OPENCLAW_STATE_DIR/agents/<agentId>/sessions/Lịch sử & trạng thái cuộc trò chuyện (per agent)
$OPENCLAW_STATE_DIR/agents/<agentId>/sessions/sessions.jsonMetadata phiên (per agent)
Đường dẫn single-agent cũ: ~/.openclaw/agent/* (được di chuyển bởi openclaw doctor).Workspace của bạn (AGENTS.md, tệp bộ nhớ, kỹ năng, v.v.) là riêng biệt và được cấu hình qua agents.defaults.workspace (mặc định: ~/.openclaw/workspace).
Các tệp này sống trong agent workspace, không phải ~/.openclaw.
  • Workspace (per agent): AGENTS.md, SOUL.md, IDENTITY.md, USER.md, MEMORY.md (hoặc fallback cũ memory.md khi MEMORY.md không có), memory/YYYY-MM-DD.md, tùy chọn HEARTBEAT.md.
  • Thư mục trạng thái (~/.openclaw): cấu hình, thông tin xác thực, hồ sơ xác thực, phiên, nhật ký, và kỹ năng chia sẻ (~/.openclaw/skills).
Workspace mặc định là ~/.openclaw/workspace, có thể cấu hình qua:
{
  agents: { defaults: { workspace: "~/.openclaw/workspace" } },
}
Nếu bot “quên” sau khi khởi động lại, xác nhận Gateway đang sử dụng cùng một workspace trong mỗi lần khởi động (và nhớ: chế độ từ xa sử dụng workspace của gateway host, không phải máy tính xách tay cục bộ của bạn).Mẹo: nếu bạn muốn một hành vi hoặc sở thích bền vững, yêu cầu bot ghi nó vào AGENTS.md hoặc MEMORY.md thay vì dựa vào lịch sử chat.Xem Agent workspace và Memory.
Đặt agent workspace của bạn vào một repo git riêng tư và sao lưu nó ở đâu đó riêng tư (ví dụ GitHub private). Điều này lưu trữ bộ nhớ + tệp AGENTS/SOUL/USER, và cho phép bạn khôi phục “tâm trí” của trợ lý sau này.Không cam kết bất cứ điều gì dưới ~/.openclaw (thông tin xác thực, phiên, token, hoặc tải bí mật được mã hóa). Nếu bạn cần khôi phục đầy đủ, sao lưu cả workspace và thư mục trạng thái riêng biệt (xem câu hỏi di chuyển ở trên).Tài liệu: Agent workspace.
Xem hướng dẫn chuyên dụng: Uninstall.
Có. Workspace là cwd mặc định và điểm neo bộ nhớ, không phải là một sandbox cứng. Các đường dẫn tương đối giải quyết bên trong workspace, nhưng các đường dẫn tuyệt đối có thể truy cập các vị trí host khác trừ khi sandboxing được bật. Nếu bạn cần cách ly, sử dụng agents.defaults.sandbox hoặc cài đặt sandbox per-agent. Nếu bạn muốn một repo là thư mục làm việc mặc định, chỉ định workspace của agent đó đến gốc repo. Repo OpenClaw chỉ là mã nguồn; giữ workspace riêng biệt trừ khi bạn cố ý muốn agent làm việc bên trong nó.Ví dụ (repo làm cwd mặc định):
{
  agents: {
    defaults: {
      workspace: "~/Projects/my-repo",
    },
  },
}
Trạng thái phiên thuộc về gateway host. Nếu bạn đang ở chế độ từ xa, kho lưu trữ phiên mà bạn quan tâm nằm trên máy từ xa, không phải máy tính xách tay cục bộ của bạn. Xem Session management.

​
Cấu hình cơ bản

OpenClaw đọc một cấu hình JSON5 tùy chọn từ $OPENCLAW_CONFIG_PATH (mặc định: ~/.openclaw/openclaw.json):
$OPENCLAW_CONFIG_PATH
Nếu tệp bị thiếu, nó sử dụng các giá trị mặc định an toàn (bao gồm một workspace mặc định là ~/.openclaw/workspace).
Các bind không phải loopback yêu cầu xác thực. Cấu hình gateway.auth.mode + gateway.auth.token (hoặc sử dụng OPENCLAW_GATEWAY_TOKEN).
{
  gateway: {
    bind: "lan",
    auth: {
      mode: "token",
      token: "replace-me",
    },
  },
}
Ghi chú:
  • gateway.remote.token / .password không kích hoạt xác thực gateway cục bộ một mình.
  • Các đường dẫn cuộc gọi cục bộ có thể sử dụng gateway.remote.* làm fallback chỉ khi gateway.auth.* không được đặt.
  • Nếu gateway.auth.token / gateway.auth.password được cấu hình rõ ràng qua SecretRef và không được giải quyết, việc giải quyết sẽ thất bại (không có fallback từ xa che giấu).
  • Giao diện người dùng điều khiển xác thực qua connect.params.auth.token (lưu trữ trong cài đặt app/UI). Tránh đặt token trong URL.
OpenClaw thực thi xác thực token theo mặc định, bao gồm cả loopback. Nếu không có token nào được cấu hình, khởi động gateway sẽ tự động tạo một token và lưu nó vào gateway.auth.token, vì vậy các client WS cục bộ phải xác thực. Điều này ngăn chặn các quy trình cục bộ khác gọi Gateway.Nếu bạn thực sự muốn mở loopback, đặt gateway.auth.mode: "none" rõ ràng trong cấu hình của bạn. Doctor có thể tạo một token cho bạn bất cứ lúc nào: openclaw doctor --generate-gateway-token.
Gateway theo dõi cấu hình và hỗ trợ tải lại nóng:
  • gateway.reload.mode: "hybrid" (mặc định): áp dụng nóng các thay đổi an toàn, khởi động lại cho những thay đổi quan trọng
  • hot, restart, off cũng được hỗ trợ
Đặt cli.banner.taglineMode trong cấu hình:
{
  cli: {
    banner: {
      taglineMode: "off", // random | default | off
    },
  },
}
  • off: ẩn văn bản tagline nhưng giữ lại dòng tiêu đề/phiên bản banner.
  • default: sử dụng All your chats, one OpenClaw. mỗi lần.
  • random: xoay vòng các tagline hài hước/theo mùa (hành vi mặc định).
  • Nếu bạn không muốn banner nào cả, đặt env OPENCLAW_HIDE_BANNER=1.
web_fetch hoạt động mà không cần khóa API. web_search yêu cầu một khóa cho nhà cung cấp bạn chọn (Brave, Gemini, Grok, Kimi, hoặc Perplexity). Khuyến nghị: chạy openclaw configure --section web và chọn một nhà cung cấp. Các lựa chọn thay thế môi trường:
  • Brave: BRAVE_API_KEY
  • Gemini: GEMINI_API_KEY
  • Grok: XAI_API_KEY
  • Kimi: KIMI_API_KEY hoặc MOONSHOT_API_KEY
  • Perplexity: PERPLEXITY_API_KEY hoặc OPENROUTER_API_KEY
{
  plugins: {
    entries: {
      brave: {
        config: {
          webSearch: {
            apiKey: "BRAVE_API_KEY_HERE",
          },
        },
      },
    },
  },
  tools: {
    web: {
      search: {
        enabled: true,
        provider: "brave",
        maxResults: 5,
      },
      fetch: {
        enabled: true,
      },
    },
  },
}
Cấu hình tìm kiếm web cụ thể cho nhà cung cấp hiện sống dưới plugins.entries.<plugin>.config.webSearch.*. Các đường dẫn nhà cung cấp tools.web.search.* cũ vẫn tải tạm thời để tương thích, nhưng không nên sử dụng cho các cấu hình mới.Ghi chú:
  • Nếu bạn sử dụng danh sách cho phép, thêm web_search/web_fetch hoặc group:web.
  • web_fetch được bật theo mặc định (trừ khi bị tắt rõ ràng).
  • Daemons đọc các biến môi trường từ ~/.openclaw/.env (hoặc môi trường dịch vụ).
Tài liệu: Web tools.
config.apply thay thế toàn bộ cấu hình. Nếu bạn gửi một đối tượng không đầy đủ, mọi thứ khác sẽ bị xóa.Khôi phục:
  • Khôi phục từ bản sao lưu (git hoặc một bản sao ~/.openclaw/openclaw.json).
  • Nếu bạn không có bản sao lưu, chạy lại openclaw doctor và cấu hình lại các kênh/mô hình.
  • Nếu điều này không mong đợi, gửi một lỗi và bao gồm cấu hình cuối cùng bạn biết hoặc bất kỳ bản sao lưu nào.
  • Một agent mã hóa cục bộ thường có thể tái tạo một cấu hình hoạt động từ nhật ký hoặc lịch sử.
Tránh nó:
  • Sử dụng openclaw config set cho các thay đổi nhỏ.
  • Sử dụng openclaw configure cho các chỉnh sửa tương tác.
Tài liệu: Config, Configure, Doctor.
Mẫu phổ biến là một Gateway (ví dụ Raspberry Pi) cộng với nodes và agents:
  • Gateway (trung tâm): sở hữu các kênh (Signal/WhatsApp), định tuyến, và các phiên.
  • Nodes (thiết bị): Macs/iOS/Android kết nối như các thiết bị ngoại vi và cung cấp các công cụ cục bộ (system.run, canvas, camera).
  • Agents (worker): các bộ não/workspace riêng biệt cho các vai trò đặc biệt (ví dụ “Hetzner ops”, “Dữ liệu cá nhân”).
  • Sub-agents: tạo công việc nền từ một agent chính khi bạn muốn song song.
  • TUI: kết nối với Gateway và chuyển đổi agents/sessions.
Tài liệu: Nodes, Remote access, Multi-Agent Routing, Sub-agents, TUI.
Có. Đó là một tùy chọn cấu hình:
{
  browser: { headless: true },
  agents: {
    defaults: {
      sandbox: { browser: { headless: true } },
    },
  },
}
Mặc định là false (headful). Headless có khả năng kích hoạt các kiểm tra chống bot trên một số trang web. Xem Browser.Headless sử dụng cùng một engine Chromium và hoạt động cho hầu hết các tự động hóa (forms, clicks, scraping, logins). Sự khác biệt chính:
  • Không có cửa sổ trình duyệt hiển thị (sử dụng ảnh chụp màn hình nếu bạn cần hình ảnh).
  • Một số trang web nghiêm ngặt hơn về tự động hóa trong chế độ headless (CAPTCHAs, chống bot). Ví dụ, X/Twitter thường chặn các phiên headless.
Đặt browser.executablePath đến binary Brave của bạn (hoặc bất kỳ trình duyệt dựa trên Chromium nào) và khởi động lại Gateway. Xem các ví dụ cấu hình đầy đủ trong Browser.

​
Remote gateways và nodes

Tin nhắn Telegram được xử lý bởi gateway. Gateway chạy agent và chỉ sau đó gọi nodes qua Gateway WebSocket khi cần một công cụ node:Telegram → Gateway → Agent → node.* → Node → Gateway → TelegramNodes không thấy lưu lượng nhà cung cấp đầu vào; chúng chỉ nhận các cuộc gọi RPC node.
Câu trả lời ngắn: ghép nối máy tính của bạn như một node. Gateway chạy ở nơi khác, nhưng nó có thể gọi các công cụ node.* (màn hình, camera, hệ thống) trên máy cục bộ của bạn qua Gateway WebSocket.Thiết lập điển hình:
  1. Chạy Gateway trên host luôn bật (VPS/home server).
  2. Đặt Gateway host + máy tính của bạn trên cùng một tailnet.
  3. Đảm bảo Gateway WS có thể truy cập (tailnet bind hoặc SSH tunnel).
  4. Mở ứng dụng macOS cục bộ và kết nối ở chế độ Remote over SSH (hoặc tailnet trực tiếp) để nó có thể đăng ký như một node.
  5. Phê duyệt node trên Gateway: 
    openclaw devices list
openclaw devices approve <requestId>
Không cần cầu TCP riêng biệt; nodes kết nối qua Gateway WebSocket.Nhắc nhở bảo mật: ghép nối một node macOS cho phép system.run trên máy đó. Chỉ ghép nối các thiết bị bạn tin tưởng, và xem xét Security.Tài liệu: Nodes, Gateway protocol, macOS remote mode, Security.
Kiểm tra những điều cơ bản:
  • Gateway đang chạy: openclaw gateway status
  • Sức khỏe Gateway: openclaw status
  • Sức khỏe kênh: openclaw channels status
Sau đó xác minh xác thực và định tuyến:
  • Nếu bạn sử dụng Tailscale Serve, đảm bảo gateway.auth.allowTailscale được đặt đúng.
  • Nếu bạn kết nối qua SSH tunnel, xác nhận tunnel cục bộ đang hoạt động và trỏ đến cổng đúng.
  • Xác nhận danh sách cho phép của bạn (DM hoặc nhóm) bao gồm tài khoản của bạn.
Tài liệu: Tailscale, Remote access, Channels.
Có. Không có cầu nối “bot-to-bot” tích hợp, nhưng bạn có thể kết nối nó theo một vài cách đáng tin cậy:Đơn giản nhất: sử dụng một kênh chat thông thường mà cả hai bot có thể truy cập (Telegram/Slack/WhatsApp). Để Bot A gửi một tin nhắn đến Bot B, sau đó để Bot B trả lời như bình thường.Cầu nối CLI (tổng quát): chạy một script gọi Gateway khác với openclaw agent --message ... --deliver, nhắm mục tiêu vào một chat nơi bot khác lắng nghe. Nếu một bot nằm trên VPS từ xa, trỏ CLI của bạn vào Gateway từ xa đó qua SSH/Tailscale (xem Remote access).Mẫu ví dụ (chạy từ một máy có thể truy cập Gateway mục tiêu):
openclaw agent --message "Hello from local bot" --deliver --channel telegram --reply-to <chat-id>
Mẹo: thêm một rào chắn để hai bot không lặp lại vô tận (chỉ đề cập, danh sách cho phép kênh, hoặc một quy tắc “không trả lời tin nhắn bot”).Tài liệu: Remote access, Agent CLI, Agent send.
Không. Một Gateway có thể lưu trữ nhiều agent, mỗi agent có workspace riêng, mô hình mặc định, và định tuyến. Đó là thiết lập bình thường và nó rẻ hơn và đơn giản hơn nhiều so với việc chạy một VPS cho mỗi agent.Chỉ sử dụng các VPS riêng biệt khi bạn cần cách ly cứng (ranh giới bảo mật) hoặc rất các cấu hình khác nhau mà bạn không muốn chia sẻ. Nếu không, giữ một Gateway và sử dụng nhiều agent hoặc sub-agents.
Có - nodes là cách chính để truy cập máy tính xách tay của bạn từ một Gateway từ xa, và chúng mở khóa nhiều hơn là truy cập shell. Gateway chạy trên macOS/Linux (Windows qua WSL2) và là nhẹ (một VPS nhỏ hoặc hộp Raspberry Pi-class là đủ; 4 GB RAM là đủ), vì vậy một thiết lập phổ biến là một host luôn bật cộng với máy tính xách tay của bạn như một node.
  • Không cần SSH inbound. Nodes kết nối ra ngoài đến Gateway WebSocket và sử dụng ghép nối thiết bị.
  • Kiểm soát thực thi an toàn hơn. system.run được kiểm soát bởi danh sách cho phép/phê duyệt node trên máy tính xách tay đó.
  • Nhiều công cụ thiết bị hơn. Nodes cung cấp canvas, camera, và screen ngoài system.run.
  • Tự động hóa trình duyệt cục bộ. Giữ Gateway trên VPS, nhưng chạy Chrome cục bộ qua một node host trên máy tính xách tay, hoặc kết nối với Chrome cục bộ trên host qua Chrome MCP.
SSH là tốt cho truy cập shell ad-hoc, nhưng nodes đơn giản hơn cho các quy trình làm việc agent liên tục và tự động hóa thiết bị.Tài liệu: Nodes, Nodes CLI, Browser.
Không. Chỉ một gateway nên chạy trên mỗi host trừ khi bạn cố ý chạy các hồ sơ cách ly (xem Multiple gateways). Nodes là các thiết bị ngoại vi kết nối với gateway (iOS/Android nodes, hoặc chế độ “node mode” trên macOS trong ứng dụng menubar). Đối với các node host headless và điều khiển CLI, xem Node host CLI.Một khởi động lại đầy đủ là cần thiết cho các thay đổi gateway, discovery, và canvasHost.
Có. config.apply xác thực + ghi cấu hình đầy đủ và khởi động lại Gateway như một phần của hoạt động.
{
  agents: { defaults: { workspace: "~/.openclaw/workspace" } },
  channels: { whatsapp: { allowFrom: ["+15555550123"] } },
}
Điều này thiết lập workspace của bạn và hạn chế ai có thể kích hoạt bot.
Các bước tối thiểu:
  1. Cài đặt + đăng nhập trên VPS 
    curl -fsSL https://tailscale.com/install.sh | sh
sudo tailscale up
  2. Cài đặt + đăng nhập trên Mac của bạn
    • Sử dụng ứng dụng Tailscale và đăng nhập vào cùng một tailnet.
  3. Kích hoạt MagicDNS (khuyến nghị)
    • Trong bảng điều khiển quản trị Tailscale, kích hoạt MagicDNS để VPS có một tên ổn định.
  4. Sử dụng hostname tailnet
    • SSH: ssh user@your-vps.tailnet-xxxx.ts.net
    • Gateway WS: ws://your-vps.tailnet-xxxx.ts.net:18789
Nếu bạn muốn giao diện người dùng điều khiển mà không cần SSH, sử dụng Tailscale Serve trên VPS:
openclaw gateway --tailscale serve
Điều này giữ gateway được ràng buộc với loopback và cung cấp HTTPS qua Tailscale. Xem Tailscale.
Serve cung cấp Gateway Control UI + WS. Nodes kết nối qua cùng một điểm cuối Gateway WS.Thiết lập khuyến nghị:
  1. Đảm bảo VPS + Mac nằm trên cùng một tailnet.
  2. Sử dụng ứng dụng macOS ở chế độ Remote (mục tiêu SSH có thể là hostname tailnet). Ứng dụng sẽ tạo đường hầm cổng Gateway và kết nối như một node.
  3. Phê duyệt node trên gateway: 
    openclaw devices list
openclaw devices approve <requestId>
Tài liệu: Gateway protocol, Discovery, macOS remote mode.
Nếu bạn chỉ cần công cụ cục bộ (màn hình/camera/exec) trên máy tính xách tay thứ hai, hãy thêm nó như một node. Điều đó giữ một Gateway duy nhất và tránh cấu hình trùng lặp. Các công cụ node cục bộ hiện chỉ có trên macOS, nhưng chúng tôi dự định mở rộng chúng sang các hệ điều hành khác.Chỉ cài đặt một Gateway thứ hai khi bạn cần cách ly cứng hoặc hai bot hoàn toàn riêng biệt.Tài liệu: Nodes, Nodes CLI, Multiple gateways.

​
Env vars và tải .env

OpenClaw đọc các biến môi trường từ quy trình cha (shell, launchd/systemd, CI, v.v.) và bổ sung tải:
  • .env từ thư mục làm việc hiện tại
  • một .env dự phòng toàn cầu từ ~/.openclaw/.env (hay $OPENCLAW_STATE_DIR/.env)
Không có tệp .env nào ghi đè các biến môi trường hiện có.Bạn cũng có thể định nghĩa các biến môi trường nội tuyến trong cấu hình (chỉ áp dụng nếu thiếu trong môi trường quy trình):
{
  env: {
    OPENROUTER_API_KEY: "sk-or-...",
    vars: { GROQ_API_KEY: "gsk-..." },
  },
}
Xem /environment để biết đầy đủ thứ tự ưu tiên và nguồn.
Hai cách khắc phục phổ biến:
  1. Đặt các khóa bị thiếu trong ~/.openclaw/.env để chúng được chọn ngay cả khi dịch vụ không kế thừa môi trường shell của bạn.
  2. Kích hoạt nhập shell (tiện lợi opt-in):
{
  env: {
    shellEnv: {
      enabled: true,
      timeoutMs: 15000,
    },
  },
}
Điều này chạy shell đăng nhập của bạn và chỉ nhập các khóa mong đợi bị thiếu (không bao giờ ghi đè). Các biến môi trường tương đương: OPENCLAW_LOAD_SHELL_ENV=1, OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000.
openclaw models status báo cáo liệu nhập shell env có được bật không. “Shell env: off” không có nghĩa là các biến môi trường của bạn bị thiếu - nó chỉ có nghĩa là OpenClaw sẽ không tải shell đăng nhập của bạn tự động.Nếu Gateway chạy như một dịch vụ (launchd/systemd), nó sẽ không kế thừa môi trường shell của bạn. Khắc phục bằng cách làm một trong những điều này:
  1. Đặt token trong ~/.openclaw/.env: 
    COPILOT_GITHUB_TOKEN=...
  2. Hoặc kích hoạt nhập shell (env.shellEnv.enabled: true).
  3. Hoặc thêm nó vào khối cấu hình env của bạn (chỉ áp dụng nếu thiếu).
Sau đó khởi động lại gateway và kiểm tra lại:
openclaw models status
Các token Copilot được đọc từ COPILOT_GITHUB_TOKEN (cũng GH_TOKEN / GITHUB_TOKEN). Xem /concepts/model-providers và /environment.

​
Phiên làm việc và nhiều cuộc trò chuyện

Gửi /new hoặc /reset như một tin nhắn độc lập. Xem thêm Quản lý phiên làm việc.
Có. Phiên làm việc sẽ hết hạn sau session.idleMinutes (mặc định là 60). Tin nhắn tiếp theo sẽ bắt đầu một ID phiên mới cho khóa trò chuyện đó. Điều này không xóa các bản ghi - chỉ bắt đầu một phiên mới.
{
  session: {
    idleMinutes: 240,
  },
}
Có, thông qua định tuyến đa tác nhân và tác nhân phụ. Bạn có thể tạo một tác nhân điều phối và nhiều tác nhân làm việc với không gian làm việc và mô hình riêng của họ.Tuy nhiên, đây nên được xem như một thí nghiệm thú vị. Nó tiêu tốn nhiều token và thường kém hiệu quả hơn so với việc sử dụng một bot với các phiên riêng biệt. Mô hình điển hình mà chúng tôi hình dung là một bot bạn nói chuyện với, với các phiên khác nhau cho công việc song song. Bot đó cũng có thể tạo ra các tác nhân phụ khi cần.Tài liệu: Định tuyến đa tác nhân, Tác nhân phụ, Agents CLI.
Ngữ cảnh phiên làm việc bị giới hạn bởi cửa sổ mô hình. Các cuộc trò chuyện dài, đầu ra công cụ lớn, hoặc nhiều tệp có thể kích hoạt việc nén hoặc cắt bớt.Những gì có thể giúp:
  • Yêu cầu bot tóm tắt trạng thái hiện tại và ghi vào một tệp.
  • Sử dụng /compact trước các nhiệm vụ dài, và /new khi chuyển chủ đề.
  • Giữ ngữ cảnh quan trọng trong không gian làm việc và yêu cầu bot đọc lại.
  • Sử dụng tác nhân phụ cho công việc dài hoặc song song để cuộc trò chuyện chính nhỏ hơn.
  • Chọn mô hình có cửa sổ ngữ cảnh lớn hơn nếu điều này xảy ra thường xuyên.
Sử dụng lệnh đặt lại:
openclaw reset
Đặt lại hoàn toàn không tương tác:
openclaw reset --scope full --yes --non-interactive
Sau đó chạy lại cài đặt:
openclaw onboard --install-daemon
Ghi chú:
  • Quá trình onboard cũng cung cấp Đặt lại nếu phát hiện cấu hình hiện có. Xem Onboarding (CLI).
  • Nếu bạn đã sử dụng các hồ sơ (--profile / OPENCLAW_PROFILE), đặt lại từng thư mục trạng thái (mặc định là ~/.openclaw-<profile>).
  • Đặt lại cho nhà phát triển: openclaw gateway --dev --reset (chỉ dành cho dev; xóa cấu hình dev + thông tin xác thực + phiên + không gian làm việc).
Sử dụng một trong những cách sau:
  • Nén (giữ cuộc trò chuyện nhưng tóm tắt các lượt cũ hơn): 
    /compact
    hoặc /compact <instructions> để hướng dẫn tóm tắt.
  • Đặt lại (ID phiên mới cho cùng khóa trò chuyện): 
    /new
/reset
Nếu điều này tiếp tục xảy ra:
  • Bật hoặc điều chỉnh cắt tỉa phiên (agents.defaults.contextPruning) để cắt bớt đầu ra công cụ cũ.
  • Sử dụng mô hình có cửa sổ ngữ cảnh lớn hơn.
Tài liệu: Nén, Cắt tỉa phiên, Quản lý phiên.
Đây là lỗi xác thực của nhà cung cấp: mô hình đã phát ra một khối tool_use mà không có input cần thiết. Thường có nghĩa là lịch sử phiên đã cũ hoặc bị hỏng (thường sau các chuỗi dài hoặc thay đổi công cụ/lược đồ).Khắc phục: bắt đầu một phiên mới với /new (tin nhắn độc lập).
Heartbeat chạy mỗi 30 phút theo mặc định. Điều chỉnh hoặc vô hiệu hóa chúng:
{
  agents: {
    defaults: {
      heartbeat: {
        every: "2h", // hoặc "0m" để vô hiệu hóa
      },
    },
  },
}
Nếu HEARTBEAT.md tồn tại nhưng thực tế trống (chỉ có dòng trống và tiêu đề markdown như # Heading), OpenClaw bỏ qua việc chạy heartbeat để tiết kiệm cuộc gọi API. Nếu tệp bị thiếu, heartbeat vẫn chạy và mô hình quyết định phải làm gì.Ghi đè theo tác nhân sử dụng agents.list[].heartbeat. Tài liệu: Heartbeat.
Không. OpenClaw chạy trên tài khoản của bạn, vì vậy nếu bạn có trong nhóm, OpenClaw có thể thấy nó. Theo mặc định, các phản hồi nhóm bị chặn cho đến khi bạn cho phép người gửi (groupPolicy: "allowlist").Nếu bạn chỉ muốn bạn có thể kích hoạt phản hồi nhóm:
{
  channels: {
    whatsapp: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15551234567"],
    },
  },
}
Lựa chọn 1 (nhanh nhất): theo dõi log và gửi một tin nhắn thử nghiệm trong nhóm:
openclaw logs --follow --json
Tìm chatId (hoặc from) kết thúc bằng @g.us, như: 1234567890-1234567890@g.us.Lựa chọn 2 (nếu đã được cấu hình/cho phép): liệt kê các nhóm từ cấu hình:
openclaw directory groups list --channel whatsapp
Tài liệu: WhatsApp, Directory, Logs.
Hai nguyên nhân phổ biến:
  • Chế độ chặn đề cập đang bật (mặc định). Bạn phải @mention bot (hoặc khớp với mentionPatterns).
  • Bạn đã cấu hình channels.whatsapp.groups mà không có "*" và nhóm không được cho phép.
Xem Groups và Group messages.
Các cuộc trò chuyện trực tiếp sụp đổ về phiên chính theo mặc định. Các nhóm/kênh có khóa phiên riêng của họ, và các chủ đề Telegram / luồng Discord là các phiên riêng biệt. Xem Groups và Group messages.
Không có giới hạn cứng. Hàng chục (thậm chí hàng trăm) là ổn, nhưng hãy chú ý:
  • Tăng trưởng đĩa: các phiên + bản ghi sống dưới ~/.openclaw/agents/<agentId>/sessions/.
  • Chi phí token: nhiều tác nhân có nghĩa là sử dụng mô hình đồng thời nhiều hơn.
  • Chi phí vận hành: hồ sơ xác thực, không gian làm việc và định tuyến kênh cho mỗi tác nhân.
Mẹo:
  • Giữ một không gian làm việc hoạt động cho mỗi tác nhân (agents.defaults.workspace).
  • Cắt tỉa các phiên cũ (xóa JSONL hoặc lưu trữ các mục) nếu đĩa tăng trưởng.
  • Sử dụng openclaw doctor để phát hiện các không gian làm việc lạc và không khớp hồ sơ.
Có. Sử dụng Định tuyến Đa Tác Nhân để chạy nhiều tác nhân cô lập và định tuyến tin nhắn đến theo kênh/tài khoản/người gửi. Slack được hỗ trợ như một kênh và có thể được gắn với các tác nhân cụ thể.Truy cập trình duyệt mạnh mẽ nhưng không phải “làm bất cứ điều gì một con người có thể” - chống bot, CAPTCHA, và MFA vẫn có thể chặn tự động hóa. Để kiểm soát trình duyệt đáng tin cậy nhất, sử dụng Chrome MCP cục bộ trên máy chủ, hoặc sử dụng CDP trên máy thực sự chạy trình duyệt.Thiết lập tốt nhất:
  • Máy chủ Gateway luôn bật (VPS/Mac mini).
  • Một tác nhân cho mỗi vai trò (ràng buộc).
  • Kênh Slack được gắn với các tác nhân đó.
  • Trình duyệt cục bộ qua Chrome MCP hoặc một node khi cần.
Tài liệu: Định tuyến Đa Tác Nhân, Slack, Trình duyệt, Nodes.

​
Mô hình: mặc định, lựa chọn, bí danh, chuyển đổi

Mô hình mặc định của OpenClaw là bất kỳ mô hình nào bạn đã đặt:
agents.defaults.model.primary
Các mô hình được tham chiếu dưới dạng provider/model (ví dụ: anthropic/claude-opus-4-6). Nếu bạn bỏ qua nhà cung cấp, OpenClaw hiện tại giả định anthropic như một biện pháp tạm thời - nhưng bạn vẫn nên rõ ràng đặt provider/model.
Mặc định đề xuất: sử dụng mô hình thế hệ mới mạnh nhất có sẵn trong ngăn xếp nhà cung cấp của bạn. Đối với các tác nhân có công cụ hoặc đầu vào không đáng tin cậy: ưu tiên sức mạnh mô hình hơn chi phí. Đối với trò chuyện thường xuyên/ít rủi ro: sử dụng các mô hình dự phòng rẻ hơn và định tuyến theo vai trò tác nhân.MiniMax có tài liệu riêng: MiniMax và Mô hình cục bộ.Quy tắc chung: sử dụng mô hình tốt nhất bạn có thể chi trả cho công việc quan trọng, và một mô hình rẻ hơn cho trò chuyện thường xuyên hoặc tóm tắt. Bạn có thể định tuyến mô hình theo tác nhân và sử dụng tác nhân phụ để song song hóa các nhiệm vụ dài (mỗi tác nhân phụ tiêu thụ token). Xem Mô hình và Tác nhân phụ.Cảnh báo mạnh: các mô hình yếu hơn/quá lượng hóa dễ bị tấn công chèn lệnh và hành vi không an toàn hơn. Xem Bảo mật.Thêm ngữ cảnh: Mô hình.
Sử dụng lệnh mô hình hoặc chỉ chỉnh sửa các trường mô hình. Tránh thay thế cấu hình hoàn toàn.Các tùy chọn an toàn:
  • /model trong trò chuyện (nhanh, theo phiên)
  • openclaw models set ... (cập nhật chỉ cấu hình mô hình)
  • openclaw configure --section model (tương tác)
  • chỉnh sửa agents.defaults.model trong ~/.openclaw/openclaw.json
Tránh config.apply với một đối tượng một phần trừ khi bạn định thay thế toàn bộ cấu hình. Nếu bạn đã ghi đè cấu hình, khôi phục từ bản sao lưu hoặc chạy lại openclaw doctor để sửa chữa.Tài liệu: Mô hình, Cấu hình, Config, Doctor.
Có. Ollama là con đường dễ nhất cho các mô hình cục bộ.Thiết lập nhanh nhất:
  1. Cài đặt Ollama từ https://ollama.com/download
  2. Kéo một mô hình cục bộ như ollama pull glm-4.7-flash
  3. Nếu bạn muốn Ollama Cloud, chạy ollama signin
  4. Chạy openclaw onboard và chọn Ollama
  5. Chọn Local hoặc Cloud + Local
Ghi chú:
  • Cloud + Local cung cấp cho bạn các mô hình Ollama Cloud cộng với các mô hình Ollama cục bộ của bạn
  • các mô hình đám mây như kimi-k2.5:cloud không cần kéo cục bộ
  • để chuyển đổi thủ công, sử dụng openclaw models list và openclaw models set ollama/<model>
Ghi chú bảo mật: các mô hình nhỏ hơn hoặc quá lượng hóa dễ bị tấn công chèn lệnh. Chúng tôi khuyến nghị mạnh mẽ các mô hình lớn cho bất kỳ bot nào có thể sử dụng công cụ. Nếu bạn vẫn muốn các mô hình nhỏ, hãy bật sandboxing và danh sách cho phép công cụ nghiêm ngặt.Tài liệu: Ollama, Mô hình cục bộ, Nhà cung cấp mô hình, Bảo mật, Sandboxing.
  • Các triển khai này có thể khác nhau và có thể thay đổi theo thời gian; không có khuyến nghị nhà cung cấp cố định.
  • Kiểm tra cài đặt runtime hiện tại trên mỗi gateway với openclaw models status.
  • Đối với các tác nhân nhạy cảm với bảo mật/có công cụ, sử dụng mô hình thế hệ mới mạnh nhất có sẵn.
Sử dụng lệnh /model như một tin nhắn độc lập:
/model sonnet
/model haiku
/model opus
/model gpt
/model gpt-mini
/model gemini
/model gemini-flash
Bạn có thể liệt kê các mô hình có sẵn với /model, /model list, hoặc /model status./model (và /model list) hiển thị một danh sách chọn số gọn. Chọn theo số:
/model 3
Bạn cũng có thể buộc một hồ sơ xác thực cụ thể cho nhà cung cấp (theo phiên):
/model opus@anthropic:default
/model opus@anthropic:work
Mẹo: /model status hiển thị tác nhân nào đang hoạt động, tệp auth-profiles.json nào đang được sử dụng, và hồ sơ xác thực nào sẽ được thử tiếp theo. Nó cũng hiển thị điểm cuối nhà cung cấp được cấu hình (baseUrl) và chế độ API (api) khi có sẵn.Làm thế nào để tôi bỏ ghim một hồ sơ tôi đã đặt với @profile?Chạy lại /model mà không có hậu tố @profile:
/model anthropic/claude-opus-4-6
Nếu bạn muốn quay lại mặc định, chọn nó từ /model (hoặc gửi /model <default provider/model>). Sử dụng /model status để xác nhận hồ sơ xác thực nào đang hoạt động.
Có. Đặt một cái làm mặc định và chuyển đổi khi cần:
  • Chuyển đổi nhanh (theo phiên): /model gpt-5.2 cho công việc hàng ngày, /model openai-codex/gpt-5.4 cho lập trình với Codex OAuth.
  • Mặc định + chuyển đổi: đặt agents.defaults.model.primary thành openai/gpt-5.2, sau đó chuyển sang openai-codex/gpt-5.4 khi lập trình (hoặc ngược lại).
  • Tác nhân phụ: định tuyến các nhiệm vụ lập trình đến các tác nhân phụ với mô hình mặc định khác.
Xem Mô hình và Lệnh gạch chéo.
Nếu agents.defaults.models được đặt, nó trở thành danh sách cho phép cho /model và bất kỳ ghi đè phiên nào. Chọn một mô hình không có trong danh sách đó sẽ trả về:
Model "provider/model" is not allowed. Use /model to list available models.
Lỗi đó được trả về thay vì một phản hồi bình thường. Khắc phục: thêm mô hình vào agents.defaults.models, xóa danh sách cho phép, hoặc chọn một mô hình từ /model list.
Điều này có nghĩa là nhà cung cấp chưa được cấu hình (không tìm thấy cấu hình nhà cung cấp MiniMax hoặc hồ sơ xác thực), vì vậy mô hình không thể được giải quyết. Một bản sửa lỗi cho phát hiện này sẽ có trong 2026.1.12 (chưa phát hành tại thời điểm viết).Danh sách kiểm tra sửa lỗi:
  1. Nâng cấp lên 2026.1.12 (hoặc chạy từ nguồn main), sau đó khởi động lại gateway.
  2. Đảm bảo MiniMax được cấu hình (wizard hoặc JSON), hoặc rằng một khóa API MiniMax tồn tại trong hồ sơ môi trường/xác thực để nhà cung cấp có thể được tiêm.
  3. Sử dụng ID mô hình chính xác (phân biệt chữ hoa chữ thường): minimax/MiniMax-M2.7, minimax/MiniMax-M2.7-highspeed, minimax/MiniMax-M2.5, hoặc minimax/MiniMax-M2.5-highspeed.
  4. Chạy: 
    openclaw models list
    và chọn từ danh sách (hoặc /model list trong trò chuyện).
Xem MiniMax và Mô hình.
Có. Sử dụng MiniMax làm mặc định và chuyển đổi mô hình theo phiên khi cần. Dự phòng là cho lỗi, không phải “nhiệm vụ khó”, vì vậy sử dụng /model hoặc một tác nhân riêng biệt.Lựa chọn A: chuyển đổi theo phiên
{
  env: { MINIMAX_API_KEY: "sk-...", OPENAI_API_KEY: "sk-..." },
  agents: {
    defaults: {
      model: { primary: "minimax/MiniMax-M2.7" },
      models: {
        "minimax/MiniMax-M2.7": { alias: "minimax" },
        "openai/gpt-5.2": { alias: "gpt" },
      },
    },
  },
}
Sau đó:
/model gpt
Lựa chọn B: tác nhân riêng biệt
  • Tác nhân A mặc định: MiniMax
  • Tác nhân B mặc định: OpenAI
  • Định tuyến theo tác nhân hoặc sử dụng /agent để chuyển đổi
Tài liệu: Mô hình, Định tuyến Đa Tác Nhân, MiniMax, OpenAI.
Có. OpenClaw cung cấp một số phím tắt mặc định (chỉ áp dụng khi mô hình tồn tại trong agents.defaults.models):
  • opus → anthropic/claude-opus-4-6
  • sonnet → anthropic/claude-sonnet-4-6
  • gpt → openai/gpt-5.4
  • gpt-mini → openai/gpt-5-mini
  • gemini → google/gemini-3.1-pro-preview
  • gemini-flash → google/gemini-3-flash-preview
  • gemini-flash-lite → google/gemini-3.1-flash-lite-preview
Nếu bạn đặt bí danh của riêng mình với cùng tên, giá trị của bạn sẽ được ưu tiên.
Bí danh đến từ agents.defaults.models.<modelId>.alias. Ví dụ:
{
  agents: {
    defaults: {
      model: { primary: "anthropic/claude-opus-4-6" },
      models: {
        "anthropic/claude-opus-4-6": { alias: "opus" },
        "anthropic/claude-sonnet-4-6": { alias: "sonnet" },
        "anthropic/claude-haiku-4-5": { alias: "haiku" },
      },
    },
  },
}
Sau đó /model sonnet (hoặc /<alias> khi được hỗ trợ) sẽ giải quyết đến ID mô hình đó.
OpenRouter (trả tiền theo token; nhiều mô hình):
{
  agents: {
    defaults: {
      model: { primary: "openrouter/anthropic/claude-sonnet-4-6" },
      models: { "openrouter/anthropic/claude-sonnet-4-6": {} },
    },
  },
  env: { OPENROUTER_API_KEY: "sk-or-..." },
}
Z.AI (mô hình GLM):
{
  agents: {
    defaults: {
      model: { primary: "zai/glm-5" },
      models: { "zai/glm-5": {} },
    },
  },
  env: { ZAI_API_KEY: "..." },
}
Nếu bạn tham chiếu một nhà cung cấp/mô hình nhưng khóa nhà cung cấp cần thiết bị thiếu, bạn sẽ nhận được lỗi xác thực runtime (ví dụ: No API key found for provider "zai").Không tìm thấy khóa API cho nhà cung cấp sau khi thêm một tác nhân mớiĐiều này thường có nghĩa là tác nhân mới có một kho lưu trữ xác thực trống. Xác thực là theo tác nhân và được lưu trữ trong:
~/.openclaw/agents/<agentId>/agent/auth-profiles.json
Các tùy chọn sửa lỗi:
  • Chạy openclaw agents add <id> và cấu hình xác thực trong wizard.
  • Hoặc sao chép auth-profiles.json từ agentDir của tác nhân chính vào agentDir của tác nhân mới.
Không **tái sử dụng agentDir giữa các tác nhân; nó gây ra xung đột xác thực/phiên.

​
Chuyển đổi mô hình và “Tất cả các mô hình đều thất bại”

Chuyển đổi dự phòng diễn ra trong hai giai đoạn:
  1. Xoay vòng hồ sơ xác thực trong cùng một nhà cung cấp.
  2. Dự phòng mô hình sang mô hình tiếp theo trong agents.defaults.model.fallbacks.
Thời gian chờ áp dụng cho các hồ sơ thất bại (backoff theo cấp số nhân), vì vậy OpenClaw có thể tiếp tục phản hồi ngay cả khi một nhà cung cấp bị giới hạn tốc độ hoặc tạm thời thất bại.
Điều này có nghĩa là hệ thống đã cố gắng sử dụng ID hồ sơ xác thực anthropic:default, nhưng không thể tìm thấy thông tin xác thực cho nó trong kho lưu trữ xác thực mong đợi.Danh sách kiểm tra sửa lỗi:
  • Xác nhận nơi lưu trữ hồ sơ xác thực (đường dẫn mới so với đường dẫn cũ)
    • Hiện tại: ~/.openclaw/agents/<agentId>/agent/auth-profiles.json
    • Cũ: ~/.openclaw/agent/* (được di chuyển bởi openclaw doctor)
  • Xác nhận biến môi trường của bạn được tải bởi Gateway
    • Nếu bạn đặt ANTHROPIC_API_KEY trong shell của bạn nhưng chạy Gateway qua systemd/launchd, nó có thể không kế thừa nó. Đặt nó trong ~/.openclaw/.env hoặc bật env.shellEnv.
  • Đảm bảo bạn đang chỉnh sửa tác nhân đúng
    • Các thiết lập đa tác nhân có nghĩa là có thể có nhiều tệp auth-profiles.json.
  • Kiểm tra trạng thái mô hình/xác thực
    • Sử dụng openclaw models status để xem các mô hình đã cấu hình và liệu các nhà cung cấp có được xác thực hay không.
Danh sách kiểm tra sửa lỗi cho “No credentials found for profile anthropic”Điều này có nghĩa là chạy được ghim vào một hồ sơ xác thực Anthropic, nhưng Gateway không thể tìm thấy nó trong kho lưu trữ xác thực của nó.
  • Sử dụng mã thông báo cài đặt
    • Chạy claude setup-token, sau đó dán nó với openclaw models auth setup-token --provider anthropic.
    • Nếu mã thông báo được tạo trên máy khác, sử dụng openclaw models auth paste-token --provider anthropic.
  • Nếu bạn muốn sử dụng khóa API thay thế
    • Đặt ANTHROPIC_API_KEY trong ~/.openclaw/.env trên máy chủ gateway.
    • Xóa bất kỳ thứ tự ghim nào buộc một hồ sơ bị thiếu: 
      openclaw models auth order clear --provider anthropic
  • Xác nhận bạn đang chạy lệnh trên máy chủ gateway
    • Trong chế độ từ xa, hồ sơ xác thực sống trên máy gateway, không phải máy tính xách tay của bạn.
Nếu cấu hình mô hình của bạn bao gồm Google Gemini như một dự phòng (hoặc bạn đã chuyển sang một phím tắt Gemini), OpenClaw sẽ thử nó trong quá trình dự phòng mô hình. Nếu bạn chưa cấu hình thông tin xác thực Google, bạn sẽ thấy No API key found for provider "google".Khắc phục: hoặc cung cấp xác thực Google, hoặc xóa/tránh các mô hình Google trong agents.defaults.model.fallbacks / bí danh để dự phòng không định tuyến đến đó.Yêu cầu LLM bị từ chối: chữ ký suy nghĩ cần thiết (Google Antigravity)Nguyên nhân: lịch sử phiên chứa các khối suy nghĩ không có chữ ký (thường từ một luồng bị hủy/bị cắt). Google Antigravity yêu cầu chữ ký cho các khối suy nghĩ.Khắc phục: OpenClaw hiện loại bỏ các khối suy nghĩ không có chữ ký cho Google Antigravity Claude. Nếu nó vẫn xuất hiện, bắt đầu một phiên mới hoặc đặt /thinking off cho tác nhân đó.

​
Hồ sơ xác thực: chúng là gì và cách quản lý chúng

Liên quan: /concepts/oauth (luồng OAuth, lưu trữ mã thông báo, mẫu nhiều tài khoản)
Hồ sơ xác thực là một bản ghi thông tin xác thực được đặt tên (OAuth hoặc khóa API) gắn liền với một nhà cung cấp. Hồ sơ sống trong:
~/.openclaw/agents/<agentId>/agent/auth-profiles.json
OpenClaw sử dụng các ID có tiền tố nhà cung cấp như:
  • anthropic:default (phổ biến khi không có danh tính email)
  • anthropic:<email> cho danh tính OAuth
  • ID tùy chỉnh bạn chọn (ví dụ: anthropic:work)
Có. Cấu hình hỗ trợ siêu dữ liệu tùy chọn cho hồ sơ và một thứ tự theo nhà cung cấp (auth.order.<provider>). Điều này không lưu trữ bí mật; nó ánh xạ ID đến nhà cung cấp/chế độ và đặt thứ tự xoay vòng.OpenClaw có thể tạm thời bỏ qua một hồ sơ nếu nó đang trong một thời gian chờ ngắn (giới hạn tốc độ/thời gian chờ/lỗi xác thực) hoặc một trạng thái bị vô hiệu hóa dài hơn (thanh toán/không đủ tín dụng). Để kiểm tra điều này, chạy openclaw models status --json và kiểm tra auth.unusableProfiles. Điều chỉnh: auth.cooldowns.billingBackoffHours*.Bạn cũng có thể đặt một ghi đè thứ tự theo tác nhân (được lưu trữ trong auth-profiles.json của tác nhân đó) qua CLI:
# Mặc định cho tác nhân mặc định đã cấu hình (bỏ qua --agent)
openclaw models auth order get --provider anthropic

# Khóa xoay vòng vào một hồ sơ duy nhất (chỉ thử cái này)
openclaw models auth order set --provider anthropic anthropic:default

# Hoặc đặt một thứ tự rõ ràng (dự phòng trong nhà cung cấp)
openclaw models auth order set --provider anthropic anthropic:work anthropic:default

# Xóa ghi đè (quay lại cấu hình auth.order / vòng tròn)
openclaw models auth order clear --provider anthropic
Để nhắm mục tiêu một tác nhân cụ thể:
openclaw models auth order set --provider anthropic --agent main anthropic:default
OpenClaw hỗ trợ cả hai:
  • OAuth thường tận dụng quyền truy cập đăng ký (nếu có).
  • Khóa API sử dụng thanh toán theo token.
Wizard hỗ trợ rõ ràng mã thông báo cài đặt Anthropic và OpenAI Codex OAuth và có thể lưu trữ khóa API cho bạn.

​
Gateway: cổng, “đã chạy”, và chế độ từ xa

gateway.port kiểm soát cổng đơn được ghép nối cho WebSocket + HTTP (Giao diện điều khiển, hooks, v.v.).Thứ tự ưu tiên:
--port > OPENCLAW_GATEWAY_PORT > gateway.port > mặc định 18789
Bởi vì “running” là cái nhìn của supervisor (launchd/systemd/schtasks). RPC probe là CLI thực sự kết nối với WebSocket gateway và gọi status.Sử dụng openclaw gateway status và tin tưởng vào các dòng này:
  • Probe target: (URL mà probe thực sự đã sử dụng)
  • Listening: (cái gì thực sự được gắn trên cổng)
  • Last gateway error: (nguyên nhân gốc phổ biến khi quá trình đang sống nhưng cổng không lắng nghe)
Bạn đang chỉnh sửa một tệp cấu hình trong khi dịch vụ đang chạy một tệp khác (thường là không khớp --profile / OPENCLAW_STATE_DIR).Khắc phục:
openclaw gateway install --force
Chạy điều đó từ cùng một --profile / môi trường bạn muốn dịch vụ sử dụng.
OpenClaw thực thi khóa runtime bằng cách gắn ngay lập tức trình nghe WebSocket khi khởi động (mặc định ws://127.0.0.1:18789). Nếu việc gắn thất bại với EADDRINUSE, nó ném GatewayLockError chỉ ra rằng một phiên bản khác đã đang lắng nghe.Khắc phục: dừng phiên bản khác, giải phóng cổng, hoặc chạy với openclaw gateway --port <port>.
Đặt gateway.mode: "remote" và chỉ đến một URL WebSocket từ xa, tùy chọn với một mã thông báo/mật khẩu:
{
  gateway: {
    mode: "remote",
    remote: {
      url: "ws://gateway.tailnet:18789",
      token: "your-token",
      password: "your-password",
    },
  },
}
Ghi chú:
  • openclaw gateway chỉ bắt đầu khi gateway.mode là local (hoặc bạn truyền cờ ghi đè).
  • Ứng dụng macOS theo dõi tệp cấu hình và chuyển đổi chế độ trực tiếp khi các giá trị này thay đổi.
Gateway của bạn đang chạy với xác thực được bật (gateway.auth.*), nhưng UI không gửi mã thông báo/mật khẩu khớp.Thực tế (từ mã):
  • Giao diện điều khiển giữ mã thông báo trong sessionStorage cho phiên tab trình duyệt hiện tại và URL gateway đã chọn, vì vậy làm mới cùng tab vẫn hoạt động mà không cần khôi phục mã thông báo lưu trữ lâu dài.
  • Trên AUTH_TOKEN_MISMATCH, các khách hàng đáng tin cậy có thể thử một lần thử lại có giới hạn với mã thông báo thiết bị đã lưu khi gateway trả về gợi ý thử lại (canRetryWithDeviceToken=true, recommendedNextStep=retry_with_device_token).
Khắc phục:
  • Nhanh nhất: openclaw dashboard (in + sao chép URL bảng điều khiển, cố gắng mở; hiển thị gợi ý SSH nếu không có giao diện).
  • Nếu bạn chưa có mã thông báo: openclaw doctor --generate-gateway-token.
  • Nếu từ xa, trước tiên hãy tạo đường hầm: ssh -N -L 18789:127.0.0.1:18789 user@host sau đó mở http://127.0.0.1:18789/.
  • Đặt gateway.auth.token (hoặc OPENCLAW_GATEWAY_TOKEN) trên máy chủ gateway.
  • Trong cài đặt giao diện điều khiển, dán cùng mã thông báo.
  • Nếu không khớp vẫn tồn tại sau một lần thử lại, xoay vòng/làm mới mã thông báo thiết bị đã ghép đôi:
    • openclaw devices list
    • openclaw devices rotate --device <id> --role operator
  • Vẫn bị kẹt? Chạy openclaw status --all và làm theo Khắc phục sự cố. Xem Dashboard để biết chi tiết xác thực.
tailnet bind chọn một IP Tailscale từ các giao diện mạng của bạn (100.64.0.0/10). Nếu máy không nằm trên Tailscale (hoặc giao diện bị tắt), không có gì để gắn vào.Khắc phục:
  • Khởi động Tailscale trên máy đó (để nó có địa chỉ 100.x), hoặc
  • Chuyển sang gateway.bind: "loopback" / "lan".
Lưu ý: tailnet là rõ ràng. auto ưu tiên loopback; sử dụng gateway.bind: "tailnet" khi bạn muốn một bind chỉ tailnet.
Thường thì không - một Gateway có thể chạy nhiều kênh nhắn tin và tác nhân. Sử dụng nhiều Gateway chỉ khi bạn cần dự phòng (ví dụ: bot cứu hộ) hoặc cách ly cứng.Có, nhưng bạn phải cách ly:
  • OPENCLAW_CONFIG_PATH (cấu hình theo phiên bản)
  • OPENCLAW_STATE_DIR (trạng thái theo phiên bản)
  • agents.defaults.workspace (cách ly không gian làm việc)
  • gateway.port (cổng duy nhất)
Thiết lập nhanh (khuyến nghị):
  • Sử dụng openclaw --profile <name> ... cho mỗi phiên bản (tự động tạo ~/.openclaw-<name>).
  • Đặt một gateway.port duy nhất trong mỗi cấu hình hồ sơ (hoặc truyền --port cho các lần chạy thủ công).
  • Cài đặt một dịch vụ theo hồ sơ: openclaw --profile <name> gateway install.
Hồ sơ cũng thêm hậu tố tên dịch vụ (ai.openclaw.<profile>; cũ com.openclaw.*, openclaw-gateway-<profile>.service, OpenClaw Gateway (<profile>)). Hướng dẫn đầy đủ: Nhiều gateway.
Gateway là một máy chủ WebSocket, và nó mong đợi tin nhắn đầu tiên là một khung connect. Nếu nó nhận được bất cứ điều gì khác, nó đóng kết nối với mã 1008 (vi phạm chính sách).Nguyên nhân phổ biến:
  • Bạn đã mở URL HTTP trong trình duyệt (http://...) thay vì một khách hàng WS.
  • Bạn đã sử dụng sai cổng hoặc đường dẫn.
  • Một proxy hoặc đường hầm đã loại bỏ tiêu đề xác thực hoặc gửi một yêu cầu không phải Gateway.
Sửa nhanh:
  1. Sử dụng URL WS: ws://<host>:18789 (hoặc wss://... nếu HTTPS).
  2. Không mở cổng WS trong một tab trình duyệt thông thường.
  3. Nếu xác thực đang bật, bao gồm mã thông báo/mật khẩu trong khung connect.
Nếu bạn đang sử dụng CLI hoặc TUI, URL nên trông như:
openclaw tui --url ws://<host>:18789 --token <token>
Chi tiết giao thức: Giao thức Gateway.

​
Ghi log và gỡ lỗi

Log tệp (có cấu trúc):
/tmp/openclaw/openclaw-YYYY-MM-DD.log
Bạn có thể đặt một đường dẫn ổn định qua logging.file. Mức độ log tệp được kiểm soát bởi logging.level. Độ chi tiết của console được kiểm soát bởi --verbose và logging.consoleLevel.Theo dõi log nhanh nhất:
openclaw logs --follow
Log dịch vụ/supervisor (khi gateway chạy qua launchd/systemd):
  • macOS: $OPENCLAW_STATE_DIR/logs/gateway.log và gateway.err.log (mặc định: ~/.openclaw/logs/...; hồ sơ sử dụng ~/.openclaw-<profile>/logs/...)
  • Linux: journalctl --user -u openclaw-gateway[-<profile>].service -n 200 --no-pager
  • Windows: schtasks /Query /TN "OpenClaw Gateway (<profile>)" /V /FO LIST
Xem Khắc phục sự cố để biết thêm.
Sử dụng các trợ giúp gateway:
openclaw gateway status
openclaw gateway restart
Nếu bạn chạy gateway thủ công, openclaw gateway --force có thể thu hồi cổng. Xem Gateway.
Có hai chế độ cài đặt Windows:1) WSL2 (khuyến nghị): Gateway chạy bên trong Linux.Mở PowerShell, vào WSL, sau đó khởi động lại:
wsl
openclaw gateway status
openclaw gateway restart
Nếu bạn chưa bao giờ cài đặt dịch vụ, khởi động nó ở chế độ nền:
openclaw gateway run
2) Windows gốc (không khuyến nghị): Gateway chạy trực tiếp trên Windows.Mở PowerShell và chạy:
openclaw gateway status
openclaw gateway restart
Nếu bạn chạy nó thủ công (không có dịch vụ), sử dụng:
openclaw gateway run
Tài liệu: Windows (WSL2), Sổ tay dịch vụ Gateway.
Bắt đầu với một kiểm tra sức khỏe nhanh:
openclaw status
openclaw models status
openclaw channels status
openclaw logs --follow
Nguyên nhân phổ biến:
  • Xác thực mô hình không được tải trên máy chủ gateway (kiểm tra models status).
  • Ghép đôi kênh/danh sách cho phép chặn phản hồi (kiểm tra cấu hình kênh + log).
  • WebChat/Dashboard đang mở mà không có mã thông báo đúng.
Nếu bạn đang từ xa, xác nhận kết nối đường hầm/Tailscale đang hoạt động và WebSocket Gateway có thể truy cập được.Tài liệu: Kênh, Khắc phục sự cố, Truy cập từ xa.
Điều này thường có nghĩa là UI đã mất kết nối WebSocket. Kiểm tra:
  1. Gateway có đang chạy không? openclaw gateway status
  2. Gateway có khỏe không? openclaw status
  3. UI có mã thông báo đúng không? openclaw dashboard
  4. Nếu từ xa, liên kết đường hầm/Tailscale có hoạt động không?
Sau đó theo dõi log:
openclaw logs --follow
Tài liệu: Dashboard, Truy cập từ xa, Khắc phục sự cố.
Bắt đầu với log và trạng thái kênh:
openclaw channels status
openclaw channels logs --channel telegram
Sau đó khớp lỗi:
  • BOT_COMMANDS_TOO_MUCH: menu Telegram có quá nhiều mục. OpenClaw đã cắt giảm đến giới hạn Telegram và thử lại với ít lệnh hơn, nhưng một số mục menu vẫn cần được loại bỏ. Giảm lệnh plugin/kỹ năng/tùy chỉnh, hoặc vô hiệu hóa channels.telegram.commands.native nếu bạn không cần menu.
  • TypeError: fetch failed, Network request for 'setMyCommands' failed!, hoặc lỗi mạng tương tự: nếu bạn đang trên VPS hoặc sau một proxy, xác nhận HTTPS ra ngoài được phép và DNS hoạt động cho api.telegram.org.
Nếu Gateway là từ xa, đảm bảo bạn đang xem log trên máy chủ Gateway.Tài liệu: Telegram, Khắc phục sự cố kênh.
Đầu tiên xác nhận Gateway có thể truy cập và tác nhân có thể chạy:
openclaw status
openclaw models status
openclaw logs --follow
Trong TUI, sử dụng /status để xem trạng thái hiện tại. Nếu bạn mong đợi phản hồi trong một kênh trò chuyện, đảm bảo việc giao hàng được bật (/deliver on).Tài liệu: TUI, Lệnh gạch chéo.
Nếu bạn đã cài đặt dịch vụ:
openclaw gateway stop
openclaw gateway start
Điều này dừng/khởi động dịch vụ giám sát (launchd trên macOS, systemd trên Linux). Sử dụng điều này khi Gateway chạy ở chế độ nền như một daemon.Nếu bạn đang chạy ở chế độ nền, dừng với Ctrl-C, sau đó:
openclaw gateway run
Tài liệu: Sổ tay dịch vụ Gateway.
  • openclaw gateway restart: khởi động lại dịch vụ nền (launchd/systemd).
  • openclaw gateway: chạy gateway ở chế độ nền cho phiên terminal này.
Nếu bạn đã cài đặt dịch vụ, sử dụng các lệnh gateway. Sử dụng openclaw gateway khi bạn muốn một lần chạy nền.
Khởi động Gateway với --verbose để có thêm chi tiết console. Sau đó kiểm tra tệp log để biết xác thực kênh, định tuyến mô hình, và lỗi RPC.

​
Phương tiện và tệp đính kèm

Các tệp đính kèm gửi đi từ tác nhân phải bao gồm một dòng MEDIA:<path-or-url> (trên dòng riêng của nó). Xem Thiết lập trợ lý OpenClaw và Gửi tác nhân.Gửi qua CLI:
openclaw message send --target +15555550123 --message "Here you go" --media /path/to/file.png
Cũng kiểm tra:
  • Kênh mục tiêu hỗ trợ phương tiện gửi đi và không bị chặn bởi danh sách cho phép.
  • Tệp nằm trong giới hạn kích thước của nhà cung cấp (hình ảnh được thay đổi kích thước tối đa 2048px).
Xem Hình ảnh.

​
Bảo mật và kiểm soát truy cập

Hãy coi tin nhắn trực tiếp (DM) như là dữ liệu không đáng tin cậy. Các thiết lập mặc định được thiết kế để giảm thiểu rủi ro:
  • Hành vi mặc định trên các kênh có khả năng DM là pairing:
    • Người gửi không xác định sẽ nhận mã pairing; bot không xử lý tin nhắn của họ.
    • Phê duyệt với: openclaw pairing approve --channel <channel> [--account <id>] <code>
    • Yêu cầu đang chờ xử lý bị giới hạn ở 3 mỗi kênh; kiểm tra openclaw pairing list --channel <channel> [--account <id>] nếu không nhận được mã.
  • Mở DM công khai yêu cầu phải chọn tham gia rõ ràng (dmPolicy: "open" và danh sách cho phép "*").
Chạy openclaw doctor để phát hiện các chính sách DM có rủi ro.
Không. Prompt injection liên quan đến nội dung không đáng tin cậy, không chỉ ai có thể DM bot. Nếu trợ lý của bạn đọc nội dung bên ngoài (tìm kiếm/lấy dữ liệu web, trang trình duyệt, email, tài liệu, tệp đính kèm, nhật ký dán), nội dung đó có thể chứa hướng dẫn cố gắng chiếm quyền điều khiển mô hình. Điều này có thể xảy ra ngay cả khi bạn là người gửi duy nhất.Rủi ro lớn nhất là khi các công cụ được kích hoạt: mô hình có thể bị lừa để lấy cắp ngữ cảnh hoặc gọi công cụ thay bạn. Giảm thiểu rủi ro bằng cách:
  • sử dụng một agent “đọc” chỉ đọc hoặc không có công cụ để tóm tắt nội dung không đáng tin cậy
  • giữ web_search / web_fetch / browser tắt cho các agent có công cụ
  • sử dụng sandbox và danh sách cho phép công cụ nghiêm ngặt
Chi tiết: Bảo mật.
Có, đối với hầu hết các thiết lập. Cách ly bot với các tài khoản và số điện thoại riêng giúp giảm thiểu rủi ro nếu có sự cố xảy ra. Điều này cũng giúp dễ dàng xoay vòng thông tin xác thực hoặc thu hồi quyền truy cập mà không ảnh hưởng đến tài khoản cá nhân của bạn.Bắt đầu nhỏ. Chỉ cấp quyền truy cập vào các công cụ và tài khoản bạn thực sự cần, và mở rộng sau nếu cần thiết.Tài liệu: Bảo mật, Pairing.
Chúng tôi không khuyến nghị cho phép tự động hoàn toàn quản lý tin nhắn cá nhân của bạn. Mô hình an toàn nhất là:
  • Giữ DM ở chế độ pairing hoặc danh sách cho phép chặt chẽ.
  • Sử dụng số hoặc tài khoản riêng nếu bạn muốn nó nhắn tin thay bạn.
  • Để nó soạn thảo, sau đó phê duyệt trước khi gửi.
Nếu bạn muốn thử nghiệm, hãy thực hiện trên một tài khoản riêng biệt và giữ nó cách ly. Xem Bảo mật.
Có, nếu agent chỉ chat và đầu vào là đáng tin cậy. Các mô hình nhỏ hơn dễ bị tấn công chiếm quyền điều khiển, vì vậy tránh sử dụng chúng cho các agent có công cụ hoặc khi đọc nội dung không đáng tin cậy. Nếu bạn phải sử dụng mô hình nhỏ hơn, hãy khóa công cụ và chạy trong sandbox. Xem Bảo mật.
Mã pairing chỉ được gửi khi một người gửi không xác định nhắn tin cho bot và dmPolicy: "pairing" được kích hoạt. /start tự nó không tạo mã.Kiểm tra các yêu cầu đang chờ xử lý:
openclaw pairing list telegram
Nếu bạn muốn truy cập ngay lập tức, hãy thêm id người gửi vào danh sách cho phép hoặc đặt dmPolicy: "open" cho tài khoản đó.
Không. Chính sách DM mặc định của WhatsApp là pairing. Người gửi không xác định chỉ nhận mã pairing và tin nhắn của họ không được xử lý. OpenClaw chỉ trả lời các cuộc trò chuyện mà nó nhận được hoặc các gửi đi rõ ràng mà bạn kích hoạt.Phê duyệt pairing với:
openclaw pairing approve whatsapp <code>
Liệt kê các yêu cầu đang chờ xử lý:
openclaw pairing list whatsapp
Nhắc nhở số điện thoại của wizard: nó được sử dụng để thiết lập danh sách cho phép/chủ sở hữu để DM của bạn được phép. Nó không được sử dụng để tự động gửi. Nếu bạn chạy trên số WhatsApp cá nhân của mình, hãy sử dụng số đó và kích hoạt channels.whatsapp.selfChatMode.

​
Lệnh chat, hủy tác vụ, và “nó sẽ không dừng lại”

Hầu hết các tin nhắn nội bộ hoặc công cụ chỉ xuất hiện khi verbose hoặc reasoning được kích hoạt cho phiên đó.Sửa trong chat nơi bạn thấy nó:
/verbose off
/reasoning off
Nếu vẫn còn ồn ào, kiểm tra cài đặt phiên trong Control UI và đặt verbose thành inherit. Cũng xác nhận bạn không sử dụng hồ sơ bot với verboseDefault đặt thành on trong cấu hình.Tài liệu: Suy nghĩ và verbose, Bảo mật.
Gửi bất kỳ lệnh nào sau đây như một tin nhắn độc lập (không có dấu gạch chéo):
stop
stop action
stop current action
stop run
stop current run
stop agent
stop the agent
stop openclaw
openclaw stop
stop don't do anything
stop do not do anything
stop doing anything
please stop
stop please
abort
esc
wait
exit
interrupt
Đây là các kích hoạt hủy (không phải lệnh gạch chéo).Đối với các quy trình nền (từ công cụ exec), bạn có thể yêu cầu agent chạy:
process action:kill sessionId:XXX
Tổng quan về lệnh gạch chéo: xem Lệnh gạch chéo.Hầu hết các lệnh phải được gửi như một tin nhắn độc lập bắt đầu bằng /, nhưng một số phím tắt (như /status) cũng hoạt động nội tuyến cho người gửi trong danh sách cho phép.
OpenClaw chặn nhắn tin giữa các nhà cung cấp theo mặc định. Nếu một cuộc gọi công cụ được ràng buộc với Telegram, nó sẽ không gửi đến Discord trừ khi bạn cho phép rõ ràng.Kích hoạt nhắn tin giữa các nhà cung cấp cho agent:
{
  agents: {
    defaults: {
      tools: {
        message: {
          crossContext: {
            allowAcrossProviders: true,
            marker: { enabled: true, prefix: "[from {channel}] " },
          },
        },
      },
    },
  },
}
Khởi động lại gateway sau khi chỉnh sửa cấu hình. Nếu bạn chỉ muốn điều này cho một agent duy nhất, hãy đặt nó dưới agents.list[].tools.message.
Chế độ hàng đợi kiểm soát cách các tin nhắn mới tương tác với một tác vụ đang chạy. Sử dụng /queue để thay đổi chế độ:
  • steer - tin nhắn mới điều hướng tác vụ hiện tại
  • followup - chạy tin nhắn từng cái một
  • collect - gom tin nhắn và trả lời một lần (mặc định)
  • steer-backlog - điều hướng ngay, sau đó xử lý backlog
  • interrupt - hủy chạy hiện tại và bắt đầu lại
Bạn có thể thêm các tùy chọn như debounce:2s cap:25 drop:summarize cho các chế độ followup.

​
Khác

Trong OpenClaw, thông tin xác thực và lựa chọn mô hình là riêng biệt. Thiết lập ANTHROPIC_API_KEY (hoặc lưu khóa API Anthropic trong hồ sơ xác thực) cho phép xác thực, nhưng mô hình mặc định thực tế là bất kỳ mô hình nào bạn cấu hình trong agents.defaults.model.primary (ví dụ, anthropic/claude-sonnet-4-6 hoặc anthropic/claude-opus-4-6). Nếu bạn thấy No credentials found for profile "anthropic:default", điều đó có nghĩa là Gateway không thể tìm thấy thông tin xác thực Anthropic trong auth-profiles.json như mong đợi cho agent đang chạy.
Vẫn gặp khó khăn? Hỏi trong Discord hoặc mở một thảo luận trên GitHub.
Last modified on March 22, 2026