Các phần phụ trợ CLI

• Các công cụ OpenClaw không được tiêm trực tiếp, nhưng các backend có bundleMcp: true có thể nhận công cụ gateway qua một cầu nối MCP loopback.
• Phát trực tuyến JSONL cho các CLI hỗ trợ.
• Có hỗ trợ phiên (để các lượt tiếp theo vẫn mạch lạc).
• Có thể truyền hình ảnh qua nếu CLI chấp nhận đường dẫn hình ảnh.

​

Bắt đầu nhanh thân thiện với người mới

openclaw agent --agent main --message "hi" --model claude-cli/claude-sonnet-4-6

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

​

Dùng làm phương án dự phòng

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

• Nếu bạn dùng agents.defaults.models (danh sách cho phép), bạn cũng phải đưa các mô hình backend CLI của mình vào đó.
• 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 chờ), OpenClaw sẽ thử backend CLI tiếp theo.

​

Tổng quan cấu hình

agents.defaults.cliBackends

<provider>/<model>

​

Cấu hình ví dụ

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

​

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. Tạo system prompt bằng cùng prompt OpenClaw + ngữ cảnh workspace.
3. Thực thi CLI với id phiên (nếu được hỗ trợ) để lịch sử vẫn nhất quán. Backend claude-cli đi kèm giữ một tiến trình Claude stdio sống cho mỗi phiên OpenClaw và gửi các lượt tiếp theo qua stdin stream-json.
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 bền vững id phiên cho từng backend, để các lượt tiếp theo dùng lại cùng phiên CLI.

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

​

Phiên

• Nếu CLI hỗ trợ phiên, đặt sessionArg (ví dụ --session-id) hoặc sessionArgs (placeholder {sessionId}) khi ID cần được chèn vào nhiều cờ.
• Nếu CLI dùng lệnh con resume với các cờ khác, đặt resumeArgs (thay thế args khi resume) và tùy chọn resumeOutput (cho resume không phải JSON).
• sessionMode:
  • always: luôn gửi id phiên (UUID mới nếu chưa có lưu trữ).
  • existing: chỉ gửi id phiên nếu trước đó đã lưu.
  • none: không bao giờ gửi id phiên.
• claude-cli mặc định là liveSession: "claude-stdio", output: "jsonl", và input: "stdin" để các lượt tiếp theo dùng lại tiến trình Claude live trong khi nó đang hoạt động. Stdio ấm giờ là mặc định, kể cả với cấu hình tùy chỉnh bỏ qua các trường transport. Nếu Gateway khởi động lại hoặc tiến trình nhàn rỗi thoát, OpenClaw resume từ id phiên Claude đã lưu. Các id phiên đã lưu được xác minh với transcript dự án hiện có và có thể đọc trước khi resume, nên các binding ảo bị xóa với reason=transcript-missing thay vì âm thầm bắt đầu một phiên Claude CLI mới dưới --resume.
• Phiên Claude live giữ các bộ giới hạn đầu ra JSONL có biên. Mặc định cho phép tối đa 8 MiB và 20.000 dòng JSONL thô mỗi lượt. Các lượt Claude dùng nhiều công cụ có thể tăng chúng theo từng backend bằng agents.defaults.cliBackends.claude-cli.reliability.outputLimits.maxTurnRawChars và maxTurnLines; OpenClaw kẹp các thiết lập đó ở 64 MiB và 100.000 dòng.
• Các phiên CLI đã lưu là tính liên tục do nhà cung cấp sở hữu. Việc đặt lại phiên hằng ngày ngầm định không cắt chúng; /reset và các chính sách session.reset rõ ràng vẫn cắt.
• Phiên CLI mới thường chỉ gieo lại từ tóm tắt Compaction của OpenClaw cộng với phần đuôi sau Compaction. Để khôi phục các phiên ngắn bị vô hiệu hóa trước Compaction, backend có thể chọn tham gia bằng reseedFromRawTranscriptWhenUncompacted: true. OpenClaw vẫn giữ việc gieo lại transcript thô trong giới hạn và chỉ giới hạn vào các vô hiệu hóa an toàn như thiếu transcript CLI, thay đổi system-prompt/MCP, hoặc thử lại do phiên hết hạn; thay đổi hồ sơ xác thực hoặc credential-epoch không bao giờ gieo lại lịch sử transcript thô.

• serialize: true giữ các lượt chạy cùng làn theo đúng thứ tự.
• Hầu hết CLI tuần tự hóa trên một làn nhà cung cấp.
• OpenClaw bỏ việc dùng lại phiên CLI đã lưu khi danh tính xác thực được chọn thay đổi, bao gồm id hồ sơ xác thực đã thay đổi, API key tĩnh, token tĩnh, hoặc danh tính tài khoản OAuth khi CLI phơi bày một danh tính. Việc xoay vòng access token và refresh token OAuth không cắt phiên CLI đã lưu. Nếu CLI không phơi bày một id tài khoản OAuth ổn định, OpenClaw để CLI đó thực thi quyền resume.

​

Phần mở đầu dự phòng từ phiên claude-cli

• Phần mở đầu ưu tiên tóm tắt /compact mới nhất hoặc dấu mốc compact_boundary, rồi nối thêm các lượt sau ranh giới gần đây nhất đến giới hạn ký tự. Các lượt trước ranh giới bị bỏ vì tóm tắt đã đại diện cho chúng.
• Các khối công cụ được gộp thành gợi ý gọn (tool call: name) và (tool result: …) để giữ ngân sách prompt trung thực. Tóm tắt được gắn nhãn (truncated) nếu vượt quá giới hạn.
• Các dự phòng cùng nhà cung cấp từ claude-cli sang claude-cli dựa vào --resume riêng của Claude và bỏ qua phần mở đầu.
• Seed dùng lại cơ chế xác thực đường dẫn file phiên Claude hiện có, nên không thể đọc đường dẫn tùy ý.

​

Hình ảnh (truyền qua)

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

​

Đầu vào / đầu ra

• output: "json" (mặc định) cố phân tích JSON và trích xuất văn bản + id phiên.
• Đối với đầu ra JSON của Gemini CLI, OpenClaw đọc văn bản trả lời từ response và usage từ stats khi usage bị thiếu hoặc rỗng. Mặc định Gemini CLI đi kèm dùng stream-json, nhưng các ghi đè --output-format json cũ vẫn dùng trình phân tích JSON.
• output: "jsonl" phân tích luồng JSONL và trích xuất tin nhắn tác tử cuối cùng cùng các định danh phiên khi có.
• output: "text" xem stdout là phản hồi cuối cùng.

• input: "arg" (mặc định) truyền prompt dưới dạng đối 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 dùng.

​

Mặc định (do Plugin sở hữu)

• command: "claude"
• args: ["-p","--output-format","stream-json","--include-partial-messages","--verbose", ...]
• output: "jsonl"
• input: "stdin"
• modelArg: "--model"
• sessionMode: "always"

• command: "gemini"
• args: ["--skip-trust", "--approval-mode", "auto_edit", "--output-format", "stream-json", "--prompt", "{prompt}"]
• resumeArgs: ["--skip-trust", "--approval-mode", "auto_edit", "--resume", "{sessionId}", "--output-format", "stream-json", "--prompt", "{prompt}"]
• output: "jsonl"
• resumeOutput: "jsonl"
• jsonlDialect: "gemini-stream-json"
• imageArg: "@"
• imagePathScope: "workspace"
• modelArg: "--model"
• sessionMode: "existing"
• sessionIdFields: ["session_id", "sessionId"]

• Bộ phân tích cú pháp stream-json mặc định đọc các sự kiện message của trợ lý, sự kiện công cụ, mức sử dụng result cuối cùng, và các sự kiện lỗi Gemini nghiêm trọng.
• Nếu bạn ghi đè đối số Gemini thành --output-format json, OpenClaw chuẩn hóa backend đó trở lại output: "json" và đọc văn bản phản hồi từ trường JSON response.
• Mức sử dụng dùng dự phòng stats khi usage vắng mặt hoặc rỗng.
• stats.cached được chuẩn hóa thành cacheRead của OpenClaw.
• Nếu thiếu stats.input, OpenClaw suy ra token đầu vào từ stats.input_tokens - stats.cached.

​

Mặc định do Plugin sở hữu

• Plugin đăng ký chúng bằng api.registerCliBackend(...).
• id của backend trở thành tiền tố nhà cung cấp trong tham chiếu mô hình.
• Cấu hình người dùng trong agents.defaults.cliBackends.<id> vẫn ghi đè mặc định của Plugin.
• Dọn dẹp cấu hình riêng cho backend vẫn do Plugin sở hữu thông qua hook tùy chọn 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" },
  ],
});

​

Quyền sở hữu Compaction gốc

api.registerCliBackend({ id: "my-cli", ownsNativeCompaction: true /* ... */ });

​

Lớp phủ MCP gói kèm

• claude-cli: tệp cấu hình MCP nghiêm ngặt được tạo
• google-gemini-cli: tệp thiết lập hệ thống Gemini được tạo

• khởi chạy một máy chủ MCP HTTP local loopback, phơi bày các công cụ Gateway cho tiến trình CLI
• xác thực cầu nối bằng token theo phiên (OPENCLAW_MCP_TOKEN)
• giới hạn quyền truy cập công cụ trong phạm vi phiên, tài khoản, và ngữ cảnh kênh hiện tại
• tải các máy chủ bundle-MCP đã bật cho workspace hiện tại
• hợp nhất chúng với mọi dạng cấu hình/thiết lập MCP backend hiện có
• viết lại cấu hình khởi chạy bằng chế độ tích hợp do backend sở hữu từ tiện ích mở rộng sở hữu nó

​

Giới hạn lịch sử reseed

• Giới hạn này chỉ quản lý khối lịch sử trước đó trong prompt reseed. Các giới hạn đầu ra phiên đang hoạt động được tinh chỉnh riêng trong reliability.outputLimits (xem Phiên).

​

Hạn chế

• Không có lệnh gọi công cụ OpenClaw trực tiếp. OpenClaw không chèn lệnh gọi công cụ vào giao thức backend CLI. Backend chỉ thấy công cụ Gateway khi chúng chọn dùng bundleMcp: true.
• Streaming phụ thuộc vào backend. Một số backend stream JSONL; các backend khác đệm cho đến khi thoát.
• Đầu ra có cấu trúc phụ thuộc vào định dạng JSON của CLI.

​

Khắc phục sự cố

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

​

Liên quan

• Runbook Gateway
• Mô hình cục bộ