แบ็กเอนด์ CLI

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

• เครื่องมือ OpenClaw จะไม่ถูกฉีดเข้าไปโดยตรง แต่แบ็กเอนด์ที่มี bundleMcp: true สามารถรับเครื่องมือ Gateway ผ่านสะพาน MCP แบบ local loopback ได้
• การสตรีม JSONL สำหรับ CLI ที่รองรับ
• รองรับเซสชัน (ดังนั้นรอบสนทนาต่อเนื่องจึงยังสอดคล้องกัน)
• สามารถส่งรูปภาพผ่านได้ หาก CLI รับพาธรูปภาพ

​

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

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

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

​

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

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

• หากคุณใช้ agents.defaults.models (รายการอนุญาต) คุณต้องใส่โมเดลของแบ็กเอนด์ CLI ของคุณไว้ที่นั่นด้วย
• หากผู้ให้บริการหลักล้มเหลว (auth, การจำกัดอัตรา, timeout) OpenClaw จะ ลองใช้แบ็กเอนด์ CLI ถัดไป

​

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

agents.defaults.cliBackends

<provider>/<model>

​

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

{
  agents: {
    defaults: {
      cliBackends: {
        "codex-cli": {
          command: "/opt/homebrew/bin/codex",
        },
        "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",
          // For CLIs with a dedicated prompt-file flag:
          // systemPromptFileArg: "--system-file",
          // Codex-style CLIs can point at a prompt file instead:
          // systemPromptFileConfigArg: "-c",
          // systemPromptFileConfigKey: "model_instructions_file",
          systemPromptWhen: "first",
          imageArg: "--image",
          imageMode: "repeat",
          // Opt in only if this backend may reseed safe invalidated sessions
          // from bounded raw OpenClaw transcript history before compaction.
          reseedFromRawTranscriptWhenUncompacted: true,
          serialize: true,
        },
      },
    },
  },
}

​

วิธีการทำงาน

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

claude auth login
claude auth status --text
openclaw models auth login --provider anthropic --method cli --set-default

​

เซสชัน

• หาก CLI รองรับเซสชัน ให้ตั้งค่า sessionArg (เช่น --session-id) หรือ sessionArgs (placeholder {sessionId}) เมื่อจำเป็นต้องแทรก ID ลงใน flag หลายตัว
• หาก CLI ใช้ resume subcommand พร้อม flag ที่ต่างกัน ให้ตั้งค่า resumeArgs (แทนที่ args เมื่อ resume) และอาจตั้งค่า resumeOutput (สำหรับ resume ที่ไม่ใช่ JSON)
• sessionMode:
  • always: ส่ง session id เสมอ (UUID ใหม่หากยังไม่มีที่เก็บไว้)
  • existing: ส่ง session id เฉพาะเมื่อเคยมีที่เก็บไว้ก่อนหน้า
  • none: ไม่ส่ง session id เลย
• claude-cli มีค่าเริ่มต้นเป็น liveSession: "claude-stdio", output: "jsonl", และ input: "stdin" เพื่อให้รอบสนทนาต่อเนื่องใช้โปรเซส Claude ที่ยังทำงานอยู่ซ้ำ ขณะที่ยัง active อยู่ ตอนนี้ warm stdio เป็นค่าเริ่มต้นแล้ว รวมถึง config แบบกำหนดเอง ที่ละเว้นฟิลด์ transport หาก Gateway รีสตาร์ตหรือโปรเซส idle ออก OpenClaw จะ resume จาก session id ของ Claude ที่เก็บไว้ session id ที่เก็บไว้จะถูกตรวจสอบกับ transcript โปรเจกต์ที่มีอยู่และอ่านได้ก่อน resume ดังนั้นการผูก phantom จะถูกล้างด้วย reason=transcript-missing แทนที่จะเริ่มเซสชัน Claude CLI ใหม่อย่างเงียบๆ ภายใต้ --resume
• เซสชัน live ของ Claude เก็บ guard ของ output JSONL แบบจำกัดขอบเขต ค่าเริ่มต้นอนุญาตสูงสุด 8 MiB และ 20,000 บรรทัด JSONL ดิบต่อรอบ รอบ Claude ที่ใช้เครื่องมือหนักสามารถเพิ่มค่าเหล่านี้ ต่อแบ็กเอนด์ได้ด้วย agents.defaults.cliBackends.claude-cli.reliability.outputLimits.maxTurnRawChars และ maxTurnLines; OpenClaw จะ clamp การตั้งค่าเหล่านั้นไว้ที่ 64 MiB และ 100,000 บรรทัด
• เซสชัน CLI ที่เก็บไว้คือความต่อเนื่องที่ผู้ให้บริการเป็นเจ้าของ การรีเซ็ตเซสชันรายวันโดยนัย จะไม่ตัดเซสชันเหล่านั้น; /reset และนโยบาย session.reset ที่ชัดเจนยังคงตัด
• โดยปกติเซสชัน CLI ใหม่จะ reseed เฉพาะจากสรุป Compaction ของ OpenClaw รวมกับ tail หลัง Compaction หากต้องการกู้เซสชันสั้นที่ถูกทำให้ invalid ก่อน Compaction แบ็กเอนด์สามารถ opt in ด้วย reseedFromRawTranscriptWhenUncompacted: true OpenClaw ยังคงจำกัดขอบเขต raw transcript reseed และจำกัดไว้เฉพาะการ invalidation ที่ปลอดภัย เช่น transcript ของ CLI หาย, การเปลี่ยนแปลง system-prompt/MCP หรือการ retry จาก session-expired; การเปลี่ยนแปลง auth profile หรือ credential-epoch จะไม่ reseed ประวัติ raw transcript

• serialize: true ทำให้การรันใน lane เดียวกันเรียงตามลำดับ
• CLI ส่วนใหญ่ serialize บน lane ผู้ให้บริการเดียว
• OpenClaw จะเลิกใช้ซ้ำเซสชัน CLI ที่เก็บไว้เมื่อ auth identity ที่เลือกเปลี่ยนไป รวมถึง auth profile id, static API key, static token หรือ OAuth account identity ที่เปลี่ยนเมื่อ CLI เปิดเผยตัวตนดังกล่าว การหมุนเวียน OAuth access token และ refresh token จะไม่ตัดเซสชัน CLI ที่เก็บไว้ หาก CLI ไม่เปิดเผย OAuth account id ที่เสถียร OpenClaw จะให้ CLI นั้นบังคับใช้สิทธิ์ resume เอง

​

พรีลูดทางสำรองจากเซสชัน claude-cli

• prelude จะเลือกสรุป /compact ล่าสุดหรือ marker compact_boundary ก่อน จากนั้นแนบรอบสนทนาหลัง boundary ล่าสุดจนถึงงบประมาณจำนวนอักขระ รอบก่อน boundary จะถูกทิ้งเพราะสรุปเป็นตัวแทนรอบเหล่านั้นอยู่แล้ว
• บล็อกเครื่องมือจะถูกรวมเป็นคำใบ้แบบกะทัดรัด (tool call: name) และ (tool result: …) เพื่อรักษางบประมาณ prompt ให้ตรงความจริง สรุปจะถูกติดป้าย (truncated) หากล้น
• fallback จาก claude-cli ไป claude-cli ผู้ให้บริการเดียวกันจะพึ่งพา --resume ของ Claude เองและข้าม prelude
• seed ใช้การตรวจสอบพาธไฟล์เซสชัน Claude ที่มีอยู่ซ้ำ ดังนั้น จึงไม่สามารถอ่านพาธตามอำเภอใจได้

​

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

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

​

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

• output: "json" (ค่าเริ่มต้น) จะพยายามแยกวิเคราะห์ JSON และดึงข้อความ + session id
• สำหรับ output JSON ของ Gemini CLI, OpenClaw จะอ่านข้อความตอบกลับจาก response และ usage จาก stats เมื่อ usage หายไปหรือว่าง
• output: "jsonl" แยกวิเคราะห์สตรีม JSONL (ตัวอย่างเช่น Codex CLI --json) และดึงข้อความสุดท้ายของเอเจนต์พร้อม session identifiers เมื่อมี
• output: "text" ถือว่า stdout เป็นคำตอบสุดท้าย

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

​

ค่าเริ่มต้น (Plugin เป็นเจ้าของ)

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

• command: "gemini"
• args: ["--output-format", "json", "--prompt", "{prompt}"]
• resumeArgs: ["--resume", "{sessionId}", "--output-format", "json", "--prompt", "{prompt}"]
• imageArg: "@"
• imagePathScope: "workspace"
• modelArg: "--model"
• sessionMode: "existing"
• sessionIdFields: ["session_id", "sessionId"]

• ข้อความตอบกลับจะถูกอ่านจากฟิลด์ JSON response
• การใช้งานจะถอยไปใช้ stats เมื่อ usage ไม่มีอยู่หรือว่างเปล่า
• stats.cached จะถูกทำให้เป็นรูปแบบ OpenClaw cacheRead
• หาก stats.input หายไป OpenClaw จะอนุมานโทเค็นอินพุตจาก stats.input_tokens - stats.cached

​

ค่าเริ่มต้นที่ Plugin เป็นเจ้าของ

• Plugins ลงทะเบียนค่าเหล่านี้ด้วย api.registerCliBackend(...)
• id ของแบ็กเอนด์จะกลายเป็นคำนำหน้าผู้ให้บริการใน model refs
• การกำหนดค่าผู้ใช้ใน agents.defaults.cliBackends.<id> ยังเขียนทับค่าเริ่มต้นของ Plugin ได้
• การล้างการกำหนดค่าเฉพาะแบ็กเอนด์ยังคงเป็นของ Plugin ผ่าน hook normalizeConfig ที่เป็นตัวเลือก

api.registerTextTransforms({
  input: [
    { from: /red basket/g, to: "blue basket" },
    { from: /paper ticket/g, to: "digital ticket" },
    { from: /left shelf/g, to: "right shelf" },
  ],
  output: [
    { from: /blue basket/g, to: "red basket" },
    { from: /digital ticket/g, to: "paper ticket" },
    { from: /right shelf/g, to: "left shelf" },
  ],
});

​

โอเวอร์เลย์ MCP ของบันเดิล

• claude-cli: ไฟล์การกำหนดค่า MCP แบบเข้มงวดที่สร้างขึ้น
• codex-cli: การเขียนทับการกำหนดค่าแบบอินไลน์สำหรับ mcp_servers; เซิร์ฟเวอร์ local loopback ของ OpenClaw ที่สร้างขึ้นจะถูกทำเครื่องหมายด้วยโหมดอนุมัติเครื่องมือต่อเซิร์ฟเวอร์ของ Codex เพื่อไม่ให้การเรียก MCP ค้างอยู่ที่พรอมป์อนุมัติภายในเครื่อง
• google-gemini-cli: ไฟล์การตั้งค่าระบบ Gemini ที่สร้างขึ้น

• สร้างเซิร์ฟเวอร์ HTTP MCP แบบ loopback ที่เปิดเผยเครื่องมือ Gateway ให้กับโปรเซส CLI
• ตรวจสอบสิทธิ์บริดจ์ด้วยโทเค็นต่อเซสชัน (OPENCLAW_MCP_TOKEN)
• จำกัดขอบเขตการเข้าถึงเครื่องมือไว้ที่บริบทเซสชัน บัญชี และช่องทางปัจจุบัน
• โหลดเซิร์ฟเวอร์ bundle-MCP ที่เปิดใช้งานสำหรับเวิร์กสเปซปัจจุบัน
• รวมเข้ากับรูปแบบการกำหนดค่า/การตั้งค่า MCP ของแบ็กเอนด์ที่มีอยู่
• เขียนการกำหนดค่าเริ่มทำงานใหม่โดยใช้โหมดการผสานรวมที่แบ็กเอนด์เป็นเจ้าของจาก extension เจ้าของ

​

ข้อจำกัด

• ไม่มี tool calls ของ OpenClaw โดยตรง OpenClaw ไม่ฉีด tool calls เข้าไปใน โปรโตคอลแบ็กเอนด์ CLI แบ็กเอนด์จะเห็นเครื่องมือ Gateway เฉพาะเมื่อเลือกใช้ bundleMcp: true เท่านั้น
• การสตรีมขึ้นอยู่กับแบ็กเอนด์ บางแบ็กเอนด์สตรีม JSONL; ส่วนอื่นบัฟเฟอร์ จนกว่าจะออก
• เอาต์พุตแบบมีโครงสร้าง ขึ้นอยู่กับรูปแบบ JSON ของ CLI
• เซสชัน Codex CLI ดำเนินต่อผ่านเอาต์พุตข้อความ (ไม่มี JSONL) ซึ่งมีโครงสร้างน้อยกว่า การรัน --json ครั้งแรก เซสชัน OpenClaw ยังคงทำงานได้ ตามปกติ

​

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

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

​

ที่เกี่ยวข้อง

• คู่มือปฏิบัติการ Gateway
• โมเดลภายในเครื่อง