แบ็กเอนด์CLI(รันไทม์สำรอง)¶

OpenClawสามารถรันCLIของAIในเครื่องเป็นทางสำรองแบบข้อความล้วนเมื่อผู้ให้บริการAPIล่ม ถูกจำกัดอัตรา หรือทำงานผิดพลาดชั่วคราว แนวทางนี้ตั้งใจให้保守เป็นพิเศษ: This is intentionally conservative:

• ปิดการใช้งานเครื่องมือ(ไม่มีการเรียกเครื่องมือ)
• ข้อความเข้า→ข้อความออก(เชื่อถือได้)
• รองรับเซสชัน(เพื่อให้การสนทนาต่อเนื่องสอดคล้องกัน)
• สามารถส่งผ่านรูปภาพได้หากCLIยอมรับพาธของรูปภาพ

This is designed as a safety net rather than a primary path. ออกแบบมาเป็นตาข่ายนิรภัยมากกว่าเส้นทางหลัก ใช้เมื่อคุณต้องการคำตอบแบบข้อความที่ “ใช้งานได้เสมอ”โดยไม่ต้องพึ่งพาAPIภายนอก

เริ่มต้นอย่างรวดเร็วสำหรับผู้เริ่มต้น¶

คุณสามารถใช้Claude Code CLIได้โดยไม่ต้องตั้งค่าใดๆ(OpenClawมีค่าเริ่มต้นในตัว):

openclaw agent --message "hi" --model claude-cli/opus-4.6

Codex CLIก็ใช้งานได้ทันทีเช่นกัน:

openclaw agent --message "hi" --model codex-cli/gpt-5.3-codex

หากGatewayของคุณรันภายใต้launchd/systemdและPATHมีน้อย ให้เพิ่มเพียง พาธของคำสั่ง:

{
  agents: {
    defaults: {
      cliBackends: {
        "claude-cli": {
          command: "/opt/homebrew/bin/claude",
        },
      },
    },
  },
}

That’s it. เพียงเท่านี้ ไม่ต้องใช้คีย์ และไม่ต้องตั้งค่าการยืนยันตัวตนเพิ่มเติมนอกเหนือจากตัวCLIเอง

การใช้เป็นทางสำรอง¶

เพิ่มแบ็กเอนด์CLIลงในรายการทางสำรองเพื่อให้ทำงานเฉพาะเมื่อโมเดลหลักล้มเหลว:

{
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-opus-4-6",
        fallbacks: ["claude-cli/opus-4.6", "claude-cli/opus-4.5"],
      },
      models: {
        "anthropic/claude-opus-4-6": { alias: "Opus" },
        "claude-cli/opus-4.6": {},
        "claude-cli/opus-4.5": {},
      },
    },
  },
}

หมายเหตุ:

• หากคุณใช้agents.defaults.models(allowlist)คุณต้องรวมclaude-cli/...ด้วย
• หากผู้ให้บริการหลักล้มเหลว(การยืนยันตัวตน ข้อจำกัดอัตรา ไทม์เอาต์)OpenClawจะ ลองใช้แบ็กเอนด์CLIถัดไป

ภาพรวมการกำหนดค่า¶

แบ็กเอนด์CLIทั้งหมดอยู่ภายใต้:

agents.defaults.cliBackends

แต่ละรายการใช้คีย์เป็นprovider id(เช่นclaude-cli,my-cli) provider idจะกลายเป็นฝั่งซ้ายของการอ้างอิงโมเดลของคุณ: The provider id becomes the left side of your model ref:

<provider>/<model>

ตัวอย่างการกำหนดค่า¶

{
  agents: {
    defaults: {
      cliBackends: {
        "claude-cli": {
          command: "/opt/homebrew/bin/claude",
        },
        "my-cli": {
          command: "my-cli",
          args: ["--json"],
          output: "json",
          input: "arg",
          modelArg: "--model",
          modelAliases: {
            "claude-opus-4-6": "opus",
            "claude-opus-4-5": "opus",
            "claude-sonnet-4-5": "sonnet",
          },
          sessionArg: "--session",
          sessionMode: "existing",
          sessionIdFields: ["session_id", "conversation_id"],
          systemPromptArg: "--system",
          systemPromptWhen: "first",
          imageArg: "--image",
          imageMode: "repeat",
          serialize: true,
        },
      },
    },
  },
}

ทำงานอย่างไร¶

1. เลือกแบ็กเอนด์ตามคำนำหน้าprovider(claude-cli/...)
2. สร้างsystem promptโดยใช้พรอมป์ของOpenClawเดียวกัน+บริบทเวิร์กสเปซ
3. รันCLIพร้อมsession id(ถ้ารองรับ)เพื่อให้ประวัติคงความสอดคล้อง
4. แยกผลลัพธ์(JSONหรือข้อความล้วน)และส่งคืนข้อความสุดท้าย
5. บันทึกsession idแยกตามแบ็กเอนด์เพื่อให้การติดตามผลใช้เซสชันCLIเดิม

เซสชัน¶

• หากCLIรองรับเซสชัน ให้ตั้งค่าsessionArg(เช่น--session-id)หรือ sessionArgs(ตัวยึดตำแหน่ง{sessionId})เมื่อจำเป็นต้องแทรกIDลงในหลายแฟลก
• หากCLIใช้คำสั่งย่อยสำหรับresumeที่มีแฟลกต่างกัน ให้ตั้งค่า resumeArgs(แทนที่argsเมื่อresume)และเลือกตั้งค่าresumeOutput (สำหรับการresumeที่ไม่ใช่JSON)
• sessionMode:
• always: ส่งsession idเสมอ(สร้างUUIDใหม่หากยังไม่ถูกเก็บ)
• existing: ส่งsession idเฉพาะเมื่อมีการเก็บไว้ก่อนหน้า
• none: ไม่ส่งsession idเลย

รูปภาพ(ส่งผ่าน)¶

หากCLIของคุณยอมรับพาธของรูปภาพ ให้ตั้งค่าimageArg:

imageArg: "--image",
imageMode: "repeat"

OpenClaw will write base64 images to temp files. If imageArg is set, those paths are passed as CLI args. OpenClawจะเขียนรูปภาพแบบbase64ลงไฟล์ชั่วคราว หากตั้งค่าimageArg พาธเหล่านั้นจะถูกส่งเป็นอาร์กิวเมนต์ให้CLI หากไม่มีimageArg OpenClawจะต่อท้าย พาธไฟล์ลงในพรอมป์(การฉีดพาธ)ซึ่งเพียงพอสำหรับCLIที่โหลดไฟล์ในเครื่องอัตโนมัติจากพาธธรรมดา (พฤติกรรมของClaude Code CLI)

อินพุต/เอาต์พุต¶

• output: "json"(ค่าเริ่มต้น)พยายามแยกJSONและดึงข้อความ+session id
• output: "jsonl"แยกสตรีมJSONL(Codex CLI --json)และดึงข้อความเอเจนต์สุดท้าย พร้อมthread_idเมื่อมี
• output: "text"ถือว่าstdoutคือคำตอบสุดท้าย

โหมดอินพุต:

• input: "arg"(ค่าเริ่มต้น)ส่งพรอมป์เป็นอาร์กิวเมนต์สุดท้ายของCLI
• input: "stdin"ส่งพรอมป์ผ่านstdin
• หากพรอมป์ยาวมากและตั้งค่าmaxPromptArgCharsจะใช้stdin

ค่าเริ่มต้น(มีในตัว)¶

OpenClawมีค่าเริ่มต้นสำหรับclaude-cli:

• command: "claude"
• args: ["-p", "--output-format", "json", "--dangerously-skip-permissions"]
• resumeArgs: ["-p", "--output-format", "json", "--dangerously-skip-permissions", "--resume", "{sessionId}"]
• modelArg: "--model"
• systemPromptArg: "--append-system-prompt"
• sessionArg: "--session-id"
• systemPromptWhen: "first"
• sessionMode: "always"

OpenClawยังมีค่าเริ่มต้นสำหรับcodex-cli:

• command: "codex"
• args: ["exec","--json","--color","never","--sandbox","read-only","--skip-git-repo-check"]
• resumeArgs: ["exec","resume","{sessionId}","--color","never","--sandbox","read-only","--skip-git-repo-check"]
• output: "jsonl"
• resumeOutput: "text"
• modelArg: "--model"
• imageArg: "--image"
• sessionMode: "existing"

ให้โอเวอร์ไรด์เฉพาะเมื่อจำเป็น(ที่พบบ่อย: พาธcommandแบบสัมบูรณ์)

ข้อจำกัด¶

• ไม่มีเครื่องมือของOpenClaw(แบ็กเอนด์CLIจะไม่รับการเรียกเครื่องมือ)บางCLI อาจยังรันเครื่องมือเอเจนต์ของตนเอง Some CLIs may still run their own agent tooling.
• ไม่มีการสตรีม(รวบรวมเอาต์พุตจากCLIแล้วจึงส่งคืน)
• เอาต์พุตแบบมีโครงสร้างขึ้นกับรูปแบบJSONของCLI
• เซสชันของCodex CLIresumeผ่านเอาต์พุตข้อความ(ไม่ใช่JSONL)ซึ่งมีโครงสร้างน้อยกว่า การรัน--jsonครั้งแรก เซสชันของOpenClawยังทำงานตามปกติ OpenClaw sessions still work normally.

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

• ไม่พบCLI: ตั้งค่าcommandเป็นพาธเต็ม
• ชื่อโมเดลไม่ถูกต้อง: ใช้modelAliasesเพื่อแมปprovider/model→โมเดลของCLI
• เซสชันไม่ต่อเนื่อง: ตรวจสอบให้ตั้งค่าsessionArgและsessionModeไม่ใช่ none(Codex CLIปัจจุบันไม่สามารถresumeด้วยเอาต์พุตJSON)
• รูปภาพถูกละเลย: ตั้งค่าimageArg(และตรวจสอบว่าCLIรองรับพาธไฟล์)