เครื่องมือแชต

แชตอนุญาตให้โมเดลเรียกเครื่องมือได้ รอบที่เปิดเครื่องมือจะทำงานเป็นลูป native หลายรอบ โมเดลขอเครื่องมือ Libre WebUI ดำเนินการภายใต้ตัวตนและสิทธิ์ของผู้ใช้ที่เรียก ส่งผลลัพธ์กลับให้โมเดล และทำต่อจนโมเดลตอบ สูงสุดแปดรอบต่อเทิร์นและแปดคำขอต่อรอบ การหยุดจะยกเลิกคำขอโมเดล เครื่องมือที่กำลังทำงาน และการรออนุมัติ

การเรียกเครื่องมือถูกบันทึกเป็นเหตุการณ์มาตรฐาน (chat.tool-call.v1, chat.tool-result.v1, chat.approval.v1) ที่ไหลเหมือนกันผ่านเส้นทาง WebSocket ส่วนตัวและสตรีมเหตุการณ์ถาวร การรีเฟรชหรือเชื่อมต่อใหม่จึงเล่นสถานะเดิมซ้ำ เทิร์นที่เสร็จจะเก็บการเรียกพร้อมตัวอย่างผลลัพธ์แบบจำกัดไว้ในข้อความผู้ช่วย

การเปิดใช้เครื่องมือ

เครื่องมือปิดโดยค่าเริ่มต้น ผู้ดูแลเปิดที่ การตั้งค่า → จัดการผู้ใช้ → การเข้าถึงและนโยบาย → สิทธิ์ใช้เครื่องมือ (เฉพาะผู้ดูแลหรือทุกคน) แต่ละเทิร์นเลือกใช้ผ่านไอคอนประแจในตัวเขียน ซึ่งเปิดตัวเลือกที่มีสวิตช์หลักและช่องเลือกต่อเครื่องมือในตัวและเซิร์ฟเวอร์ที่ลงทะเบียน เทิร์นจึงใช้เฉพาะเครื่องมือที่เลือก ตัวเลือกจำกัดสิ่งที่โปรไฟล์ผูกได้แต่ขยายไม่ได้ แชตส่วนตัว (ไม่ระบุตัวตน) ไม่มีเครื่องมือ เพราะการเรียกเครื่องมือเป็นการกระทำภายนอกและอาจทิ้งการอนุมัติกับบันทึกตรวจสอบ

สวิตช์ สิทธิ์ใช้เครื่องมือ บันทึกทันที คลิกที่สวิตช์ หรือใช้ Tab เพื่อโฟกัสแล้วกด Space เพื่อสลับค่า การเปลี่ยนสิทธิ์จะคงหน้าต่างการตั้งค่าและตำแหน่งการเลื่อนไว้ตามเดิม

โปรไฟล์ผู้ช่วย (persona) จำกัดเครื่องมือที่เสนอได้ เซิร์ฟเวอร์เครื่องมือที่ผูก ชุดย่อยเครื่องมือในตัว ทักษะที่ผูก และคอลเลกชันความรู้ที่ผูกจะจำกัดสิ่งที่โมเดลเห็นในเซสชันที่ใช้โปรไฟล์นั้น

เครื่องมือในตัว

แชตมีเครื่องมือของโครงการ 13 รายการ (ทั้งหมดอ่านอย่างเดียว ยกเว้นเครื่องมือเปลี่ยนบันทึกและปฏิทินที่ผ่านขั้นตอนอนุมัติผลข้างเคียง):

• web_search — เครื่องมือค้นหาที่ผู้ดูแลกำหนด โดยเคารพโหมดสิทธิ์ค้นหาเว็บ
• search_documents — ค้นหาแบบผสมในเอกสารอัปโหลดและคอลเลกชันความรู้ของผู้ใช้ รวมสิ่งที่แชร์ให้ (การผูกโปรไฟล์จำกัดคอลเลกชันได้) แต่ละข้อความอ้างอิงพร้อมส่วนและตำแหน่งต้นฉบับ
• list_documents — แสดงเอกสารในขอบเขตแชตพร้อม ID ชนิด และขนาด เพื่อให้โมเดลตัดสินใจว่าจะอ่านอะไร
• read_document — อ่านช่วงจำกัดของเอกสารที่ใช้ได้ตาม ID และ offset พร้อมป้ายตำแหน่งต้นฉบับ เพื่อไล่ไฟล์ที่การค้นคืนอย่างเดียวตอบไม่ได้
• load_skill — โหลดคำสั่งทักษะเต็มตาม slug คำอธิบายเครื่องมือมี manifest ทักษะที่เปิดของผู้ใช้ ทักษะจึงโหลดเมื่อโมเดลต้องใช้ หากมีไฟล์ประกอบ คำสั่งจะลงท้ายด้วยรายการไฟล์
• read_skill_file — อ่านไฟล์ประกอบหนึ่งไฟล์ตาม slug และเส้นทางสัมพัทธ์ เอกสารอ้างอิงขนาดใหญ่จึงไม่ใช้บริบทจนโมเดลเปิดจริง
• list_notes — แสดงบันทึกของผู้ใช้และที่แชร์พร้อม ID
• read_note — อ่านเนื้อหาบันทึกเต็มตาม ID
• create_note — สร้างบันทึก (มีผลข้างเคียง ต้องอนุมัติ)
• update_note — แทนเนื้อหาบันทึก โดยเก็บสถานะก่อนเป็นรุ่นที่กู้ได้ การแก้ของโมเดลจึงย้อนกลับได้เสมอ (มีผลข้างเคียง ต้องอนุมัติ)
• list_calendar_events — แสดงกิจกรรมปฏิทินของผู้ใช้ทั้งของตนและที่แชร์ในช่วงมิลลิวินาที epoch
• create_calendar_event — สร้างกิจกรรมปฏิทิน (มีผลข้างเคียง ต้องอนุมัติ)
• delete_calendar_event — ลบกิจกรรมตาม ID (มีผลข้างเคียง ต้องอนุมัติ)

เซิร์ฟเวอร์เครื่องมือ

ผู้ดูแลลงทะเบียนเซิร์ฟเวอร์เครื่องมือภายนอกใน การตั้งค่า → เครื่องมือ (เทมเพลตเริ่มต้นจะกรอกแบบฟอร์มไว้ รวม API สาธิตสาธารณะที่ปลอดภัย):

• OpenAPI: ดึงข้อกำหนด JSON OpenAPI 3.x ครั้งเดียวและตรึงด้วย digest SHA-256 แต่ละการทำงานเป็นเครื่องมือ การทำงาน GET จัดเป็นอ่านอย่างเดียว ส่วนอื่นเป็นผลข้างเคียงจนผู้ดูแลแทนการจัดประเภทต่อเครื่องมือ การดำเนินการสร้างคำขอใหม่จากการทำงานที่ตรึง อาร์กิวเมนต์โมเดลไม่เลือกปลายทาง
• MCP (HTTP แบบ streaming): ดึงรายการเครื่องมือเซิร์ฟเวอร์ผ่าน JSON-RPC และตรึงแบบเดียวกัน annotations.readOnlyHint ระบุว่าอ่านอย่างเดียว ไม่รองรับเซิร์ฟเวอร์ MCP stdio โดยตั้งใจ เพราะโปรเซสภายนอกไม่รันในโปรเซสเว็บ

รายการที่เปลี่ยนมีผลเมื่อผู้ดูแลรีเฟรชเซิร์ฟเวอร์ ซึ่งเลื่อนรุ่นที่ตรึงและเก็บการแทนต่อเครื่องมือ ความพร้อมต่อเซิร์ฟเวอร์เป็นเฉพาะผู้ดูแล ทุกผู้ใช้ หรือตามสิทธิ์ผ่านโมเดลให้ทรัพยากรร่วม (สิทธิ์ผู้ใช้และกลุ่มบนเซิร์ฟเวอร์)

ข้อมูลประจำตัว

เซิร์ฟเวอร์ที่ต้องยืนยันตัวตนใช้ข้อมูลประจำตัวต่อผู้ใช้ (bearer token หรือ header ที่มีชื่อ) ข้อมูลลับแต่ละรายการเข้ารหัสพร้อมข้อมูลยืนยันเพิ่มเติมที่ผูกกับผู้ใช้และเซิร์ฟเวอร์ตรงกัน ผู้ใช้แต่ละรายป้อนใน การตั้งค่า → เครื่องมือ และไม่แชร์ระหว่างบัญชี

OAuth แบบโต้ตอบ (MCP)

เซิร์ฟเวอร์ MCP ยังให้แต่ละคนเข้าสู่ระบบเองได้ด้วย ลงทะเบียนด้วยโหมดยืนยันตัวตน OAuth แบบโต้ตอบ แล้ว Libre WebUI จะอ่านความท้าทาย WWW-Authenticate ที่เซิร์ฟเวอร์ตอบกลับ ตามไปยัง metadata ของ protected-resource จากนั้นไปยัง metadata ของ authorization server และลงทะเบียน client แบบไดนามิก (RFC 7591) เมื่อ authorization server เปิดให้ลงทะเบียน ผู้ให้บริการที่ไม่ลงทะเบียน client อัตโนมัติจะรับ client id ที่ผู้ดูแลกรอกในแบบฟอร์มลงทะเบียน (พร้อม secret แบบ ทางเลือก) โดย secret จะถูกเข้ารหัสไว้คู่กับ endpoint ที่ค้นพบ

จากนั้นแต่ละคนกด เชื่อมต่อ บนการ์ดของเซิร์ฟเวอร์แล้วถูกพาไปยังผู้ให้บริการ flow ใช้ PKCE (S256) พร้อม CSRF state และ PKCE verifier เก็บใน cookie แบบ HttpOnly ที่จำกัดขอบเขตไว้กับเซิร์ฟเวอร์นั้นเซิร์ฟเวอร์เดียว callback จะแลก code บนฝั่งเซิร์ฟเวอร์ เก็บ token ที่เข้ารหัสด้วยการผูกผู้ใช้-เซิร์ฟเวอร์แบบ เดียวกับ secret แบบ static แล้วส่งเบราว์เซอร์กลับมาที่แอปพร้อม flag สถานะ — access และ refresh token ไม่ถึงหน้าเว็บเลย access token จะรีเฟรชอัตโนมัติ หนึ่งนาทีก่อนหมดอายุ ครั้งเดียวต่อคนต่อเซิร์ฟเวอร์แม้มีหลายการเรียกเครื่องมือ แข่งกัน เมื่อรีเฟรชไม่ได้ การเรียกเครื่องมือจะกลับมาขอให้เชื่อมต่อใหม่แทนที่ จะล้มเหลวแบบไม่ระบุตัวตน ตัดการเชื่อมต่อ จะลบ token ของคนนั้นแต่คงการ ลงทะเบียนไว้ ส่วนการลบเซิร์ฟเวอร์จะลืมค่าที่ค้นพบไปด้วย

เซิร์ฟเวอร์ที่ปฏิเสธการแสดงรายการเครื่องมือแบบไม่ยืนยันตัวตนก็ยังลงทะเบียนได้: รายการเครื่องมือจะถูกตรึงไว้ตั้งแต่การเชื่อมต่อสำเร็จครั้งแรก (และทุกครั้งที่ ผู้ดูแลรีเฟรช) จึงไม่มีอะไรถูกเสนอให้โมเดลก่อนที่จะรู้จักมันจริง ๆ

นโยบาย egress

ทุกคำขอเครื่องมือแปลงปลายทางเอง ปฏิเสธพื้นที่ที่อยู่ส่วนตัว loopback และ metadata และตรึงการเชื่อมต่อกับที่อยู่ที่แปลงเพื่อไม่ให้ DNS rebind เปลี่ยนเส้นทาง ปฏิเสธคำตอบ redirect ขนาดคำตอบถูกจำกัดและทุกคำขอมีเวลาหมดอายุเข้มงวด อนุญาตชื่อโฮสต์ภายในตรงได้ด้วย TOOLS_PRIVATE_NETWORK_ALLOWLIST (คั่นจุลภาค) โฮสต์ที่อนุญาตยังถูกตรึงและจำกัด เอาต์พุตเครื่องมือกลับเข้าโมเดลเป็นข้อความที่ไม่น่าเชื่อถือ

การอนุมัติ

เครื่องมืออ่านอย่างเดียวทำงานโดยไม่ถาม เครื่องมือมีผลข้างเคียงจะหยุดเทิร์นและถามผู้ใช้ว่าอนุญาตครั้งเดียว สำหรับแชตนี้ อนุญาตเครื่องมือนี้บนเซิร์ฟเวอร์เสมอ หรือปฏิเสธ การตัดสินใจเป็นแบบถาวร สิทธิ์ "เสมอ" อยู่ผ่านการเริ่มใหม่และถอนได้ใน การตั้งค่า → เครื่องมือ ส่วนคำขอรอจะหมดอายุหลังสองนาทีซึ่งโมเดลเห็นเป็นการปฏิเสธ การปฏิเสธและหมดเวลาไม่ดำเนินคำขอ ทุกการตัดสินใจและคำขอทิ้งเหตุการณ์ตรวจสอบความปลอดภัยที่ตัดข้อมูลแล้ว

ตัวอย่าง

เปิดสวิตช์ประแจในตัวเขียนก่อน ตัวอย่างทั้งหมดด้านล่างเป็นข้อความแชตปกติ

web_search — ค้นข้อมูล

รุ่น SQLite ล่าสุดเปลี่ยนอะไรบ้าง ค้นเว็บก่อนตอบ

โมเดลเรียก web_search ด้วยคำค้นเช่น {"query": "SQLite latest release changelog"} การ์ดคำขอแสดงข้อความผลลัพธ์ที่ได้รับและคำตอบอ้างอิงสิ่งที่พบ ต้องกำหนดค่าการค้นหาเว็บและอนุญาตบัญชีของคุณ

search_documents — ถามเกี่ยวกับไฟล์ของคุณ

อัปโหลด PDF หรือเพิ่มเอกสารในคอลเลกชันความรู้ จากนั้น:

ค้นหาข้อกำหนดการยุติในเอกสารของฉันและยกข้อความตรง ๆ

โมเดลเรียก search_documents ด้วย {"query": "termination clause"} และรับข้อความที่ตรงพร้อมป้ายเอกสารต้นฉบับ คำตอบจึงยกและระบุแหล่งที่มาได้

load_skill — ใช้ทักษะที่บันทึก

สร้างทักษะใน การตั้งค่า → ทักษะ (เช่น $release-notes วิธีที่คุณต้องการเขียนบันทึกรุ่น) แล้ว:

ร่างบันทึกรุ่นสำหรับ diff นี้ด้วย $release-notes

โมเดลเห็นทักษะใน manifest เรียก load_skill {"slug": "release-notes"} เพื่อดึงคำสั่งเต็มและทำตาม การพิมพ์ $ ในตัวเขียนจะเติม slug ทักษะอัตโนมัติ

เซิร์ฟเวอร์ OpenAPI — เช่น API สภาพอากาศ

1. การตั้งค่า → เครื่องมือ → ลงทะเบียนเซิร์ฟเวอร์: ชื่อ Weather, ชนิด OpenAPI, URL ฐาน https://api.example-weather.dev, URL ข้อกำหนด https://api.example-weather.dev/openapi.json, โหมดยืนยัน bearer

2. ข้อกำหนดถูกตรึงและการทำงานปรากฏเป็นเครื่องมือ เช่น getForecast (GET, อ่านอย่างเดียว) และ createAlert (POST, ผลข้างเคียง)

3. ผู้ใช้แต่ละรายบันทึกคีย์ API ของตนในการ์ดเซิร์ฟเวอร์

4. ในแชต:

   พยากรณ์อากาศมอนทรีออลสุดสัปดาห์นี้เป็นอย่างไร

   โมเดลเรียก weather__getForecast {"city": "Montreal"} และทำงานทันที เครื่องมืออ่านอย่างเดียวไม่ถาม

   แจ้งฉันหากคืนนี้ต่ำกว่า -20

   weather__createAlert มีผลข้างเคียง เทิร์นจึงหยุดพร้อมการ์ดอนุมัติ: อนุญาตครั้งเดียว, อนุญาตสำหรับแชตนี้, อนุญาตเสมอ หรือ ปฏิเสธ จะไม่ส่งอะไรจนคุณเลือก

Exa MCP — ค้นหาและดึงเนื้อหาเว็บ

ที่ การตั้งค่า → เครื่องมือ → เริ่มจากเทมเพลต เลือก Exa เพื่อกรอกการลงทะเบียน MCP ล่วงหน้าด้วย:

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

URL นี้เลือก web_search_exa และ web_fetch_exa ผ่านพารามิเตอร์เลือกเครื่องมือของ Exa เทมเพลตไม่ใช้การยืนยันตัวตนและจำกัดการเข้าถึงไว้เฉพาะผู้ดูแลระบบตามค่าเริ่มต้น ตรวจทานแบบฟอร์มแล้วเลือก บันทึก เพื่อเชื่อมต่อและตรึงรายการเครื่องมือ การเปิดหรือยกเลิกเทมเพลตจะไม่ติดต่อ Exa คำค้นและ URL ที่ร้องขอจะถูกส่งไปยัง Exa เมื่อเครื่องมือเหล่านี้ทำงาน

เซิร์ฟเวอร์ MCP — เช่น ตัวติดตาม issue

1. การตั้งค่า → เครื่องมือ → ลงทะเบียนเซิร์ฟเวอร์: ชื่อ Issues, ชนิด MCP, URL ฐาน https://mcp.example-tracker.dev/mcp, โหมดยืนยัน header โดยใช้ชื่อ X-Api-Key

2. รายการเครื่องมือถูกตรึง เครื่องมือที่เซิร์ฟเวอร์ระบุว่าอ่านอย่างเดียว (เช่น search_issues) ทำงานได้อิสระ ส่วนอื่น (เช่น create_issue) ต้องถามก่อน

3. ในแชต:

   ค้นหา issue เปิดที่กล่าวถึง "database lock" แล้วสร้าง issue ใหม่สรุปรูปแบบ

   issues__search_issues ทำงานทันที ส่วน issues__create_issue แสดงอาร์กิวเมนต์ตรงในการ์ดอนุมัติเพื่อให้อ่านสิ่งที่จะส่งก่อนอนุญาต

ตัวแปรสภาพแวดล้อม

ตัวแปร	ผล
TOOLS_ACCESS_MODE	ตรึงฟีเจอร์เครื่องมือเป็น admins หรือ all-users และล็อกสวิตช์ผู้ดูแล
TOOLS_PRIVATE_NETWORK_ALLOWLIST	ชื่อโฮสต์ตรงที่เซิร์ฟเวอร์เครื่องมือแปลงเป็นที่อยู่ส่วนตัวได้ (รายการจุลภาค)

ขอบเขต

• การเรียกเครื่องมือทำงานบนเส้นทาง WebSocket (การขนส่งเซสชันส่วนตัวถูกตัดโดยออกแบบ) และเส้นทางสร้างถาวรสำหรับแชตที่เก็บ endpoint REST streaming รุ่นเก่าไม่รันลูปเครื่องมือ
• การกล่าวถึง @model ในแชนเนล รันลูปเดียวกันกับแคตตาล็อกของสมาชิกที่กล่าวถึง โดยมีข้อแตกต่างหนึ่งอย่าง: ไม่มีใครให้ถาม เครื่องมือที่มีผลข้างเคียงซึ่งไม่มีสิทธิ์อนุมัติแบบถาวรจึงถูกปฏิเสธทันทีแทนการรอ ส่วนเครื่องมืออ่านอย่างเดียวทำงานตามปกติ
• เอเจนต์ Work เรียกใช้เซิร์ฟเวอร์เดียวกันผ่านเกตเวย์เดียวกัน เฉพาะการรันที่เปิดเครือข่ายเท่านั้น เซิร์ฟเวอร์ที่ไม่มีข้อมูลรับรองจะถูกกรองออกตั้งแต่ตอนเสนอเครื่องมือ และเครื่องมือที่มีผลข้างเคียงจะถูกกำกับด้วยการอนุมัติของ Work
• โมเดล Gemini และ CLI เอเจนต์ไม่ได้รับเครื่องมือ ผู้ให้บริการ Ollama, ที่เข้ากันได้กับ OpenAI, Responses-API และ Anthropic ได้รับ
• OAuth แบบโต้ตอบใช้ได้เฉพาะ MCP: เซิร์ฟเวอร์ OpenAPI ยังใช้ข้อมูลประจำตัวคงที่ต่อผู้ใช้ flow เป็น authorization-code grant แบบ PKCE ไม่มี device-code หรือ client-credentials flow ให้ใช้ และ authorization server ที่ไม่เผยแพร่ metadata (หรือไม่มี endpoint ลงทะเบียนและไม่มี client id ที่ผู้ดูแลกรอกไว้) จะเชื่อมต่อไม่ได้
• endpoint OAuth ที่ค้นพบต้องเป็น https; http ธรรมดายอมรับเฉพาะ loopback สำหรับผู้ให้บริการที่รันบนเครื่องเดียวกันระหว่างพัฒนาเท่านั้น
• redirect URI มาจาก BASE_URL (หรือ CORS_ORIGIN ตัวแรก) ดังนั้นค่านี้ต้องเป็นที่อยู่ที่เบราว์เซอร์เข้าถึงได้จริง และต้องลงทะเบียนไว้กับผู้ให้บริการที่ตรึง redirect URI