Các phần phụ trợ 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.

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

​

Khởi động nhanh thân thiện với người mới

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

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

​

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

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

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

​

Cách hoạt động

1. Chọn một backend dựa trên tiền tố nhà cung cấp (codex-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ử luôn nhất quán. Backend claude-cli đi kèm giữ một tiến trình stdio Claude 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 theo 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 tiếp tục với các cờ khác, đặ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 id phiên (UUID mới nếu chưa có gì được lưu).
  • existing: chỉ gửi id phiên nếu trước đó đã có một id đượ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 đang sống khi nó còn hoạt động. Stdio ấm hiện là mặc định, kể cả với cấu hình tùy chỉnh bỏ qua các trường truyền tải. Nếu Gateway khởi động lại hoặc tiến trình nhàn rỗi thoát, OpenClaw tiếp tục từ id phiên Claude đã lưu. Id phiên đã lưu được xác minh với transcript dự án hiện có có thể đọc trước khi tiếp tục, nên các liên kết ảo được 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.
• 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ó hiệu lực.

• serialize: true giữ các lần chạy cùng lane theo đúng thứ tự.
• Hầu hết CLI tuần tự hóa trên một lane 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 đã đổi, API key tĩnh, token tĩnh, hoặc danh tính tài khoản OAuth khi CLI cung cấp. 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 cung cấp một id tài khoản OAuth ổn định, OpenClaw để CLI đó thực thi quyền tiếp tục.

​

Prelude dự phòng từ các phiên claude-cli

• Prelude ưu tiên bản tóm tắt /compact mới nhất hoặc marker compact_boundary, rồi nối thêm các lượt sau ranh giới gần nhất tới một ngân sách ký tự. Các lượt trước ranh giới bị bỏ vì bản 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. Bản tóm tắt được gắn nhãn (truncated) nếu vượt giới hạn.
• Các phương án 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 prelude.
• Seed dùng lại xác thực đường dẫn tệp phiên Claude hiện có, nên không thể đọc đường dẫn tùy ý.

​

Hình ảnh (truyền xuyên suốt)

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.
• 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 trống.
• output: "jsonl" phân tích các stream JSONL (ví dụ Codex CLI --json) và trích xuất tin nhắn agent cuối cùng cùng các định danh phiên khi có.
• output: "text" coi stdout là phản hồi cuối cùng.

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

• Văn bản trả lời được đọc từ trường JSON response.
• Usage dùng fallback sang stats khi usage không có hoặc trố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.
• Việc dọn dẹp cấu hình riêng theo backend vẫn do Plugin sở hữu thông qua hook normalizeConfig tùy chọn.

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" },
  ],
});

​

Gói kèm các lớp phủ MCP

• claude-cli: tệp cấu hình MCP nghiêm ngặt được tạo
• codex-cli: các ghi đè cấu hình nội tuyến cho mcp_servers; máy chủ local loopback OpenClaw được tạo được đánh dấu bằng chế độ phê duyệt công cụ theo từng máy chủ của Codex để các lệnh gọi MCP không bị kẹt ở prompt phê duyệt cục bộ
• google-gemini-cli: tệp cài đặt hệ thống Gemini được tạo

• sinh ra một máy chủ HTTP MCP loopback để cung cấp 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ụ theo ngữ cảnh phiên, tài khoản và 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/cài đặt MCP hiện có của backend
• 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ừ extension sở hữu nó

​

Giới hạn

• 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. Các 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 truyền phát JSONL; số khác lưu đệ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.
• Phiên Codex CLI tiếp tục qua đầu ra văn bản (không có JSONL), nên ít có cấu trúc hơn lần chạy --json ban đầu. Các phiên OpenClaw vẫn hoạt động bình thường.

​

Khắc phục sự cố

• Không tìm thấy CLI: đặt command thành đường dẫn đầy đủ.
• Tên model sai: dùng modelAliases để ánh xạ provider/model → model CLI.
• Không có tính liên tục của phiên: đảm bảo sessionArg được đặt và sessionMode không phải là none (Codex CLI hiện chưa 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).

​

Liên quan

• Runbook Gateway
• Model cục bộ