Agent Runtime 🤖

OpenClaw chạy một agent runtime nhúng duy nhất được phát triển từ pi-mono.

Workspace (bắt buộc)

OpenClaw sử dụng một thư mục agent workspace duy nhất (agents.defaults.workspace) làm thư mục làm việc duy nhất (cwd) cho các công cụ và context.

Mình khuyên dùng: chạy openclaw setup để tạo ~/.openclaw/openclaw.json nếu chưa có và khởi tạo các file workspace.

Xem chi tiết cấu trúc workspace + hướng dẫn backup: Agent workspace

Nếu agents.defaults.sandbox được bật, các session không phải main có thể ghi đè cài đặt này bằng workspace riêng cho từng session trong agents.defaults.sandbox.workspaceRoot (xem Gateway configuration).

Bootstrap files (được inject)

Trong agents.defaults.workspace, OpenClaw cần các file có thể chỉnh sửa sau:

  • AGENTS.md — hướng dẫn vận hành + “bộ nhớ”
  • SOUL.md — tính cách, ranh giới, giọng điệu
  • TOOLS.md — ghi chú về công cụ do người dùng quản lý (ví dụ: imsg, sag, quy ước)
  • BOOTSTRAP.md — nghi thức chạy lần đầu (sẽ bị xóa sau khi hoàn thành)
  • IDENTITY.md — tên agent/phong cách/emoji
  • USER.md — hồ sơ người dùng + cách xưng hô ưa thích

Ở lượt đầu tiên của session mới, OpenClaw sẽ inject nội dung của các file này trực tiếp vào context của agent.

File trống sẽ bị bỏ qua. File lớn sẽ được cắt bớt và đánh dấu để prompt gọn nhẹ (đọc file để xem nội dung đầy đủ).

Nếu thiếu file, OpenClaw sẽ inject một dòng đánh dấu “missing file” (và openclaw setup sẽ tạo template mặc định an toàn).

BOOTSTRAP.md chỉ được tạo cho workspace hoàn toàn mới (không có bootstrap file nào khác). Nếu các bạn xóa nó sau khi hoàn thành nghi thức, nó sẽ không được tạo lại khi khởi động lại.

Để tắt hoàn toàn việc tạo bootstrap file (cho workspace đã được chuẩn bị sẵn), set:

{ agent: { skipBootstrap: true } }

Built-in tools

Các công cụ cốt lõi (read/exec/edit/write và các công cụ hệ thống liên quan) luôn khả dụng, tùy thuộc vào tool policy. apply_patch là tùy chọn và được kiểm soát bởi tools.exec.applyPatch. TOOLS.md không kiểm soát công cụ nào tồn tại; nó là hướng dẫn về cách các bạn muốn chúng được sử dụng.

Skills

OpenClaw load skills từ ba vị trí (workspace thắng khi trùng tên):

  • Bundled (đi kèm với bản cài đặt)
  • Managed/local: ~/.openclaw/skills
  • Workspace: <workspace>/skills

Skills có thể được kiểm soát bởi config/env (xem skills trong Gateway configuration).

pi-mono integration

OpenClaw tái sử dụng các phần của codebase pi-mono (models/tools), nhưng quản lý session, discovery, và tool wiring thuộc về OpenClaw.

  • Không có pi-coding agent runtime.
  • Không tham khảo cài đặt ~/.pi/agent hoặc <workspace>/.pi.

Sessions

Session transcripts được lưu dưới dạng JSONL tại:

  • ~/.openclaw/agents/<agentId>/sessions/<SessionId>.jsonl

Session ID ổn định và được chọn bởi OpenClaw. Các thư mục session Pi/Tau cũ không được đọc.

Steering while streaming

Khi queue mode là steer, các tin nhắn đến sẽ được inject vào lượt chạy hiện tại. Queue được kiểm tra sau mỗi lần gọi tool; nếu có tin nhắn trong queue, các lần gọi tool còn lại từ tin nhắn assistant hiện tại sẽ bị bỏ qua (kết quả tool lỗi với “Skipped due to queued user message.”), sau đó tin nhắn người dùng trong queue được inject trước phản hồi assistant tiếp theo.

Khi queue mode là followup hoặc collect, các tin nhắn đến được giữ lại cho đến khi lượt hiện tại kết thúc, sau đó một lượt agent mới bắt đầu với các payload trong queue. Xem Queue để biết về mode + hành vi debounce/cap.

Block streaming gửi các block assistant đã hoàn thành ngay khi chúng kết thúc; nó tắt theo mặc định (agents.defaults.blockStreamingDefault: "off"). Điều chỉnh ranh giới qua agents.defaults.blockStreamingBreak (text_end vs message_end; mặc định là text_end). Kiểm soát soft block chunking với agents.defaults.blockStreamingChunk (mặc định 800–1200 ký tự; ưu tiên ngắt đoạn văn, sau đó xuống dòng; câu cuối cùng). Gộp các chunk được stream với agents.defaults.blockStreamingCoalesce để giảm spam từng dòng (gộp dựa trên idle trước khi gửi). Các channel không phải Telegram cần *.blockStreaming: true rõ ràng để bật block replies. Tóm tắt công cụ chi tiết được phát ra khi công cụ bắt đầu (không debounce); Control UI stream tool output qua agent events khi có sẵn. Chi tiết hơn: Streaming + chunking.

Model refs

Model refs trong config (ví dụ agents.defaults.model và agents.defaults.models) được phân tích bằng cách tách ở dấu / đầu tiên.

  • Dùng provider/model khi cấu hình models.
  • Nếu model ID chứa / (kiểu OpenRouter), thêm provider prefix (ví dụ: openrouter/moonshotai/kimi-k2).
  • Nếu bỏ qua provider, OpenClaw coi input là alias hoặc model cho default provider (chỉ hoạt động khi không có / trong model ID).

Configuration (tối thiểu)

Tối thiểu, set:

  • agents.defaults.workspace
  • channels.whatsapp.allowFrom (mình khuyên nên set)

Tiếp theo: Group Chats 🦞