Giao diện điều khiển

• Trò chuyện với mô hình qua Gateway WS (chat.history, chat.send, chat.abort, chat.inject).
• Làm mới lịch sử trò chuyện yêu cầu một cửa sổ gần đây có giới hạn với giới hạn văn bản theo từng tin nhắn, để các phiên lớn không buộc trình duyệt phải render toàn bộ payload bản ghi trước khi trò chuyện trở nên dùng được.
• Nói chuyện qua các phiên realtime của trình duyệt. OpenAI dùng WebRTC trực tiếp, Google Live dùng token trình duyệt một lần bị giới hạn qua WebSocket, và các plugin giọng nói realtime chỉ backend dùng giao thức chuyển tiếp Gateway. Các phiên nhà cung cấp do máy khách sở hữu bắt đầu bằng talk.client.create; các phiên chuyển tiếp Gateway bắt đầu bằng talk.session.create. Bộ chuyển tiếp giữ thông tin xác thực nhà cung cấp trên Gateway trong khi trình duyệt stream PCM từ micro qua talk.session.appendAudio và chuyển tiếp các lệnh gọi công cụ nhà cung cấp openclaw_agent_consult qua talk.client.toolCall cho chính sách Gateway và mô hình OpenClaw lớn hơn đã cấu hình.
• Stream lệnh gọi công cụ + thẻ đầu ra công cụ trực tiếp trong Trò chuyện (sự kiện tác tử).

• Kênh: trạng thái kênh tích hợp sẵn cùng plugin đóng gói/bên ngoài, đăng nhập QR, và cấu hình theo kênh (channels.status, web.login.*, config.patch).
• Làm mới thăm dò kênh giữ ảnh chụp trước đó hiển thị trong khi các kiểm tra nhà cung cấp chậm hoàn tất, và ảnh chụp một phần được gắn nhãn khi một lượt thăm dò hoặc kiểm tra vượt quá ngân sách UI.
• Instance: danh sách hiện diện + làm mới (system-presence).
• Phiên: danh sách + ghi đè theo phiên cho model/thinking/fast/verbose/trace/reasoning (sessions.list, sessions.patch).
• Dream: trạng thái dreaming, công tắc bật/tắt, và trình đọc Nhật ký Dream (doctor.memory.status, doctor.memory.dreamDiary, config.patch).

• Tác vụ Cron: liệt kê/thêm/sửa/chạy/bật/tắt + lịch sử chạy (cron.*).
• Skills: trạng thái, bật/tắt, cài đặt, cập nhật khóa API (skills.*).
• Node: danh sách + giới hạn khả năng (node.list).
• Phê duyệt exec: chỉnh sửa allowlist gateway hoặc node + chính sách hỏi cho exec host=gateway/node (exec.approvals.*).

• Xem/sửa ~/.openclaw/openclaw.json (config.get, config.set).
• Áp dụng + khởi động lại với xác thực (config.apply) và đánh thức phiên hoạt động gần nhất.
• Thao tác ghi bao gồm bộ bảo vệ base-hash để tránh ghi đè các chỉnh sửa đồng thời.
• Thao tác ghi (config.set/config.apply/config.patch) kiểm tra trước việc phân giải SecretRef đang hoạt động cho các ref trong payload cấu hình đã gửi; các ref đã gửi đang hoạt động nhưng không phân giải được sẽ bị từ chối trước khi ghi.
• Schema + render biểu mẫu (config.schema / config.schema.lookup, bao gồm trường title / description, gợi ý UI khớp, tóm tắt con trực tiếp, siêu dữ liệu tài liệu trên các node object/wildcard/array/composition lồng nhau, cộng với schema plugin + kênh khi có); trình chỉnh sửa Raw JSON chỉ có sẵn khi ảnh chụp có vòng khứ hồi thô an toàn.
• Nếu một ảnh chụp không thể đi vòng thô một cách an toàn, Giao diện điều khiển buộc chế độ Biểu mẫu và vô hiệu hóa chế độ Thô cho ảnh chụp đó.
• "Đặt lại về bản đã lưu" của trình chỉnh sửa Raw JSON giữ nguyên hình dạng được soạn thô (định dạng, chú thích, bố cục $include) thay vì render lại một ảnh chụp đã làm phẳng, nên các chỉnh sửa bên ngoài vẫn sống sót sau khi đặt lại khi ảnh chụp có thể đi vòng an toàn.
• Các giá trị object SecretRef có cấu trúc được render chỉ đọc trong đầu vào văn bản của biểu mẫu để ngăn vô tình làm hỏng object thành chuỗi.

• Gỡ lỗi: ảnh chụp trạng thái/sức khỏe/mô hình + nhật ký sự kiện + lệnh gọi RPC thủ công (status, health, models.list).
• Nhật ký sự kiện bao gồm thời gian làm mới/RPC của Giao diện điều khiển, thời gian render trò chuyện/cấu hình chậm, và các mục độ phản hồi của trình duyệt cho frame hoạt ảnh dài hoặc tác vụ dài khi trình duyệt cung cấp các loại mục PerformanceObserver đó.
• Nhật ký: theo dõi trực tiếp nhật ký tệp gateway với lọc/xuất (logs.tail).
• Cập nhật: chạy cập nhật package/git + khởi động lại (update.run) với báo cáo khởi động lại, sau đó thăm dò update.status sau khi kết nối lại để xác minh phiên bản gateway đang chạy.

• Với tác vụ cô lập, gửi mặc định là thông báo tóm tắt. Bạn có thể chuyển sang không gửi nếu muốn các lần chạy chỉ nội bộ.
• Trường kênh/đích xuất hiện khi thông báo được chọn.
• Chế độ Webhook dùng delivery.mode = "webhook" với delivery.to được đặt thành một URL Webhook HTTP(S) hợp lệ.
• Với tác vụ phiên chính, các chế độ gửi Webhook và không gửi đều có sẵn.
• Điều khiển chỉnh sửa nâng cao bao gồm xóa sau khi chạy, xóa ghi đè tác tử, tùy chọn cron chính xác/rải thời gian, ghi đè model/thinking của tác tử, và công tắc gửi best-effort.
• Xác thực biểu mẫu nằm inline với lỗi cấp trường; giá trị không hợp lệ sẽ vô hiệu hóa nút lưu cho đến khi được sửa.
• Đặt cron.webhookToken để gửi bearer token chuyên dụng; nếu bỏ qua, Webhook được gửi không có tiêu đề xác thực.
• Dự phòng đã ngừng dùng: các tác vụ legacy đã lưu với notify: true vẫn có thể dùng cron.webhook cho đến khi được di chuyển.

• chat.send là không chặn: nó xác nhận ngay với { runId, status: "started" } và phản hồi được truyền trực tuyến qua các sự kiện chat.
• Tải lên trong trò chuyện chấp nhận hình ảnh cùng các tệp không phải video. Hình ảnh giữ đường dẫn hình ảnh gốc; các tệp khác được lưu dưới dạng phương tiện được quản lý và hiển thị trong lịch sử dưới dạng liên kết tệp đính kèm.
• Gửi lại với cùng idempotencyKey trả về { status: "in_flight" } khi đang chạy, và { status: "ok" } sau khi hoàn tất.
• Phản hồi chat.history được giới hạn kích thước để an toàn cho UI. Khi các mục bản ghi hội thoại quá lớn, Gateway có thể cắt bớt các trường văn bản dài, bỏ qua các khối siêu dữ liệu nặng, và thay thế các tin nhắn quá cỡ bằng một placeholder ([chat.history omitted: message too large]).
• Hình ảnh do trợ lý/tạo sinh tạo ra được lưu bền dưới dạng tham chiếu phương tiện được quản lý và được phục vụ lại qua URL phương tiện Gateway có xác thực, nên các lần tải lại không phụ thuộc vào việc payload hình ảnh base64 thô vẫn còn trong phản hồi lịch sử trò chuyện.
• Khi kết xuất chat.history, Control UI loại bỏ các thẻ chỉ thị nội tuyến chỉ dùng để hiển thị khỏi văn bản trợ lý nhìn thấy được (ví dụ [[reply_to_*]] và [[audio_as_voice]]), các payload XML lời gọi công cụ dạng văn bản thuần (bao gồm <tool_call>...</tool_call>, <function_call>...</function_call>, <tool_calls>...</tool_calls>, <function_calls>...</function_calls>, và các khối lời gọi công cụ bị cắt ngắn), cùng các token điều khiển mô hình ASCII/toàn chiều bị rò rỉ, và bỏ qua các mục trợ lý mà toàn bộ văn bản nhìn thấy được chỉ là token im lặng chính xác NO_REPLY / no_reply hoặc token xác nhận Heartbeat HEARTBEAT_OK.
• Trong khi một lần gửi đang hoạt động và lần làm mới lịch sử cuối cùng, khung xem trò chuyện giữ các tin nhắn người dùng/trợ lý lạc quan cục bộ hiển thị nếu chat.history trong chốc lát trả về một ảnh chụp cũ hơn; bản ghi hội thoại chuẩn sẽ thay thế các tin nhắn cục bộ đó khi lịch sử Gateway bắt kịp.
• Các sự kiện chat trực tiếp là trạng thái phân phối, trong khi chat.history được dựng lại từ bản ghi hội thoại phiên bền vững. Sau các sự kiện kết thúc công cụ, Control UI tải lại lịch sử và chỉ hợp nhất một phần đuôi lạc quan nhỏ; ranh giới bản ghi hội thoại được ghi tài liệu trong WebChat.
• chat.inject thêm một ghi chú trợ lý vào bản ghi hội thoại phiên và phát một sự kiện chat cho các cập nhật chỉ dành cho UI (không chạy agent, không phân phối qua kênh).
• Tiêu đề trò chuyện hiển thị bộ lọc agent trước bộ chọn phiên, và bộ chọn phiên được giới hạn theo agent đã chọn. Chuyển đổi agent chỉ hiển thị các phiên gắn với agent đó và quay về phiên chính của agent đó khi nó chưa có phiên bảng điều khiển đã lưu.
• Trên chiều rộng desktop, các điều khiển trò chuyện ở trên một hàng nhỏ gọn và thu gọn khi cuộn xuống bản ghi hội thoại; cuộn lên, quay lại đầu trang, hoặc đến cuối sẽ khôi phục các điều khiển.
• Các tin nhắn chỉ có văn bản trùng lặp liên tiếp được kết xuất thành một bong bóng với huy hiệu số lượng. Các tin nhắn mang hình ảnh, tệp đính kèm, đầu ra công cụ, hoặc bản xem trước canvas được giữ nguyên không thu gọn.
• Bộ chọn mô hình và suy nghĩ ở tiêu đề trò chuyện vá phiên hoạt động ngay lập tức qua sessions.patch; chúng là các ghi đè phiên bền vững, không phải tùy chọn gửi chỉ cho một lượt.
• Gõ /new trong Control UI tạo và chuyển sang cùng phiên bảng điều khiển mới như New Chat. Gõ /reset giữ thao tác đặt lại tại chỗ rõ ràng của Gateway cho phiên hiện tại.
• Bộ chọn mô hình trò chuyện yêu cầu khung nhìn mô hình đã cấu hình của Gateway. Nếu có agents.defaults.models, danh sách cho phép đó điều khiển bộ chọn. Nếu không, bộ chọn hiển thị các mục models.providers.*.models rõ ràng cộng với các nhà cung cấp có xác thực dùng được. Danh mục đầy đủ vẫn có sẵn qua RPC gỡ lỗi models.list với view: "all".
• Khi báo cáo sử dụng phiên Gateway mới cho thấy áp lực ngữ cảnh cao, khu vực trình soạn trò chuyện hiển thị thông báo ngữ cảnh và, ở các mức Compaction được khuyến nghị, một nút nhỏ gọn chạy đường dẫn Compaction phiên bình thường. Các ảnh chụp token cũ được ẩn cho đến khi Gateway báo cáo mức sử dụng mới trở lại.

Chế độ Talk sử dụng một nhà cung cấp thoại thời gian thực đã đăng ký. Cấu hình OpenAI với talk.realtime.provider: "openai" cộng với talk.realtime.providers.openai.apiKey, hoặc cấu hình Google với talk.realtime.provider: "google" cộng với talk.realtime.providers.google.apiKey. Trình duyệt không bao giờ nhận khóa API nhà cung cấp tiêu chuẩn. OpenAI nhận một bí mật máy khách Realtime tạm thời cho WebRTC. Google Live nhận một token xác thực Live API bị ràng buộc dùng một lần cho phiên WebSocket trình duyệt, với hướng dẫn và khai báo công cụ được Gateway khóa vào token. Các nhà cung cấp chỉ cung cấp cầu nối thời gian thực backend chạy qua transport chuyển tiếp Gateway, nên thông tin xác thực và socket của nhà cung cấp vẫn ở phía máy chủ trong khi âm thanh trình duyệt đi qua các RPC Gateway đã xác thực. Lời nhắc phiên Realtime được Gateway lắp ráp; talk.client.create không chấp nhận ghi đè hướng dẫn do bên gọi cung cấp.

Trong trình soạn Chat, điều khiển Talk là nút sóng bên cạnh nút chính tả bằng micro. Khi Talk bắt đầu, hàng trạng thái trình soạn hiển thị Connecting Talk..., sau đó Talk live khi âm thanh đã kết nối, hoặc Asking OpenClaw... khi một lời gọi công cụ thời gian thực đang tham vấn mô hình lớn hơn đã cấu hình qua talk.client.toolCall.

Smoke trực tiếp cho maintainer: OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts xác minh trao đổi SDP WebRTC trình duyệt của OpenAI, thiết lập WebSocket trình duyệt bằng token bị ràng buộc của Google Live, và adapter trình duyệt chuyển tiếp Gateway với phương tiện micro giả. Lệnh chỉ in trạng thái nhà cung cấp và không ghi nhật ký bí mật.

• Nhấp Dừng (gọi chat.abort).
• Khi một lần chạy đang hoạt động, các lượt tiếp theo bình thường sẽ xếp hàng. Nhấp Điều hướng trên một tin nhắn đã xếp hàng để chèn lượt tiếp theo đó vào lượt đang chạy.
• Gõ /stop (hoặc các cụm hủy bỏ độc lập như stop, stop action, stop run, stop openclaw, please stop) để hủy bỏ ngoài băng.
• chat.abort hỗ trợ { sessionKey } (không có runId) để hủy bỏ tất cả các lần chạy đang hoạt động cho phiên đó.

• Khi một lần chạy bị hủy bỏ, văn bản trợ lý chưa hoàn tất vẫn có thể được hiển thị trong UI.
• Gateway lưu bền văn bản trợ lý chưa hoàn tất đã bị hủy bỏ vào lịch sử bản ghi hội thoại khi có đầu ra đã được đệm.
• Các mục đã lưu bao gồm siêu dữ liệu hủy bỏ để người tiêu thụ bản ghi hội thoại có thể phân biệt phần hủy bỏ chưa hoàn tất với đầu ra hoàn tất bình thường.

{
  gateway: {
    controlUi: { allowInsecureAuth: true },
    bind: "tailnet",
    auth: { mode: "token", token: "replace-me" },
  },
}

allowInsecureAuth chỉ là nút bật/tắt tương thích cục bộ:

• Nó cho phép các phiên Control UI trên localhost tiếp tục mà không cần danh tính thiết bị trong ngữ cảnh HTTP không bảo mật.
• Nó không bỏ qua các bước kiểm tra ghép cặp.
• Nó không nới lỏng yêu cầu danh tính thiết bị từ xa (không phải localhost).

{
  gateway: {
    controlUi: { dangerouslyDisableDeviceAuth: true },
    bind: "tailnet",
    auth: { mode: "token", token: "replace-me" },
  },
}

• Xác thực trusted-proxy thành công có thể cho phép các phiên Control UI của operator không cần danh tính thiết bị.
• Điều này không mở rộng cho các phiên Control UI có vai trò node.
• Proxy ngược loopback cùng máy chủ vẫn không đáp ứng xác thực trusted-proxy; xem Xác thực proxy đáng tin cậy.

• gatewayUrl được lưu trong localStorage sau khi tải và bị xóa khỏi URL.
• Nếu bạn truyền một endpoint ws:// hoặc wss:// đầy đủ qua gatewayUrl, hãy mã hóa URL giá trị gatewayUrl để trình duyệt phân tích chuỗi truy vấn chính xác.
• Nên truyền token qua fragment URL (#token=...) bất cứ khi nào có thể. Fragment không được gửi tới máy chủ, giúp tránh rò rỉ qua nhật ký yêu cầu và Referer. Tham số truy vấn ?token= cũ vẫn được nhập một lần để tương thích, nhưng chỉ như phương án dự phòng, và bị xóa ngay sau khi bootstrap.
• password chỉ được giữ trong bộ nhớ.
• Khi gatewayUrl được đặt, UI không quay về thông tin đăng nhập từ cấu hình hoặc môi trường. Cung cấp rõ ràng token (hoặc password). Thiếu thông tin đăng nhập rõ ràng là một lỗi.
• Dùng wss:// khi Gateway đứng sau TLS (Tailscale Serve, proxy HTTPS, v.v.).
• gatewayUrl chỉ được chấp nhận trong cửa sổ cấp cao nhất (không nhúng) để ngăn clickjacking.
• Các triển khai Control UI không phải loopback phải đặt rõ ràng gateway.controlUi.allowedOrigins (origin đầy đủ). Điều này bao gồm các thiết lập dev từ xa.
• Khi khởi động, Gateway có thể gieo các origin cục bộ như http://localhost:<port> và http://127.0.0.1:<port> từ bind và cổng runtime hiệu lực, nhưng origin trình duyệt từ xa vẫn cần các mục nhập rõ ràng.
• Không dùng gateway.controlUi.allowedOrigins: ["*"] trừ khi kiểm thử cục bộ được kiểm soát chặt chẽ. Nó có nghĩa là cho phép mọi origin trình duyệt, không phải "khớp với bất kỳ máy chủ nào tôi đang dùng."
• gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true bật chế độ dự phòng origin theo header Host, nhưng đây là một chế độ bảo mật nguy hiểm.