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

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

1

Trạng thái nhanh

Bản tóm tắt cục bộ nhanh: hệ điều hành + bản cập nhật, khả năng kết nối đến Gateway/dịch vụ, tác tử/phiên, cấu hình nhà cung cấp + sự cố thời gian chạy (khi có thể kết nối đến Gateway).
2

Báo cáo có thể dán (an toàn để chia sẻ)

Chẩn đoán chỉ đọc kèm phần cuối nhật ký (token đã được che).
3

Trạng thái daemon + cổng

Hiển thị trạng thái thời gian chạy của trình giám sát so với khả năng kết nối RPC, URL đích của phép thăm dò và cấu hình mà dịch vụ có thể đã sử dụng.
4

Thăm dò chuyên sâu

Thăm dò trực tiếp tình trạng của Gateway, bao gồm thăm dò kênh khi được hỗ trợ (yêu cầu Gateway có thể kết nối). Xem Tình trạng.
5

Theo dõi nhật ký mới nhất

Nếu RPC ngừng hoạt động, hãy dùng phương án dự phòng:
Nhật ký tệp tách biệt với nhật ký dịch vụ; xem Ghi nhật ký và Khắc phục sự cố.
6

Chạy doctor (sửa chữa)

Sửa chữa/di chuyển cấu hình và trạng thái, sau đó chạy kiểm tra tình trạng. Xem Doctor.
7

Ảnh chụp nhanh Gateway (chỉ WS)

Yêu cầu Gateway đang chạy cung cấp ảnh chụp nhanh đầy đủ. Xem Tình trạng.

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

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

​
OpenClaw là gì?

OpenClaw là một trợ lý AI cá nhân mà bạn chạy trên thiết bị của riêng mình. Trợ lý phản hồi trên các nền tảng nhắn tin bạn đã sử dụng (Discord, Google Chat, iMessage, Mattermost, Signal, Slack, Telegram, WebChat, WhatsApp và các plugin kênh đi kèm như QQ Bot), đồng thời cũng có thể hỗ trợ giọng nói cùng 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 hoạt động; trợ lý chính là sản phẩm.
OpenClaw không “chỉ là một lớp bọc Claude”. Đây là một mặt phẳng điều khiển ưu tiên cục bộ 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 trò chuyện bạn đã sử dụng, với phiên có trạng thái, bộ nhớ và công cụ — mà không phải giao quy trình làm việc của bạn cho một dịch vụ SaaS được lưu trữ.
  • 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à lưu cục bộ không gian làm việc cùng lịch sử phiên.
  • Kênh thực, không phải môi trường web cô lập: Discord/iMessage/Signal/Slack/Telegram/WhatsApp/v.v., cùng giọng nói trên thiết bị 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, MiniMax, OpenAI, 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ỉ chạy cục bộ: chạy các mô hình cục bộ để toàn bộ dữ liệu có thể được giữ trên thiết bị của bạn.
  • Định tuyến đa tác tử: tách riêng tác tử theo từng kênh, tài khoản hoặc tác vụ, mỗi tác tử có không gian làm việc và giá trị 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ị phụ thuộc vào nhà cung cấp.
Tài liệu: Gateway, Kênh, Đa tác tử, Bộ nhớ.
Những dự án khởi đầu phù hợp: xây dựng một trang web (WordPress, Shopify hoặc trang tĩnh); tạo nguyên mẫu ứng dụng di động (dàn ý, màn hình, kế hoạch API); sắp xếp tệp và thư mục; kết nối Gmail và tự động hóa phần tóm tắt hoặc nhắc việc tiếp theo.OpenClaw có thể xử lý các tác vụ lớn, nhưng hoạt động tốt nhất khi tác vụ được chia thành nhiều giai đoạn với các tác tử con làm việc song song.
  • Bản tin cá nhân: tóm tắt hộp thư đến, lịch và tin tức mà bạn quan tâm.
  • Nghiên cứu và soạn thảo: nghiên cứu nhanh, tóm tắt và tạo bản nháp đầu tiên cho email hoặc tài liệu.
  • Nhắc nhở và theo dõi: lời nhắc và danh sách kiểm tra được kích hoạt bằng cron hoặc heartbeat.
  • Tự động hóa trình duyệt: điền biểu mẫu, thu thập dữ liệu, lặp lại các tác vụ web.
  • Phối hợp giữa các thiết bị: gửi tác vụ từ điện thoại, để Gateway chạy tác vụ đó trên máy chủ rồi nhận lại kết quả trong cuộc trò chuyện.
Có, đối với nghiên cứu, đánh giá mức độ phù hợp và soạn thảo: quét các trang web, tạo danh sách rút gọn, tóm tắt khách hàng tiềm năng, viết bản nháp nội dung tiếp cận hoặc quảng cáo.Đối với các chiến dịch tiếp cận hoặc quảng cáo, hãy luôn để con người tham gia kiểm soát. Tránh gửi thư rác, tuân thủ luật pháp địa phương và chính sách nền tảng, đồng thời xem xét mọi nội dung trước khi gửi. Hãy để OpenClaw soạn thảo; bạn phê duyệt.Tài liệu: Bảo mật.
OpenClaw là một trợ lý cá nhân và lớp điều phối, không phải công cụ thay thế IDE. Sử dụng Claude Code hoặc Codex để có vòng lặp lập trình trực tiếp nhanh nhất bên trong kho mã nguồn. Sử dụng OpenClaw để có bộ nhớ lâu dài, khả năng truy cập giữa các thiết bị và điều phối công cụ.
  • Bộ nhớ và không gian làm việc được duy trì xuyên suốt các phiên.
  • Truy cập đa nền tảng (Telegram, WhatsApp, TUI, WebChat).
  • Điều phối công cụ (trình duyệt, tệp, lập lịch, hook).
  • Gateway luôn hoạt động (chạy trên VPS, tương tác từ bất cứ đâu).
  • Các Node để sử dụng trình duyệt/màn hình/camera/thực thi cục bộ.
Nội dung tiêu biểu: https://openclaw.ai/showcase.

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

Sử dụng các ghi đè được quản lý thay vì chỉnh sửa bản sao trong kho mã nguồn. Đặt các thay đổi vào ~/.openclaw/skills/<name>/SKILL.md (hoặc thêm thư mục thông qua skills.load.extraDirs trong ~/.openclaw/openclaw.json). Thứ tự ưu tiên: <workspace>/skills -> <workspace>/.agents/skills -> ~/.agents/skills -> ~/.openclaw/skills -> đi kèm -> skills.load.extraDirs, vì vậy các ghi đè được quản lý sẽ được ưu tiên hơn Skills đi kèm mà không cần tác động đến git. Để cài đặt toàn cục nhưng chỉ cho phép một số tác tử nhìn thấy, hãy 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 / agents.list[].skills. Chỉ những chỉnh sửa phù hợp để đóng góp ngược lên thượng nguồn mới nên được gửi dưới dạng PR cho bản sao trong kho mã nguồn.
Có: thêm các thư mục thông qua skills.load.extraDirs trong ~/.openclaw/openclaw.json (mức ưu tiên thấp nhất theo thứ tự trên). Theo mặc định, clawhub cài đặt vào ./skills, nơi OpenClaw sẽ coi là <workspace>/skills trong phiên tiếp theo. Để giới hạn khả năng hiển thị cho một số tác tử nhất định, hãy kết hợp với agents.defaults.skills hoặc agents.list[].skills.
Các mẫu được hỗ trợ:
  • Công việc Cron: các công việc cô lập có thể đặt ghi đè model cho từng công việc.
  • Tác tử: định tuyến tác vụ đến các tác tử riêng biệt với mô hình mặc định, mức suy luận và tham số luồng khác nhau.
  • Chuyển đổi theo yêu cầu: /model chuyển đổi mô hình của phiên hiện tại bất cứ lúc nào.
Ví dụ — cùng một mô hình, chế độ cài đặt khác nhau theo từng tác tử:
Đặt các giá trị mặc định dùng chung theo từng mô hình trong agents.defaults.models["provider/model"].params, sau đó đặt các ghi đè riêng theo từng tác tử trong agents.list[].params dạng phẳng. Không sao chép cùng một mô hình vào agents.list[].models["provider/model"].params lồng nhau; đường dẫn đó dành cho danh mục mô hình và các ghi đè thời gian chạy theo từng tác tử.Xem Công việc Cron, Định tuyến đa tác tử, Cấu hình, Lệnh dấu gạch chéo.
Sử dụng tác tử con cho các tác vụ kéo dài hoặc song song: chúng chạy trong phiên riêng, trả về bản tóm tắt và giữ cho cuộc trò chuyện chính luôn phản hồi. Yêu cầu bot “tạo một tác tử con cho tác vụ này” hoặc sử dụng /subagents. Sử dụng /status để xem Gateway hiện có đang bận hay không.Cả tác vụ kéo dài và tác tử con đều tiêu thụ token; hãy đặt mô hình rẻ hơn cho tác tử con thông qua agents.defaults.subagents.model nếu chi phí là yếu tố quan trọng.Tài liệu: Tác tử con, Tác vụ nền.
Liên kết một luồng Discord với tác tử con hoặc đích phiên để các tin nhắn tiếp theo tại đó vẫn thuộc phiên đã liên kết.
  • Tạo bằng sessions_spawn sử dụng thread: true (tùy chọn mode: "session" để duy trì việc theo dõi).
  • Hoặc liên kết thủ công bằng /focus <target>.
  • /agents kiểm tra trạng thái liên kết.
  • /session idle <duration|off> và /session max-age <duration|off> kiểm soát việc tự động bỏ tập trung.
  • /unfocus ngắt liên kết luồng.
Cấu hình: session.threadBindings.enabled (công tắc toàn cục), session.threadBindings.idleHours (mặc định 24, 0 để tắt), session.threadBindings.maxAgeHours (mặc định 0 = không có giới hạn cứng) và các ghi đè theo từng kênh channels.discord.threadBindings.{enabled,idleHours,maxAgeHours}. channels.discord.threadBindings.spawnSessions kiểm soát tự động liên kết khi tạo (mặc định true).Tài liệu: Tác tử con, Discord, Tài liệu tham chiếu cấu hình, Lệnh dấu gạch chéo.
Kiểm tra tuyến người yêu cầu đã được phân giải:
  • Việc phân phối từ tác tử con ở chế độ hoàn thành ưu tiên luồng hoặc tuyến hội thoại đã liên kết khi có.
  • Nếu nguồn hoàn thành chỉ chứa kênh, OpenClaw sẽ quay về tuyến đã lưu của phiên người yêu cầu (lastChannel / lastTo / lastAccountId) để việc phân phối trực tiếp vẫn có thể thành công.
  • Không có tuyến đã liên kết và không có tuyến đã lưu khả dụng: việc phân phối trực tiếp có thể thất bại và kết quả sẽ chuyển sang phân phối phiên qua hàng đợi thay vì được đăng ngay lập tức.
  • Đích không hợp lệ hoặc lỗi thời cũng có thể buộc hệ thống chuyển sang hàng đợi dự phòng hoặc khiến việc phân phối cuối cùng thất bại.
  • Nếu phản hồi hiển thị cuối cùng của trợ lý con chính xác là NO_REPLY / no_reply hoặc ANNOUNCE_SKIP, OpenClaw sẽ chủ động ngăn thông báo thay vì đăng tiến trình cũ trước đó.
Gỡ lỗi: openclaw tasks show <lookup>, trong đó <lookup> là ID tác vụ, ID lần chạy hoặc khóa phiên.Tài liệu: Tác tử con, Tác vụ nền, Công cụ phiên.
Cron chạy bên trong tiến trình Gateway; nó không kích hoạt nếu Gateway không chạy liên tục.
  • Xác nhận cron đã được bật (cron.enabled) và OPENCLAW_SKIP_CRON chưa được đặt.
  • Xác nhận Gateway chạy 24/7 (không ngủ/khởi động lại).
  • Xác minh múi giờ của công việc (--tz so với múi giờ của máy chủ).
Gỡ lỗi:
Tài liệu: Tác vụ Cron, Tự động hóa.
Kiểm tra chế độ gửi:
  • --no-deliver / delivery.mode: "none": không dự kiến gửi dự phòng từ trình chạy.
  • Thiếu hoặc mục tiêu thông báo không hợp lệ (channel / to): trình chạy đã bỏ qua việc gửi ra ngoài.
  • Lỗi xác thực kênh (unauthorized, Forbidden): trình chạy đã cố gửi nhưng thông tin xác thực đã chặn việc này.
  • Kết quả cô lập im lặng (chỉ có NO_REPLY / no_reply) được coi là chủ ý không gửi, vì vậy việc gửi dự phòng trong hàng đợi cũng bị ngăn.
Đối với các tác vụ Cron cô lập, tác nhân 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 việc gửi dự phòng của trình chạy đối với văn bản cuối cùng mà tác nhân chưa tự gửi.Gỡ lỗi:
Tài liệu: Tác vụ Cron, Tác vụ nền.
Đây là đường chuyển đổi mô hình trực tiếp, không phải lập lịch trùng lặp. Cron cô lập lưu việc chuyển giao mô hình thời gian chạy và thử lại khi lượt chạy đang hoạt động ném ra LiveSessionModelSwitchError, đồng thời giữ nguyên nhà cung cấp/mô hình đã chuyển đổi (và mọi ghi đè hồ sơ xác thực đã chuyển đổi) trước khi thử lại.Thứ tự ưu tiên chọn mô hình: ghi đè mô hình của hook Gmail (hooks.gmail.model) trước tiên, sau đó là model theo từng tác vụ, tiếp theo là mọi ghi đè mô hình phiên Cron đã lưu, rồi đến lựa chọn mô hình tác nhân/mặc định thông thường.Vòng lặp thử lại được giới hạn ở lần thử ban đầu cộng với 2 lần thử lại chuyển đổi; sau đó Cron sẽ hủy thay vì lặp vô hạn.Gỡ lỗi:
Tài liệu: Tác vụ Cron, CLI cron.
Sử dụng các lệnh openclaw skills gốc hoặc đưa Skills vào không gian làm việc; giao diện Skills trên macOS không khả dụng trên Linux. Duyệt Skills tại https://clawhub.ai.
Theo mặc định, openclaw skills install gốc ghi vào thư mục skills/ của không gian làm việc đang hoạt động. Thêm --global để cài đặt vào thư mục Skills dùng chung được quản lý cho tất cả tác nhân cục bộ. Chỉ cài đặt CLI clawhub riêng biệt để xuất bản hoặc đồng bộ Skills của riêng bạn. Sử dụng agents.defaults.skills hoặc agents.list[].skills để giới hạn những tác nhân có thể thấy Skills dùng chung.
Có, thông qua bộ lập lịch Gateway:
  • Tác vụ Cron dành cho các tác vụ được lập lịch hoặc định kỳ (được duy trì qua các lần khởi động lại).
  • Heartbeat dành cho các lần kiểm tra định kỳ của phiên chính.
  • Tác vụ cô lập dành cho các tác nhân tự chủ đăng bản 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 thể trực tiếp. Skills macOS được kiểm soát bởi metadata.openclaw.os cùng các tệp nhị phân bắt buộc và chỉ tải khi đủ điều kiện trên máy chủ Gateway. Trên Linux, Skills chỉ dành cho darwin (apple-notes, apple-reminders, things-mac) sẽ không tải trừ khi bạn ghi đè điều kiện kiểm soát.Ba mô hình được hỗ trợ:Phương án A - chạy Gateway trên máy Mac (đơn giản nhất). Chạy Gateway tại nơi có các tệp nhị phân macOS, sau đó 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.Phương án B - sử dụng Node macOS (không cần SSH). Chạy Gateway trên Linux, ghép đôi một Node macOS (ứng dụng thanh menu), rồi đặt Node Run Commands thành “Always Ask” hoặc “Always Allow” trên máy Mac. OpenClaw coi Skills chỉ dành cho macOS là đủ điều kiện khi các tệp nhị phân bắt buộc tồn tại trên Node; tác nhân chạy chúng qua công cụ nodes. Với “Always Ask”, việc phê duyệt “Always Allow” trong lời nhắc sẽ thêm lệnh đó vào danh sách cho phép.Phương án C - ủy quyền tệp nhị phân macOS qua SSH (nâng cao). Giữ Gateway trên Linux, nhưng cấu hình để các tệp nhị phân CLI bắt buộc phân giải thành trình bao bọc SSH chạy trên máy Mac, sau đó ghi đè Skill để cho phép Linux nhằm duy trì trạng thái đủ điều kiện.
  1. Tạo trình bao bọc SSH cho tệp nhị phân (ví dụ: memo cho Apple Notes):
  2. Đặt trình bao bọc vào PATH trên máy chủ Linux (ví dụ ~/bin/memo).
  3. Ghi đè siêu dữ liệu Skill (không gian làm việc hoặc ~/.openclaw/skills) để cho phép Linux:
  4. Bắt đầu một phiên mới để làm mới ảnh chụp nhanh Skills.
Hiện chưa được tích hợp sẵn. Các lựa chọn:
  • Skill / Plugin tùy chỉnh: phù hợp nhất để truy cập API ổn định (cả hai đề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ễ lỗi hơn.
Đối với ngữ cảnh riêng cho từng khách hàng theo mô hình đại lý: duy trì một trang Notion cho mỗi khách hàng (ngữ cảnh + tùy chọn + công việc đang thực hiện) và yêu cầu tác nhân truy xuất trang đó khi bắt đầu phiên.Để có tích hợp gốc, hãy mở yêu cầu tính năng hoặc xây dựng một Skill dựa trên các API đó.
Các bản cài đặt gốc được đặt vào thư mục skills/ của không gian làm việc đang hoạt động; sử dụng --global cho tất cả tác nhân cục bộ hoặc cấu hình agents.defaults.skills / agents.list[].skills để giới hạn khả năng hiển thị. Một số Skills yêu cầu tệp nhị phân được cài đặt bằng Homebrew; trên Linux, điều đó có nghĩa là Linuxbrew.Xem Skills, Cấu hình Skills, ClawHub.
Sử dụng hồ sơ trình duyệt user tích hợp sẵn, hồ sơ này kết nối qua Chrome DevTools MCP:
Để sử dụng tên tùy chỉnh, hãy tạo một hồ sơ MCP rõ ràng:
Cách này có thể sử dụng trình duyệt trên máy chủ 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áy chủ Node trên máy có trình duyệt hoặc sử dụng CDP từ xa.Các giới hạn hiện tại của hồ sơ existing-session / user so với hồ sơ openclaw được quản lý:
  • click, type, hover, scrollIntoView, drag và select yêu cầu tham chiếu ảnh chụp nhanh, không phải bộ chọn CSS.
  • Các hook tải lên yêu cầu ref hoặc inputRef, mỗi lần một tệp, không có CSS element.
  • responsebody, xuất PDF, chặn tải xuống và các hành động hàng loạt vẫn yêu cầu đường dẫn trình duyệt được quản lý.
Xem Trình duyệt để biết bản so sánh đầy đủ.

​
Hộp cát và bộ nhớ

Có: Hộp cát. Để biết cách thiết lập riêng cho Docker (toàn bộ Gateway trong Docker hoặc các ảnh hộp cát), xem Docker.
Ảnh mặc định ưu tiên bảo mật và chạy dưới người dùng node, vì vậy ảnh này không bao gồm các gói hệ thống, Homebrew và trình duyệt đi kèm. Để thiết lập đầy đủ hơn:
  • Duy trì /home/node bằng OPENCLAW_HOME_VOLUME để bộ nhớ đệm không bị mất.
  • Đưa các phần phụ thuộc hệ thống vào ảnh bằng OPENCLAW_IMAGE_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à duy trì đường dẫn đó.
Tài liệu: Docker, Trình duyệt.
Có, nếu lưu lượng riêng tư là tin nhắn trực tiếp và lưu lượng công khai là nhóm. Đặt agents.defaults.sandbox.mode: "non-main" để các phiên nhóm/kênh (khóa không phải khóa chính) chạy trong backend hộp cát đã cấu hình trong khi phiên tin nhắn trực tiếp chính vẫn chạy trên máy chủ. Docker là backend mặc định sau khi bật hộp cát. Hạn chế các công cụ khả dụng trong phiên hộp cát qua tools.sandbox.tools.Hướng dẫn thiết lập: Nhóm: tin nhắn trực tiếp cá nhân + nhóm công khai. Tham khảo chính: Cấu hình Gateway.
Đặt agents.defaults.sandbox.docker.binds thành ["host:container:mode"] (ví dụ "/home/user/src:/src:ro"). Các liên kết gắn toàn cục và theo từng tác nhân được hợp nhất; liên kết gắn theo từng tác nhân bị bỏ qua khi scope: "shared". Sử dụng :ro cho mọi nội dung nhạy cảm; các liên kết gắn bỏ qua rào chắn hệ thống tệp của hộp cát.OpenClaw xác thực nguồn liên kết gắn dựa trên cả đường dẫn đã chuẩn hóa và đường dẫn chính tắc được phân giải qua tổ tiên tồn tại sâu nhất, vì vậy các hành vi thoát qua thư mục cha là liên kết tượng trưng sẽ bị từ chối an toàn ngay cả khi đoạn cuối của đường dẫn chưa tồn tại.Xem Hộp cát và Hộp cát so với chính sách công cụ so với quyền nâng cao.
Bộ nhớ OpenClaw là các tệp Markdown trong không gian làm việc của tác nhân: 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ỉ dành cho phiên chính/riêng tư).OpenClaw cũng chạy một lần xả bộ nhớ trước Compaction im lặng trước khi Compaction tóm tắt cuộc trò chuyện, nhắc mô hình ghi các ghi chú bền vững trước. Quá trình này chỉ chạy khi không gian làm việc có thể ghi (hộp cát chỉ đọc sẽ bỏ qua); tắt bằng agents.defaults.compaction.memoryFlush.enabled: false. Xem Bộ nhớ.
Yêu cầu bot ghi thông tin vào bộ nhớ: ghi chú dài hạn được lưu trong MEMORY.md, ngữ cảnh ngắn hạn trong memory/YYYY-MM-DD.md. Việc nhắc mô hình lưu ký ức thường sẽ giải quyết vấn đề. Nếu vẫn tiếp tục quên, hãy xác minh Gateway sử dụng cùng một không gian làm việc trong mọi lượt chạy.Tài liệu: Bộ nhớ, Không gian làm việc của tác nhân.
Các tệp bộ nhớ nằm trên đĩa và tồn tại cho đến khi bị xóa; 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ể được nén hoặc cắt bớt - đó là lý do tính năng tìm kiếm bộ nhớ tồn tại, chỉ đưa 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 sử dụng embedding của OpenAI, đây là nhà cung cấp mặc định. OAuth của Codex hỗ trợ trò chuyện/hoàn thành và không cấp quyền truy cập embedding, vì vậy việc đăng nhập bằng Codex (OAuth hoặc thông tin đăng nhập CLI của Codex) không bật tính năng tìm kiếm bộ nhớ ngữ nghĩa. Embedding của OpenAI vẫn cần khóa API thực (OPENAI_API_KEY hoặc models.providers.openai.apiKey).Để duy trì xử lý cục bộ, hãy đặt agents.defaults.memorySearch.provider: "local" (GGUF/llama.cpp). Các nhà cung cấp được hỗ trợ khác: Bedrock, DeepInfra, Gemini (GEMINI_API_KEY hoặc memorySearch.remote.apiKey), GitHub Copilot, LM Studio, Mistral, Ollama, tương thích với OpenAI và Voyage. Xem Bộ nhớ và Tìm kiếm bộ nhớ để biết chi tiết thiết lập.

​
Vị trí lưu trữ trên đĩa

Không: trạng thái riêng của OpenClaw được lưu 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ọ.
  • Mặc định cục bộ: các phiên, tệp bộ nhớ, cấu hình và không gian làm việc nằm trên máy chủ Gateway (~/.openclaw cùng thư mục không gian làm việc của bạn).
  • Bắt buộc từ xa: các thông báo gửi đến nhà cung cấp mô hình (Anthropic/OpenAI/v.v.) được chuyển đến API của họ, còn các nền tảng trò chuyện (Slack/Telegram/WhatsApp/v.v.) lưu trữ 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: các mô hình cục bộ giữ lời nhắc 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: Không gian làm việc của tác nhân, Bộ nhớ.
Mọi thứ nằm trong $OPENCLAW_STATE_DIR (mặc định: ~/.openclaw):Đường dẫn một tác nhân cũ ~/.openclaw/agent/* được openclaw doctor di chuyển.Không gian làm việc của bạn (AGENTS.md, các tệp bộ nhớ, Skills, v.v.) nằm riêng biệt, được cấu hình qua agents.defaults.workspace (mặc định: ~/.openclaw/workspace).
Các tệp này nằm trong không gian làm việc của tác nhân, không phải ~/.openclaw.
  • Không gian làm việc (theo từng tác nhân): AGENTS.md, SOUL.md, IDENTITY.md, USER.md, MEMORY.md, memory/YYYY-MM-DD.md, HEARTBEAT.md tùy chọn. Thư mục gốc viết thường memory.md chỉ là dữ liệu đầu vào sửa chữa cũ; openclaw doctor --fix có thể hợp nhất nó vào MEMORY.md khi cả hai cùng tồn tại.
  • Thư mục trạng thái (~/.openclaw): cấu hình, trạng thái kênh/nhà cung cấp, hồ sơ xác thực, phiên, nhật ký, Skills dùng chung (~/.openclaw/skills).
Không gian làm việc mặc định là ~/.openclaw/workspace, có thể cấu hình:
Nếu bot “quên” sau khi khởi động lại, hãy xác nhận Gateway sử dụng cùng một không gian làm việc trong mỗi lần khởi chạy (chế độ từ xa sử dụng không gian làm việc của máy chủ Gateway, không phải máy tính xách tay cục bộ của bạn).Mẹo: đối với hành vi hoặc tùy chọn cần duy trì lâu dài, hãy yêu cầu bot ghi nội dung đó vào AGENTS.md hoặc MEMORY.md thay vì dựa vào lịch sử trò chuyện.Xem Không gian làm việc của tác nhân và Bộ nhớ.
Có. SOUL.md là một trong các tệp khởi tạo không gian làm việc được đưa vào ngữ cảnh tác nhân. Giới hạn đưa vào mặc định cho mỗi tệp là 20000 ký tự; tổng dung lượng khởi tạo trên tất cả các tệp là 60000 ký tự.Thay đổi giá trị mặc định dùng chung:
Hoặc ghi đè một tác nhân trong agents.list[].bootstrapMaxChars / bootstrapTotalMaxChars.Sử dụng /context để kiểm tra kích thước thô so với kích thước được đưa vào và xem có xảy ra việc cắt bớt hay không. Giữ SOUL.md tập trung vào giọng điệu, lập trường và tính cách; đặt các quy tắc vận hành trong AGENTS.md và các dữ kiện lâu dài trong bộ nhớ.Xem Ngữ cảnh và Cấu hình tác nhân.
Đặt không gian làm việc của tác nhân vào một kho git riêng tư và sao lưu ở một nơi riêng tư (ví dụ: GitHub private). Việc này lưu lại bộ nhớ cùng 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ỳ nội dung nào trong ~/.openclaw (thông tin xác thực, phiên, token, dữ liệu bí mật được mã hóa). Để khôi phục đầy đủ, hãy sao lưu riêng không gian làm việc và thư mục trạng thái.Tài liệu: Không gian làm việc của tác nhân.
Có. Không gian làm việc là cwd mặc định và điểm neo bộ nhớ, không phải sandbox cứng. Các đường dẫn tương đối được phân giải bên trong không gian làm việc; các đường dẫn tuyệt đối có thể truy cập các vị trí khác trên máy chủ trừ khi tính năng sandbox được bật. Để cô lập, hãy sử dụng agents.defaults.sandbox hoặc cài đặt sandbox theo từng tác nhân. Để đặt một kho lưu trữ làm thư mục làm việc mặc định, hãy trỏ workspace của tác nhân đó đến thư mục gốc của kho lưu trữ - bản thân kho lưu trữ OpenClaw chỉ là mã nguồn, vì vậy hãy giữ không gian làm việc tách biệt trừ khi bạn chủ ý muốn tác nhân làm việc bên trong kho.
Trạng thái phiên thuộc quyền sở hữu của máy chủ Gateway. Trong chế độ từ xa, kho lưu trữ phiên 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 Quản lý phiên.

​
Kiến thức 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). Nếu thiếu tệp này, OpenClaw sử dụng các giá trị mặc định tương đối an toàn, bao gồm không gian làm việc mặc định là ~/.openclaw/workspace.
Các liên kết không phải loopback yêu cầu một đường dẫn xác thực Gateway hợp lệ: xác thực bằng bí mật dùng chung (token hoặc mật khẩu), hoặc gateway.auth.mode: "trusted-proxy" phía sau proxy ngược nhận biết danh tính được cấu hình đúng.
  • gateway.remote.token / .password tự chúng không bật xác thực Gateway cục bộ; các đường dẫn gọi cục bộ chỉ có thể sử dụng gateway.remote.* làm phương án dự phòng khi gateway.auth.* chưa được đặt.
  • Đối với xác thực bằng mật khẩu, hãy đặt gateway.auth.mode: "password" cùng với gateway.auth.password (hoặc OPENCLAW_GATEWAY_PASSWORD).
  • Nếu gateway.auth.token / .password được cấu hình rõ ràng qua SecretRef nhưng không thể phân giải, quá trình phân giải sẽ đóng khi lỗi (không có phương án dự phòng từ xa che giấu lỗi).
  • Các thiết lập Control UI dùng bí mật chung 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/giao diện người dùng). Các chế độ mang danh tính như Tailscale Serve hoặc trusted-proxy sử dụng tiêu đề yêu cầu thay thế - tránh đưa bí mật dùng chung vào URL.
  • Với gateway.auth.mode: "trusted-proxy", proxy ngược loopback trên cùng máy chủ yêu cầu gateway.auth.trustedProxy.allowLoopback = true rõ ràng và một mục loopback trong gateway.trustedProxies.
OpenClaw mặc định thực thi xác thực Gateway, bao gồm cả loopback. Nếu không có đường dẫn xác thực rõ ràng nào được cấu hình, quá trình khởi động sẽ chọn chế độ token và tạo một token chỉ tồn tại trong thời gian chạy cho lần khởi động đó, vì vậy các máy khách WS cục bộ phải xác thực. Điều này ngăn các tiến trình cục bộ khác gọi Gateway.Cấu hình rõ ràng gateway.auth.token, gateway.auth.password, OPENCLAW_GATEWAY_TOKEN hoặc OPENCLAW_GATEWAY_PASSWORD khi máy khách cần bí mật ổn định qua các lần khởi động lại. Bạn cũng có thể chọn chế độ mật khẩu hoặc trusted-proxy cho proxy ngược nhận biết danh tính. Để mở loopback, hãy đặt rõ ràng gateway.auth.mode: "none". openclaw doctor --generate-gateway-token tạo token bất kỳ lúc nào.
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 và khởi động lại đối với các thay đổi quan trọng. hot, restart và off cũng được hỗ trợ. Hầu hết các thay đổi đối với tools.*, chính sách agents.*, session.* và messages.* được áp dụng ngay lập tức mà không cần bất kỳ thao tác tải lại nào; các thay đổi về liên kết/cổng gateway.* yêu cầu khởi động lại.
Đặt cli.banner.taglineMode:
  • off: ẩn văn bản khẩu hiệu nhưng giữ lại dòng tiêu đề/phiên bản của biểu ngữ.
  • default: luôn sử dụng All your chats, one OpenClaw..
  • random: luân phiên các khẩu hiệu hài hước/theo mùa (hành vi mặc định).
  • Để không hiển thị biểu ngữ nào, hãy đặt biến môi trường OPENCLAW_HIDE_BANNER=1.
web_fetch hoạt động mà không cần khóa API. web_search phụ thuộc vào nhà cung cấp bạn chọn:Grok cũng có thể tái sử dụng OAuth xAI từ xác thực mô hình (openclaw onboard --auth-choice xai-oauth).Khuyến nghị: openclaw configure --section web và chọn một nhà cung cấp.
Cấu hình tìm kiếm web dành riêng cho từng nhà cung cấp nằm trong plugins.entries.<plugin>.config.webSearch.*. Các đường dẫn nhà cung cấp tools.web.search.* cũ vẫn được tải để tương thích nhưng không nên dùng trong cấu hình mới. Cấu hình dự phòng tìm nạp web của Firecrawl nằm trong plugins.entries.firecrawl.config.webFetch.*.
  • Danh sách cho phép: thêm web_search/web_fetch/x_search, hoặc group:web cho cả ba.
  • web_fetch được bật theo mặc định.
  • Nếu bỏ qua tools.web.fetch.provider, OpenClaw tự động phát hiện nhà cung cấp dự phòng tìm nạp sẵn sàng đầu tiên từ các thông tin xác thực hiện có; Plugin Firecrawl chính thức cung cấp phương án dự phòng đó.
  • Các 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; một đối tượng không đầy đủ sẽ loại bỏ mọi thứ khác.OpenClaw hiện tại bảo vệ khỏi hầu hết các trường hợp vô tình ghi đè:
  • Các thao tác ghi cấu hình do OpenClaw sở hữu xác thực toàn bộ cấu hình sau khi thay đổi trước khi ghi.
  • Các thao tác ghi không hợp lệ hoặc có tính phá hủy do OpenClaw sở hữu sẽ bị từ chối và lưu dưới dạng openclaw.json.rejected.*.
  • Một 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 sẽ khiến Gateway đóng khi lỗi hoặc bỏ qua việc tải lại; thao tác này không ghi lại openclaw.json.
  • openclaw doctor --fix chịu trách nhiệm sửa chữa, có thể khôi phục trạng thái tốt gần nhất và 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 không có trạng thái tốt gần nhất hoặc payload bị từ chối: 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 mất dữ liệu ngoài dự kiến: hãy báo lỗi kèm cấu hình gần nhất mà bạn biết hoặc bản sao lưu. Một agent lập trình cục bộ thường có thể tái dựng cấu hình hoạt động từ nhật ký hoặc lịch sử.
Cách tránh: dùng openclaw config set cho các thay đổi nhỏ, openclaw configure để chỉnh sửa tương tác, config.schema.lookup để kiểm tra một đường dẫn chưa quen thuộc (trả về một nút lược đồ nông cùng phần tóm tắt các nút con trực tiếp), và config.patch để chỉnh sửa RPC từng phần — chỉ dành config.apply cho việc thay thế toàn bộ cấu hình. Công cụ runtime gateway dành cho agent từ chối ghi lại tools.exec.ask / tools.exec.security ngay cả thông qua các bí danh tools.bash.* cũ.Tài liệu: Cấu hình, Thiết lập cấu hình, Khắc phục sự cố Gateway, Doctor.
Mô hình phổ biến: một Gateway (ví dụ: Raspberry Pi) cùng với các node và các agent.
  • Gateway (trung tâm): quản lý các kênh (Signal/WhatsApp), định tuyến và phiên.
  • Các node (thiết bị): Mac/iOS/Android kết nối như thiết bị ngoại vi và cung cấp các công cụ cục bộ (system.run, canvas, camera).
  • Các agent (worker): các bộ não/không gian làm việc riêng biệt dành cho vai trò chuyên biệt (ví dụ: vận hành so với dữ liệu cá nhân).
  • Các agent con: khởi tạo công việc nền từ một agent chính để xử lý song song.
  • TUI: kết nối với Gateway và chuyển đổi agent/phiên.
Tài liệu: Các node, Truy cập từ xa, Định tuyến đa agent, Các agent con, TUI.
Có:
Mặc định là false (có giao diện). Chế độ không giao diện có nhiều khả năng kích hoạt cơ chế kiểm tra chống bot trên một số trang web hơn (X/Twitter thường chặn các phiên không giao diện). Chế độ này dùng cùng công cụ Chromium và hoạt động với hầu hết tác vụ tự động hóa; khác biệt chính là không có cửa sổ trình duyệt hiển thị (dùng ảnh chụp màn hình để xem hình ảnh). Xem Trình duyệt.
Đặ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) rồi khởi động lại Gateway. Xem Trình duyệt.

​
Gateway và node từ xa

Tin nhắn Telegram được Gateway xử lý; Gateway chạy agent rồi chỉ gọi các node qua Gateway WebSocket khi cần công cụ node:Telegram -> Gateway -> Agent -> node.* -> Node -> Gateway -> TelegramCác node không thấy lưu lượng đến từ nhà cung cấp; chúng chỉ nhận các lệnh gọi RPC của node.
Ghép nối máy tính của bạn dưới dạng một 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.
  1. Chạy Gateway trên máy chủ luôn bật (VPS/máy chủ gia đình).
  2. Đặt máy chủ Gateway và 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 được (liên kết tailnet hoặc đường hầm SSH).
  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) để ứng dụng đăng ký làm node.
  5. Phê duyệt node:
Không cần cầu nối TCP riêng; các node 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 cậy; xem lại Bảo mật.Tài liệu: Các node, Giao thức Gateway, Chế độ từ xa trên macOS, Bảo mật.
Kiểm tra các yếu tố cơ bản:
Sau đó xác minh việc xác thực và định tuyến: nếu dùng Tailscale Serve, hãy xác nhận gateway.auth.allowTailscale được đặt chính xác; nếu kết nối qua đường hầm SSH, hãy xác nhận đường hầm đang hoạt động và trỏ đến đúng cổng; xác nhận danh sách cho phép DM/nhóm có bao gồm tài khoản của bạn.Tài liệu: Tailscale, Truy cập từ xa, Các kênh.
Có, mặc dù không có cầu nối bot-với-bot tích hợp sẵn.Đơn giản nhất: dùng một kênh trò chuyện thông thường mà cả hai bot đều có thể truy cập (Slack/Telegram/WhatsApp). Cho Bot A gửi tin nhắn đến Bot B, sau đó để Bot B trả lời như bình thường.Cầu nối CLI (chung): chạy một tập lệnh gọi Gateway còn lại bằng openclaw agent --message ... --deliver, nhắm đến một cuộc trò chuyện nơi bot kia đang lắng nghe. Nếu một bot nằm trên VPS từ xa, hãy trỏ CLI của bạn đến Gateway từ xa đó qua SSH/Tailscale (xem Truy cập từ xa):
Thêm biện pháp bảo vệ để hai bot không lặp vô hạn (chỉ phản hồi khi được nhắc đến, danh sách kênh cho phép, hoặc quy tắc “không trả lời tin nhắn của bot”).Tài liệu: Truy cập từ xa, CLI agent, Gửi từ agent.
Không. Một Gateway lưu trữ nhiều agent, mỗi agent có không gian làm việc, giá trị mặc định của mô hình và định tuyến riêng — đây là cách thiết lập thông thường, rẻ hơn và đơn giản hơn nhiều so với việc dùng một VPS cho mỗi agent. Chỉ dùng các VPS riêng biệt khi cần cách ly nghiêm ngặt (ranh giới bảo mật) hoặc có các cấu hình rất khác nhau mà bạn không muốn chia sẻ.
Có: node là phương thức chính thức để truy cập máy tính xách tay từ Gateway từ xa và mở khóa nhiều khả năng hơn quyền truy cập shell. Gateway chạy trên macOS/Linux (Windows qua WSL2) và có dung lượng nhẹ (một VPS nhỏ hoặc máy cấp Raspberry Pi là đủ; RAM 4 GB là dư dả), vì vậy cách thiết lập phổ biến là một máy chủ luôn bật cùng máy tính xách tay của bạn làm node.
  • Không cần SSH đến — các node chủ động kết nối với Gateway WebSocket thông qua 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ằng danh sách cho phép/phê duyệt của node trên máy tính xách tay đó.
  • Nhiều công cụ thiết bị hơn — ngoài system.run, các node còn cung cấp canvas, camera và screen.
  • Tự động hóa trình duyệt cục bộ — giữ Gateway trên VPS nhưng chạy Chrome cục bộ thông qua máy chủ node, hoặc kết nối với Chrome cục bộ qua Chrome MCP.
SSH phù hợp để truy cập shell không thường xuyên; node đơn giản hơn cho các quy trình agent và tự động hóa thiết bị liên tục.Tài liệu: Các node, CLI node, Trình duyệt.
Không. Mỗi máy chủ chỉ nên chạy một Gateway, trừ khi bạn chủ ý chạy các hồ sơ cách ly (xem Nhiều Gateway). Node là thiết bị ngoại vi kết nối với Gateway (các node iOS/Android hoặc “chế độ node” macOS trong ứng dụng trên thanh menu). Đối với máy chủ node không giao diện và điều khiển bằng CLI, xem CLI máy chủ node.Cần khởi động lại hoàn toàn khi 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 cùng với nút lược đồ nông, gợi ý UI khớp và phần tóm tắt các nút con trực tiếp trước khi ghi.
  • config.get: lấy ảnh chụp nhanh hiện tại cùng với hàm băm.
  • config.patch: cập nhật một phần an toàn (ưu tiên cho hầu hết chỉnh sửa RPC); tải lại nóng khi có thể, khởi động lại khi cần.
  • config.apply: xác thực và thay thế toàn bộ cấu hình; tải lại nóng khi có thể, khởi động lại khi cần.
  • Công cụ thời gian chạy gateway dành cho tác nhân vẫn từ chối ghi lại tools.exec.ask / tools.exec.security; các bí danh tools.bash.* cũ được chuẩn hóa thành cùng các đường dẫn được bảo vệ.
Đặt không gian làm việc và giới hạn những người có thể kích hoạt bot.
  1. Cài đặt + đăng nhập trên VPS:
  2. Cài đặt + đăng nhập trên máy Mac bằng ứng dụng Tailscale, sử dụng cùng tailnet.
  3. Bật MagicDNS trong bảng điều khiển quản trị Tailscale để VPS có tên ổn định.
  4. Sử dụng tên máy chủ tailnet: SSH ssh user@your-vps.tailnet-xxxx.ts.net; Gateway WS ws://your-vps.tailnet-xxxx.ts.net:18789.
Để sử dụng UI Điều khiển mà không cần SSH, hãy dùng Tailscale Serve trên VPS:
Thao tác này giữ Gateway liên kết với loopback và cung cấp HTTPS qua Tailscale. Xem Tailscale.
Serve cung cấp UI Điều khiển Gateway + WS; các Node kết nối qua cùng điểm cuối Gateway WS.
  1. Đảm bảo VPS và máy Mac nằm trên cùng một tailnet.
  2. Sử dụng ứng dụng macOS ở chế độ Từ xa (đích SSH có thể là tên máy chủ tailnet) - ứng dụng sẽ tạo đường hầm cho cổng Gateway và kết nối dưới dạng một Node.
  3. Phê duyệt Node:
Tài liệu: Giao thức Gateway, Khám phá, chế độ từ xa trên macOS.
Đối với chỉ các 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 máy đó dưới dạng một Node - một Gateway, không trùng lặp cấu hình. Các công cụ Node cục bộ hiện chỉ hỗ trợ macOS. Chỉ cài đặt Gateway thứ hai khi cần cách ly nghiêm ngặt 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à việc tải .env

OpenClaw đọc các biến môi trường từ tiến trình cha (shell, launchd/systemd, CI, v.v.) và còn tải thêm:
  • .env từ thư mục làm việc hiện tại.
  • một phương án dự phòng toàn cục .env từ ~/.openclaw/.env ($OPENCLAW_STATE_DIR/.env).
Không tệp .env nào ghi đè các biến môi trường hiện có. Các khóa thông tin xác thực của nhà cung cấp và định tuyến điểm cuối là ngoại lệ đối với .env của không gian làm việc: các khóa như GEMINI_API_KEY, XAI_API_KEY, MISTRAL_API_KEY hoặc bất kỳ khóa nào kết thúc bằng _ENDPOINT (và các biến môi trường xác thực hoặc điểm cuối khác của nhà cung cấp đi kèm) sẽ bị bỏ qua trong .env của không gian làm việc và nên nằm trong môi trường tiến trình, ~/.openclaw/.env hoặc cấu hình env.Các biến môi trường nội tuyến trong cấu hình chỉ áp dụng nếu chúng không có trong môi trường tiến trình:
Xem /environment để biết đầy đủ thứ tự ưu tiên và các nguồn.
Có hai cách khắc phục:
  1. Đặt các khóa bị thiếu vào ~/.openclaw/.env để chúng được tải ngay cả khi dịch vụ không kế thừa môi trường shell của bạn.
  2. Bật nhập shell (tiện ích tùy chọn):
    Thao tác này chạy shell đăng nhập của bạn và chỉ nhập các khóa dự kiến còn 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 cho biết liệu nhập môi trường 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 là OpenClaw sẽ không tự động tải shell đăng nhập của bạn.Nếu Gateway chạy dưới dạng dịch vụ (launchd/systemd), nó sẽ không kế thừa môi trường shell của bạn. Hãy khắc phục bằng cách đặt token vào ~/.openclaw/.env, bật env.shellEnv.enabled: true hoặc thêm token vào cấu hình env (chỉ áp dụng nếu còn thiếu), sau đó khởi động lại Gateway và kiểm tra lại:
Token Copilot được phân giải theo thứ tự này: OPENCLAW_GITHUB_TOKEN, sau đó COPILOT_GITHUB_TOKEN, tiếp theo GH_TOKEN, rồi 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.
Không, mặc định là không. Các phiên giữ nguyên sessionId, còn Compaction giới hạn ngữ cảnh mô hình đang hoạt động khi cuộc trò chuyện dài ra. /new và /reset vẫn khả dụng, hoặc bạn có thể chọn tự động đặt lại bằng mode: "daily" hoặc mode: "idle". Chế độ hằng ngày chuyển sang chu kỳ mới vào session.reset.atHour (mặc định 4, 0-23) trên máy chủ Gateway; chế độ nhàn rỗi sử dụng session.reset.idleMinutes kể từ lần tương tác thực gần nhất, không tính các sự kiện hệ thống heartbeat/cron/exec.
resetByType hỗ trợ direct (bí danh cũ dm), group và thread. session.idleMinutes cấp cao nhất kiểu cũ vẫn hoạt động như một bí danh tương thích cho giá trị mặc định của chế độ nhàn rỗi khi không đặt khối session.reset/resetByType. Xem Quản lý phiên để biết toàn bộ vòng đời.
Có, thông qua định tuyến đa tác nhân và tác nhân phụ: một tác nhân điều phối cùng nhiều tác nhân thực thi, mỗi tác nhân có không gian làm việc và mô hình riêng.Tốt nhất nên xem đây là một thử nghiệm thú vị - cách này tiêu tốn nhiều token và thường kém hiệu quả hơn một bot có các phiên riêng biệt. Mô hình điển hình 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 và tạo 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ụ, CLI tác nhân.
Ngữ cảnh phiên bị giới hạn bởi cửa sổ của 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 Compaction hoặc cắt bớt.
  • 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 tác vụ dài, /new khi chuyển chủ đề.
  • Lưu 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 gọn hơn.
  • Chọn mô hình có cửa sổ ngữ cảnh lớn hơn nếu điều này thường xuyên xảy ra.
Đặt lại toàn bộ không tương tác:
Sau đó chạy lại quá trình thiết lập:
Quá trình làm quen cũng cung cấp tùy chọn Đặt lại nếu phát hiện cấu hình hiện có; xem Làm quen (CLI). Nếu bạn đã sử dụng hồ sơ (--profile / OPENCLAW_PROFILE), hãy đặt lại từng thư mục trạng thái (mặc định ~/.openclaw-<profile>). Đặt lại chỉ dành cho môi trường phát triển: openclaw gateway --dev --reset xóa cấu hình phát triển, thông tin xác thực, phiên và không gian làm việc.
  • Compaction (giữ lại cuộc trò chuyện, tóm tắt các lượt cũ hơn): /compact hoặc /compact <instructions> để định hướng phần tóm tắt.
  • Đặt lại (ID phiên mới cho cùng khóa trò chuyện): /new hoặc /reset.
Nếu lỗi tiếp tục xảy ra, hãy điều chỉnh cắt tỉa phiên (agents.defaults.contextPruning) để loại bớt đầu ra công cụ cũ hoặc sử dụng mô hình có cửa sổ ngữ cảnh lớn hơn.Tài liệu: Compaction, Cắt tỉa phiên, Quản lý phiên.
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 bắt buộc. Điều này thường có nghĩa là lịch sử phiên đã cũ hoặc bị hỏng (thường xảy ra sau các luồng dài hoặc thay đổi công cụ/lược đồ).Cách khắc phục: bắt đầu phiên mới bằng /new (tin nhắn độc lập).
Heartbeat mặc định chạy mỗi 30m, hoặc 1h khi chế độ xác thực được phân giải là xác thực bằng OAuth/token Anthropic (bao gồm cả việc tái sử dụng Claude CLI) và chưa đặt heartbeat.every. Điều chỉnh hoặc tắt:
Nếu HEARTBEAT.md tồn tại nhưng thực tế trống (chỉ có dòng trống, chú thích Markdown/HTML, tiêu đề ATX, dấu phân cách khối mã hoặc mục danh sách trống), OpenClaw bỏ qua lần chạy Heartbeat để tiết kiệm lệnh gọi API. Nếu tệp bị thiếu, Heartbeat vẫn chạy và mô hình quyết định việc cần làm.Các ghi đè theo từng tác nhân sử dụng agents.list[].heartbeat. Tài liệu: Heartbeat.
Không. OpenClaw chạy trên chính tài khoản của bạn - nếu bạn có mặt trong nhóm, OpenClaw có thể thấy nhóm đó. Theo mặc định, phản hồi trong nhóm bị chặn cho đến khi bạn cho phép người gửi (groupPolicy: "allowlist").Để giới hạn phản hồi trong nhóm chỉ cho bạn:
Cách nhanh nhất: theo dõi nhật ký và gửi một tin nhắn thử nghiệm trong nhóm.
Tìm chatId (hoặc from) kết thúc bằng @g.us, chẳng hạn như 1234567890-1234567890@g.us.Nếu đã được cấu hình/đưa vào danh sách cho phép, hãy liệt kê các nhóm từ cấu hình:
Tài liệu: WhatsApp, Thư mục, Nhật ký.
Hai nguyên nhân phổ biến: cơ chế yêu cầu đề cập được bật theo mặc định (bạn phải @đề cập bot hoặc khớp với mentionPatterns), hoặc bạn đã cấu hình channels.whatsapp.groups mà không có "*" và nhóm không nằm trong danh sách cho phép.Xem Nhóm và Tin nhắn nhóm.
Theo mặc định, các cuộc trò chuyện trực tiếp được gộp vào phiên chính. Nhóm/kênh có khóa phiên riêng, còn chủ đề Telegram / luồng Discord là các phiên riêng biệt. Xem Nhóm và Tin nhắn nhóm.
Không có giới hạn cứng — vài chục hoặc thậm chí vài trăm đều được, nhưng hãy lưu ý:
  • Dung lượng đĩa tăng: các phiên đang hoạt động và bản chép lời nằm trong cơ sở dữ liệu SQLite riêng của từng tác tử; các thành phần cũ/lưu trữ vẫn có thể tích lũy trong ~/.openclaw/agents/<agentId>/sessions/.
  • Chi phí token: nhiều tác tử hơn đồng nghĩa với mức sử dụng mô hình đồng thời cao 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 riêng cho từng tác tử.
Duy trì một không gian làm việc đang hoạt động cho mỗi tác tử (agents.defaults.workspace), dọn các phiên cũ bằng openclaw sessions cleanup nếu dung lượng đĩa tăng (không chỉnh sửa thủ công trạng thái SQLite đang hoạt động), và dùng openclaw doctor để phát hiện các không gian làm việc thừa và hồ sơ không khớp.
Có, thông qua Đị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ợ dưới dạng một kênh và có thể được liên kết với các tác tử cụ thể.Khả năng truy cập trình duyệt rất mạnh nhưng không phải là “làm được mọi thứ con người có thể làm” — các cơ chế chống bot, CAPTCHA và MFA vẫn có thể chặn hoạt động tự động hóa. Để điều khiển đáng tin cậy nhất, hãy dùng Chrome MCP cục bộ trên máy chủ hoặc CDP trên máy thực sự chạy trình duyệt.Thiết lập theo phương pháp hay nhất: máy chủ Gateway luôn bật (VPS/Mac mini), mỗi vai trò một tác tử (liên kết), các kênh Slack được liên kết với những tác tử đó và trình duyệt cục bộ thông 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, Node.

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

Phần hỏi đáp về mô hình — giá trị 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 kiểm soát cổng ghép kênh duy nhất cho WebSocket + HTTP (Giao diện điều khiển, hook, v.v.). Thứ tự ưu tiên:
“Running” là góc nhìn của trình giám sát (launchd/systemd/schtasks); phép kiểm tra kết nối là CLI thực sự kết nối đến WebSocket của Gateway. Hãy tin các dòng sau từ openclaw gateway status: Probe target: (URL mà phép kiểm tra đã dùng), Listening: (thành phần thực sự đang liên kết với cổng), Last gateway error: (nguyên nhân gốc phổ biến khi tiến trình vẫn chạy 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ụ chạy bằng một tệp khác (thường là do --profile / OPENCLAW_STATE_DIR không khớp).Để khắc phục, hãy chạy từ cùng --profile / môi trường mà bạn muốn dịch vụ sử dụng:
OpenClaw thực thi khóa thời gian chạy bằng cách liên kết trình lắng nghe WebSocket ngay khi khởi động (mặc định là ws://127.0.0.1:18789). Nếu thao tác liên kết thất bại với EADDRINUSE, hệ thống sẽ đưa ra GatewayLockError (“một phiên bản Gateway khác đã lắng nghe”).Cách khắc phục: 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:
  • openclaw gateway chỉ khởi động khi gateway.mode là local (hoặc khi 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.remote.token / .password chỉ là thông tin xác thực từ xa phía máy khách; bản thân chúng không bật xác thực Gateway cục bộ.
Đường dẫn xác thực Gateway và phương thức xác thực của giao diện không khớp nhau.Thông tin thực tế (từ mã nguồn):
  • Giao diện điều khiển giữ token trong sessionStorage, giới hạn trong tab trình duyệt hiện tại và URL Gateway đã chọn, vì vậy việc làm mới trong cùng tab vẫn hoạt động mà không cần duy trì token lâu dài trong localStorage.
  • Trên AUTH_TOKEN_MISMATCH, máy khách đáng tin cậy có thể thử lại một lần trong giới hạn bằng token thiết bị đã lưu vào bộ nhớ đệ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 vào bộ nhớ đệm đó tái sử dụng các phạm vi đã được phê duyệt và lưu cùng token thiết bị; các bên gọi cung cấp rõ deviceToken / scopes rõ ràng vẫn giữ tập hợp phạm vi yêu cầu của mình thay vì kế thừa các phạm vi đã lưu.
  • 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 được chỉ định rõ trước tiên, sau đó là deviceToken được chỉ định rõ, rồi token thiết bị đã lưu và cuối cùng là token khởi tạo.
  • Quá trình khởi tạo bằng mã thiết lập tích hợp trả về token thiết bị Node với scopes: [] cùng một token bàn giao cho người vận hành có giới hạn để tiếp nhận trên thiết bị di động đáng tin cậy. Bàn giao cho người vận hành có thể đọc cấu hình gốc tại thời điểm thiết lập nhưng không cấp các phạm vi thay đổi ghép nối hoặc operator.admin.
Cách khắc phục:
  • Nhanh nhất: openclaw dashboard (in + sao chép URL bảng điều khiển, thử mở; hiển thị gợi ý SSH nếu không có giao diện đồ họa).
  • Chưa có token: openclaw doctor --generate-gateway-token.
  • Từ xa: trước tiên tạo đường hầm bằng ssh -N -L 18789:127.0.0.1:18789 user@host, sau đó 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, sau đó dán bí mật tương ứng vào phần cài đặt của Giao diện điều khiển.
  • Chế độ Tailscale Serve: xác nhận gateway.auth.allowTailscale đã bật và bạn đang mở URL Serve, không phải URL loopback/tailnet thô bỏ qua các tiêu đề danh tính Tailscale.
  • Chế độ proxy đáng tin cậy: xác nhận bạn đang đi qua proxy nhận biết danh tính đã cấu hình. Proxy loopback trên cùng máy chủ cũng cần gateway.auth.trustedProxy.allowLoopback = true.
  • Nếu tình trạng không khớp vẫn còn sau một lần thử lại: xoay vòng/phê duyệt lại token của thiết bị đã ghép nối:
  • Xoay vòng bị từ chối: các phiên thiết bị đã ghép nối chỉ có thể xoay vòng thiết bị của chính chúng, trừ khi chúng cũng có operator.admin, và các giá trị --scope được chỉ định rõ không thể vượt quá phạm vi người vận hành hiện tại của bên gọi.
  • Vẫn bị kẹt: openclaw status --all cùng với Khắc phục sự cố. Xem Bảng điều khiển để biết chi tiết về xác thực.
Liên kết tailnet chọn một địa chỉ 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 không hoạt động), Gateway sẽ quay về loopback thay vì để lộ một giao diện mạng khác.Cách khắc phục: khởi động Tailscale trên máy chủ đó và khởi động lại Gateway, hoặc chuyển rõ ràng sang gateway.bind: "loopback" / "lan".tailnet là lựa chọn rõ ràng; auto ưu tiên loopback. Dùng gateway.bind: "tailnet" để giới hạn việc tiếp xúc ngoài loopback trong Tailnet, đồng thời duy trì trình lắng nghe 127.0.0.1 bắt buộc trên cùng máy chủ.
Thông 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 để dự phòng (ví dụ: bot cứu hộ) hoặc cách ly nghiêm ngặt, đồng thời cách ly từng Gateway bằng OPENCLAW_CONFIG_PATH, OPENCLAW_STATE_DIR, agents.defaults.workspace riêng và gateway.port duy nhất.Khuyến nghị: dùng openclaw --profile <name> ... cho mỗi phiên bản (tự động tạo ~/.openclaw-<name>), một gateway.port duy nhất cho mỗi cấu hình hồ sơ (hoặc --port khi chạy thủ công) và một dịch vụ cho mỗi hồ sơ với openclaw --profile <name> gateway install.Hồ sơ cũng thêm hậu tố vào tên dịch vụ: launchd ai.openclaw.<profile>, systemd openclaw-gateway-<profile>.service, Windows OpenClaw Gateway (<profile>). Đơn vị systemd openclaw-gateway không có định danh chỉ tồn tại cho hồ sơ mặc định; tên đơn vị systemd cũ trước khi đổi tên là clawdbot-gateway được di chuyển tự động.Hướng dẫn đầy đủ: Nhiều Gateway.
Gateway là một máy chủ WebSocket và yêu cầu tin nhắn đầu tiên phải là khung connect. Mọi nội dung khác sẽ đó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 thay vì dùng máy khách WS, sử dụng sai cổng/đường dẫn hoặc proxy/đường hầm đã loại bỏ tiêu đề xác thực hay gửi một yêu cầu không dành cho Gateway.Cách khắc phục: dùng URL WS (ws://<host>:18789 hoặc wss://... qua HTTPS), không mở cổng WS trong tab trình duyệt thông thường và đưa token/mật khẩu vào khung connect khi xác thực được bật. Ví dụ CLI/TUI:
Chi tiết giao thức: Giao thức Gateway.

​
Ghi nhật ký và gỡ lỗi

Nhật ký tệp (có cấu trúc): /tmp/openclaw/openclaw-YYYY-MM-DD.log. Đặt đường dẫn ổn định qua logging.file; cấp độ nhật ký tệp qua logging.level; độ chi tiết của bảng điều khiển qua --verbose và logging.consoleLevel.Cách theo dõi nhanh nhất:
Nhật ký dịch vụ/trình giám sát (khi Gateway chạy qua launchd/systemd):
  • stdout của launchd trên macOS: ~/Library/Logs/openclaw/gateway.log (hồ sơ dùng gateway-<profile>.log; stderr bị tắt).
  • 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 thông tin.
Nếu bạn chạy Gateway thủ công, openclaw gateway --force có thể thu hồi cổng. Xem Gateway.
Ba chế độ cài đặt trên Windows:1) Thiết lập cục bộ Windows Hub: ứng dụng gốc quản lý một Gateway WSL cục bộ thuộc sở hữu của ứng dụng. Mở OpenClaw Companion từ menu Start hoặc khay hệ thống, sau đó dùng Gateway Setup hoặc tab Connections.2) Gateway WSL2 thủ công: Gateway chạy bên trong Linux.
Nếu bạn chưa từng cài đặt dịch vụ, hãy khởi động dịch vụ ở chế độ tiền cảnh: openclaw gateway run.3) CLI/Gateway Windows gốc: chạy trực tiếp trong Windows.
Nếu chạy thủ công (không dùng dịch vụ): openclaw gateway run.Tài liệu: Windows, Cẩm nang vận hành dịch vụ Gateway.
Kiểm tra nhanh tình trạng hệ thống:
Các nguyên nhân thường gặp: thông tin 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/danh sách cho phép của kênh chặn phản hồi (kiểm tra cấu hình và nhật ký kênh), hoặc WebChat/Bảng điều khiển được mở mà không có đúng token. Nếu truy cập từ xa, hãy xác nhận đường hầm/kết nối Tailscale đang hoạt động và có thể truy cập WebSocket của Gateway.Tài liệu: Kênh, Khắc phục sự cố, Truy cập từ xa.
Thường có nghĩa là giao diện người dùng đã mất kết nối WebSocket. Hãy kiểm tra: Gateway có đang chạy không (openclaw gateway status)? Gateway có hoạt động bình thường không (openclaw status)? Giao diện người dùng có đúng token không (openclaw dashboard)? 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ý:
Tài liệu: Bảng điều khiển, Truy cập từ xa, Khắc phục sự cố.
Sau đó đối chiếu lỗi:
  • BOT_COMMANDS_TOO_MUCH: menu Telegram có quá nhiều mục. OpenClaw đã tự động cắt giảm theo 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ó thể bị loại bỏ. Hãy giảm số lệnh của plugin/skill/tùy chỉnh hoặc tắt channels.telegram.commands.native nếu không cần menu.
  • TypeError: fetch failed, Network request for 'setMyCommands' failed! hoặc các lỗi mạng tương tự: trên VPS hoặc phía sau proxy, hãy xác nhận HTTPS đi ra được cho phép và DNS hoạt động với api.telegram.org.
Nếu Gateway ở xa, hãy kiểm tra nhật ký trên máy chủ Gateway.Tài liệu: Telegram, Khắc phục sự cố kênh.
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 xác nhận tính năng chuyển phát đã được bật (/deliver on).Tài liệu: TUI, Lệnh dấu gạch chéo.
Nếu đã cài đặt dịch vụ (launchd trên macOS, systemd trên Linux):
Khi chạy ở chế độ nền trước, dừng bằng Ctrl-C, sau đó openclaw gateway run.Tài liệu: Cẩm nang 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 ở chế độ nền trước trong phiên terminal này. Dùng các lệnh con của Gateway nếu đã cài đặt dịch vụ; dùng lệnh chạy nền trước không có lệnh con cho một lần chạy riêng lẻ.
Khởi động Gateway bằng --verbose để nhận thêm chi tiết trên bảng điều khiển, sau đó kiểm tra tệp nhật ký để tìm lỗi xác thực kênh, định tuyến mô hình và RPC.

​
Nội dung đa phương tiện và tệp đính kèm

Tệp đính kèm gửi đi từ agent phải sử dụng các trường nội dung đa phương tiện có cấu trúc như media, mediaUrl, path hoặc filePath. Xem Thiết lập trợ lý OpenClaw và Agent gửi.
Đồng thời kiểm tra: kênh đích hỗ trợ nội dung đa phương tiện gửi đi 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 để cạnh tối đa là 2048px); tools.fs.workspaceOnly=true giới hạn việc gửi theo đường dẫn cục bộ ở không gian làm việc, kho tạm thời/nội dung đa phương tiện và các tệp đã được sandbox xác thực; tools.fs.workspaceOnly=false (mặc định) cho phép việc gửi nội dung đa phương tiện cục bộ có cấu trúc sử dụng các tệp cục bộ trên máy chủ mà agent đã có thể đọc, bao gồm nội dung đa phương tiện và các loại tài liệu an toàn (hình ảnh, âm thanh, video, PDF, tài liệu Office và tài liệu văn bản đã được xác thực như Markdown/MD, TXT, JSON, YAML/YML). Đây không phải là trình quét bí mật — secret.txt hoặc config.json mà agent có thể đọc có thể được đính kèm khi phần mở rộng và nội dung vượt qua bước xác thực. Hãy giữ các tệp nhạy cảm bên ngoài những đường dẫn agent có thể đọc hoặc giữ tools.fs.workspaceOnly=true để áp dụng quy tắc gửi theo đường dẫn cục bộ nghiêm ngặt hơn.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 gửi đến là đầu vào không đáng tin cậy. Các giá trị mặc định giúp giảm rủi ro:
  • Hành vi mặc định trên các kênh hỗ trợ tin nhắn trực tiếp là ghép đôi: người gửi không xác định sẽ nhận được mã ghép đôi và tin nhắn của họ không được xử lý. Phê duyệt bằng openclaw pairing approve --channel <channel> [--account <id>] <code>. Số yêu cầu đang chờ được giới hạn ở 3 trên mỗi kênh; hãy kiểm tra openclaw pairing list --channel <channel> [--account <id>] nếu không nhận được mã.
  • Mở công khai tin nhắn trực tiếp yêu cầu chủ động bật 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 tin nhắn trực tiếp có rủi ro.
Không. Prompt injection liên quan đến nội dung không đáng tin cậy, không chỉ phụ thuộc vào người có thể gửi tin nhắn trực tiếp cho bot. Nếu trợ lý đọc nội dung bên ngoài (tìm kiếm/truy xuất 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 các chỉ dẫn cố chiếm quyền điều khiển mô hình — ngay cả khi bạn là người gửi duy nhất.Rủi ro lớn nhất xuất hiện khi các công cụ được bật: mô hình có thể bị lừa để làm rò rỉ ngữ cảnh hoặc gọi công cụ thay bạn. Giảm phạm vi ảnh hưởng:
  • dùng agent “đọc” chỉ đọc hoặc đã tắt công cụ để tóm tắt nội dung không đáng tin cậy
  • giữ web_search / web_fetch / browser ở trạng thái tắt đối với agent đã bật công cụ
  • cũng coi văn bản tệp/tài liệu đã giải mã là không đáng tin cậy: cả input_file của OpenResponses và quá trình trích xuất tệp đính kèm đa phương tiện đều bọc văn bản được trích xuất trong các dấu mốc ranh giới nội dung bên ngoài rõ ràng thay vì truyền trực tiếp văn bản thô của tệp
  • dùng sandbox và danh sách cho phép công cụ nghiêm ngặt
Chi tiết: Bảo mật.
Ngôn ngữ và runtime có vai trò quan trọng, nhưng không phải là rủi ro chính đối với agent cá nhân. Các rủi ro thực tế gồm Gateway bị phơi lộ, ai có thể nhắn tin cho bot, prompt injection, phạm vi công cụ, cách xử lý thông tin xác thực, quyền truy cập trình duyệt, quyền thực thi và độ tin cậy của skill/plugin bên thứ ba.Rust và WASM có thể cung cấp khả năng cô lập mạnh hơn cho một số loại mã, nhưng không giải quyết được prompt injection, danh sách cho phép không phù hợp, Gateway bị phơi lộ công khai, công cụ có phạm vi quá rộng hoặc hồ sơ trình duyệt đã đăng nhập vào các tài khoản nhạy cảm. Hãy coi đây là các biện pháp kiểm soát chính: giữ Gateway ở chế độ riêng tư hoặc yêu cầu xác thực, dùng ghép đôi và danh sách cho phép cho tin nhắn trực tiếp/nhóm, từ chối hoặc dùng sandbox cho các công cụ rủi ro khi xử lý đầu vào không đáng tin cậy, chỉ cài đặt plugin và skill đáng tin cậy, đồng thời chạy openclaw security audit --deep sau khi thay đổi cấu hình.Chi tiết: Bảo mật, Sandbox.
Cấu hình cơ sở an toàn hơn: Gateway được liên kết với loopback hoặc chỉ được phơi lộ qua quyền truy cập riêng tư đã xác thực (tailnet, đường hầm SSH, xác thực bằng token/mật khẩu hoặc proxy đáng tin cậy được cấu hình đúng); tin nhắn trực tiếp ở chế độ pairing hoặc allowlist; các nhóm nằm trong danh sách cho phép và yêu cầu đề cập trừ khi mọi thành viên đều đáng tin cậy; các công cụ rủi ro cao (exec, browser, gateway, cron) bị từ chối hoặc giới hạn phạm vi chặt chẽ đối với agent đọc nội dung không đáng tin cậy; bật sandbox ở những nơi việc thực thi công cụ cần phạm vi ảnh hưởng nhỏ hơn.Liên kết công khai không có xác thực, tin nhắn trực tiếp/nhóm mở có công cụ và quyền điều khiển trình duyệt bị phơi lộ là những phát hiện cần khắc phục trước tiên. Chi tiết: openclaw security audit.
Hãy coi skill và plugin bên thứ ba là mã mà bạn chủ động chọn tin tưởng. Các trang skill ClawHub hiển thị trạng thái quét trước khi cài đặt, nhưng việc quét không phải là một ranh giới bảo mật hoàn chỉnh. OpenClaw không thực hiện chặn mã nguy hiểm cục bộ tích hợp sẵn trong quá trình cài đặt hoặc cập nhật plugin/skill; hãy dùng security.installPolicy do người vận hành quản lý để đưa ra quyết định cho phép/chặn cục bộ.Mô hình an toàn hơn: ưu tiên tác giả đáng tin cậy và phiên bản được ghim, đọc skill/plugin trước khi bật, giữ danh sách cho phép plugin/skill ở phạm vi hẹp, chạy quy trình làm việc với đầu vào không đáng tin cậy trong sandbox có tối thiểu công cụ và tránh cấp cho mã bên thứ ba quyền truy cập rộng vào hệ thống tệp, quyền thực thi, trình duyệt hoặc bí mật.Chi tiết: Skills, Plugin, Bảo mật.
Có, đối với hầu hết cấu hình. Việc 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ố, đồng thời giúp việc luân chuyển thông tin xác thực hoặc thu hồi quyền truy cập dễ dàng hơn mà không ảnh hưởng đến tài khoản cá nhân.Hãy bắt đầu ở quy mô nhỏ: chỉ cấp quyền truy cập vào những công cụ và tài khoản thực sự cần thiết, 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. Mô hình an toàn nhất: giữ tin nhắn trực tiếp ở chế độ ghép đôi hoặc dùng danh sách cho phép nghiêm ngặt, sử dụng số điện thoại hoặc tài khoản riêng nếu bot cần nhắn tin thay bạn và để bot soạn bản nháp trong khi bạn phê duyệt trước khi gửi.Để thử nghiệm, hãy thực hiện trên một tài khoản chuyên dụng, được cô lập. Xem Bảo mật.
Có, nếu agent chỉ trò chuyện và đầu vào đáng tin cậy. Các tầng mô hình nhỏ hơn dễ bị chiếm quyền điều khiển bằng chỉ dẫn hơn, vì vậy hãy tránh dùng chúng cho agent đã bật công cụ hoặc khi đọc nội dung không đáng tin cậy. Nếu buộc 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 chỉ được gửi khi người gửi không xác định nhắn tin cho bot và dmPolicy: "pairing" được bật; chỉ riêng /start không tạo mã.Kiểm tra các yêu cầu đang chờ:
Để 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 tin nhắn trực tiếp mặc định của WhatsApp là ghép đôi. Người gửi không xác định chỉ nhận được mã ghép đôi; tin nhắn của họ không được xử lý. OpenClaw chỉ phản hồi các cuộc trò chuyện mà nó nhận được hoặc các lần gửi rõ ràng do bạn kích hoạt.
Lời nhắc nhập số điện thoại của trình hướng dẫn thiết lập danh sách cho phép/chủ sở hữu để cho phép tin nhắn trực tiếp của chính bạn - số này không được dùng để tự động gửi. Đối với 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ó không chịu dừng”

Hầu hết thông báo nội bộ/công cụ chỉ xuất hiện khi verbose, trace hoặc reasoning được bật cho phiên đó.Khắc phục trong cuộc trò chuyện nơi bạn thấy chúng:
Nếu vẫn còn nhiều thông báo: hãy kiểm tra cài đặt phiên trong giao diện điều khiển và đặt verbose thành inherit; xác nhận rằng bạn không dùng hồ sơ bot có verboseDefault: "on" trong cấu hình.Tài liệu: Suy luận 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 riêng biệt (không có dấu gạch chéo) để kích hoạt việc hủy: 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, do not do that, please stop, stop please, abort, esc, exit, interrupt, halt. Các cụm từ kích hoạt phổ biến không phải tiếng Anh (tiếng Pháp, tiếng Đức, tiếng Tây Ban Nha, tiếng Trung, tiếng Nhật, tiếng Hindi, tiếng Ả Rập, tiếng Nga) cũng hoạt động.Đối với các tiến trình nền do công cụ exec khởi chạy, hãy yêu cầu agent chạy:
Hầu hết lệnh gạch chéo phải được gửi dưới dạng một tin nhắn riêng biệt bắt đầu bằng /, nhưng một vài lối tắt (như /status) cũng hoạt động ngay trong dòng đối với người gửi có trong danh sách cho phép. Xem Lệnh gạch chéo.
Theo mặc định, OpenClaw chặn việc nhắn tin giữa các nhà cung cấp. Nếu một lệnh gọi công cụ được liên kết với Telegram, lệnh đó sẽ không gửi đến Discord trừ khi bạn cho phép rõ ràng - và thay đổi này có hiệu lực ngay lập tức, không cần khởi động lại Gateway:
Theo mặc định, các lời nhắc giữa chừng được điều hướng vào lượt chạy đang hoạt động. Dùng /queue để chọn hành vi của lượt chạy đang hoạt động:
  • steer (mặc định) - hướng dẫn lượt chạy đang hoạt động tại ranh giới mô hình tiếp theo.
  • followup - xếp hàng các tin nhắn và chạy từng tin một sau khi lượt chạy hiện tại kết thúc.
  • collect - xếp hàng các tin nhắn tương thích và phản hồi một lần sau khi lượt chạy hiện tại kết thúc.
  • interrupt - hủy lượt chạy hiện tại và bắt đầu lại.
Thêm tùy chọn vào các chế độ xếp hàng như debounce:0.5s cap:25 drop:summarize. Xem Hàng đợi lệnh và Hàng đợi điều hướng.

​
Khác

Thông tin xác thực và việc chọn mô hình là hai vấn đề 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à mô hình 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). No credentials found for profile "anthropic:default" có nghĩa là Gateway không thể tìm thấy thông tin xác thực Anthropic trong auth-profiles.json dự kiến dành cho agent đ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