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

Documentation Index

Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

Câu trả lời nhanh cùng hướng dẫn khắc phục sự cố chuyên sâu hơn cho các thiết lập thực tế (phát triển cục bộ, VPS, đa tác tử, OAuth/khóa API, chuyển đổi dự phòng mô hình). Để chẩn đoán runtime, xem Khắc phục sự cố. Để xem tham chiếu cấu hình đầy đủ, xem Cấu hình.

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

  1. Trạng thái nhanh (kiểm tra đầu tiên) 
    openclaw status
    Tóm tắt cục bộ nhanh: HĐH + bản cập nhật, khả năng truy cập gateway/dịch vụ, agents/sessions, cấu hình provider + sự cố runtime (khi có thể truy cập gateway).
  2. Báo cáo có thể dán (an toàn để chia sẻ) 
    openclaw status --all
    Chẩn đoán chỉ đọc kèm phần cuối log (token được biên tập lại).
  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 mà dịch vụ có khả năng đã dùng.
  4. Probe chuyên sâu 
    openclaw status --deep
    Chạy probe sức khỏe Gateway trực tiếp, bao gồm probe kênh khi được hỗ trợ (yêu cầu Gateway có thể truy cập được). Xem Sức khỏe.
  5. Theo dõi log mới nhất 
    openclaw logs --follow
    Nếu RPC không hoạt động, dùng phương án dự phòng: 
    tail -f "$(ls -t /tmp/openclaw/openclaw-*.log | head -1)"
    Log tệp tách biệt với log dịch vụ; xem Ghi log và Khắc phục sự cố.
  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. Ảnh chụp nhanh Gateway 
    openclaw health --json
openclaw health --verbose   # shows the target URL + config path on errors
    Yêu cầu Gateway đang chạy cung cấp ảnh chụp nhanh đầy đủ (chỉ WS). Xem Sức khỏe.

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

Hỏi đáp lần chạy đầu — cài đặt, onboarding, tuyến xác thực, đăng ký, lỗi ban đầu — nằm trong Câu hỏi thường gặp về lần chạy đầu.

​
OpenClaw là gì?

OpenClaw là trợ lý AI cá nhân bạn chạy trên thiết bị của chính mình. Nó trả lời trên các bề mặt nhắn tin bạn đã dùng (WhatsApp, Telegram, Slack, Mattermost, Discord, Google Chat, Signal, iMessage, WebChat và các Plugin kênh đi kèm như QQ Bot) và cũng có thể hỗ trợ 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 phải “chỉ là một wrapper Claude.” Đây là 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 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 đã dùng, với phiên có trạng thái, bộ nhớ và công cụ - mà không 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 cứ đâu bạn muốn (Mac, Linux, VPS) và giữ workspace + lịch sử phiên ở cục bộ.
  • Kênh thật, không phải sandbox web: WhatsApp/Telegram/Slack/Discord/Signal/iMessage/v.v., 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: dùng Anthropic, OpenAI, MiniMax, OpenRouter, v.v., với định tuyến và chuyển đổi dự phòng theo từng tác tử.
  • Tùy chọn chỉ cục bộ: chạy mô hình cục bộ để toàn bộ 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 đa tác tử: tách tác tử theo kênh, tài khoản hoặc tác vụ, mỗi tác tử có workspace và mặc định riêng.
  • Mã nguồn mở và dễ tùy biến: kiểm tra, mở rộng và tự lưu trữ mà không bị khóa vào nhà cung cấp.
Tài liệu: Gateway, Kênh, Đa tác tử, Bộ nhớ.
Các dự án khởi đầu phù hợp:
  • Xây dựng website (WordPress, Shopify hoặc một site tĩnh đơn giản).
  • Tạo prototype ứng dụng di động (đề cương, màn hình, kế hoạch API).
  • Sắp xếp tệp 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 tiếp.
Nó có thể xử lý tác vụ lớn, nhưng hoạt động tốt nhất khi bạn chia chúng thành các giai đoạn và dùng tác tử phụ cho công việc song song.
Các lợi ích hằng ngày thường là:
  • Tóm tắt cá nhân: tóm tắt hộp thư, 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 nháp đầu cho email hoặc tài liệu.
  • Nhắc việc và theo dõi tiếp: lời nhắc và danh sách kiểm tra do Cron hoặc Heartbeat thúc đẩy.
  • Tự động hóa trình duyệt: điền biểu mẫu, thu thập dữ liệu và lặp lại tác vụ web.
  • Phối hợp liên thiết bị: gửi tác vụ từ điện thoại, để Gateway chạy trên máy chủ và nhận kết quả trong chat.
Có, cho nghiên cứu, đánh giá chất lượng và soạn thảo. Nó có thể quét site, tạo danh sách rút gọn, tóm tắt khách hàng tiềm năng và viết bản nháp tiếp cận hoặc nội dung quảng cáo.Với chiến dịch tiếp cận hoặc quảng cáo, hãy giữ con người trong vòng kiểm soát. Tránh spam, tuân thủ luật địa phương và chính sách nền tảng, đồng thời rà soát mọi thứ trước khi gửi. Mẫu an toàn nhất là để OpenClaw soạn nháp và bạn phê duyệt.Tài liệu: Bảo mật.
OpenClaw là trợ lý cá nhân và lớp phối hợp, không phải thay thế IDE. Dùng Claude Code hoặc Codex để có vòng lặp lập trình trực tiếp nhanh nhất trong repo. Dùng OpenClaw khi bạn muốn bộ nhớ bền vững, truy cập liên thiết bị và điều phối công cụ.Ưu điểm:
  • Bộ nhớ bền vững + workspace xuyên suốt 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, tệp, lập lịch, hook)
  • Gateway luôn bật (chạy trên VPS, tương tác từ mọi nơi)
  • Nodes cho trình duyệt/màn hình/camera/exec cục bộ
Showcase: https://openclaw.ai/showcase

​
Skills và tự động hóa

Dùng override được quản lý thay vì chỉnh bản sao trong repo. Đặt thay đổi của bạn trong ~/.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 → <workspace>/.agents/skills → ~/.agents/skills → ~/.openclaw/skills → đi kèm → skills.load.extraDirs, nên override được quản lý vẫn thắng skills đi kèm mà không cần chạm vào git. Nếu bạn cần cài skill toàn cục nhưng chỉ hiển thị với một số tác tử, giữ bản sao dùng chung trong ~/.openclaw/skills và kiểm soát khả năng hiển thị bằng agents.defaults.skills và agents.list[].skills. Chỉ các chỉnh sửa đáng đưa upstream mới nên nằm trong repo và đi ra dưới dạng PR.
Có. Thêm thư mục bổ sung qua skills.load.extraDirs trong ~/.openclaw/openclaw.json (mức ưu tiên thấp nhất). Thứ tự ưu tiên mặc định là <workspace>/skills → <workspace>/.agents/skills → ~/.agents/skills → ~/.openclaw/skills → đi kèm → skills.load.extraDirs. clawhub cài vào ./skills theo mặc định, OpenClaw xem đây là <workspace>/skills trong phiên tiếp theo. Nếu skill chỉ nên hiển thị với một số tác tử nhất định, kết hợp điều đó với agents.defaults.skills hoặc agents.list[].skills.
Hiện nay các mẫu được hỗ trợ là:
  • Cron jobs: tác vụ cô lập có thể đặt override model theo từng job.
  • Tác tử phụ: định tuyến tác vụ đến các tác tử riêng với mô hình mặc định khác nhau.
  • Chuyển đổi theo yêu cầu: dùng /model để chuyển mô hình phiên hiện tại bất cứ lúc nào.
Xem Cron jobs, Định tuyến đa tác tử và Lệnh gạch chéo.
Dùng tác tử phụ cho tác vụ dài hoặc song song. Tác tử phụ chạy trong phiên riêng, trả về tóm tắt và giữ chat chính của bạn phản hồi nhanh.Yêu cầu bot của bạn “spawn a sub-agent for this task” hoặc dùng /subagents. Dùng /status trong chat để xem Gateway đang làm gì ngay lúc này (và liệu nó có bận không).Mẹo token: tác vụ dài và tác tử phụ đều tiêu thụ token. Nếu lo ngại chi phí, đặt mô hình rẻ hơn cho tác tử phụ qua agents.defaults.subagents.model.Tài liệu: Tác tử phụ, Tác vụ nền.
Dùng binding thread. Bạn có thể bind một thread Discord với một subagent hoặc mục tiêu phiên để các tin nhắn theo sau trong thread đó ở lại phiên đã bind.Luồng cơ bản:
  • Spawn bằng sessions_spawn với thread: true (và tùy chọn mode: "session" để theo dõi tiếp bền vững).
  • Hoặc bind thủ công bằng /focus <target>.
  • Dùng /agents để kiểm tra trạng thái binding.
  • Dùng /session idle <duration|off> và /session max-age <duration|off> để kiểm soát tự động hủy focus.
  • Dùng /unfocus để tách thread.
Cấu hình bắt buộc:
  • Mặc định toàn cục: session.threadBindings.enabled, session.threadBindings.idleHours, session.threadBindings.maxAgeHours.
  • Override Discord: channels.discord.threadBindings.enabled, channels.discord.threadBindings.idleHours, channels.discord.threadBindings.maxAgeHours.
  • Tự động bind khi spawn: channels.discord.threadBindings.spawnSessions mặc định là true; đặt thành false để tắt spawn phiên gắn với thread.
Tài liệu: Tác tử phụ, Discord, Tham chiếu cấu hình, Lệnh gạch chéo.
Trước tiên hãy kiểm tra tuyến requester đã phân giải:
  • Việc gửi subagent ở chế độ hoàn tất ưu tiên mọi thread đã bind hoặc tuyến cuộc trò chuyện khi có.
  • Nếu origin hoàn tất chỉ mang một kênh, OpenClaw dùng dự phòng tuyến đã lưu của phiên requester (lastChannel / lastTo / lastAccountId) để việc gửi trực tiếp vẫn có thể thành công.
  • Nếu không có tuyến đã bind lẫn tuyến đã lưu có thể dùng, việc gửi trực tiếp có thể thất bại và kết quả chuyển sang gửi phiên theo hàng đợi thay vì đăng ngay vào chat.
  • Mục tiêu không hợp lệ hoặc cũ vẫn có thể buộc dùng dự phòng hàng đợi hoặc khiến gửi cuối cùng thất bại.
  • Nếu câu trả lời trợ lý hiển thị cuối cùng của child là token im lặng chính xác NO_REPLY / no_reply, hoặc chính xác ANNOUNCE_SKIP, OpenClaw cố ý chặn thông báo thay vì đăng lại tiến trình cũ trước đó.
  • Nếu child hết thời gian sau khi chỉ gọi công cụ, thông báo có thể rút gọn thành một tóm tắt tiến độ một phần ngắn thay vì phát lại đầu ra công cụ thô.
Gỡ lỗi:
openclaw tasks show <runId-or-sessionKey>
Tài liệu: Tác tử phụ, Tác vụ nền, Công cụ phiên.
Cron chạy bên trong tiến trình Gateway. Nếu Gateway không chạy liên tục, các job đã lập lịch sẽ không chạy.Danh sách kiểm tra:
  • Xác nhận cron đã bật (cron.enabled) và OPENCLAW_SKIP_CRON chưa được đặt.
  • Kiểm tra Gateway đang chạy 24/7 (không ngủ/khởi động lại).
  • Xác minh thiết lập múi giờ cho job (--tz so với múi giờ host).
Gỡ lỗi:
openclaw cron run <jobId>
openclaw cron runs --id <jobId> --limit 50
Tài liệu: Cron jobs, Tự động hóa.
Trước tiên hãy kiểm tra chế độ gửi:
  • --no-deliver / delivery.mode: "none" nghĩa là không mong đợi runner gửi dự phòng.
  • Thiếu hoặc mục tiêu thông báo không hợp lệ (channel / to) nghĩa là runner đã bỏ qua việc gửi ra ngoài.
  • Lỗi xác thực kênh (unauthorized, Forbidden) nghĩa là runner đã cố gửi nhưng thông tin xác thực đã chặn việc đó.
  • Kết quả cô lập im lặng (chỉ NO_REPLY / no_reply) được xem là cố ý không thể gửi, nên runner cũng chặn việc gửi dự phòng đã xếp hàng.
Với các tác vụ cron cô lập, agent vẫn có thể gửi trực tiếp bằng công cụ message khi có tuyến trò chuyện. --announce chỉ kiểm soát đường dẫn dự phòng của runner cho văn bản cuối cùng mà agent chưa tự gửi.Gỡ lỗi:
openclaw cron runs --id <jobId> --limit 50
openclaw tasks show <runId-or-sessionKey>
Tài liệu: Tác vụ Cron, Tác vụ nền.
Đó thường là đường dẫn chuyển mô hình trực tiếp, không phải lập lịch trùng lặp.Cron cô lập có thể lưu một lần chuyển giao mô hình lúc chạy và thử lại khi lần chạy đang hoạt động ném LiveSessionModelSwitchError. Lần thử lại giữ nguyên provider/model đã chuyển, và nếu lần chuyển đi kèm một ghi đè hồ sơ xác thực mới, cron cũng lưu ghi đè đó trước khi thử lại.Quy tắc chọn liên quan:
  • Ghi đè mô hình của hook Gmail thắng trước khi áp dụng được.
  • Sau đó đến model theo từng tác vụ.
  • Sau đó đến mọi ghi đè mô hình phiên cron đã lưu.
  • Sau đó đến lựa chọn mô hình agent/mặc định bình thường.
Vòng lặp thử lại có giới hạn. Sau lần thử ban đầu cộng thêm 2 lần thử lại do chuyển đổi, cron sẽ hủy thay vì lặp mãi.Gỡ lỗi:
openclaw cron runs --id <jobId> --limit 50
openclaw tasks show <runId-or-sessionKey>
Tài liệu: Tác vụ Cron, CLI cron.
Dùng các lệnh openclaw skills gốc hoặc thả skills vào workspace của bạn. Giao diện Skills trên macOS không có trên Linux. Duyệt skills tại https://clawhub.ai.
openclaw skills search "calendar"
openclaw skills search --limit 20
openclaw skills install <skill-slug>
openclaw skills install <skill-slug> --version <version>
openclaw skills install <skill-slug> --force
openclaw skills update --all
openclaw skills list --eligible
openclaw skills check
openclaw skills install gốc ghi vào thư mục skills/ của workspace đang hoạt động. Chỉ cài CLI clawhub riêng nếu bạn muốn xuất bản hoặc đồng bộ skills của riêng mình. Với cài đặt dùng chung giữa các agent, hãy đặt skill dưới ~/.openclaw/skills và dùng agents.defaults.skills hoặc agents.list[].skills nếu bạn muốn giới hạn agent nào có thể thấy nó.
Có. Dùng bộ lập lịch Gateway:
  • Tác vụ Cron cho các tác vụ đã lên lịch hoặc lặp lại (tồn tại qua các lần khởi động lại).
  • Heartbeat cho kiểm tra định kỳ của “phiên chính”.
  • Tác vụ cô lập cho các agent tự chủ đăng tóm tắt hoặc gửi đến các cuộc trò chuyện.
Tài liệu: Tác vụ Cron, Tự động hóa, Heartbeat.
Không trực tiếp. Skills trên macOS được kiểm soát bởi metadata.openclaw.os cùng các binary bắt buộc, và skills chỉ xuất hiện trong prompt hệ thống khi chúng đủ điều kiện trên máy chủ Gateway. Trên Linux, skills chỉ dành cho darwin (như apple-notes, apple-reminders, things-mac) sẽ không tải trừ khi bạn ghi đè cơ chế kiểm soát đó.Bạn có ba mẫu được 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ác binary macOS, rồi kết nối từ Linux ở chế độ từ xa hoặc qua Tailscale. Skills tải bình thường vì máy chủ Gateway là macOS.Tùy chọn B - 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 thanh menu), và đặt Node Run Commands thành “Always Ask” hoặc “Always Allow” trên Mac. OpenClaw có thể xem skills chỉ dành cho macOS là đủ điều kiện khi các binary bắt buộc tồn tại trên Node. Agent chạy các skills đó 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 allowlist.Tùy chọn C - proxy binary macOS qua SSH (nâng cao). Giữ Gateway trên Linux, nhưng làm cho các binary CLI bắt buộc phân giải thành wrapper SSH chạy trên Mac. Sau đó ghi đè skill để cho phép Linux nhằm giữ 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 vào PATH trên máy chủ Linux (ví dụ ~/bin/memo).
  3. Ghi đè metadata của skill (workspace hoặc ~/.openclaw/skills) để cho phép Linux: 
    ---
name: apple-notes
description: Manage Apple Notes via the memo CLI on macOS.
metadata: { "openclaw": { "os": ["darwin", "linux"], "requires": { "bins": ["memo"] } } }
---
  4. Bắt đầu một phiên mới để ảnh chụp nhanh skills được làm mới.
Hiện chưa được tích hợp sẵn.Các tùy chọn:
  • Skill / plugin tùy chỉnh: phù hợp nhất để truy cập API đáng tin cậy (Notion/HeyGen đều có API).
  • Tự động hóa trình duyệt: hoạt động mà không cần code nhưng chậm hơn và dễ hỏng hơn.
Nếu bạn muốn giữ ngữ cảnh theo từng khách hàng (quy trình agency), một mẫu đơn giản là:
  • Một trang Notion cho mỗi khách hàng (ngữ cảnh + tùy chọn + công việc đang hoạt động).
  • Yêu cầu agent lấy trang đó khi bắt đầu phiên.
Nếu bạn muốn có tích hợp gốc, hãy mở một yêu cầu tính năng hoặc xây dựng một skill nhắm đến các API đó.Cài đặt skills:
openclaw skills install <skill-slug>
openclaw skills update --all
Cài đặt gốc sẽ nằm trong thư mục skills/ của workspace đang hoạt động. Với skills dùng chung giữa các agent, hãy đặt chúng trong ~/.openclaw/skills/<name>/SKILL.md. Nếu chỉ một số agent nên thấy một cài đặt dùng chung, hãy cấu hình agents.defaults.skills hoặc agents.list[].skills. Một số skills yêu cầu binary được cài qua Homebrew; trên Linux, điều đó nghĩa là Linuxbrew (xem mục FAQ Homebrew Linux ở trên). Xem Skills, Cấu hình Skills, và ClawHub.
Dùng hồ sơ trình duyệt user tích hợp sẵn, được gắn 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, hãy 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 có thể dùng trình duyệt trên máy cục bộ hoặc một Node trình duyệt đã kết nối. Nếu Gateway chạy ở nơi khác, hãy chạy một máy chủ Node trên máy trình duyệt hoặc dùng CDP từ xa thay thế.Các giới hạn hiện tại trên existing-session / user:
  • thao tác dựa trên ref, không dựa trên CSS selector
  • tải lên yêu cầu ref / inputRef và hiện chỉ hỗ trợ một tệp mỗi lần
  • responsebody, xuất PDF, chặn tải xuống, và thao tác theo lô vẫn cần một trình duyệt được quản lý hoặc hồ sơ CDP thô

​
Cách ly và bộ nhớ

Có. Xem Cách ly. Với thiết lập dành riêng cho Docker (Gateway đầy đủ trong Docker hoặc image cách ly), xem Docker.
Image mặc định ưu tiên bảo mật và chạy với người dùng node, nên nó không bao gồm các gói hệ thống, Homebrew, hoặc trình duyệt đi kèm. Để thiết lập đầy đủ hơn:
  • Duy trì /home/node với OPENCLAW_HOME_VOLUME để cache vẫn tồn tại.
  • Đưa dependency hệ thống vào image bằng OPENCLAW_DOCKER_APT_PACKAGES.
  • Cài 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à bảo đảm đường dẫn được duy trì.
Tài liệu: Docker, Trình duyệt.
Có - nếu lưu lượng riêng tư của bạn là DM và lưu lượng công khai của bạn là nhóm.Dùng agents.defaults.sandbox.mode: "non-main" để các phiên nhóm/kênh (khóa không phải main) chạy trong backend cách ly đã cấu hình, trong khi phiên DM chính vẫn ở trên máy chủ. Docker là backend mặc định nếu bạn không chọn backend nào. Sau đó giới hạn các công cụ có sẵn trong phiên được cách ly qua tools.sandbox.tools.Hướng dẫn thiết lập + cấu hình ví dụ: Nhóm: DM cá nhân + nhóm công khaiTham chiếu cấu hình chính: Cấu hình Gateway
Đặt agents.defaults.sandbox.docker.binds thành ["host:path:mode"] (ví dụ, "/home/user/src:/src:ro"). Bind toàn cục + theo agent sẽ được gộp; bind theo agent bị bỏ qua khi scope: "shared". Dùng :ro cho mọi thứ nhạy cảm và nhớ rằng bind vượt qua các ranh giới hệ thống tệp của sandbox.OpenClaw xác thực nguồn bind dựa trên cả đường dẫn đã chuẩn hóa và đường dẫn chuẩn được phân giải qua tổ tiên sâu nhất đang tồn tại. Điều đó nghĩa là việc thoát qua parent symlink vẫn bị đóng thất bại ngay cả khi đoạn đường dẫn cuối chưa tồn tại, và kiểm tra root được phép vẫn áp dụng sau khi phân giải symlink.Xem Cách ly và Sandbox so với chính sách công cụ so với đặc quyền nâng cao để 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 đã tuyển chọn trong MEMORY.md (chỉ phiên chính/riêng tư)
OpenClaw cũng chạy một lần flush bộ nhớ im lặng trước Compaction để nhắc mô hình ghi các ghi chú bền vững trước khi tự động Compaction. Việc này chỉ chạy khi workspace có thể ghi (sandbox chỉ đọc sẽ bỏ qua). Xem Bộ nhớ.
Yêu cầu bot ghi sự kiện đó 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 mảng chúng tôi đang cải thiện. Việc nhắc mô hình lưu bộ nhớ sẽ hữu ích; nó sẽ biết cần làm gì. Nếu nó vẫn quên, hãy xác minh Gateway đang dùng cùng một workspace trong mọi lần chạy.Tài liệu: Bộ nhớ, Workspace của agent.
Tệp bộ nhớ nằm 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, nên các cuộc trò chuyện dài có thể bị Compaction hoặc cắt bớt. Đó là lý do 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: Bộ nhớ, Ngữ cảnh.
Chỉ khi bạn dùng embedding OpenAI. Codex OAuth bao gồm chat/completions và không cấp quyền truy cập embedding, vì vậy đăng nhập bằng Codex (OAuth hoặc đăng nhập Codex CLI) không giúp ích cho tìm kiếm bộ nhớ ngữ nghĩa. Embedding OpenAI vẫn cần một khóa API thật (OPENAI_API_KEY hoặc models.providers.openai.apiKey).Nếu bạn không đặt provider rõ ràng, OpenClaw tự động chọn provider khi nó có thể phân giải một khóa API (hồ sơ xác thực, models.providers.*.apiKey, hoặc biến môi trường). Nó ưu tiên OpenAI nếu phân giải được khóa OpenAI, nếu không thì Gemini nếu phân giải được khóa Gemini, sau đó là Voyage, rồi Mistral. Nếu không có khóa từ xa nào, tìm kiếm bộ nhớ vẫn bị tắt cho đến khi bạn cấu hình nó. Nếu bạn đã cấu hình và có sẵn đường dẫn mô hình cục bộ, 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 embedding Gemini, đặt memorySearch.provider = "gemini" và cung cấp GEMINI_API_KEY (hoặc memorySearch.remote.apiKey). Chúng tôi hỗ trợ các mô hình embedding OpenAI, Gemini, Voyage, Mistral, Ollama, hoặc local - xem Bộ nhớ để biết chi tiết thiết lập.

​
Nơi các thành phần nằm 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 họ.
  • Cục bộ theo mặc định: phiên, tệp bộ nhớ, cấu hình và workspace nằm trên máy chủ Gateway (~/.openclaw + thư mục workspace của bạn).
  • Từ xa do cần thiết: tin nhắn bạn gửi đến provider mô hình (Anthropic/OpenAI/v.v.) đi tới API của họ, và các nền tảng chat (WhatsApp/Telegram/Slack/v.v.) lưu dữ liệu tin nhắn trên máy chủ của họ.
  • Bạn kiểm soát phạm vi dữ liệu: dùng mô hình cục bộ giữ 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: Workspace của agent, Bộ nhớ.
Mọi thứ nằm 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 kế thừa (được sao chép vào hồ sơ xác thực khi dùng lần đầu)
$OPENCLAW_STATE_DIR/agents/<agentId>/agent/auth-profiles.jsonHồ sơ xác thực (OAuth, khóa API, và keyRef/tokenRef tùy chọn)
$OPENCLAW_STATE_DIR/secrets.jsonPayload bí mật tùy chọn dựa trên tệp cho provider SecretRef file
$OPENCLAW_STATE_DIR/agents/<agentId>/agent/auth.jsonTệp tương thích kế thừa (các mục api_key tĩnh đã được xóa sạch)
$OPENCLAW_STATE_DIR/credentials/Trạng thái provider (ví dụ: whatsapp/<accountId>/creds.json)
$OPENCLAW_STATE_DIR/agents/Trạng thái theo từng agent (agentDir + phiên)
$OPENCLAW_STATE_DIR/agents/<agentId>/sessions/Lịch sử hội thoại & trạng thái (theo từng agent)
$OPENCLAW_STATE_DIR/agents/<agentId>/sessions/sessions.jsonMetadata phiên (theo từng agent)
Đường dẫn một agent kế thừa: ~/.openclaw/agent/* (được di chuyển bởi openclaw doctor).Workspace của bạn (AGENTS.md, tệp bộ nhớ, Skills, 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 nằm trong workspace của agent, không phải ~/.openclaw.
  • Workspace (theo từng agent): AGENTS.md, SOUL.md, IDENTITY.md, USER.md, MEMORY.md, memory/YYYY-MM-DD.md, HEARTBEAT.md tùy chọn. memory.md viết thường ở gốc chỉ là đầu vào sửa chữa kế thừa; openclaw doctor --fix có thể hợp nhất nó vào MEMORY.md khi cả hai tệp đều tồn tại.
  • Thư mục trạng thái (~/.openclaw): cấu hình, trạng thái kênh/provider, hồ sơ xác thực, phiên, nhật ký, và Skills dùng chung (~/.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, hãy xác nhận Gateway đang dùng cùng workspace trong mọi lần khởi chạy (và nhớ rằng: chế độ từ xa dùng workspace của máy chủ gateway, không phải laptop cục bộ của bạn).Mẹo: nếu bạn muốn một hành vi hoặc tùy chọn bền vững, hãy 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 Workspace của agent và Bộ nhớ.
Đặt workspace của agent trong một repo git riêng tư và sao lưu nó ở nơi riêng tư (ví dụ GitHub private). Việc này ghi lại bộ nhớ + các 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 commit bất kỳ thứ gì dưới ~/.openclaw (thông tin xác thực, phiên, token, hoặc payload bí mật đã mã hóa). Nếu cần khôi phục đầy đủ, hã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: Workspace của agent.
Xem hướng dẫn riêng: Gỡ cài đặt.
Có. Workspace là cwd mặc định và neo bộ nhớ, không phải sandbox cứng. Đường dẫn tương đối được phân giải bên trong workspace, nhưng đường dẫn tuyệt đối có thể truy cập các vị trí khác trên máy chủ trừ khi sandboxing được bật. Nếu cần cô lập, hãy dùng agents.defaults.sandbox hoặc cài đặt sandbox theo từng agent. Nếu bạn muốn một repo là thư mục làm việc mặc định, hãy trỏ workspace của agent đó đến gốc repo. Repo OpenClaw chỉ là mã nguồn; hãy giữ workspace riêng biệt trừ khi bạn chủ ý muốn agent làm việc bên trong đó.Ví dụ (repo làm cwd mặc định):
{
  agents: {
    defaults: {
      workspace: "~/Projects/my-repo",
    },
  },
}
Trạng thái phiên thuộc về máy chủ gateway. Nếu bạn đang ở chế độ từ xa, kho phiên bạn quan tâm nằm trên máy từ xa, không phải laptop cục bộ của bạn. Xem Quản lý phiên.

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

OpenClaw đọc cấu hình JSON5 tùy chọn từ $OPENCLAW_CONFIG_PATH (mặc định: ~/.openclaw/openclaw.json):
$OPENCLAW_CONFIG_PATH
Nếu thiếu tệp, nó dùng các mặc định tương đối an toàn (bao gồm workspace mặc định là ~/.openclaw/workspace).
Bind không phải loopback yêu cầu một đường dẫn xác thực gateway hợp lệ. Trong thực tế, điều đó có nghĩa là:
  • xác thực shared-secret: token hoặc mật khẩu
  • gateway.auth.mode: "trusted-proxy" phía sau một reverse proxy nhận biết danh tính được cấu hình đúng
{
  gateway: {
    bind: "lan",
    auth: {
      mode: "token",
      token: "replace-me",
    },
  },
}
Ghi chú:
  • gateway.remote.token / .password không tự bật xác thực gateway cục bộ.
  • Đường dẫn gọi cục bộ chỉ có thể dùng gateway.remote.* làm fallback khi gateway.auth.* chưa được đặt.
  • Với xác thực bằng mật khẩu, thay vào đó đặt gateway.auth.mode: "password" cộng với gateway.auth.password (hoặc OPENCLAW_GATEWAY_PASSWORD).
  • Nếu gateway.auth.token / gateway.auth.password được cấu hình rõ ràng qua SecretRef và không phân giải được, quá trình phân giải sẽ đóng an toàn (không bị fallback từ xa che lấp).
  • Thiết lập Control UI dùng shared-secret xác thực qua connect.params.auth.token hoặc connect.params.auth.password (được lưu trong cài đặt ứng dụng/UI). Các chế độ mang danh tính như Tailscale Serve hoặc trusted-proxy dùng header yêu cầu thay thế. Tránh đặt shared secret trong URL.
  • Với gateway.auth.mode: "trusted-proxy", reverse proxy loopback cùng máy chủ yêu cầu đặt rõ ràng gateway.auth.trustedProxy.allowLoopback = true và một mục loopback trong gateway.trustedProxies.
OpenClaw thực thi xác thực gateway theo mặc định, bao gồm cả loopback. Trong đường dẫn mặc định thông thường, điều đó nghĩa là xác thực token: nếu không cấu hình đường dẫn xác thực rõ ràng, quá trình khởi động gateway phân giải sang chế độ token và tạo token chỉ dùng trong runtime cho lần khởi động đó, vì vậy client WS cục bộ phải xác thực. Cấu hình rõ ràng gateway.auth.token, gateway.auth.password, OPENCLAW_GATEWAY_TOKEN, hoặc OPENCLAW_GATEWAY_PASSWORD khi client cần một bí mật ổn định qua các lần khởi động lại. Việc này chặn các tiến trình cục bộ khác gọi Gateway.Nếu bạn thích một đường dẫn xác thực khác, bạn có thể chọn rõ ràng chế độ mật khẩu (hoặc, với reverse proxy nhận biết danh tính, trusted-proxy). Nếu bạn thực sự muốn loopback mở, hãy đặt rõ ràng gateway.auth.mode: "none" trong cấu hình của bạn. Doctor có thể tạo 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 với các 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 khẩu hiệu nhưng giữ dòng tiêu đề/phiên bản banner.
  • default: luôn dùng All your chats, one OpenClaw..
  • random: các khẩu hiệu vui nhộn/theo mùa xoay vòng (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 phụ thuộc vào provider bạn chọn:
  • Các provider dựa trên API như Brave, Exa, Firecrawl, Gemini, Grok, Kimi, MiniMax Search, Perplexity, và Tavily yêu cầu thiết lập khóa API thông thường của chúng.
  • Ollama Web Search không cần khóa, nhưng nó dùng máy chủ Ollama đã cấu hình của bạn và yêu cầu ollama signin.
  • DuckDuckGo không cần khóa, nhưng đây là tích hợp dựa trên HTML không chính thức.
  • SearXNG không cần khóa/tự host; cấu hình SEARXNG_BASE_URL hoặc plugins.entries.searxng.config.webSearch.baseUrl.
Khuyến nghị: chạy openclaw configure --section web và chọn một provider. Các lựa chọn thay thế bằng môi trường:
  • Brave: BRAVE_API_KEY
  • Exa: EXA_API_KEY
  • Firecrawl: FIRECRAWL_API_KEY
  • Gemini: GEMINI_API_KEY
  • Grok: XAI_API_KEY
  • Kimi: KIMI_API_KEY hoặc MOONSHOT_API_KEY
  • MiniMax Search: MINIMAX_CODE_PLAN_KEY, MINIMAX_CODING_API_KEY, hoặc MINIMAX_API_KEY
  • Perplexity: PERPLEXITY_API_KEY hoặc OPENROUTER_API_KEY
  • SearXNG: SEARXNG_BASE_URL
  • Tavily: TAVILY_API_KEY
{
  plugins: {
    entries: {
      brave: {
        config: {
          webSearch: {
            apiKey: "BRAVE_API_KEY_HERE",
          },
        },
      },
    },
    },
    tools: {
      web: {
        search: {
          enabled: true,
          provider: "brave",
          maxResults: 5,
        },
        fetch: {
          enabled: true,
          provider: "firecrawl", // optional; omit for auto-detect
        },
      },
    },
}
Cấu hình tìm kiếm web theo từng nhà cung cấp hiện nằm dưới plugins.entries.<plugin>.config.webSearch.*. Các đường dẫn nhà cung cấp tools.web.search.* cũ vẫn tạm thời được tải để tương thích, nhưng không nên dùng cho cấu hình mới. Cấu hình dự phòng tìm nạp web Firecrawl nằm dưới plugins.entries.firecrawl.config.webFetch.*.Ghi chú:
  • Nếu bạn dùng danh sách cho phép, hãy thêm web_search/web_fetch/x_search hoặc group:web.
  • web_fetch được bật theo mặc định (trừ khi bị tắt rõ ràng).
  • Nếu tools.web.fetch.provider bị bỏ qua, OpenClaw sẽ tự động phát hiện nhà cung cấp dự phòng tìm nạp đầu tiên sẵn sàng từ thông tin đăng nhập hiện có. Hiện nay nhà cung cấp đi kèm là Firecrawl.
  • Daemon đọc biến môi trường từ ~/.openclaw/.env (hoặc môi trường dịch vụ).
Tài liệu: Công cụ web.
config.apply thay thế toàn bộ cấu hình. Nếu bạn gửi một đối tượng một phần, mọi thứ khác sẽ bị xóa.OpenClaw hiện tại bảo vệ nhiều trường hợp ghi đè nhầm:
  • Các lần ghi cấu hình do OpenClaw sở hữu xác thực toàn bộ cấu hình sau thay đổi trước khi ghi.
  • Các lần ghi do OpenClaw sở hữu không hợp lệ hoặc có tính phá hủy sẽ bị từ chối và được lưu dưới dạng openclaw.json.rejected.*.
  • Nếu chỉnh sửa trực tiếp làm hỏng quá trình khởi động hoặc tải lại nóng, Gateway sẽ đóng an toàn hoặc bỏ qua lần tải lại; nó không ghi lại openclaw.json.
  • openclaw doctor --fix sở hữu việc sửa chữa và có thể khôi phục bản tốt gần nhất trong khi lưu tệp bị từ chối dưới dạng openclaw.json.clobbered.*.
Khôi phục:
  • Kiểm tra openclaw logs --follow để tìm Invalid config at, Config write rejected:, hoặc config reload skipped (invalid config).
  • Kiểm tra openclaw.json.clobbered.* hoặc openclaw.json.rejected.* mới nhất bên cạnh cấu hình đang hoạt động.
  • Chạy openclaw config validate và openclaw doctor --fix.
  • Chỉ sao chép lại các khóa mong muốn bằng openclaw config set hoặc config.patch.
  • Nếu bạn không có bản tốt gần nhất hoặc payload bị từ chối, hãy khôi phục từ bản sao lưu, hoặc chạy lại openclaw doctor và cấu hình lại các kênh/mô hình.
  • Nếu việc này ngoài dự kiến, hãy báo lỗi và đính kèm cấu hình gần nhất bạn biết hoặc bất kỳ bản sao lưu nào.
  • Một tác tử lập trình cục bộ thường có thể dựng lại cấu hình hoạt động từ nhật ký hoặc lịch sử.
Tránh việc này:
  • Dùng openclaw config set cho các thay đổi nhỏ.
  • Dùng openclaw configure cho chỉnh sửa tương tác.
  • Dùng config.schema.lookup trước khi bạn không chắc về đường dẫn chính xác hoặc hình dạng trường; nó trả về một nút schema nông cộng với tóm tắt các con trực tiếp để đi sâu.
  • Dùng config.patch cho các chỉnh sửa RPC một phần; chỉ dùng config.apply cho thay thế toàn bộ cấu hình.
  • Nếu bạn đang dùng công cụ gateway chỉ dành cho chủ sở hữu từ một lần chạy tác tử, nó vẫn sẽ từ chối ghi vào tools.exec.ask / tools.exec.security (bao gồm các bí danh tools.bash.* cũ được chuẩn hóa về cùng các đường dẫn exec được bảo vệ).
Tài liệu: Cấu hình, Cấu hình tương tác, Khắc phục sự cố Gateway, Doctor.
Mẫu phổ biến là một Gateway (ví dụ Raspberry Pi) cộng với node và tác tử:
  • Gateway (trung tâm): sở hữu các kênh (Signal/WhatsApp), định tuyến và phiên.
  • Node (thiết bị): Mac/iOS/Android kết nối như thiết bị ngoại vi và cung cấp công cụ cục bộ (system.run, canvas, camera).
  • Tác tử (worker): các bộ não/không gian làm việc riêng cho vai trò đặc biệt (ví dụ “vận hành Hetzner”, “Dữ liệu cá nhân”).
  • Tác tử con: sinh công việc nền từ một tác tử chính khi bạn muốn song song hóa.
  • TUI: kết nối tới Gateway và chuyển đổi tác tử/phiên.
Tài liệu: Node, Truy cập từ xa, Định tuyến đa tác tử, Tác tử con, TUI.
Có. Đây 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 (có giao diện). Headless dễ kích hoạt kiểm tra chống bot hơn trên một số trang. Xem Trình duyệt.Headless dùng cùng công cụ Chromium và hoạt động cho hầu hết tự động hóa (biểu mẫu, nhấp chuột, scraping, đăng nhập). Các khác biệt chính:
  • Không có cửa sổ trình duyệt hiển thị (dùng ảnh chụp màn hình nếu bạn cần hình ảnh).
  • Một số trang nghiêm ngặt hơn với tự động hóa ở chế độ headless (CAPTCHA, chống bot). Ví dụ, X/Twitter thường chặn phiên headless.
Đặt browser.executablePath thành tệp nhị phân 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 Trình duyệt.

​
Gateway và node từ xa

Tin nhắn Telegram được xử lý bởi gateway. Gateway chạy tác tử và chỉ sau đó gọi node qua Gateway WebSocket khi cần công cụ node:Telegram → Gateway → Tác tử → node.* → Node → Gateway → TelegramNode không thấy lưu lượng nhà cung cấp đi vào; chúng chỉ nhận các lệnh gọi RPC node.
Trả lời ngắn gọn: ghép đôi máy tính của bạn dưới dạng node. Gateway chạy ở nơi khác, nhưng 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 máy chủ luôn bật (VPS/máy chủ tại nhà).
  2. Đưa máy chủ Gateway và máy tính của bạn vào cùng một tailnet.
  3. Đảm bảo Gateway WS có thể truy cập được (bind tailnet hoặc SSH tunnel).
  4. Mở ứng dụng macOS cục bộ và kết nối ở chế độ Từ xa qua SSH (hoặc tailnet trực tiếp) để nó có thể đăng ký làm node.
  5. Phê duyệt node trên Gateway: 
    openclaw devices list
openclaw devices approve <requestId>
Không cần cầu nối TCP riêng; node kết nối qua Gateway WebSocket.Nhắc nhở bảo mật: ghép đôi một node macOS cho phép system.run trên máy đó. Chỉ ghép đôi các thiết bị bạn tin cậy, và xem Bảo mật.Tài liệu: Node, Giao thức Gateway, Chế độ từ xa macOS, Bảo mật.
Kiểm tra những điều cơ bản:
  • Gateway đang chạy: openclaw gateway status
  • Tình trạng Gateway: openclaw status
  • Tình trạng kênh: openclaw channels status
Sau đó xác minh xác thực và định tuyến:
  • Nếu bạn dùng Tailscale Serve, hãy đả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ỏ tới đúng cổ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, Truy cập từ xa, Kênh.
Có. Không có cầu nối “bot-với-bot” tích hợp sẵn, nhưng bạn có thể nối nó theo một vài cách đáng tin cậy:Đơn giản nhất: dùng một kênh chat thông thường mà cả hai bot đều có thể truy cập (Telegram/Slack/WhatsApp). Cho Bot A gửi tin nhắn tới Bot B, rồi để Bot B trả lời như thường lệ.Cầu nối CLI (chung): chạy một script gọi Gateway còn lại bằng openclaw agent --message ... --deliver, nhắm tới một chat nơi bot còn lại lắng nghe. Nếu một bot nằm trên VPS từ xa, hãy trỏ CLI của bạn tới Gateway từ xa đó qua SSH/Tailscale (xem Truy cập từ xa).Mẫu ví dụ (chạy từ một máy có thể truy cập Gateway đích):
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 vô tận (chỉ khi được nhắc đến, danh sách cho phép kênh, hoặc quy tắc “không trả lời tin nhắn bot”).Tài liệu: Truy cập từ xa, CLI tác tử, Gửi tác tử.
Không. Một Gateway có thể lưu trữ nhiều tác tử, mỗi tác tử có không gian làm việc, mặc định mô hình, và định tuyến riêng. Đó là thiết lập thông thường và rẻ hơn, đơn giản hơn nhiều so với chạy một VPS cho mỗi tác tử.Chỉ dùng VPS riêng khi bạn cần cô lập cứng (ranh giới bảo mật) hoặc các cấu hình rất khác nhau mà bạn không muốn chia sẻ. Nếu không, hãy giữ một Gateway và dùng nhiều tác tử hoặc tác tử con.
Có - node là cách hạng nhất để truy cập laptop của bạn từ Gateway từ xa, và chúng mở khóa nhiều hơn truy cập shell. Gateway chạy trên macOS/Linux (Windows qua WSL2) và nhẹ (một VPS nhỏ hoặc máy cỡ Raspberry Pi là đủ; 4 GB RAM là dư), nên thiết lập phổ biến là một máy chủ luôn bật cộng với laptop của bạn làm node.
  • Không cần SSH vào. Node kết nối ra Gateway WebSocket và dùng ghép đôi thiết bị.
  • Kiểm soát thực thi an toàn hơn. system.run được chặn bằng danh sách cho phép/phê duyệt node trên laptop đó.
  • Nhiều công cụ thiết bị hơn. Node 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 máy chủ node trên laptop, hoặc gắn vào Chrome cục bộ trên máy chủ qua Chrome MCP.
SSH ổn cho truy cập shell tùy dịp, nhưng node đơn giản hơn cho quy trình tác tử đang diễn ra và tự động hóa thiết bị.Tài liệu: Node, CLI Node, Trình duyệt.
Không. Chỉ nên chạy một gateway trên mỗi máy chủ trừ khi bạn cố ý chạy các hồ sơ cô lập (xem Nhiều gateway). Node là thiết bị ngoại vi kết nối tới gateway (node iOS/Android, hoặc “chế độ node” macOS trong ứng dụng thanh menu). Với máy chủ node headless và điều khiển CLI, xem CLI máy chủ Node.Cần khởi động lại toàn bộ cho các thay đổi gateway, discovery, và bề mặt Plugin được lưu trữ.
Có.
  • config.schema.lookup: kiểm tra một cây con cấu hình với nút schema nông của nó, gợi ý UI khớp, và các tóm tắt con trực tiếp trước khi ghi
  • config.get: lấy snapshot hiện tại + hash
  • config.patch: cập nhật từng phần an toàn (ưu tiên cho hầu hết chỉnh sửa RPC); hot-reload khi có thể và khởi động lại khi cần
  • config.apply: xác thực + thay thế toàn bộ cấu hình; hot-reload khi có thể và khởi động lại khi cần
  • Công cụ runtime gateway chỉ dành cho owner vẫn từ chối ghi lại tools.exec.ask / tools.exec.security; các alias cũ tools.bash.* được chuẩn hóa về cùng các đường dẫn exec được bảo vệ
{
  agents: { defaults: { workspace: "~/.openclaw/workspace" } },
  channels: { whatsapp: { allowFrom: ["+15555550123"] } },
}
Cấu hình này đặt workspace của bạn và giới hạn 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
    • Dùng ứng dụng Tailscale và đăng nhập vào cùng tailnet.
  3. Bật MagicDNS (khuyến nghị)
    • Trong bảng điều khiển quản trị Tailscale, bật MagicDNS để VPS có tên ổn định.
  4. 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 Control UI mà không cần SSH, dùng Tailscale Serve trên VPS:
openclaw gateway --tailscale serve
Cách này giữ gateway bind vào loopback và phơi bày HTTPS qua Tailscale. Xem Tailscale.
Serve phơi bày Gateway Control UI + WS. Các node kết nối qua cùng endpoint Gateway WS.Thiết lập khuyến nghị:
  1. Đảm bảo VPS + Mac ở cùng tailnet.
  2. Dùng ứng dụng macOS ở chế độ Remote (đích SSH có thể là hostname tailnet). Ứng dụng sẽ tạo tunnel cho 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: Giao thức Gateway, Khám phá, chế độ remote macOS.
Nếu bạn chỉ cần công cụ cục bộ (màn hình/camera/exec) trên laptop thứ hai, hãy thêm nó làm node. Cách này 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ỉ hỗ trợ macOS, nhưng chúng tôi dự định mở rộng sang các OS khác.Chỉ cài Gateway thứ hai khi bạn cần cô lập cứng hoặc hai bot hoàn toàn riêng biệt.Tài liệu: Node, CLI node, Nhiều gateway.

​
Biến môi trường và nạp .env

OpenClaw đọc biến môi trường từ tiến trình cha (shell, launchd/systemd, CI, v.v.) và đồng thời nạp:
  • .env từ thư mục làm việc hiện tại
  • .env dự phòng toàn cục từ ~/.openclaw/.env (còn gọi là $OPENCLAW_STATE_DIR/.env)
Không tệp .env nào ghi đè biến môi trường hiện có.Bạn cũng có thể định nghĩa biến môi trường inline trong cấu hình (chỉ áp dụng nếu chưa có trong env của tiến 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 sửa thường gặp:
  1. Đặt các khóa bị thiếu vào ~/.openclaw/.env để chúng vẫn được nạp ngay cả khi service không kế thừa env shell của bạn.
  2. Bật nhập shell (tiện ích opt-in):
{
  env: {
    shellEnv: {
      enabled: true,
      timeoutMs: 15000,
    },
  },
}
Cách này chạy login shell của bạn và chỉ nhập các khóa dự kiến còn thiếu (không bao giờ ghi đè). 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 env shell có được bật hay 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 OpenClaw sẽ không tự động nạp login shell của bạn.Nếu Gateway chạy dưới dạng service (launchd/systemd), nó sẽ không kế thừa môi trường shell của bạn. Sửa bằng một trong các cách sau:
  1. Đặt token vào ~/.openclaw/.env: 
    COPILOT_GITHUB_TOKEN=...
  2. Hoặc bật nhập shell (env.shellEnv.enabled: true).
  3. Hoặc thêm nó vào khối env trong cấu hình của bạn (chỉ áp dụng nếu còn thiếu).
Sau đó khởi động lại gateway và kiểm tra lại:
openclaw models status
Token Copilot được đọc từ COPILOT_GITHUB_TOKEN (cũng như GH_TOKEN / GITHUB_TOKEN). Xem /concepts/model-providers và /environment.

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

Gửi /new hoặc /reset dưới dạng một tin nhắn độc lập. Xem Quản lý phiên.
Phiên có thể hết hạn sau session.idleMinutes, nhưng tính năng này bị tắt theo mặc định (mặc định 0). Đặt nó thành một giá trị dương để bật hết hạn khi không hoạt động. Khi được bật, tin nhắn tiếp theo sau khoảng thời gian không hoạt động sẽ bắt đầu một session id mới cho khóa chat đó. Điều này không xóa transcript - nó chỉ bắt đầu một phiên mới.
{
  session: {
    idleMinutes: 240,
  },
}
Có, thông qua định tuyến đa agent và sub-agent. Bạn có thể tạo một agent điều phối và nhiều agent worker với workspace và model riêng.Dù vậy, tốt nhất nên xem đây là một thử nghiệm thú vị. Nó tốn nhiều token và thường kém hiệu quả hơn so với dùng một bot với các phiên riêng. Mô hình điển hình mà chúng tôi hình dung là một bot mà bạn trò chuyện, với các phiên khác nhau cho công việc song song. Bot đó cũng có thể tạo sub-agent khi cần.Tài liệu: Định tuyến đa agent, Sub-agent, CLI agent.
Context phiên bị giới hạn bởi cửa sổ model. Cuộc trò chuyện dài, output công cụ lớn, hoặc nhiều tệp có thể kích hoạt compaction hoặc cắt bớt.Những điều hữu ích:
  • 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.
  • Dùng /compact trước các tác vụ dài, và /new khi chuyển chủ đề.
  • Giữ context quan trọng trong workspace và yêu cầu bot đọc lại.
  • Dùng sub-agent cho công việc dài hoặc song song để chat chính nhỏ hơn.
  • Chọn model có cửa sổ context lớn hơn nếu việc này xảy ra thường xuyên.
Dùng lệnh reset:
openclaw reset
Reset toàn bộ không tương tác:
openclaw reset --scope full --yes --non-interactive
Sau đó chạy lại thiết lập:
openclaw onboard --install-daemon
Ghi chú:
  • Onboarding cũng cung cấp Reset nếu phát hiện cấu hình hiện có. Xem Onboarding (CLI).
  • Nếu bạn đã dùng profile (--profile / OPENCLAW_PROFILE), hãy reset từng state dir (mặc định là ~/.openclaw-<profile>).
  • Reset dev: openclaw gateway --dev --reset (chỉ dành cho dev; xóa cấu hình dev + credentials + phiên + workspace).
Dùng một trong các cách sau:
  • Compact (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 phần tóm tắt.
  • Reset (session ID mới cho cùng khóa chat): 
    /new
/reset
Nếu vẫn tiếp diễn:
  • Bật hoặc tinh chỉnh cắt tỉa phiên (agents.defaults.contextPruning) để cắt output công cụ cũ.
  • Dùng model có cửa sổ context lớn hơn.
Tài liệu: Compaction, Cắt tỉa phiên, Quản lý phiên.
Đây là lỗi xác thực của provider: model đã phát ra một khối tool_use thiếu trường bắt buộc input. Điều này thường nghĩa là lịch sử phiên đã cũ hoặc bị hỏng (thường sau các thread dài hoặc thay đổi công cụ/schema).Cách sửa: bắt đầu một phiên mới bằng /new (tin nhắn độc lập).
Heartbeat chạy mỗi 30m theo mặc định (1h khi dùng xác thực OAuth). Tinh chỉnh hoặc tắt chúng:
{
  agents: {
    defaults: {
      heartbeat: {
        every: "2h", // or "0m" to disable
      },
    },
  },
}
Nếu HEARTBEAT.md tồn tại nhưng thực chất trống (chỉ có dòng trống và header markdown như # Heading), OpenClaw bỏ qua lượt heartbeat để tiết kiệm API call. Nếu tệp bị thiếu, heartbeat vẫn chạy và model quyết định phải làm gì.Ghi đè theo từng agent dùng agents.list[].heartbeat. Tài liệu: Heartbeat.
Không. OpenClaw chạy trên tài khoản của chính bạn, nên nếu bạn ở trong nhóm, OpenClaw có thể thấy nhóm đó. Theo mặc định, trả lời trong nhóm bị chặn cho đến khi bạn cho phép người gửi (groupPolicy: "allowlist").Nếu bạn muốn chỉ bạn có thể kích hoạt trả lời trong nhóm:
{
  channels: {
    whatsapp: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15551234567"],
    },
  },
}
Tùy chọn 1 (nhanh nhất): tail log và gửi một tin nhắn thử trong nhóm:
openclaw logs --follow --json
Tìm chatId (hoặc from) kết thúc bằng @g.us, ví dụ: 1234567890-1234567890@g.us.Tùy chọn 2 (nếu đã được cấu hình/allowlist): liệt kê nhóm từ cấu hình:
openclaw directory groups list --channel whatsapp
Tài liệu: WhatsApp, Directory, Log.
Hai nguyên nhân thường gặp:
  • Cổng mention đang bật (mặc định). Bạn phải @mention bot (hoặc khớp mentionPatterns).
  • Bạn đã cấu hình channels.whatsapp.groups mà không có "*" và nhóm chưa được allowlist.
Xem Nhóm và Tin nhắn nhóm.
Chat trực tiếp mặc định được gộp vào phiên chính. Nhóm/kênh có khóa phiên riêng, và topic Telegram / thread Discord là các phiên riêng. Xem Nhóm và Tin nhắn nhóm.
Không có giới hạn cứng. Vài chục (thậm chí vài trăm) đều ổn, nhưng hãy lưu ý:
  • Dung lượng đĩa tăng: phiên + bản ghi nằm trong ~/.openclaw/agents/<agentId>/sessions/.
  • Chi phí token: nhiều tác tử hơn nghĩa là nhiều lượt dùng mô hình đồng thời hơn.
  • Chi phí vận hành: hồ sơ xác thực, workspace và định tuyến kênh theo từng tác tử.
Mẹo:
  • Giữ một workspace đang hoạt động cho mỗi tác tử (agents.defaults.workspace).
  • Dọn các phiên cũ (xóa JSONL hoặc mục lưu trữ) nếu dung lượng đĩa tăng.
  • Dùng openclaw doctor để phát hiện workspace sót lại và hồ sơ không khớp.
Có. Dùng Định tuyến đa tác tử để chạy nhiều tác tử biệt lập và định tuyến tin nhắn đến theo kênh/tài khoản/đối tượng ngang hàng. Slack được hỗ trợ như một kênh và có thể được gắn với các tác tử cụ thể.Quyền truy cập trình duyệt rất mạnh, nhưng không phải là “làm được mọi thứ như con người” - cơ chế chống bot, CAPTCHA và MFA vẫn có thể chặn tự động hóa. Để điều khiển trình duyệt đáng tin cậy nhất, hãy dùng Chrome MCP cục bộ trên máy chủ, hoặc dùng CDP trên máy thực sự chạy trình duyệt.Thiết lập khuyến nghị:
  • Máy chủ Gateway luôn bật (VPS/Mac mini).
  • Một tác tử cho mỗi vai trò (liên kết).
  • Các kênh Slack được gắn với các tác tử đó.
  • 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 tử, Slack, Trình duyệt, Nodes.

​
Mô hình, chuyển đổi dự phòng và hồ sơ xác thực

Hỏi đáp về mô hình — mặc định, lựa chọn, bí danh, chuyển đổi, chuyển đổi dự phòng, hồ sơ xác thực — nằm trong Câu hỏi thường gặp về mô hình.

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

gateway.port điều khiển một cổng ghép kênh duy nhất cho WebSocket + HTTP (Control UI, hooks, v.v.).Thứ tự ưu tiên:
--port > OPENCLAW_GATEWAY_PORT > gateway.port > default 18789
Vì “running” là góc nhìn của supervisor (launchd/systemd/schtasks). Kiểm tra kết nối là CLI thực sự kết nối đến WebSocket của Gateway.Dùng openclaw gateway status và tin vào các dòng này:
  • Probe target: (URL mà kiểm tra thực sự đã dùng)
  • Listening: (thứ thực sự đang được bind trên cổng)
  • Last gateway error: (nguyên nhân gốc thường gặp khi tiến trình còn sống nhưng cổng không lắng nghe)
Bạn đang sửa một tệp cấu hình trong khi dịch vụ chạy một tệp khác (thường là không khớp --profile / OPENCLAW_STATE_DIR).Cách sửa:
openclaw gateway install --force
Chạy lệnh đó từ cùng --profile / môi trường mà bạn muốn dịch vụ sử dụng.
OpenClaw áp dụng khóa runtime bằng cách bind bộ lắng nghe WebSocket ngay khi khởi động (mặc định ws://127.0.0.1:18789). Nếu bind thất bại với EADDRINUSE, nó ném GatewayLockError cho biết một phiên bản khác đang lắng nghe.Cách sửa: dừng phiên bản kia, giải phóng cổng, hoặc chạy với openclaw gateway --port <port>.
Đặt gateway.mode: "remote" và trỏ đến một URL WebSocket từ xa, tùy chọn kèm thông tin xác thực từ xa bằng bí mật dùng chung:
{
  gateway: {
    mode: "remote",
    remote: {
      url: "ws://gateway.tailnet:18789",
      token: "your-token",
      password: "your-password",
    },
  },
}
Ghi chú:
  • openclaw gateway chỉ khởi động 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 chế độ trực tiếp khi các giá trị này thay đổi.
  • gateway.remote.token / .password chỉ là thông tin xác thực từ xa phía máy khách; tự chúng không bật xác thực Gateway cục bộ.
Đường dẫn xác thực Gateway của bạn và phương thức xác thực của UI không khớp.Sự thật (từ mã):
  • Control UI giữ token trong sessionStorage cho phiên tab trình duyệt hiện tại và URL Gateway đã chọn, nên làm mới cùng tab vẫn hoạt động mà không khôi phục việc lưu token dài hạn trong localStorage.
  • Khi gặp AUTH_TOKEN_MISMATCH, máy khách tin cậy có thể thử lại có giới hạn một lần với token thiết bị đã lưu đệm khi Gateway trả về gợi ý thử lại (canRetryWithDeviceToken=true, recommendedNextStep=retry_with_device_token).
  • Lần thử lại bằng token đã lưu đệm đó giờ tái sử dụng các phạm vi đã phê duyệt được lưu cùng token thiết bị. Bên gọi deviceToken rõ ràng / scopes rõ ràng vẫn giữ tập phạm vi đã yêu cầu thay vì kế thừa phạm vi đã lưu đệm.
  • Ngoài đường dẫn thử lại đó, thứ tự ưu tiên xác thực kết nối là token/mật khẩu dùng chung rõ ràng trước, rồi deviceToken rõ ràng, rồi token thiết bị đã lưu, rồi bootstrap token.
  • Kiểm tra phạm vi bootstrap token có tiền tố vai trò. Danh sách cho phép operator bootstrap tích hợp chỉ thỏa mãn yêu cầu operator; Node hoặc các vai trò không phải operator khác vẫn cần phạm vi dưới tiền tố vai trò riêng của chúng.
Cách sửa:
  • Nhanh nhất: openclaw dashboard (in + sao chép URL dashboard, cố mở; hiển thị gợi ý SSH nếu không có giao diện).
  • Nếu bạn chưa có token: openclaw doctor --generate-gateway-token.
  • Nếu từ xa, tạo tunnel trước: ssh -N -L 18789:127.0.0.1:18789 user@host rồi mở http://127.0.0.1:18789/.
  • Chế độ bí mật dùng chung: đặt gateway.auth.token / OPENCLAW_GATEWAY_TOKEN hoặc gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD, rồi dán bí mật khớp vào phần cài đặt Control UI.
  • Chế độ Tailscale Serve: bảo đảm gateway.auth.allowTailscale được bật và bạn đang mở URL Serve, không phải URL loopback/tailnet thô bỏ qua header danh tính Tailscale.
  • Chế độ proxy tin cậy: bảo đảm bạn đang đi qua proxy nhận biết danh tính đã cấu hình, không phải URL Gateway thô. Proxy local loopback cùng máy chủ cũng cần gateway.auth.trustedProxy.allowLoopback = true.
  • Nếu không khớp vẫn tiếp diễn sau một lần thử lại, xoay/phê duyệt lại token thiết bị đã ghép:
    • openclaw devices list
    • openclaw devices rotate --device <id> --role operator
  • Nếu lệnh xoay đó báo bị từ chối, hãy kiểm tra hai điều:
    • phiên thiết bị đã ghép chỉ có thể xoay thiết bị của chính nó trừ khi chúng cũng có operator.admin
    • giá trị --scope rõ ràng không được vượt quá phạm vi operator hiện tại của bên gọi
  • Vẫn 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.
Bind tailnet 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 ở trên Tailscale (hoặc giao diện đang tắt), không có gì để bind.Cách sửa:
  • Khởi động Tailscale trên máy chủ đó (để nó có địa chỉ 100.x), hoặc
  • Chuyển sang gateway.bind: "loopback" / "lan".
Lưu ý: tailnet là tường minh. auto ưu tiên loopback; dùng gateway.bind: "tailnet" khi bạn muốn bind chỉ dành cho tailnet.
Thường là không - một Gateway có thể chạy nhiều kênh nhắn tin và tác tử. Chỉ dùng nhiều Gateway 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 từng phiên bản)
  • OPENCLAW_STATE_DIR (trạng thái theo từng phiên bản)
  • agents.defaults.workspace (cách ly workspace)
  • gateway.port (cổng duy nhất)
Thiết lập nhanh (khuyến nghị):
  • 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 cấu hình của từng hồ sơ (hoặc truyền --port cho các lần chạy thủ công).
  • Cài đặt dịch vụ theo từng hồ sơ: openclaw --profile <name> gateway install.
Hồ sơ cũng thêm hậu tố cho tên dịch vụ (ai.openclaw.<profile>; kế thừa 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ó kỳ vọng tin nhắn đầu tiên phải là một frame connect. Nếu nhận bất cứ thứ gì khác, nó đóng kết nối với mã 1008 (vi phạm chính sách).Nguyên nhân thường gặp:
  • Bạn đã mở URL HTTP trong trình duyệt (http://...) thay vì máy khách WS.
  • Bạn đã dùng sai cổng hoặc đường dẫn.
  • Proxy hoặc tunnel đã loại bỏ header xác thực hoặc gửi một yêu cầu không phải Gateway.
Cách sửa nhanh:
  1. Dùng URL WS: ws://<host>:18789 (hoặc wss://... nếu HTTPS).
  2. Đừng mở cổng WS trong tab trình duyệt bình thường.
  3. Nếu xác thực đang bật, hãy đưa token/mật khẩu vào frame connect.
Nếu bạn đang dùng CLI hoặc TUI, URL nên có dạng:
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 đường dẫn ổn định qua logging.file. Mức log tệp được điều khiển bởi logging.level. Độ chi tiết console được điều khiển 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ơ 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.
Dùng các helper Gateway:
openclaw gateway status
openclaw gateway restart
Nếu bạn chạy Gateway thủ công, openclaw gateway --force có thể lấy lạ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, rồi khởi động lại:
wsl
openclaw gateway status
openclaw gateway restart
Nếu bạn chưa từng cài đặt dịch vụ, hãy khởi động nó ở foreground:
openclaw gateway run
2) Windows gốc (không khuyến nghị): Gateway chạy trực tiếp trong Windows.Mở PowerShell và chạy:
openclaw gateway status
openclaw gateway restart
Nếu bạn chạy thủ công (không có dịch vụ), dùng:
openclaw gateway run
Tài liệu: Windows (WSL2), Runbook dịch vụ Gateway.
Bắt đầu bằng một lượt quét sức khỏe nhanh:
openclaw status
openclaw models status
openclaw channels status
openclaw logs --follow
Nguyên nhân thường gặp:
  • Xác thực mô hình chưa đượ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 đang chặn phản hồi (kiểm tra cấu hình kênh + nhật ký).
  • WebChat/Bảng điều khiển đang mở mà không có token đúng.
Nếu bạn đang truy cập từ xa, hãy xác nhận kết nối đường hầm/Tailscale đang hoạt động và WebSocket của 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 mạnh không? openclaw status
  3. UI có token đúng không? openclaw dashboard
  4. Nếu truy cập từ xa, liên kết đường hầm/Tailscale có đang hoạt động không?
Sau đó theo dõi nhật ký:
openclaw logs --follow
Tài liệu: Bảng điều khiển, Truy cập từ xa, Khắc phục sự cố.
Bắt đầu với nhật ký 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 bớt xuống giới hạn của Telegram và thử lại với ít lệnh hơn, nhưng một số mục menu vẫn cần bị loại bỏ. Giảm lệnh plugin/skill/tùy chỉnh, hoặc tắt channels.telegram.commands.native nếu bạn không cần menu.
  • TypeError: fetch failed, Network request for 'setMyCommands' failed!, hoặc các lỗi mạng tương tự: nếu bạn đang dùng VPS hoặc đứng sau proxy, hãy xác nhận HTTPS đi ra được cho phép và DNS hoạt động cho api.telegram.org.
Nếu Gateway ở xa, hãy đảm bảo bạn đang xem nhật ký trên máy chủ Gateway.Tài liệu: Telegram, Khắc phục sự cố kênh.
Trước tiên xác nhận Gateway có thể truy cập được và tác nhân có thể chạy:
openclaw status
openclaw models status
openclaw logs --follow
Trong TUI, 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, hãy đảm bảo việc gửi đượ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
Lệnh này dừng/khởi động dịch vụ được giám sát (launchd trên macOS, systemd trên Linux). Dùng cách này khi Gateway chạy nền dưới dạng daemon.Nếu bạn đang chạy ở nền trước, dừng bằng Ctrl-C, rồi:
openclaw gateway run
Tài liệu: Sổ tay vận hành dịch vụ Gateway.
  • openclaw gateway restart: khởi động lại dịch vụ nền (launchd/systemd).
  • openclaw gateway: chạy gateway ở nền trước cho phiên terminal này.
Nếu bạn đã cài đặt dịch vụ, hãy dùng các lệnh gateway. Dùng openclaw gateway khi bạn muốn chạy một lần ở nền trước.
Khởi động Gateway với --verbose để có thêm chi tiết trên console. Sau đó kiểm tra tệp nhật ký để xem lỗi xác thực kênh, định tuyến mô hình và RPC.

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

Tệp đính kèm gửi ra từ tác nhân phải bao gồm một dòng MEDIA:<path-or-url> (trên dòng riêng). Xem Thiết lập trợ lý OpenClaw và Gửi bằng tác nhân.Gửi bằng CLI:
openclaw message send --target +15555550123 --message "Here you go" --media /path/to/file.png
Cũng kiểm tra:
  • Kênh đích hỗ trợ phương tiện gửi ra và không bị danh sách cho phép chặn.
  • Tệp nằm trong giới hạn kích thước của nhà cung cấp (hình ảnh được đổi kích thước tối đa 2048px).
  • tools.fs.workspaceOnly=true giữ việc gửi đường dẫn cục bộ giới hạn trong workspace, temp/media-store và các tệp đã được sandbox xác thực.
  • tools.fs.workspaceOnly=false cho phép MEDIA: gửi các tệp cục bộ trên máy chủ mà tác nhân đã có thể đọc, nhưng chỉ cho phương tiện và các loại tài liệu an toàn (hình ảnh, âm thanh, video, PDF và tài liệu Office). Tệp văn bản thuần túy và các tệp giống bí mật vẫn bị chặn.
Xem Hình ảnh.

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

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

​
Lệnh trò chuyện, hủy tác vụ và “nó sẽ không dừng”

Hầu hết thông báo nội bộ hoặc thông báo công cụ chỉ xuất hiện khi verbose, trace hoặc reasoning được bật cho phiên đó.Sửa trong cuộc trò chuyện nơi bạn thấy nó:
/verbose off
/trace off
/reasoning off
Nếu vẫn còn nhiễu, hãy kiểm tra cài đặt phiên trong UI Điều khiển và đặt verbose thành kế thừa. Đồng thời xác nhận bạn không dùng hồ sơ bot có verboseDefault được đặ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ỳ nội dung nào sau đây dưới dạng một tin nhắn độc lập (không có 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 trình kích hoạt hủy (không phải lệnh gạch chéo).Với tiến trình nền (từ công cụ exec), bạn có thể yêu cầu tác nhân 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 lệnh phải được gửi dưới dạng một tin nhắn độc lập bắt đầu bằng /, nhưng một vài lối 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 xuyên nhà cung cấp theo mặc định. Nếu một lệnh gọi công cụ được ràng buộc với Telegram, nó sẽ không gửi tới Discord trừ khi bạn cho phép rõ ràng.Bật nhắn tin xuyên nhà cung cấp cho tác nhân:
{
  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.
Chế độ hàng đợi kiểm soát cách tin nhắn mới tương tác với một lượt chạy đang diễn ra. Dùng /queue để đổi chế độ:
  • steer - xếp hàng tất cả chỉ đạo đang chờ cho ranh giới mô hình tiếp theo trong lượt chạy hiện tại
  • queue - chỉ đạo kiểu cũ, mỗi lần một tin
  • followup - chạy từng tin nhắn một
  • collect - gom nhóm tin nhắn và trả lời một lần
  • steer-backlog - chỉ đạo ngay, rồi xử lý phần tồn đọng
  • interrupt - hủy lượt chạy hiện tại và bắt đầu mới
Chế độ mặc định là steer. Bạn có thể thêm các tùy chọn như debounce:0.5s cap:25 drop:summarize cho các chế độ theo dõi. Xem Hàng đợi lệnh và Hàng đợi điều hướng.

​
Khác

Trong OpenClaw, thông tin xác thực và lựa chọn mô hình là riêng biệt. Việc đặt ANTHROPIC_API_KEY (hoặc lưu khóa API Anthropic trong hồ sơ xác thực) sẽ bật 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 đó nghĩa là Gateway không tìm thấy thông tin xác thực Anthropic trong auth-profiles.json dự kiến cho tác tử đang chạy.
Vẫn chưa giải quyết được? Hãy hỏi trong Discord hoặc mở một thảo luận trên GitHub.

​
Liên quan