​

CLI backends (thời gian chạy dự phòng)

• Công cụ bị vô hiệu hóa (không có cuộc gọi công cụ).
• Văn bản vào → văn bản ra (đáng tin cậy).
• Hỗ trợ phiên (để các lượt tiếp theo vẫn nhất quán).
• Hình ảnh có thể được truyền qua nếu CLI chấp nhận đường dẫn hình ảnh.

​

Hướng dẫn nhanh cho người mới bắt đầu

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

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

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

​

Sử dụng như một phương án dự phòng

{
  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": {},
      },
    },
  },
}

• Nếu bạn sử dụng agents.defaults.models (danh sách cho phép), bạn phải bao gồm claude-cli/....
• Nếu nhà cung cấp chính thất bại (xác thực, giới hạn tốc độ, hết thời gian), OpenClaw sẽ thử CLI backend tiếp theo.

​

Tổng quan cấu hình

agents.defaults.cliBackends

<provider>/<model>

​

Ví dụ cấu hình

{
  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-6": "opus",
            "claude-sonnet-4-6": "sonnet",
          },
          sessionArg: "--session",
          sessionMode: "existing",
          sessionIdFields: ["session_id", "conversation_id"],
          systemPromptArg: "--system",
          systemPromptWhen: "first",
          imageArg: "--image",
          imageMode: "repeat",
          serialize: true,
        },
      },
    },
  },
}

​

Cách hoạt động

1. Chọn một backend dựa trên tiền tố nhà cung cấp (claude-cli/...).
2. Xây dựng một hệ thống prompt sử dụng cùng prompt OpenClaw + ngữ cảnh workspace.
3. Thực thi CLI với một session id (nếu được hỗ trợ) để lịch sử vẫn nhất quán.
4. Phân tích đầu ra (JSON hoặc văn bản thuần) và trả về văn bản cuối cùng.
5. Lưu trữ session ids cho mỗi backend, để các lượt tiếp theo tái sử dụng cùng một phiên CLI.

​

Phiên

• Nếu CLI hỗ trợ phiên, đặt sessionArg (ví dụ: --session-id) hoặc sessionArgs (chỗ chèn {sessionId}) khi ID cần được chèn vào nhiều cờ.
• Nếu CLI sử dụng một lệnh phụ resume với các cờ khác nhau, đặt resumeArgs (thay thế args khi tiếp tục) và tùy chọn resumeOutput (cho các lần tiếp tục không phải JSON).
• sessionMode:
  • always: luôn gửi một session id (UUID mới nếu không có lưu trữ).
  • existing: chỉ gửi một session id nếu đã lưu trữ trước đó.
  • none: không bao giờ gửi một session id.

​

Hình ảnh (truyền qua)

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

​

Đầu vào / đầu ra

• output: "json" (mặc định) cố gắng phân tích JSON và trích xuất văn bản + session id.
• output: "jsonl" phân tích các luồng JSONL (Codex CLI --json) và trích xuất thông điệp cuối cùng của agent cùng với thread_id khi có.
• output: "text" coi stdout là phản hồi cuối cùng.

• input: "arg" (mặc định) truyền prompt dưới dạng tham số CLI cuối cùng.
• input: "stdin" gửi prompt qua stdin.
• Nếu prompt rất dài và maxPromptArgChars được đặt, stdin sẽ được sử dụng.

​

Mặc định (tích hợp sẵn)

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

• 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"

​

Hạn chế

• Không có công cụ OpenClaw (CLI backend không bao giờ nhận cuộc gọi công cụ). Một số CLI có thể vẫn chạy công cụ agent của riêng chúng.
• Không có streaming (đầu ra CLI được thu thập rồi trả về).
• Đầu ra có cấu trúc phụ thuộc vào định dạng JSON của CLI.
• Phiên Codex CLI tiếp tục qua đầu ra văn bản (không phải JSONL), ít có cấu trúc hơn so với lần chạy --json ban đầu. Phiên OpenClaw vẫn hoạt động bình thường.

​

Khắc phục sự cố

• CLI không tìm thấy: đặt command thành đường dẫn đầy đủ.
• Sai tên mô hình: sử dụng modelAliases để ánh xạ provider/model → mô hình CLI.
• Không có sự liên tục phiên: đảm bảo sessionArg được đặt và sessionMode không phải none (Codex CLI hiện không thể tiếp tục với đầu ra JSON).
• Hình ảnh bị bỏ qua: đặt imageArg (và xác minh CLI hỗ trợ đường dẫn tệp).