---
read_when:
- คุณต้องการทางเลือกสำรองที่เชื่อถือได้เมื่อผู้ให้บริการ API ขัดข้อง
- คุณกำลังใช้งาน CLI สำหรับ AI ภายในเครื่องและต้องการนำกลับมาใช้ซ้ำ
- คุณต้องการทำความเข้าใจบริดจ์ลูปแบ็ก MCP สำหรับการเข้าถึงเครื่องมือแบ็กเอนด์ผ่าน CLI
summary: 'แบ็กเอนด์ CLI: ทางเลือกสำรองของ AI CLI ภายในเครื่องพร้อมบริดจ์เครื่องมือ MCP ที่เลือกใช้ได้'
title: แบ็กเอนด์ CLI
x-i18n:
generated_at: "2026-07-20T05:58:44Z"
model: gpt-5.6
postprocess_version: locale-links-v1
prompt_version: 32
provider: openai
source_hash: d71300fa7383b021ee12bdeafedfc48cb9f0d7746a02efff5e609544c7b4b081
source_path: gateway/cli-backends.md
workflow: 16
---
OpenClaw สามารถเรียกใช้ AI CLI ภายในเครื่องเป็นทางเลือกสำรองแบบข้อความเท่านั้น เมื่อผู้ให้บริการ API หยุดทำงาน ถูกจำกัดอัตรา หรือทำงานผิดปกติ โดยออกแบบให้ระมัดระวังโดยเจตนา:
- เครื่องมือ OpenClaw จะไม่ถูกแทรกโดยตรง แต่แบ็กเอนด์ที่มี `bundleMcp: true` สามารถรับเครื่องมือ Gateway ผ่านบริดจ์ MCP แบบลูปแบ็กได้
- การสตรีม JSONL สำหรับ CLI ที่รองรับ
- รองรับเซสชัน จึงทำให้การโต้ตอบต่อเนื่องยังคงสอดคล้องกัน
- รูปภาพจะถูกส่งผ่านหาก CLI ยอมรับพาธรูปภาพ
ใช้เป็นกลไกสำรองสำหรับการตอบกลับข้อความที่ "ใช้งานได้เสมอ" ไม่ใช่เส้นทางหลัก สำหรับรันไทม์ฮาร์เนสเต็มรูปแบบที่มีการควบคุมเซสชัน ACP, งานเบื้องหลัง, การผูกเธรด/การสนทนา และเซสชันการเขียนโค้ดภายนอกแบบถาวร ให้ใช้ [เอเจนต์ ACP](/th/tools/acp-agents) แทน โดยแบ็กเอนด์ CLI ไม่ใช่ ACP
กำลังสร้าง Plugin แบ็กเอนด์ใหม่อยู่ใช่ไหม โปรดดู [Plugin แบ็กเอนด์ CLI](/th/plugins/cli-backend-plugins) หน้านี้ครอบคลุมการกำหนดค่าและใช้งานแบ็กเอนด์ที่ลงทะเบียนไว้แล้ว
## เริ่มต้นอย่างรวดเร็ว
Plugin Anthropic ที่รวมมาให้จะลงทะเบียนแบ็กเอนด์ `claude-cli` เริ่มต้น จึงใช้งานได้โดยไม่ต้องกำหนดค่าเพิ่มเติม นอกจากติดตั้ง Claude Code และเข้าสู่ระบบแล้ว:
```bash
openclaw agent --agent main --message "hi" --model claude-cli/claude-sonnet-4-6
```
`main` คือ ID เอเจนต์เริ่มต้นเมื่อไม่ได้กำหนดรายการเอเจนต์อย่างชัดเจน มิฉะนั้นให้แทนที่ด้วย ID เอเจนต์ของคุณเอง
หาก Gateway ทำงานภายใต้ launchd/systemd ที่มี `PATH` ขั้นต่ำ ให้ระบุไบนารีอย่างชัดเจน:
```json5
{
agents: {
defaults: {
cliBackends: {
"claude-cli": {
command: "/opt/homebrew/bin/claude",
},
},
},
},
}
```
หากใช้แบ็กเอนด์ CLI ที่รวมมาให้เป็นผู้ให้บริการข้อความหลักบนโฮสต์ Gateway OpenClaw จะโหลด Plugin ที่รวมมาให้และเป็นเจ้าของแบ็กเอนด์นั้นโดยอัตโนมัติ เมื่อการกำหนดค่าของคุณอ้างอิงแบ็กเอนด์นั้นในข้อมูลอ้างอิงโมเดลหรือภายใต้ `agents.defaults.cliBackends`
## การใช้เป็นทางเลือกสำรอง
เพิ่มแบ็กเอนด์ CLI ลงในรายการทางเลือกสำรอง เพื่อให้ทำงานเฉพาะเมื่อโมเดลหลักล้มเหลว:
```json5
{
agents: {
defaults: {
model: {
primary: "anthropic/claude-opus-4-6",
fallbacks: ["claude-cli/claude-sonnet-4-6"],
},
models: {
"anthropic/claude-opus-4-6": { alias: "Opus" },
"claude-cli/claude-sonnet-4-6": {},
},
},
},
}
```
ทางเลือกสำรองที่กำหนดค่าไว้ยังคงมีสิทธิ์ใช้งานเมื่อผู้ให้บริการหลักล้มเหลว (การยืนยันตัวตน การจำกัดอัตรา การหมดเวลา) แม้จะไม่อยู่ใน `agents.defaults.modelPolicy.allow` ก็ตาม เพิ่มโมเดลแบ็กเอนด์ CLI ลงในนโยบายนั้นเฉพาะเมื่อผู้ใช้ควรเลือกโมเดลนั้นโดยตรงผ่าน `/model`, การแทนที่ระดับเซสชัน หรือ `--model` ได้ด้วยเท่านั้น `agents.defaults.models` มีหน้าที่เฉพาะกับชื่อแทน พารามิเตอร์ และข้อมูลเมตาของแต่ละโมเดล
## การกำหนดค่า
แบ็กเอนด์ CLI ทั้งหมดอยู่ภายใต้ `agents.defaults.cliBackends` โดยใช้ ID ผู้ให้บริการเป็นคีย์ (เช่น `claude-cli`, `my-cli`) ID ผู้ให้บริการจะกลายเป็นด้านซ้ายของข้อมูลอ้างอิงโมเดล: `/`
```json5
{
agents: {
defaults: {
cliBackends: {
"my-cli": {
command: "my-cli",
args: ["--json"],
output: "json",
input: "arg",
modelArg: "--model",
modelAliases: {
"claude-opus-4-6": "opus",
"claude-sonnet-4-6": "sonnet",
},
sessionArg: "--session",
sessionMode: "existing",
sessionIdFields: ["session_id", "conversation_id"],
systemPromptArg: "--system",
// แฟล็กไฟล์พรอมต์เฉพาะ:
// systemPromptFileArg: "--system-file",
// ใช้แฟล็กแทนที่การกำหนดค่าแบบ Codex แทน:
// systemPromptFileConfigArg: "-c",
// systemPromptFileConfigKey: "model_instructions_file",
systemPromptWhen: "first",
imageArg: "--image",
imageMode: "repeat",
// เลือกใช้เฉพาะเมื่อแบ็กเอนด์นี้อาจเติมข้อมูลเริ่มต้นให้เซสชันที่ใช้ไม่ได้อีกครั้งจาก
// ประวัติทรานสคริปต์ดิบแบบจำกัดของ OpenClaw ก่อน Compaction
reseedFromRawTranscriptWhenUncompacted: true,
serialize: true,
},
},
},
},
}
```
## หลักการทำงาน
1. เลือกแบ็กเอนด์ตามคำนำหน้าผู้ให้บริการ (`claude-cli/...`)
2. สร้างพรอมต์ระบบโดยใช้พรอมต์และบริบทเวิร์กสเปซเดียวกับ OpenClaw
3. เรียกใช้ CLI พร้อม ID เซสชัน (หากรองรับ) เพื่อให้ประวัติสอดคล้องกัน แบ็กเอนด์ `claude-cli` ที่รวมมาให้จะคงกระบวนการ stdio ของ Claude ไว้ต่อเซสชัน OpenClaw และส่งการโต้ตอบต่อเนื่องผ่าน stdin แบบ stream-json
4. แยกวิเคราะห์เอาต์พุต (JSON หรือข้อความธรรมดา) และส่งคืนข้อความสุดท้าย
5. จัดเก็บ ID เซสชันแบบถาวรแยกตามแบ็กเอนด์ เพื่อให้การโต้ตอบต่อเนื่องใช้เซสชัน CLI เดิมซ้ำ
## การหมดเวลาและงานที่ทำงานเป็นเวลานาน
แบ็กเอนด์ CLI มีขีดจำกัดอิสระสองรายการ:
- `agents.defaults.timeoutSeconds` จำกัดการโต้ตอบทั้งหมดของเอเจนต์ การโต้ตอบ Gateway ปกติจะสืบทอดค่าเริ่มต้น 48 ชั่วโมง ส่วน `0` ทำให้งบเวลาของการโต้ตอบไม่จำกัด การแทนที่ที่จัดเก็บไว้ เช่น `600` จะแทนที่ค่าเริ่มต้นดังกล่าว
- ตัวเฝ้าระวังเมื่อ CLI ไม่มีเอาต์พุตจะหยุดกระบวนการย่อยที่ไม่มีการตอบสนอง โดยใช้โปรไฟล์แยกสำหรับการเริ่มใหม่/ดำเนินการต่อภายใต้ `agents.defaults.cliBackends..reliability.watchdog` และยังคงทำงานแม้งบเวลาโดยรวมของการโต้ตอบจะไม่จำกัด
นำการแทนที่การหมดเวลาโดยรวมที่สั้นออกเพื่อกลับไปใช้ค่าเริ่มต้น 48 ชั่วโมง หรือตั้งงบเวลาอย่างชัดเจน เช่น 12 ชั่วโมง:
```bash
# กลับไปใช้ค่าเริ่มต้น 48 ชั่วโมง:
openclaw config unset agents.defaults.timeoutSeconds
# หรือเลือกขีดจำกัด 12 ชั่วโมงอย่างชัดเจน:
openclaw config set agents.defaults.timeoutSeconds 43200
```
งานเบื้องหลังที่เริ่มภายใน CLI ยังคงเป็นส่วนหนึ่งของกระบวนการย่อย CLI นั้น หากการโต้ตอบหลักถึงขีดจำกัดโดยรวม OpenClaw จะหยุดกระบวนการย่อยพร้อมกับงานเบื้องหลังภายใน CLI สำหรับงานระยะยาวที่ต้องคงอยู่ ให้ใช้ [เอเจนต์ย่อย](/th/tools/subagents) หรือ [เอเจนต์ ACP](/th/tools/acp-agents) แบบแยกออกจาก OpenClaw โดยเอเจนต์ย่อยแบบแยกออกไม่มีการหมดเวลาการทำงานเป็นค่าเริ่มต้น
คำสั่ง `openclaw agent` ยังมีกำหนดเวลาคำขอของตนเอง ค่าเริ่มต้นสำรอง 600 วินาทีใช้กับการเรียกคำสั่งนั้น ไม่ใช่การโต้ตอบ Gateway ทั่วไป โปรดดู [`openclaw agent`](/th/cli/agent)
### รายละเอียดเฉพาะของ Claude CLI
แบ็กเอนด์ `claude-cli` ที่รวมมาให้จะเลือกใช้ตัวแก้ไข Skills แบบเนทีฟของ Claude Code เมื่อสแนปชอต Skills ปัจจุบันมี Skills ที่เลือกอย่างน้อยหนึ่งรายการพร้อมพาธที่สร้างขึ้นจริง OpenClaw จะส่ง Plugin Claude Code ชั่วคราวผ่าน `--plugin-dir` และละเว้นแค็ตตาล็อก Skills ของ OpenClaw ที่ซ้ำกันออกจากพรอมต์ระบบที่ต่อท้าย หากไม่มี Skills ของ Plugin ที่สร้างขึ้นจริง OpenClaw จะคงแค็ตตาล็อกพรอมต์ไว้เป็นทางเลือกสำรอง การแทนที่สภาพแวดล้อม/คีย์ API ของ Skills ยังคงมีผลกับสภาพแวดล้อมของกระบวนการลูกสำหรับการทำงานนั้น
Claude CLI มีโหมดสิทธิ์แบบไม่โต้ตอบของตนเอง OpenClaw จะแมปโหมดดังกล่าวเข้ากับนโยบายการดำเนินการที่มีอยู่ แทนการเพิ่มการกำหนดค่าเฉพาะ Claude สำหรับเซสชัน Claude แบบสดที่ OpenClaw จัดการ นโยบายการดำเนินการที่มีผลถือเป็นข้อกำหนดหลัก: โดยปกติ YOLO (`tools.exec.security: "full"` และ `tools.exec.ask: "off"`) จะเปิด Claude ด้วย `--permission-mode bypassPermissions` ส่วนนโยบายที่เข้มงวดจะเปิดด้วย `--permission-mode default` Gateway ที่ทำงานด้วย root จะใช้ `default` ด้วย เนื่องจาก Claude Code ปฏิเสธโหมดข้ามข้อจำกัดสำหรับ root โดย OpenClaw ยังคงตอบคำขอควบคุมเครื่องมือผ่าน stdio ของ Claude ตามนโยบายการดำเนินการที่กำหนดค่าไว้ การตั้งค่า `agents.list[].tools.exec` รายเอเจนต์จะแทนที่ `tools.exec` ส่วนกลางสำหรับเอเจนต์นั้น อาร์กิวเมนต์แบ็กเอนด์ดิบอาจยังมี `--permission-mode` แต่การเปิด Claude แบบสดจะปรับแฟล็กนั้นให้สอดคล้องกับนโยบายที่มีผลและข้อจำกัดของโฮสต์
แบ็กเอนด์ยังแมประดับ `/think` ของ OpenClaw ไปยังแฟล็ก `--effort` แบบเนทีฟของ Claude Code ดังนี้: `minimal`/`low` -> `low`, `medium` -> `medium` และ `high`/`xhigh`/`max` จะถูกส่งผ่านโดยตรง วิธีนี้ทำให้ระดับความพยายาม Fable 5 ที่รองรับเหมือนกันทั้ง Claude CLI ที่ใช้การสมัครสมาชิกและเส้นทางคีย์ API `adaptive` จะนำแฟล็ก `--effort` ที่กำหนดค่าไว้ออกโดยไม่ใส่ค่าแทน เพื่อให้ Claude Code กำหนดความพยายามที่มีผลจากสภาพแวดล้อม การตั้งค่า และค่าเริ่มต้นของโมเดลเอง แบ็กเอนด์ CLI อื่นต้องให้ Plugin เจ้าของประกาศตัวแมป argv ที่เทียบเท่าก่อนที่ `/think` จะส่งผลต่อ CLI ที่เปิดขึ้น
ก่อนที่ OpenClaw จะใช้ `claude-cli` ได้ Claude Code ต้องเข้าสู่ระบบบนโฮสต์เดียวกันก่อน:
```bash
claude auth login
claude auth status --text
openclaw models auth login --provider anthropic --method cli --set-default
```
การติดตั้ง Docker ต้องติดตั้งและเข้าสู่ระบบ Claude Code ภายในโฮมของคอนเทนเนอร์ที่จัดเก็บถาวร ไม่ใช่เฉพาะบนโฮสต์ โปรดดู [แบ็กเอนด์ Claude CLI ใน Docker](/th/install/docker#claude-cli-backend-in-docker)
ตั้งค่า `agents.defaults.cliBackends.claude-cli.command` เฉพาะเมื่อไบนารี `claude` ยังไม่อยู่ใน `PATH`
## เซสชัน
- หาก CLI รองรับเซสชัน ให้ตั้งค่า `sessionArg` (เช่น `--session-id`) หรือ `sessionArgs` (ตัวยึดตำแหน่ง `{sessionId}`) เมื่อจำเป็นต้องใส่ ID ในหลายแฟล็ก
- หาก CLI ใช้คำสั่งย่อยสำหรับดำเนินการต่อพร้อมแฟล็กที่ต่างกัน ให้ตั้งค่า `resumeArgs` (แทนที่ `args` เมื่อดำเนินการต่อ) และอาจตั้งค่า `resumeOutput` สำหรับการดำเนินการต่อที่ไม่ใช่ JSON
- `sessionMode`:
- `always`: ส่ง ID เซสชันเสมอ (UUID ใหม่หากยังไม่มีที่จัดเก็บไว้)
- `existing`: ส่ง ID เซสชันเฉพาะเมื่อเคยจัดเก็บไว้ก่อนแล้ว
- `none`: ไม่ส่ง ID เซสชัน
- `claude-cli` มีค่าเริ่มต้นเป็น `liveSession: "claude-stdio"`, `output: "jsonl"` และ `input: "stdin"` ดังนั้นการโต้ตอบต่อเนื่องจะใช้กระบวนการ Claude แบบสดซ้ำขณะที่ยังทำงานอยู่ รวมถึงการกำหนดค่าแบบกำหนดเองที่ละเว้นฟิลด์การรับส่ง หาก Gateway รีสตาร์ตหรือกระบวนการที่ไม่ได้ใช้งานปิดตัวลง OpenClaw จะดำเนินการต่อจาก ID เซสชัน Claude ที่จัดเก็บไว้ ระบบจะตรวจสอบ ID เซสชันที่จัดเก็บไว้กับทรานสคริปต์โปรเจกต์ที่อ่านได้ก่อนดำเนินการต่อ หากไม่มีทรานสคริปต์ ระบบจะล้างการผูก (บันทึกเป็น `reason=transcript-missing`) แทนการเริ่มเซสชันใหม่ภายใต้ `--resume` โดยไม่แจ้ง
- เซสชัน Claude แบบสดมีขีดจำกัดการป้องกันเอาต์พุต JSONL: 8 MiB และ 20,000 บรรทัด JSONL ดิบต่อการโต้ตอบ
- เซสชัน CLI ที่จัดเก็บไว้เป็นความต่อเนื่องที่ผู้ให้บริการเป็นเจ้าของ การรีเซ็ตอัตโนมัติถูกปิดเป็นค่าเริ่มต้น โดย `/reset` และนโยบาย `session.reset` แบบรายวันหรือเมื่อไม่ได้ใช้งานที่กำหนดไว้อย่างชัดเจนยังคงตัดเซสชันเหล่านี้
- โดยปกติเซสชัน CLI ใหม่จะเติมข้อมูลเริ่มต้นอีกครั้งเฉพาะจากสรุป Compaction ของ OpenClaw และส่วนท้ายหลัง Compaction เพื่อกู้คืนเซสชันระยะสั้นที่ใช้ไม่ได้ก่อน Compaction แบ็กเอนด์สามารถเลือกใช้ `reseedFromRawTranscriptWhenUncompacted: true` ได้ การเติมข้อมูลเริ่มต้นจากทรานสคริปต์ดิบอีกครั้งยังคงมีขอบเขตจำกัดและจำกัดไว้เฉพาะกรณีที่ใช้ไม่ได้อย่างปลอดภัย เช่น ทรานสคริปต์ CLI หายไป ส่วนท้ายการใช้เครื่องมือที่ไม่มีเจ้าของ การเปลี่ยนแปลงนโยบายข้อความ/พรอมต์ระบบ/cwd/MCP หรือการลองใหม่หลังเซสชันหมดอายุ ส่วนการเปลี่ยนแปลงโปรไฟล์การยืนยันตัวตนหรือยุคของข้อมูลประจำตัวจะไม่เติมข้อมูลเริ่มต้นจากประวัติทรานสคริปต์ดิบอีกครั้ง
การทำงานแบบลำดับ: `serialize: true` จะรักษาลำดับการทำงานในเลนเดียวกัน (CLI ส่วนใหญ่ทำงานเป็นลำดับบนเลนผู้ให้บริการเดียว) OpenClaw ยังยกเลิกการใช้เซสชัน CLI ที่จัดเก็บไว้ซ้ำเมื่อข้อมูลประจำตัวสำหรับการยืนยันตัวตนที่เลือกเปลี่ยนแปลง รวมถึง ID โปรไฟล์การยืนยันตัวตน คีย์ API แบบคงที่ โทเค็นแบบคงที่ หรือข้อมูลประจำตัวบัญชี OAuth ที่เปลี่ยนแปลงเมื่อ CLI เปิดเผยข้อมูลดังกล่าว การหมุนเวียนโทเค็นการเข้าถึง/รีเฟรช OAuth เพียงอย่างเดียวจะไม่ตัดเซสชัน หาก CLI ไม่มี ID บัญชี OAuth ที่เสถียร OpenClaw จะให้ CLI นั้นบังคับใช้สิทธิ์ในการดำเนินการต่อเอง
## ส่วนเกริ่นนำสำหรับทางเลือกสำรองจากเซสชัน claude-cli
เมื่อความพยายาม `claude-cli` สลับไปยังตัวเลือกที่ไม่ใช่ CLI ใน [`agents.defaults.model.fallbacks`](/th/concepts/model-failover) OpenClaw จะเติมข้อมูลเริ่มต้นให้ความพยายามถัดไปด้วยส่วนเกริ่นนำบริบทที่เก็บจากทรานสคริปต์ JSONL ภายในเครื่องของ Claude Code (ภายใต้ `~/.claude/projects/` โดยใช้คีย์แยกตามเวิร์กสเปซ) หากไม่มีข้อมูลเริ่มต้นนี้ ผู้ให้บริการทางเลือกสำรองจะเริ่มโดยไม่มีบริบท เนื่องจากทรานสคริปต์เซสชันของ OpenClaw เองว่างเปล่าสำหรับการทำงาน `claude-cli`
- บทนำจะเลือกสรุป `/compact` ล่าสุดหรือเครื่องหมาย `compact_boundary` ก่อน จากนั้นจึงต่อท้ายผลัดการสนทนาหลังขอบเขตที่ล่าสุดตามงบประมาณจำนวนอักขระ ผลัดการสนทนาก่อนขอบเขตจะถูกตัดออก เนื่องจากสรุปได้แทนเนื้อหาเหล่านั้นไว้แล้ว
- บล็อกเครื่องมือจะถูกรวมเป็นคำใบ้ `(tool call: name)` และ `(tool result: …)` แบบกระชับ เพื่อควบคุมงบประมาณพรอมต์ให้ตรงตามจริง ส่วนสรุปที่มีขนาดใหญ่เกินไปจะถูกตัดทอนและติดป้าย `(truncated)`
- การสำรองจาก `claude-cli` ไปยัง `claude-cli` ภายในผู้ให้บริการเดียวกันจะใช้ `--resume` ของ Claude เองและข้ามบทนำ
- ข้อมูลตั้งต้นจะใช้การตรวจสอบพาธไฟล์เซสชัน Claude ที่มีอยู่แล้วซ้ำ จึงไม่สามารถอ่านพาธตามอำเภอใจได้
## รูปภาพ
หาก CLI รองรับพาธรูปภาพ ให้ตั้งค่า `imageArg`:
```json5
imageArg: "--image",
imageMode: "repeat"
```
OpenClaw เขียนรูปภาพ base64 ลงในไฟล์ชั่วคราว หากตั้งค่า `imageArg` พาธเหล่านั้นจะถูกส่งเป็นอาร์กิวเมนต์ CLI หากไม่ได้ตั้งค่า OpenClaw จะต่อท้ายพาธไฟล์เข้ากับพรอมต์ (การแทรกพาธ) ซึ่งใช้ได้กับ CLI ที่โหลดไฟล์ในเครื่องโดยอัตโนมัติจากพาธแบบข้อความธรรมดา
## อินพุตและเอาต์พุต
- `output: "text"` (ค่าเริ่มต้น) ถือว่า stdout เป็นคำตอบสุดท้าย
- `output: "json"` พยายามแยกวิเคราะห์ JSON และดึงข้อความพร้อมรหัสเซสชัน
- `output: "jsonl"` แยกวิเคราะห์สตรีม JSONL และดึงข้อความสุดท้ายของเอเจนต์พร้อมตัวระบุเซสชันเมื่อมี
- สำหรับเอาต์พุต JSON ของ Gemini CLI นั้น OpenClaw จะอ่านข้อความตอบกลับจาก `response` และข้อมูลการใช้งานจาก `stats` เมื่อ `usage` ไม่มีอยู่หรือว่างเปล่า ค่าเริ่มต้นของ Gemini CLI ที่รวมมาให้ใช้ `stream-json` ส่วนการแทนที่ `--output-format json` แบบเก่ายังคงใช้ตัวแยกวิเคราะห์ JSON
โหมดอินพุต:
- `input: "arg"` (ค่าเริ่มต้น) ส่งพรอมต์เป็นอาร์กิวเมนต์ CLI ตัวสุดท้าย
- `input: "stdin"` ส่งพรอมต์ผ่าน stdin
- หากพรอมต์ยาวมากและตั้งค่า `maxPromptArgChars` ระบบจะใช้ stdin แทน
## ค่าเริ่มต้นที่ Plugin เป็นเจ้าของ
ค่าเริ่มต้นของแบ็กเอนด์ CLI เป็นส่วนหนึ่งของพื้นผิว Plugin:
- Plugin ลงทะเบียนค่าเหล่านี้ด้วย `api.registerCliBackend(...)`
- `id` ของแบ็กเอนด์จะกลายเป็นคำนำหน้าผู้ให้บริการในการอ้างอิงโมเดล
- การกำหนดค่าของผู้ใช้ใน `agents.defaults.cliBackends.` ยังคงแทนที่ค่าเริ่มต้นของ Plugin
- การล้างการกำหนดค่าเฉพาะแบ็กเอนด์ยังคงเป็นความรับผิดชอบของ Plugin ผ่านฮุก `normalizeConfig` ที่เป็นทางเลือก
Anthropic เป็นเจ้าของ `claude-cli` และ Google เป็นเจ้าของ `google-gemini-cli` การทำงานของเอเจนต์ OpenAI Codex ใช้ชุดทดสอบ app-server ของ Codex ผ่าน `openai/*` โดย OpenClaw จะไม่ลงทะเบียนแบ็กเอนด์ `codex-cli` ที่รวมมาให้อีกต่อไป
Plugin Anthropic ที่รวมมาให้ลงทะเบียนสำหรับ `claude-cli`:
| คีย์ | ค่า |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `command` | `claude` |
| `args` | `-p --output-format stream-json --include-partial-messages --verbose --setting-sources user --allowedTools mcp__openclaw__* --disallowedTools ScheduleWakeup,CronCreate,Bash(run_in_background:true),Monitor` |
| `output` | `jsonl` |
| `input` | `stdin` |
| `modelArg` | `--model` |
| `sessionArg` | `--session-id` |
| `sessionMode` | `always` |
| `imageArg` | `@` |
| `imagePathScope` | `workspace` |
| `systemPromptFileArg` | `--append-system-prompt-file` |
| `systemPromptMode` | `append` |
Plugin Google ที่รวมมาให้ลงทะเบียนสำหรับ `google-gemini-cli`:
| คีย์ | ค่า |
| ------------------------- | -------------------------------------------------------------------------------------- |
| `command` | `gemini` |
| `args` | `--skip-trust --approval-mode auto_edit --output-format stream-json --prompt {prompt}` |
| `resumeArgs` | เหมือนกัน โดยมี `--resume {sessionId}` |
| `output` / `resumeOutput` | `jsonl` |
| `jsonlDialect` | `gemini-stream-json` |
| `imageArg` | `@` |
| `imagePathScope` | `workspace` |
| `modelArg` | `--model` |
| `sessionMode` | `existing` |
| `sessionIdFields` | `["session_id", "sessionId"]` |
ข้อกำหนดเบื้องต้น: ต้องติดตั้ง Gemini CLI ในเครื่องและให้อยู่ใน `PATH` ในชื่อ `gemini` (`brew install gemini-cli` หรือ `npm install -g @google/gemini-cli`)
หมายเหตุเกี่ยวกับเอาต์พุต Gemini CLI:
- ตัวแยกวิเคราะห์ `stream-json` เริ่มต้นจะอ่านเหตุการณ์ `message` ของผู้ช่วย เหตุการณ์เครื่องมือ ข้อมูลการใช้งาน `result` สุดท้าย และเหตุการณ์ข้อผิดพลาดร้ายแรงของ Gemini
- หากแทนที่อาร์กิวเมนต์ Gemini เป็น `--output-format json` OpenClaw จะปรับแบ็กเอนด์นั้นกลับเป็น `output: "json"` และอ่านข้อความตอบกลับจากฟิลด์ `response` ใน JSON
- ข้อมูลการใช้งานจะสำรองไปใช้ `stats` เมื่อ `usage` ไม่มีอยู่หรือว่างเปล่า โดย `stats.cached` จะถูกปรับให้อยู่ในรูป `cacheRead` ของ OpenClaw และหากไม่มี `stats.input` จำนวนโทเค็นอินพุตจะคำนวณจาก `stats.input_tokens - stats.cached`
แทนที่ค่าเริ่มต้นเฉพาะเมื่อจำเป็นเท่านั้น (กรณีที่พบบ่อยที่สุดคือพาธ `command` แบบสัมบูรณ์)
## โอเวอร์เลย์การแปลงข้อความ
Plugin ที่ต้องใช้ชิมความเข้ากันได้ขนาดเล็กสำหรับพรอมต์/ข้อความ สามารถประกาศการแปลงข้อความแบบสองทิศทางได้โดยไม่ต้องแทนที่ผู้ให้บริการหรือแบ็กเอนด์ CLI:
```typescript
api.registerTextTransforms({
input: [{ from: /red basket/g, to: "blue basket" }],
output: [{ from: /blue basket/g, to: "red basket" }],
});
```
`input` เขียนพรอมต์ระบบและพรอมต์ผู้ใช้ที่ส่งไปยัง CLI ใหม่ ส่วน `output` เขียนข้อความผู้ช่วยที่สตรีมและข้อความสุดท้ายที่แยกวิเคราะห์แล้วใหม่ ก่อนที่ OpenClaw จะจัดการเครื่องหมายควบคุมและการส่งผ่านช่องทางของตนเอง สำหรับการเรียกโมเดลผ่านผู้ให้บริการ ระบบยังคืนค่าสตริงภายในอาร์กิวเมนต์การเรียกเครื่องมือแบบมีโครงสร้าง หลังการซ่อมแซมสตรีมและก่อนเรียกใช้เครื่องมือด้วย ส่วนย่อย JSON ดิบจากผู้ให้บริการจะไม่ถูกเปลี่ยนแปลง ผู้ใช้ข้อมูลควรใช้เพย์โหลดบางส่วน สิ้นสุด หรือผลลัพธ์แบบมีโครงสร้าง
สำหรับ CLI ที่ส่งเหตุการณ์ JSONL เฉพาะผู้ให้บริการ ให้ตั้งค่า `jsonlDialect` ในการกำหนดค่าของแบ็กเอนด์นั้น: `claude-stream-json` สำหรับสตรีมที่เข้ากันได้กับ Claude Code และ `gemini-stream-json` สำหรับเหตุการณ์ `stream-json` ของ Gemini CLI
## การเป็นเจ้าของ Compaction แบบเนทีฟ
แบ็กเอนด์ CLI บางรายการเรียกใช้เอเจนต์ที่ทำ Compaction ทรานสคริปต์ของตนเอง ดังนั้น OpenClaw ต้องไม่เรียกใช้ตัวสรุปเพื่อป้องกันกับแบ็กเอนด์เหล่านั้น เพราะจะขัดแย้งกับ Compaction ของแบ็กเอนด์เองและอาจทำให้ผลัดการทำงานล้มเหลวโดยสิ้นเชิง
`claude-cli` ไม่มีปลายทางชุดทดสอบ (Claude Code ทำ Compaction ภายใน) จึงประกาศ `ownsNativeCompaction: true` และเส้นทาง Compaction ของ OpenClaw จะคืนรายการเซสชันโดยไม่เปลี่ยนแปลง OpenClaw ส่งงบประมาณบริบทที่มีผลของการทำงานผ่าน [`CLAUDE_CODE_AUTO_COMPACT_WINDOW`](https://code.claude.com/docs/en/env-vars) ที่ Claude Code จัดทำเอกสารไว้ เพื่อให้การทำ Compaction อัตโนมัติแบบเนทีฟสอดคล้องกับขีดจำกัด `contextTokens` ของ Anthropic ที่กำหนดค่าไว้ ส่วนเซสชันชุดทดสอบแบบเนทีฟ เช่น Codex ยังคงส่งต่อไปยังปลายทาง Compaction ของชุดทดสอบนั้นแทน
```typescript
api.registerCliBackend({ id: "my-cli", ownsNativeCompaction: true /* ... */ });
```
ประกาศ `ownsNativeCompaction` เฉพาะสำหรับแบ็กเอนด์ที่เป็นเจ้าของ Compaction อย่างแท้จริงเท่านั้น โดยต้องจำกัดขนาดทรานสคริปต์ของตนเองให้อยู่ใกล้กับหน้าต่างบริบทได้อย่างน่าเชื่อถือ และบันทึกเซสชันที่กลับมาทำต่อได้ (เช่น `--resume` / `--session-id`) มิฉะนั้นเซสชันที่เลื่อนออกไปอาจยังคงเกินงบประมาณได้
## โอเวอร์เลย์ MCP แบบรวมชุด
แบ็กเอนด์ CLI ไม่ได้รับการเรียกเครื่องมือของ OpenClaw โดยตรง แต่แบ็กเอนด์สามารถเลือกใช้โอเวอร์เลย์การกำหนดค่า MCP ที่สร้างขึ้นด้วย `bundleMcp: true` ได้ พฤติกรรมปัจจุบันที่รวมมาให้มีดังนี้:
- `claude-cli`: ไฟล์การกำหนดค่า MCP แบบเข้มงวดที่สร้างขึ้น
- `google-gemini-cli`: ไฟล์การตั้งค่าระบบ Gemini ที่สร้างขึ้น
เมื่อเปิดใช้งาน MCP แบบรวมชุด OpenClaw จะ:
- สร้างเซิร์ฟเวอร์ HTTP MCP แบบลูปแบ็กที่เปิดเผยเครื่องมือ Gateway ให้แก่กระบวนการ CLI โดยยืนยันตัวตนด้วยสิทธิ์บริบทเฉพาะการทำงาน (`OPENCLAW_MCP_TOKEN`) ซึ่งมีผลเฉพาะความพยายามดำเนินการปัจจุบัน
- ผูกการเข้าถึงเครื่องมือกับบริบทเซสชัน บัญชี และช่องทางที่ Gateway เลือก แทนการเชื่อถือส่วนหัวจากกระบวนการลูก
- โหลดเซิร์ฟเวอร์ bundle-MCP ที่เปิดใช้งานสำหรับเวิร์กสเปซปัจจุบัน และผสานเข้ากับรูปแบบการกำหนดค่า/การตั้งค่า MCP ของแบ็กเอนด์ที่มีอยู่
- เขียนการกำหนดค่าการเปิดใช้ใหม่โดยใช้โหมดการผสานรวมที่แบ็กเอนด์เป็นเจ้าของจาก Plugin เจ้าของ
หากไม่มีเซิร์ฟเวอร์ MCP ที่เปิดใช้งาน OpenClaw ยังคงแทรกการกำหนดค่าแบบเข้มงวดเมื่อแบ็กเอนด์เลือกใช้ MCP แบบรวมชุด เพื่อให้การทำงานเบื้องหลังยังคงแยกออกจากกัน
รันไทม์ MCP ที่รวมมาให้และจำกัดขอบเขตตามเซสชันจะถูกแคชเพื่อนำกลับมาใช้ซ้ำภายในเซสชัน จากนั้นจะถูกเก็บกวาดหลังไม่มีการใช้งานเป็นเวลา 10 นาที การทำงานแบบฝังครั้งเดียว เช่น การตรวจสอบการยืนยันตัวตน การสร้าง slug และการเรียกคืน Active Memory จะร้องขอให้ล้างข้อมูลเมื่อสิ้นสุดการทำงาน เพื่อไม่ให้กระบวนการลูก stdio และสตรีม HTTP/SSE แบบ Streamable มีอายุยาวเกินกว่าการทำงาน
## ขีดจำกัดประวัติการตั้งข้อมูลเริ่มต้นใหม่
เมื่อเซสชัน CLI ใหม่ถูกตั้งต้นจากทรานสคริปต์ OpenClaw ก่อนหน้า (เช่น หลังจากลอง `session_expired` อีกครั้ง) บล็อก `` ที่เรนเดอร์จะถูกจำกัดขนาดเพื่อป้องกันไม่ให้พรอมต์สำหรับการตั้งต้นใหม่ขยายใหญ่เกินไป ค่าเริ่มต้นคือ 12,288 อักขระ (ประมาณ 3,000 โทเค็น)
แบ็กเอนด์ Claude CLI จะปรับขนาดขีดจำกัดนี้ตามหน้าต่างบริบทของ Claude ที่ได้รับการกำหนดแทน โดยหน้าต่างบริบทที่ใหญ่กว่าจะได้รับส่วนของประวัติก่อนหน้าที่ใหญ่ขึ้นจนถึงเพดานคงที่ ส่วนแบ็กเอนด์ CLI อื่นจะยังคงใช้ค่าเริ่มต้นแบบระมัดระวัง ขีดจำกัดนี้ควบคุมเฉพาะบล็อกประวัติก่อนหน้าในพรอมต์สำหรับการตั้งต้นใหม่เท่านั้น
## ข้อจำกัด
- ไม่มีการเรียกใช้เครื่องมือ OpenClaw โดยตรง: OpenClaw ไม่แทรกการเรียกใช้เครื่องมือลงในโปรโตคอลของแบ็กเอนด์ CLI แบ็กเอนด์จะเห็นเครื่องมือ Gateway เฉพาะเมื่อเลือกใช้ `bundleMcp: true`
- การสตรีมขึ้นอยู่กับแบ็กเอนด์: แบ็กเอนด์บางรายการสตรีม JSONL ส่วนรายการอื่นจะบัฟเฟอร์จนกว่ากระบวนการจะสิ้นสุด
- เอาต์พุตแบบมีโครงสร้างขึ้นอยู่กับรูปแบบ JSON ของ CLI เอง
## การแก้ไขปัญหา
| อาการ | วิธีแก้ไข |
| --------------------- | ----------------------------------------------------------------- |
| ไม่พบ CLI | ตั้งค่า `command` เป็นพาธแบบเต็ม |
| ชื่อโมเดลไม่ถูกต้อง | ใช้ `modelAliases` เพื่อแมป `provider/model` กับรหัสโมเดลของ CLI |
| เซสชันไม่ต่อเนื่อง | ตรวจสอบว่าได้ตั้งค่า `sessionArg` และ `sessionMode` ไม่ใช่ `none` |
| รูปภาพถูกละเว้น | ตั้งค่า `imageArg` และตรวจสอบว่า CLI รองรับพาธไฟล์ |
## ที่เกี่ยวข้อง
- [คู่มือการปฏิบัติงาน Gateway](/th/gateway)
- [โมเดลภายในเครื่อง](/th/gateway/local-models)