ClawRouter

ClawRouter มอบคีย์เดียวที่จำกัดขอบเขตด้วยนโยบายให้ OpenClaw สำหรับผู้ให้บริการโมเดลต้นทางหลายราย Plugin clawrouter ที่รวมมาให้จะค้นหาเฉพาะโมเดลที่คีย์นั้นอนุญาต กำหนดเส้นทางแต่ละโมเดลผ่านโปรโตคอลที่ประกาศไว้ และรายงานงบประมาณกับการใช้งานรวมของคีย์บนส่วนแสดงการใช้งานของ OpenClaw

ข้อมูลประจำตัวของระบบต้นทางและการส่งต่อตามผู้ให้บริการจะอยู่ใน ClawRouter ดังนั้นคุณจึงไม่ต้องติดตั้งหรือยืนยันตัวตน Plugin ของผู้ให้บริการต้นทางแต่ละรายบนโฮสต์ OpenClaw Plugin นี้รวมมากับ OpenClaw (enabledByDefault: true) คุณต้องมีเพียงข้อมูลประจำตัว ClawRouter ที่ออกให้แล้ว

เริ่มต้นใช้งาน

export CLAWROUTER_API_KEY="..."openclaw onboard --auth-choice clawrouter-api-keyopenclaw plugins enable clawrouter

openclaw models list --all --provider clawrouter

openclaw models set clawrouter/<provider>/<model>

การติดตั้งใช้งานแบบไม่โต้ตอบที่มีการจัดการ

เก็บคีย์พร็อกซีไว้ในการฉีดข้อมูลลับของเวิร์กโหลด และจัดเก็บเฉพาะ SecretRef ใน openclaw.json ฟิลด์มาตรฐานสำหรับการจัดการมีดังนี้:

ตัวอย่างเช่น ตัวควบคุมการติดตั้งใช้งานสามารถเป็นเจ้าของแพตช์ JSON5 นี้:

{  plugins: {    entries: { clawrouter: { enabled: true } },  },  models: {    providers: {      clawrouter: {        baseUrl: "https://clawrouter.internal.example",        apiKey: {          source: "env",          provider: "default",          id: "CLAWROUTER_API_KEY",        },        headers: {          "X-ClawRouter-Project-Id": "fakeco",        },      },    },  },  agents: {    defaults: {      model: { primary: "clawrouter/openai/gpt-5.5" },    },  },}

หากการติดตั้งใช้งานตั้งค่า plugins.allow ให้คงรายการเดิมไว้และเพิ่ม clawrouter ตรวจสอบความถูกต้องและนำไปใช้โดยไม่ใช้ตัวช่วยสร้างแบบโต้ตอบ:

openclaw config patch --file ./clawrouter.patch.json5 --dry-run --jsonopenclaw config patch --file ./clawrouter.patch.json5

การทดลองรันจะประมวลผล SecretRef แต่จะไม่แสดงค่าของข้อมูลลับ หากต้องการหมุนเวียนข้อมูลประจำตัว ให้อัปเดต Secret ภายนอกที่จัดหา CLAWROUTER_API_KEY และเริ่มเวิร์กโหลด Gateway ใหม่เพื่อโหลดสภาพแวดล้อมของกระบวนการใหม่ ไฟล์การกำหนดค่าและการอ้างอิงโมเดลจะไม่เปลี่ยนแปลง

สำหรับ Gateway แบบ Docker สแตนด์อโลนที่สร้างจากซอร์ส ClawRouter รวมอยู่ในรันไทม์รากแล้ว ให้เลือกเฉพาะ Plugin ช่องทางที่ต้องจัดแพ็กเกจแยกต่างหาก เช่น OPENCLAW_EXTENSIONS=clickclack, slack หรือ msteams โปรดดู อิมเมจที่สร้างจากซอร์สพร้อม Plugin ที่เลือก การติดตั้งใช้งานแบบไฟล์เก็บถาวร/อุปกรณ์ต้องจัดแพ็กเกจซอร์สเดียวกันที่รวมเข้ามาแล้วผ่านไปป์ไลน์อาร์ติแฟกต์ของตนเอง แทนการใช้อิมเมจ OCI

ความพร้อมและหลักฐานจากระบบจริง

การตรวจสอบเหล่านี้พิสูจน์ขอบเขตที่แตกต่างกัน ห้ามใช้แทนกัน:

# ClawRouter process health only; no credential or upstream model is exercised.curl -fsS https://clawrouter.internal.example/v1/health # OpenClaw gateway startup readiness only; no model call is made.curl -fsS http://127.0.0.1:18789/readyz # Credential-scoped catalog discovery.openclaw models list --all --provider clawrouter --json # Minimal real inference probe through the configured ClawRouter provider.openclaw models status --probe --probe-provider clawrouter --probe-max-tokens 8 --json # Workload canary using an exact granted model ref.openclaw agent --agent main \  --model clawrouter/openai/gpt-5.5 \  --message "Reply exactly: CLAWROUTER_CANARY_OK" \  --json

ใช้โมเดลที่ส่งคืนจากแค็ตตาล็อกที่จำกัดขอบเขต แทนการคัดลอกโมเดลตัวอย่างโดยไม่ตรวจสอบ การตอบกลับ /readyz ที่สำเร็จหมายความว่า Gateway สามารถให้บริการคำขอได้ แต่ไม่ได้ยืนยันว่า ClawRouter ข้อมูลประจำตัวของมัน หรือผู้ให้บริการต้นทางพร้อมใช้งาน การตรวจสอบโมเดลและคานารีของเอเจนต์คือหลักฐานการอนุมาน

สำหรับการวินิจฉัยระบบจริง ให้เรียกคานารีและตรวจสอบบันทึกมาตรฐานของ Gateway การวินิจฉัยการขนส่งโมเดลที่มีเฉพาะข้อมูลเมตาซึ่งมีอยู่แล้วจะแสดงบรรทัดในรูปแบบดังนี้:

[model-fetch] start provider=clawrouter api=openai-responses model=openai/gpt-5.5 method=POST url=https://clawrouter.internal.example/v1/responses[model-fetch] response provider=clawrouter api=openai-responses model=openai/gpt-5.5 status=200

Plugin จะส่งส่วนหัว X-ClawRouter-Client, X-ClawRouter-Agent-Id และ X-ClawRouter-Session-Id ที่มีความยาวจำกัดเมื่อมีตัวระบุเหล่านั้น นอกจากนี้ยังแมป callId สำหรับการวินิจฉัยของการเรียกโมเดล (<run-id>:model:<n>) ไปยัง X-Request-ID เพื่อให้เชื่อมโยงเหตุการณ์การเรียกโมเดลของ OpenClaw กับเส้นทางการตรวจสอบที่มีเฉพาะข้อมูลเมตาของ ClawRouter ได้ ค่าที่อยู่ภายในขีดจำกัดรหัสคำขอ 128 อักขระจะเหมือนกันทุกประการ ค่าที่ยาวกว่าจะคงส่วนต่อท้าย :model:<n> และแฮชแบบกำหนดแน่นอนไว้ เพื่อให้การเรียกแต่ละครั้งยังคงมีขอบเขตและเชื่อมโยงกันได้ ข้อมูลเมตาคงที่ของการติดตั้งใช้งาน เช่น X-ClawRouter-Project-Id สามารถตั้งค่าได้ในแมป headers ของผู้ให้บริการ ส่วนหัวการระบุที่มาของเอเจนต์และเซสชันยังคงมีขีดจำกัดแยกกันที่ 256 อักขระ รหัสคำขออัตโนมัติที่มีอักขระนอกชุดตัวระบุ ASCII ของ ClawRouter จะใช้รูปแบบที่มีขอบเขตและกำหนดแน่นอนแบบเดียวกัน ส่วนหัวที่กำหนดค่าไว้อย่างชัดเจน รวมถึง X-Request-ID ในรูปแบบตัวพิมพ์เล็กใหญ่ใด ๆ จะมีลำดับความสำคัญเหนือค่าอัตโนมัติ การวินิจฉัยการขนส่งจะบันทึกข้อมูลเมตาของการกำหนดเส้นทางและการตอบกลับ แต่จะไม่บันทึกข้อมูลประจำตัว รหัสคำขอ พรอมต์ หรือคำตอบที่สร้างเสร็จ เหตุการณ์การตรวจสอบของ ClawRouter เองจะระบุผู้ให้บริการต้นทางที่เลือกและสถานะการเก็บรักษาเนื้อหา

การค้นหาโมเดล

GET /v1/catalog ส่งคืน { providers: [...] } โดยรายการผู้ให้บริการแต่ละรายการจะแสดง models[] ของตนเอง (พร้อมรหัสต้นทาง ความสามารถ และราคา) รวมถึงเส้นทางคำขอที่รองรับ OpenClaw ไม่ได้จัดส่งรายการโมเดล ClawRouter แบบคงที่ชุดที่สอง โมเดลในแค็ตตาล็อกจะถูกประกาศเป็นโมเดล OpenClaw เมื่อ:

• นโยบายของข้อมูลประจำตัวให้สิทธิ์ผู้ให้บริการของโมเดลนั้น
• โมเดลในแค็ตตาล็อกประกาศความสามารถ LLM ที่รองรับ (llm.responses, llm.chat, llm.messages หรือ llm.stream พร้อมเส้นทางสตรีมมิงที่ตรงกัน) และ
• ผู้ให้บริการเปิดเผยเส้นทางที่ตรงกันสำหรับหนึ่งในการขนส่งด้านล่าง

การเพิ่มโมเดลให้กับผู้ให้บริการ ClawRouter ที่รองรับไม่จำเป็นต้องมี OpenClaw รุ่นใหม่ การรีเฟรชแค็ตตาล็อกครั้งถัดไป (แคช 60 วินาทีต่อขอบเขตข้อมูลประจำตัว) จะค้นพบโมเดลนั้น โมเดลที่ต้องใช้โปรโตคอลการสื่อสารแบบใหม่ต้องได้รับการรองรับจาก Plugin ก่อน

โปรโตคอลและ Plugin ผู้ให้บริการ

ClawRouter เป็นเจ้าของข้อมูลประจำตัวของระบบต้นทาง โดยแค็ตตาล็อกจะแจ้ง OpenClaw ว่าต้องใช้การขนส่งใด คุณจึงไม่ต้องติดตั้ง Plugin การยืนยันตัวตนของบริษัทต้นทางทุกแห่ง

Plugin ยังใช้นโยบายการเล่นซ้ำและสคีมาเครื่องมือที่ตรงกันสำหรับตระกูลเหล่านั้นด้วย (ความเข้ากันได้ของสคีมาเครื่องมือ OpenAI/DeepSeek/Gemini และนโยบายการเล่นซ้ำแบบเนทีฟของ Anthropic และ Google Gemini) ผู้ให้บริการในแค็ตตาล็อกที่เปิดเผยเฉพาะรูปแบบคำขอที่ไม่รองรับจะไม่ถูกประกาศเป็นโมเดลข้อความ OpenClaw โดยตั้งใจ ให้ปรับผู้ให้บริการเหล่านั้นใน ClawRouter ให้เป็นหนึ่งในสัญญาที่รองรับ แทนการส่งเพย์โหลดที่เข้ากันไม่ได้

โควตาและการใช้งาน

การตอบกลับ /v1/usage ของ ClawRouter จะป้อนข้อมูลไปยังส่วนแสดงการใช้งานของผู้ให้บริการตามปกติใน OpenClaw ได้แก่ ยอดรวมคำขอ โทเค็น และค่าใช้จ่าย รวมถึงช่วงงบประมาณรายเดือนเมื่อคีย์มีขีดจำกัด คีย์ที่ไม่มีการวัดปริมาณยังคงแสดงการใช้งานรวมโดยไม่มีช่วงเปอร์เซ็นต์

การค้นหาโควตาใช้คีย์ที่จำกัดขอบเขตเดียวกับการค้นหาโมเดล การค้นหาโควตาที่ล้มเหลวจะไม่ขัดขวางการทำงานของโมเดล

ตรวจสอบสแนปช็อตระบบจริงด้วย:

openclaw status --usageopenclaw models status

สแนปช็อตผู้ให้บริการเดียวกันนี้พร้อมใช้งานสำหรับ /status ในแชตและ UI การใช้งานของ OpenClaw งบประมาณมีผลทั่วทั้งนโยบาย ดังนั้นคำขอจากไคลเอนต์อื่นที่ใช้นโยบาย ClawRouter เดียวกันอาจเปลี่ยนเปอร์เซ็นต์ที่เหลือได้

การแก้ไขปัญหา

ลักษณะการทำงานด้านความปลอดภัย

• การค้นหาแค็ตตาล็อกถูกจำกัดขอบเขตตามคีย์พร็อกซีที่กำหนดค่าไว้ และแคชแยกตามขอบเขตของข้อมูลประจำตัว (ไดเรกทอรีเอเจนต์ ไดเรกทอรีพื้นที่ทำงาน รหัสโปรไฟล์การตรวจสอบสิทธิ์ และ URL ฐาน)
• คีย์พร็อกซีจะถูกแนบเฉพาะเมื่อส่งคำขอเท่านั้น โดยจะไม่ถูกจัดเก็บไว้ในข้อมูลเมตาของโมเดล
• ค่าการระบุแหล่งที่มาและค่าความสัมพันธ์ของคำขอที่สร้างโดยอัตโนมัติจะถูกตัดช่องว่าง และปฏิเสธอักขระควบคุมก่อนส่งคำขอ ค่าการระบุแหล่งที่มาจำกัดไว้ที่ 256 อักขระ ส่วนรหัสคำขอจำกัดไว้ที่ 128 อักขระ
• ข้อมูลวินิจฉัยการรับส่งข้อมูลของโมเดลมีเฉพาะข้อมูลเมตาเท่านั้น และจะไม่มีคีย์พร็อกซีหรือเนื้อหาของโมเดล
• รหัสโมเดล Anthropic และ Gemini แบบเนทีฟจะถูกเขียนใหม่เป็นรหัสต้นทางเฉพาะเมื่อส่งคำขอเท่านั้น
• แถวในแค็ตตาล็อกที่ไม่รองรับหรือไม่ได้รับสิทธิ์จะปฏิเสธการทำงานโดยค่าเริ่มต้นและไม่สามารถเลือกได้

เนื้อหาที่เกี่ยวข้อง