Công cụ trò chuyện

Trò chuyện có thể cho phép mô hình gọi công cụ. Một lượt bật công cụ chạy vòng lặp native nhiều vòng: mô hình yêu cầu công cụ, Libre WebUI thực thi theo danh tính và quyền của người dùng gọi, kết quả được gửi lại cho mô hình, rồi vòng lặp tiếp tục đến khi mô hình trả lời—tối đa tám vòng mỗi lượt và tám lệnh gọi mỗi vòng. Dừng sẽ hủy lệnh gọi mô hình, mọi lệnh gọi công cụ đang chạy và mọi lần chờ phê duyệt.

Lệnh gọi công cụ được ghi thành các sự kiện chuẩn hóa (chat.tool-call.v1, chat.tool-result.v1, chat.approval.v1) chảy giống nhau qua đường WebSocket riêng tư và luồng sự kiện bền vững, nên làm mới hoặc kết nối lại sẽ phát lại cùng trạng thái. Lượt đã hoàn tất lưu các lệnh gọi cùng bản xem trước kết quả có giới hạn trên tin nhắn trợ lý.

Bật công cụ

Công cụ mặc định bị tắt. Quản trị viên mở chúng trong Cài đặt → Quản lý người dùng → Quyền truy cập và chính sách → Quyền dùng công cụ (chỉ quản trị viên hoặc mọi người dùng); mỗi lượt sau đó chọn tham gia qua biểu tượng cờ lê trong trình soạn thảo, mở bộ chọn gồm công tắc chính cùng một hộp kiểm cho mỗi công cụ tích hợp và máy chủ đã đăng ký. Vì vậy, lượt chỉ chạy đúng các công cụ bạn chọn. Bộ chọn có thể thu hẹp nội dung hồ sơ ràng buộc, không bao giờ mở rộng. Trò chuyện riêng tư (ẩn danh) không cung cấp công cụ: lệnh gọi công cụ là hành động hướng ra ngoài và có thể để lại phê duyệt cùng bản ghi kiểm toán.

Công tắc Quyền dùng công cụ lưu ngay lập tức. Bấm vào nó, hoặc dùng Tab để đưa tiêu điểm vào rồi Space để bật tắt. Việc đổi quyền vẫn giữ nguyên cửa sổ Cài đặt và vị trí cuộn của nó.

Hồ sơ trợ lý (persona) có thể giới hạn công cụ được cung cấp: máy chủ công cụ ràng buộc, một tập con công cụ tích hợp, kỹ năng ràng buộc và bộ sưu tập kiến thức ràng buộc sẽ hạn chế những gì mô hình thấy trong phiên dùng hồ sơ đó.

Công cụ tích hợp

Trò chuyện đi kèm mười ba công cụ chính chủ (tất cả chỉ đọc ngoại trừ công cụ thay đổi ghi chú và lịch, vốn phải qua luồng phê duyệt tác dụng phụ):

• web_search — công cụ tìm kiếm do quản trị viên cấu hình, tuân theo chế độ truy cập tìm kiếm web.
• search_documents — tìm kiếm kết hợp trong tài liệu tải lên và bộ sưu tập kiến thức của người dùng, gồm bộ sưu tập được chia sẻ với họ (ràng buộc hồ sơ có thể giới hạn bộ sưu tập); mỗi đoạn đều được trích dẫn cùng vị trí đoạn và nguồn.
• list_documents — liệt kê tài liệu trong phạm vi trò chuyện này cùng ID, loại và kích thước để mô hình quyết định nội dung cần đọc.
• read_document — đọc một cửa sổ có giới hạn của tài liệu khả dụng theo ID và offset, có nhãn vị trí nguồn, để duyệt tệp mà chỉ truy xuất không đủ trả lời.
• load_skill — nạp toàn bộ hướng dẫn kỹ năng theo slug; mô tả công cụ mang manifest các kỹ năng đang bật của người dùng, nên kỹ năng chỉ được nạp khi mô hình cần. Nếu kỹ năng có tệp đi kèm, hướng dẫn đã nạp kết thúc bằng danh mục tệp.
• read_skill_file — đọc một tệp đi kèm trong kỹ năng theo slug và đường dẫn tương đối, nên tài liệu tham chiếu lớn không tốn ngữ cảnh đến khi mô hình thật sự mở.
• list_notes — liệt kê ghi chú của người dùng và ghi chú được chia sẻ cùng ID.
• read_note — đọc toàn bộ nội dung một ghi chú theo ID.
• create_note — tạo ghi chú (có tác dụng phụ, cần phê duyệt).
• update_note — thay nội dung ghi chú; trạng thái trước được giữ làm phiên bản có thể khôi phục, nên chỉnh sửa của mô hình luôn hoàn tác được (có tác dụng phụ, cần phê duyệt).
• list_calendar_events — liệt kê sự kiện lịch của người dùng, cả của mình và được chia sẻ, trong phạm vi mili giây epoch.
• create_calendar_event — tạo sự kiện lịch (có tác dụng phụ, cần phê duyệt).
• delete_calendar_event — xóa một sự kiện lịch theo ID (có tác dụng phụ, cần phê duyệt).

Máy chủ công cụ

Quản trị viên đăng ký máy chủ công cụ bên ngoài trong Cài đặt → Công cụ (các mẫu ban đầu điền sẵn biểu mẫu, gồm một API demo công khai an toàn):

• OpenAPI: đặc tả JSON OpenAPI 3.x được tải một lần và ghim bằng digest SHA-256. Mỗi thao tác trở thành một công cụ; thao tác GET được phân loại chỉ đọc, còn tất cả thao tác khác là tác dụng phụ cho đến khi quản trị viên ghi đè phân loại theo từng công cụ. Việc thực thi dựng lại lệnh gọi từ thao tác đã ghim—đối số mô hình không bao giờ chọn đích.
• MCP (HTTP có thể truyền luồng): danh sách công cụ của máy chủ được tải qua JSON-RPC và ghim tương tự. annotations.readOnlyHint đánh dấu công cụ chỉ đọc. Máy chủ MCP stdio chủ ý không được hỗ trợ: tiến trình bên ngoài không bao giờ chạy trong tiến trình web.

Danh mục thay đổi chỉ có hiệu lực khi quản trị viên làm mới máy chủ, từ đó tăng phiên bản đã ghim và giữ override theo công cụ. Khả dụng theo máy chủ có thể là chỉ quản trị viên, mọi người dùng hoặc dựa trên quyền qua mô hình cấp tài nguyên chung (cấp cho người dùng và nhóm trên máy chủ công cụ).

Thông tin xác thực

Máy chủ cần xác thực dùng thông tin xác thực theo người dùng (token bearer hoặc header có tên). Mỗi bí mật được mã hóa cùng dữ liệu xác thực bổ sung để ràng buộc với đúng người dùng và máy chủ, do từng người dùng nhập trong Cài đặt → Công cụ và không bao giờ chia sẻ giữa các tài khoản.

OAuth tương tác (MCP)

Một máy chủ MCP cũng có thể cho từng người tự đăng nhập. Đăng ký máy chủ với chế độ xác thực OAuth tương tác và Libre WebUI đọc thử thách WWW-Authenticate mà máy chủ trả về, đi theo nó tới metadata resource được bảo vệ, rồi tới metadata của authorization server, và đăng ký một client động (RFC 7591) khi authorization server hỗ trợ đăng ký. Với provider không tự đăng ký client, administrator nhập client id (và tùy chọn secret) ngay trên form đăng ký; secret được mã hóa cùng các endpoint đã khám phá.

Mỗi người sau đó bấm Kết nối trên card của máy chủ và được chuyển đến provider. Luồng này dùng PKCE (S256) với CSRF state, và verifier PKCE được giữ trong cookie HttpOnly chỉ dành riêng cho máy chủ đó. Callback đổi code trên server, lưu token đã mã hóa với cùng ràng buộc theo người dùng và máy chủ như một secret tĩnh, rồi đưa trình duyệt quay lại app với một cờ trạng thái — access token và refresh token không bao giờ đến trang. Access token tự làm mới một phút trước khi hết hạn, một lần cho mỗi người và mỗi máy chủ kể cả khi nhiều lệnh gọi công cụ chạy đua nhau. Khi không thể làm mới, lệnh gọi công cụ trả lời yêu cầu kết nối lại thay vì thất bại âm thầm. Ngắt kết nối xóa token của người đó và giữ nguyên đăng ký máy chủ; xóa máy chủ thì quên luôn cấu hình đã khám phá.

Một máy chủ từ chối liệt kê công cụ khi chưa xác thực vẫn được đăng ký bình thường: danh mục công cụ của nó được ghim lại ở lần kết nối thành công đầu tiên (và ở mỗi lần administrator làm mới), nên không gì được đưa cho một mô hình trước khi đã biết rõ.

Chính sách egress

Mỗi yêu cầu công cụ tự phân giải đích, từ chối không gian địa chỉ riêng tư, loopback và metadata, đồng thời ghim kết nối vào địa chỉ đã phân giải để DNS rebind không thể chuyển hướng lệnh gọi. Phản hồi chuyển hướng bị từ chối. Kích thước phản hồi bị giới hạn và mọi lệnh gọi có thời gian chờ cứng. Có thể cho phép tên máy chủ nội bộ chính xác bằng TOOLS_PRIVATE_NETWORK_ALLOWLIST (phân tách bằng dấu phẩy); máy chủ được cho phép vẫn bị ghim và giới hạn. Đầu ra công cụ quay lại mô hình dưới dạng văn bản không đáng tin cậy.

Phê duyệt

Công cụ chỉ đọc chạy mà không hỏi. Công cụ có tác dụng phụ tạm dừng lượt và hỏi người dùng: cho phép một lần, cho phép trong cuộc trò chuyện này, luôn cho phép công cụ này trên máy chủ này hoặc từ chối. Quyết định có tính bền vững—quyền "luôn cho phép" tồn tại qua khởi động lại và có thể thu hồi trong Cài đặt → Công cụ—còn yêu cầu đang chờ hết hạn sau hai phút, được mô hình xem là từ chối. Việc từ chối và hết thời gian không bao giờ thực thi lệnh gọi. Mọi quyết định và lệnh gọi đều để lại sự kiện kiểm toán bảo mật đã biên tập.

Ví dụ

Trước tiên hãy bật công tắc cờ lê trong trình soạn thảo; mỗi ví dụ dưới đây là một tin nhắn trò chuyện thông thường.

web_search — tra cứu thông tin

Điều gì thay đổi trong bản phát hành SQLite mới nhất? Hãy tìm kiếm trên web trước khi trả lời.

Mô hình gọi web_search với truy vấn như {"query": "SQLite latest release changelog"}, thẻ lệnh gọi hiển thị các đoạn kết quả nhận được và câu trả lời trích dẫn nội dung tìm thấy. Tìm kiếm web phải được cấu hình và cho phép cho tài khoản của bạn.

search_documents — hỏi về tệp của bạn

Tải PDF lên hoặc thêm tài liệu vào bộ sưu tập kiến thức, sau đó:

Tìm điều khoản chấm dứt trong tài liệu của tôi và trích nguyên văn.

Mô hình gọi search_documents với {"query": "termination clause"} và nhận các đoạn phù hợp có nhãn tài liệu nguồn, nhờ đó câu trả lời có thể trích dẫn và ghi nguồn.

load_skill — áp dụng kỹ năng đã lưu

Tạo kỹ năng trong Cài đặt → Kỹ năng (ví dụ $release-notes—cách bạn muốn viết ghi chú phát hành), rồi:

Soạn ghi chú phát hành cho diff này bằng $release-notes.

Mô hình thấy kỹ năng trong manifest, gọi load_skill {"slug": "release-notes"} để lấy đầy đủ hướng dẫn rồi làm theo. Gõ $ trong trình soạn thảo sẽ tự động hoàn thành slug kỹ năng của bạn.

Máy chủ OpenAPI — ví dụ API thời tiết

1. Cài đặt → Công cụ → Đăng ký máy chủ: tên Weather, loại OpenAPI, URL cơ sở https://api.example-weather.dev, URL đặc tả https://api.example-weather.dev/openapi.json, chế độ xác thực bearer.

2. Đặc tả được ghim và các thao tác xuất hiện dưới dạng công cụ—ví dụ getForecast (GET, chỉ đọc) và createAlert (POST, tác dụng phụ).

3. Mỗi người dùng muốn sử dụng phải lưu khóa API riêng trên thẻ máy chủ.

4. Trong trò chuyện:

   Dự báo thời tiết Montreal cuối tuần này thế nào?

   Mô hình gọi weather__getForecast {"city": "Montreal"} và chạy ngay—công cụ chỉ đọc không bao giờ hỏi.

   Báo cho tôi nếu nhiệt độ xuống dưới -20 tối nay.

   weather__createAlert có tác dụng phụ nên lượt tạm dừng với thẻ phê duyệt: Cho phép một lần, Cho phép trong cuộc trò chuyện này, Luôn cho phép hoặc Từ chối. Không có gì được gửi trước khi bạn chọn.

Exa MCP — tìm kiếm và tải nội dung web

Trong Cài đặt → Công cụ → Bắt đầu từ một mẫu, chọn Exa để điền sẵn một đăng ký MCP với:

https://mcp.exa.ai/mcp?tools=web_search_exa,web_fetch_exa

URL này chọn web_search_exa và web_fetch_exa bằng tham số chọn công cụ của Exa. Mẫu không dùng xác thực và mặc định chỉ cho quản trị viên truy cập. Hãy xem lại biểu mẫu rồi chọn Lưu để kết nối và ghim danh sách công cụ. Việc mở hoặc hủy mẫu không liên hệ với Exa. Truy vấn tìm kiếm và URL được yêu cầu sẽ gửi tới Exa khi các công cụ này chạy.

Máy chủ MCP — ví dụ trình theo dõi issue

1. Cài đặt → Công cụ → Đăng ký máy chủ: tên Issues, loại MCP, URL cơ sở https://mcp.example-tracker.dev/mcp, chế độ xác thực header với tên header X-Api-Key.

2. Danh sách công cụ được ghim; công cụ được máy chủ đánh dấu chỉ đọc (như search_issues) chạy tự do, còn mọi công cụ khác (như create_issue) đều hỏi trước.

3. Trong trò chuyện:

   Tìm các issue đang mở có nhắc "database lock" và tạo issue mới tóm tắt mẫu đó.

   issues__search_issues chạy ngay; issues__create_issue hiển thị đối số chính xác trong thẻ phê duyệt để bạn đọc nội dung sẽ gửi trước khi cho phép.

Biến môi trường

Biến	Tác dụng
TOOLS_ACCESS_MODE	Ghim tính năng công cụ vào admins hoặc all-users và khóa công tắc quản trị.
TOOLS_PRIVATE_NETWORK_ALLOWLIST	Tên máy chủ chính xác mà máy chủ công cụ có thể phân giải thành địa chỉ riêng (danh sách dấu phẩy).

Ranh giới

• Lệnh gọi công cụ chạy trên đường WebSocket (phương thức truyền phiên riêng tư được loại trừ theo thiết kế) và đường tạo bền vững dùng cho trò chuyện được lưu. Endpoint streaming REST cũ không chạy vòng lặp công cụ.
• Lượt nhắc @model trong kênh chạy cùng vòng lặp đó với danh mục của thành viên đã nhắc, chỉ khác một điều: không có ai để hỏi, nên một công cụ có tác dụng phụ mà chưa có phê duyệt thường trực bị từ chối ngay thay vì chờ. Công cụ chỉ đọc vẫn chạy bình thường.
• Tác tử Work gọi cùng các máy chủ đó qua cùng cổng: chỉ trong các lần chạy có bật mạng, máy chủ thiếu thông tin xác thực bị lọc bỏ ngay khi chào công cụ, công cụ có tác dụng phụ bị chặn bởi phê duyệt của Work.
• Mô hình Gemini và CLI tác tử không nhận công cụ; các nhà cung cấp Ollama, tương thích OpenAI, Responses-API và Anthropic có nhận.
• OAuth tương tác chỉ dành cho MCP: máy chủ OpenAPI vẫn dùng thông tin xác thực tĩnh theo người dùng. Luồng này là authorization-code grant kèm PKCE; luồng device-code và client-credentials không được hỗ trợ, và một authorization server không công bố metadata (hoặc không có endpoint đăng ký lẫn client id do administrator cung cấp) thì không thể kết nối.
• Các endpoint OAuth đã khám phá phải là https; http thường chỉ được chấp nhận cho loopback, dành cho một provider chạy trên cùng máy trong lúc phát triển.
• Redirect URI được suy ra từ BASE_URL (hoặc CORS_ORIGIN đầu tiên), nên giá trị đó phải là địa chỉ trình duyệt thực sự truy cập được và phải được đăng ký với provider nào ghim sẵn redirect URI.