CLI backends (fallback runtime)

OpenClaw có thể chạy các AI CLI cục bộ như một phương án dự phòng chỉ văn bản khi các API provider gặp sự cố, bị giới hạn tốc độ, hoặc tạm thời hoạt động không ổn định. Cơ chế này được thiết kế cẩn trọng:

  • Tool bị vô hiệu hóa (không có tool call).
  • Văn bản vào → văn bản ra (đáng tin cậy).
  • Session được hỗ trợ (để các lượt hội thoại tiếp theo vẫn mạch lạc).
  • Hình ảnh có thể được truyền qua nếu CLI chấp nhận đường dẫn hình ảnh.

Đây được thiết kế như một lưới an toàn thay vì đường dẫn chính. Dùng nó khi các bạn muốn có phản hồi văn bản “luôn hoạt động” mà không phụ thuộc vào các API bên ngoài.

Bắt đầu nhanh cho người mới

Các bạn có thể dùng Claude Code CLI mà không cần config gì (OpenClaw đã tích hợp sẵn cấu hình mặc định):

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

Codex CLI cũng hoạt động ngay lập tức:

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

Nếu Gateway của các bạn chạy dưới launchd/systemd và PATH bị hạn chế, chỉ cần thêm đường dẫn lệnh:

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

Vậy là xong. Không cần key, không cần config xác thực thêm ngoài chính CLI đó.

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

Thêm CLI backend vào danh sách dự phòng để nó chỉ chạy khi các model chính gặp lỗi:

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

Lưu ý:

  • Nếu các bạn dùng agents.defaults.models (allowlist), phải bao gồm claude-cli/....
  • Nếu provider chính gặp lỗi (xác thực, giới hạn tốc độ, timeout), OpenClaw sẽ thử CLI backend tiếp theo.

Tổng quan cấu hình

Tất cả CLI backend nằm dưới:

agents.defaults.cliBackends

Mỗi mục được đánh key bằng một provider id (ví dụ: claude-cli, my-cli). Provider id trở thành phần bên trái của model ref:

<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-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,
        },
      },
    },
  },
}

Cách hoạt động

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

Session

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

Hình ảnh (pass-through)

Nếu CLI của các bạn chấp nhận đường dẫn hình ảnh, đặt imageArg:

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

OpenClaw sẽ ghi các hình ảnh base64 vào file tạm. Nếu imageArg được đặt, các đường dẫn đó sẽ được truyền như CLI args. Nếu imageArg bị thiếu, OpenClaw sẽ thêm đường dẫn file vào prompt (path injection), đủ cho các CLI tự động load file cục bộ từ đường dẫn thông thường (hành vi của Claude Code CLI).

Input / Output

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

Chế độ input:

  • input: "arg" (mặc định) truyền prompt như CLI arg 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)

OpenClaw tích hợp sẵn cấu hình mặc định cho 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 cũng tích hợp sẵn cấu hình mặc định cho 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"

Chỉ ghi đè nếu cần (phổ biến: đường dẫn tuyệt đối cho command).

Hạn chế

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

Troubleshooting

  • CLI không tìm thấy: đặt command thành đường dẫn đầy đủ.
  • Tên model sai: dùng modelAliases để map provider/model → CLI model.
  • Không có tính liên tục session: đảm bảo sessionArg được đặt và sessionMode không phải none (Codex CLI hiện tại không thể resume với JSON output).
  • Hình ảnh bị bỏ qua: đặt imageArg (và kiểm tra CLI có hỗ trợ đường dẫn file không).