Tài liệu này cung cấp bảng phân tích chi tiết về cấu trúc System Prompt hoàn chỉnh được gửi bởi OpenClaw Agent đến LLM.
Phiên bản:
v2.1
Thời gian cập nhật:
2026-03-05
Sơ đồ kiến trúc tổng thể
Điều hướng nhanh (TL;DR)
Bắt buộc đọc cho người mới bắt đầu:
- Lớp 7 (Workspace Files) - Các tệp cấu hình bạn có thể chỉnh sửa trực tiếp.
- Lớp 8 (Bootstrap Hook) - Nơi bạn có thể viết script để tự động chèn nội dung.
- Các lớp khác được framework tự động tạo ra; chỉ cần hiểu chúng.
Nhu cầu phổ biến:
- Muốn định nghĩa danh tính Agent? → Chỉnh sửa IDENTITY.md trong Lớp 7.
- Muốn thêm tài liệu dự án? → Sử dụng Hook bootstrap-extra-files trong Lớp 8.
- Muốn chèn ngữ cảnh thời gian thực? → Sử dụng Hook before_prompt_build trong Lớp 8.
- Muốn kiểm soát kích thước tệp? → Điều chỉnh cấu hình bootstrapMaxChars.
Lớp 1: Lõi Framework OpenClaw
Phép loại suy
Giống như phần "Hướng dẫn sử dụng" trong một cuốn sách hướng dẫn vận hành—cho LLM biết bạn là ai, bạn có thể làm gì và bạn nên phản hồi như thế nào.
Các thành phần
Ví dụ thực tế
Bạn đang hoạt động với tư cách là "Creative Partner", một Agent chuyên gia sáng tạo nội dung AI.
Thời gian hiện tại: 2026-03-05 14:37:00 CST
=== Đặc tả Gọi Công cụ ===
- Sử dụng định dạng gọi công cụ kiểu XML.
- Mỗi lần gọi công cụ phải bao gồm một tool_call_id duy nhất.
- Kết quả công cụ được trả về qua các thẻ <tool_result>.
- Cân nhắc AbortSignal khi thực thi công cụ để hỗ trợ hủy bỏ.
=== Ranh giới An toàn ===
- Nghiêm cấm thực thi các thao tác phá hủy (rm -rf, định dạng, v.v.).
- Thông tin nhạy cảm của người dùng phải được mã hóa khi xử lý.
- Nghiêm cấm gửi tin nhắn đến các kênh trái phép.
Sự đánh đổi trong thiết kế
Tại sao lại thiết kế như vậy?
- Sự đánh đổi: Linh hoạt vs. Nhất quán
- Quyết định: Tạo thống nhất ở lớp framework đảm bảo hành vi cơ bản nhất quán cho tất cả Agent.
- Lợi ích: Người dùng không cần lặp lại các quy tắc cơ bản cho mỗi Agent. Tất cả Agent tự động có được khả năng mới khi framework nâng cấp. Giảm rủi ro lỗi cấu hình.
- Chi phí: Người dùng không thể sửa đổi các quy tắc cốt lõi này. Các hành vi đặc biệt phải được thực hiện gián tiếp qua Lớp 7/8.
Lớp 2: Định nghĩa Công cụ
Phép loại suy
Giống như danh sách công cụ của một con dao quân đội Thụy Sĩ—cho LLM biết bạn có những công cụ nào, mỗi công cụ làm gì và cách sử dụng chúng.
Các thành phần
Ví dụ Định nghĩa Công cụ
{
"name": "read",
"description": "Đọc nội dung tệp. Hỗ trợ tệp văn bản và hình ảnh (jpg/png/gif/webp). Hình ảnh được gửi dưới dạng tệp đính kèm. Đầu ra văn bản bị giới hạn ở 2000 dòng hoặc 50KB.",
"parameters": {
"type": "object",
"properties": {
"path": {
"type": "string",
"description": "Đường dẫn tệp (tương đối hoặc tuyệt đối)"
},
"offset": {
"type": "number",
"description": "Số dòng bắt đầu (đánh số từ 1)"
},
"limit": {
"type": "number",
"description": "Số dòng tối đa để đọc"
}
},
"required": ["path"]
}
}
Sự đánh đổi trong thiết kế
Tại sao sử dụng JSON Schema?
- Sự đánh đổi: Linh hoạt vs. An toàn Kiểu dữ liệu
- Quyết định: Sử dụng JSON Schema chặt chẽ để định nghĩa tham số công cụ.
- Lợi ích: LLM hiểu cách sử dụng công cụ chính xác hơn. Framework có thể xác thực tham số trước khi gọi. Tự động tạo tài liệu và định nghĩa kiểu dữ liệu.
- Chi phí: Thêm công cụ mới yêu cầu viết Schema đầy đủ. Không thể hỗ trợ cấu trúc tham số động hoàn toàn.
Lớp 3: Danh sách Kỹ năng
Phép loại suy
Giống như "Thực đơn Đặc sản" của một nhà hàng—cho LLM biết những "công thức" chuyên nghiệp nào có sẵn để gọi.
Sự đánh đổi trong thiết kế
Tại sao sử dụng quét thư mục thay vì đăng ký thủ công?
- Sự đánh đổi: Linh hoạt vs. Chi phí Bảo trì
- Quyết định: Tự động quét thư mục ~/development/openclaw/skills/.
- Lợi ích: Thêm Kỹ năng mới chỉ cần đặt nó vào thư mục; không cần thay đổi cấu hình. Tất cả Agent tự động có được Kỹ năng mới. Giảm rủi ro lỗi cấu hình.
- Chi phí: Không thể kiểm soát chính xác Kỹ năng nào có sẵn cho mỗi Agent. Tất cả Kỹ năng đều được chèn vào System Prompt (làm tăng tiêu thụ token).
Các thành phần
Lớp 4: Bí danh Mô hình
Phép loại suy
Giống như "Phím tắt"—đặt bí danh ngắn cho các đường dẫn mô hình phức tạp để dễ dàng gọi.
Sự đánh đổi trong thiết kế
Tại sao cần bí danh mô hình?
- Sự đánh đổi: Linh hoạt vs. Khả năng đọc
- Quyết định: Cho phép người dùng định nghĩa bí danh ngắn cho các mô hình thường dùng.
- Lợi ích: Đơn giản hóa việc gọi mô hình (glm-5 thay vì zhipu/glm-5). Hỗ trợ chuyển đổi giữa nhiều Nhà cung cấp (cùng một bí danh có thể ánh xạ đến các Nhà cung cấp khác nhau). Tạo điều kiện cho thử nghiệm A/B và di chuyển mô hình.
- Chi phí: Yêu cầu duy trì tệp cấu hình bí danh. Có thể gây nhầm lẫn (cùng một bí danh có thể trỏ đến các mô hình khác nhau cho các Agent khác nhau).
Các thành phần
Ví dụ thực tế
Trong System Prompt, các bí danh mô hình được hiển thị như sau:
Bí danh Mô hình
- GLM-5: zhipu/glm-5
- Opus 4.6: xiaowang886/claude-opus-4-6-thinking
- Sonnet 4.5: xiaowang886/claude-sonnet-4-5
LLM có thể sử dụng bí danh để chuyển đổi mô hình: /model glm-5
Lớp 5: Đặc tả Giao thức
Phép loại suy
Giống như "Luật Giao thông"—định nghĩa các giao thức tiêu chuẩn cho tương tác Agent với hệ thống.
Sự đánh đổi trong thiết kế
Tại sao cần đặc tả giao thức?
- Sự đánh đổi: Tự do vs. Nhất quán
- Quyết định: Định nghĩa các giao thức tương tác được tiêu chuẩn hóa (Trả lời Im lặng, Nhịp tim, Thẻ Trả lời, v.v.).
- Lợi ích: Đảm bảo hành vi nhất quán trên tất cả các Agent. Hỗ trợ giám sát tự động và kiểm tra sức khỏe. Đơn giản hóa cộng tác đa Agent.
- Chi phí: Hạn chế quyền tự do biểu đạt của Agent. Yêu cầu LLM tuân thủ nghiêm ngặt các giao thức (có thể bị bỏ qua).
Các thành phần
Ví dụ thực tế
Ví dụ Trả lời Im lặng:
Người dùng: Đã nhận
Agent: NO_REPLY
Ví dụ Nhịp tim:
Hệ thống: [Heartbeat Poll]
Agent: HEARTBEAT_OK
Ví dụ Thẻ Trả lời:
Agent: [[reply_to_current]] Nhiệm vụ hoàn thành ✓
Lớp 6: Thông tin Thời gian chạy
Phép loại suy
Giống như "Bảng điều khiển"—cho LLM biết trạng thái thời gian thực của môi trường đang chạy hiện tại.
Sự đánh đổi trong thiết kế
Tại sao lại chèn thông tin thời gian chạy mỗi lần?
- Sự đánh đổi: Tiêu thụ Token vs. Độ chính xác của Ngữ cảnh
- Quyết định: Chèn trạng thái thời gian chạy mới nhất với mỗi yêu cầu.
- Lợi ích: LLM biết thời gian hiện tại (tránh nhầm lẫn thời gian). LLM biết mô hình hiện tại (tránh đánh giá sai khả năng). LLM biết môi trường hiện tại (tránh lỗi đường dẫn).
- Chi phí: Tiêu thụ khoảng ~2KB token cho mỗi yêu cầu. Thông tin có thể chứa sự dư thừa.
Các thành phần
Ví dụ thực tế
Thời gian chạy
Mô hình Hiện tại: claude-sonnet-4.5
Hệ điều hành: macOS 24.0.0
ID Phiên: session_abc123
Thư mục Làm việc: /Users/username/projects
Môi trường: production
Lớp 7: Workspace Files ★ Người dùng Có thể Kiểm soát
Phép loại suy
Giống như "Ghi chú Công việc của Bạn"—đây là các tệp cấu hình tĩnh bạn có thể chỉnh sửa trực tiếp.
Sự đánh đổi trong thiết kế
Tại sao chỉ lớp này mới có thể chỉnh sửa tĩnh?
- Sự đánh đổi: Tính ổn định của Framework vs. Quyền tự do của Người dùng
- Quyết định: Tách biệt phần "thay đổi" khỏi phần "không thay đổi"; lớp framework đảm bảo tính nhất quán trong khi lớp người dùng cho phép cá nhân hóa.
- Lợi ích: Người dùng có thể định nghĩa danh tính Agent, đặc tả công việc và bộ nhớ. Nâng cấp framework sẽ không làm hỏng cấu hình người dùng. Các tệp cấu hình có thể được quản lý phiên bản, sao lưu và chia sẻ.
- Chi phí: Người dùng không thể sửa đổi hành vi cốt lõi của framework. Yêu cầu học framework TELOS và cấu trúc tệp.
Các tệp cốt lõi
Lớp 8: Bootstrap Hook System ★ Người dùng Có thể Kiểm soát
Phép loại suy
Giống như "Ống tiêm Có thể Lập trình"—bạn có thể viết script để tự động chèn nội dung vào System Prompt tại thời điểm chạy.
Sự đánh đổi trong thiết kế
Tại sao cần hệ thống Hook?
- Sự đánh đổi: Sự đơn giản của Cấu hình Tĩnh vs. Tính linh hoạt của Chèn Động
- Quyết định: Cung cấp cơ chế Hook động song song với Workspace Files tĩnh.
- Lợi ích: Có thể điều chỉnh động nội dung được chèn dựa trên ngữ cảnh (kênh, người gửi, thời gian). Có thể thực thi lệnh shell và chèn đầu ra (ví dụ: thời tiết hiện tại, trạng thái Git). Có thể đọc tệp bên ngoài và chèn chúng (ví dụ: tài liệu dự án, tài liệu API). Hỗ trợ logic có điều kiện (if/else).
- Chi phí: Yêu cầu học cú pháp hệ thống Hook và cơ chế kích hoạt. Lỗi script Hook có thể gây ra sự bất thường trong System Prompt. Làm tăng độ phức tạp của hệ thống.
Bốn Cơ chế Hook
- agent:bootstrap Hook (Hệ thống Hook Nội bộ)
Vị trí Kích hoạt: applyBootstrapHookOverrides() trong bootstrap-hooks.ts
Khả năng:
- Kiểm soát hoàn toàn mảng bootstrapFiles.
- Có thể thêm, xóa hoặc sửa đổi tệp.
- Có thể sắp xếp lại thứ tự tệp.
- Có thể sửa đổi nội dung tệp.
Ai có thể đăng ký:
- Plugin OpenClaw.
- Workspace Hooks (thư mục ~/.openclaw/workspace-*/hooks/).
- Các mô-đun nội bộ.
Ví dụ Mã:
registerInternalHook("agent:bootstrap", (event) => {
const context = event.context as AgentBootstrapHookContext;
// Kiểm soát hoàn toàn mảng bootstrapFiles
context.bootstrapFiles = [
{ path: "CUSTOM.md", content: "Nội dung Tùy chỉnh" }
];
});
- bootstrap-extra-files Hook (Hook Đóng gói sẵn)
Vị trí Kích hoạt: handler.ts trong hooks/bundled/bootstrap-extra-files/
Khả năng:
- Chỉ thêm tệp; không sửa đổi tệp hiện có.
- Chỉ định tệp bổ sung thông qua tệp cấu hình.
Ví dụ Cấu hình:
{
"hooks": {
"bootstrap-extra-files": {
"enabled": true,
"paths": ["extra/*.md", "docs/CONTEXT.md"]
}
}
}
Các Tình huống Áp dụng:
- Cần chèn các tệp ngữ cảnh cụ thể cho dự án.
- Không muốn sửa đổi 8 tệp Bootstrap mặc định.
- Cần tải động tài liệu bổ sung.
- before_prompt_build Hook (Plugin Hook)
Vị trí Kích hoạt: runBeforePromptBuild() trong attempt.ts
Khả năng:
- Sửa đổi prompt cuối cùng (sau khi xây dựng system prompt, trước khi gửi đến LLM).
- Có thể thêm ngữ cảnh phía trước (thêm nội dung trước prompt).
- Có thể ghi đè systemPrompt.
Dữ liệu Sự kiện:
{
prompt: string; // Đầu vào của người dùng
messages: unknown[]; // Lịch sử tin nhắn phiên
}
Giá trị Trả về:
{
prependContext?: string; // Nội dung được thêm vào trước prompt
systemPrompt?: string; // Ghi đè system prompt
}
Các Tình huống Áp dụng:
- Cần điều chỉnh động prompt dựa trên lịch sử phiên.
- Cần chèn ngữ cảnh thời gian thực (ví dụ: thời gian hiện tại, thời tiết).
- Cần thay thế hoàn toàn system prompt.
- bootstrapMaxChars / bootstrapTotalMaxChars (Mục Cấu hình)
Loại: Mục cấu hình (không phải hook)
Khả năng:
- Kiểm soát hạn mức ký tự.
- Mặc định cho một tệp: 20K.
- Mặc định tổng cộng: 150K.
- Phần vượt quá sẽ bị cắt bớt bằng cách lấy 70% đầu + 20% cuối.
Vị trí Cấu hình:
{
"agents": {
"defaults": {
"bootstrapMaxChars": 20000,
"bootstrapTotalMaxChars": 150000
}
}
}
Lời khuyên Thực tế
Tình huống 1: Tôi muốn thêm tài liệu dự án
Giải pháp Khuyến nghị: bootstrap-extra-files
{
"hooks": {
"bootstrap-extra-files": {
"enabled": true,
"paths": ["docs/API.md", "docs/ARCHITECTURE.md"]
}
}
}
Tình huống 2: Tôi muốn tải tệp động dựa trên loại nhiệm vụ
Giải pháp Khuyến nghị: Custom agent:bootstrap Hook
registerInternalHook("agent:bootstrap", (event) => {
const context = event.context as AgentBootstrapHookContext;
const sessionKey = context.sessionKey;
// Tải các tệp khác nhau dựa trên loại phiên
if (sessionKey.includes("coding")) {
context.bootstrapFiles.push({
path: "CODING_GUIDELINES.md",
content: fs.readFileSync("...").toString()
});
}
});
Tình huống 3: Tôi muốn chèn ngữ cảnh thời gian thực (như thời gian hiện tại)
Giải pháp Khuyến nghị: before_prompt_build Hook
on("before_prompt_build", (event, ctx) => {
return {
prependContext: Thời gian hiện tại: ${new Date().toISOString()}
};
});
Lớp 9: Ngữ cảnh Đầu vào
Phép loại suy
Giống như "Thông tin Giao thông Thời gian thực"—tự động chèn thông tin ngữ cảnh của cuộc trò chuyện hiện tại với mỗi yêu cầu.
Sự đánh đổi trong thiết kế
Tại sao lại chèn ngữ cảnh mỗi lần?
- Sự đánh đổi: Tiêu thụ Token vs. Tính mạch lạc của Cuộc trò chuyện
- Quyết định: Chèn siêu dữ liệu tin nhắn mới nhất, thông tin người gửi và lịch sử trò chuyện với mỗi yêu cầu.
- Lợi ích: LLM biết ai đang nói hiện tại (tránh nhầm lẫn người gửi). LLM biết lịch sử trò chuyện (duy trì tính mạch lạc của ngữ cảnh). LLM biết liệu nó có được @đề cập hay không (quyết định có trả lời hay không).
- Chi phí: Tiêu thụ khoảng ~3KB token cho mỗi yêu cầu. Lịch sử trò chuyện có thể chứa nhiễu.
Các thành phần
Quy trình Tổng hợp System Prompt Hoàn chỉnh
Tổng kết các Lớp Người dùng Có thể Kiểm soát
OpenClaw cung cấp 3 loại cơ chế có thể kiểm soát bởi người dùng:
- Lớp 7 (Workspace Files) - Các tệp cấu hình tĩnh. Tình huống: Định nghĩa danh tính Agent, đặc tả công việc, bộ nhớ. Ưu điểm: Đơn giản, trực quan, dễ quản lý phiên bản. Nhược điểm: Không thể điều chỉnh động.
- Lớp 8 (Bootstrap Hook System) - Các script chèn động. Tình huống: Chèn nội dung dựa trên ngữ cảnh, thực thi lệnh, đọc tệp bên ngoài. Ưu điểm: Linh hoạt, mạnh mẽ, hỗ trợ logic và lệnh. Nhược điểm: Yêu cầu học hệ thống Hook; lỗi script gây ra sự cố.
- Kiểm soát Gián tiếp Lớp 9 (Ngữ cảnh Đầu vào) - Ảnh hưởng đến ngữ cảnh bằng cách gửi tin nhắn. Tình huống: Ảnh hưởng đến hành vi LLM qua lịch sử trò chuyện hoặc tin nhắn trích dẫn. Ưu điểm: Không cần cấu hình, tương tác tự nhiên. Nhược điểm: Không thể kiểm soát chính xác.
Bảng So sánh Kích thước
⚠️
Lưu ý: Dữ liệu dưới đây là ước tính; kích thước thực tế thay đổi tùy theo cấu hình và ngữ cảnh thời gian chạy. Các lớp framework (Lớp 1-6 + 9) về mặt lý thuyết phải giống nhau nhưng có thể khác nhau một chút do định nghĩa công cụ, Kỹ năng được tải, v.v.
Ghi chú:
- Lớp 7 và Lớp 8 có thể kiểm soát bởi người dùng; kích thước thay đổi tùy theo cấu hình Agent.
- Các lớp khác được tự động tạo và về mặt lý thuyết là giống nhau trên tất cả các Agent.
- Các phép đo thực tế có thể khác nhau do tính khả dụng của công cụ, tải Kỹ năng và ngữ cảnh thời gian chạy.
Gợi ý Tối ưu hóa
- Tối ưu hóa Phần Người dùng Có thể Kiểm soát (Lớp 7 + 8)
Vì Lớp 7 và 8 do người dùng kiểm soát, đây là các chiến lược tối ưu hóa:
Tối ưu hóa Lớp 7 (Tệp Tĩnh):
✅ Các Chiến lược Tinh gọn Khuyến nghị:
- IDENTITY.md: Giữ framework TELOS cốt lõi, loại bỏ mô tả dư thừa, sử dụng bảng thay vì đoạn văn.
- AGENTS.md: Sử dụng danh sách kiểm tra thay vì đoạn văn dài, hiển thị lệnh trong khối mã, loại bỏ giải thích quy tắc trùng lặp.
- MEMORY.md: Dựa vào xuất tự động của MemOS; không thêm nội dung thủ công—để hệ thống duy trì nó.
❌ Các Thực hành Cần Tránh:
- Đừng lặp lại các mô tả mà framework OpenClaw đã biết.
- Đừng sao chép mô tả Kỹ năng chi tiết vào Workspace Files.
- Đừng sử dụng quá nhiều hùng biện hoặc ngôn ngữ trang trí.
Tối ưu hóa Lớp 8 (Hệ thống Hook):
✅ Các Chiến lược Sử dụng Khuyến nghị:
- Ưu tiên bootstrap-extra-files (các tình huống đơn giản).
- Sử dụng agent:bootstrap khi cần logic có điều kiện (các tình huống phức tạp).
- Sử dụng before_prompt_build cho ngữ cảnh thời gian thực (các tình huống động).
❌ Các Thực hành Cần Tránh:
- Không thực thi các thao tác tốn thời gian trong Hooks (chặn tạo System Prompt).
- Không chèn quá nhiều nội dung trong Hooks (vượt quá giới hạn token).
- Không sử dụng các phụ thuộc bên ngoài không ổn định trong Hooks (gây lỗi khởi động).
- Chiến lược Cắt giảm Prompt
Nếu System Prompt quá lớn, hãy cân nhắc:
Kết luận
System Prompt của OpenClaw không phải là một tệp duy nhất, mà là một kiến trúc 9 lớp được dàn dựng cẩn thận:
- Lớp 1-6: Được tạo tự động bởi framework, đảm bảo tính nhất quán và ổn định.
- Lớp 7: Các tệp cấu hình tĩnh có thể chỉnh sửa bởi người dùng (IDENTITY.md, AGENTS.md, v.v.).
- Lớp 8: Các script chèn động có thể lập trình bởi người dùng (Bootstrap Hook System).
- Lớp 9: Ngữ cảnh thời gian thực được framework tự động chèn (Ngữ cảnh Đầu vào).
Có 2 lớp người dùng có thể kiểm soát (Lớp 7 + 8), không chỉ là Lớp 7 như đã nói sai trước đây.
Hiểu được sự khác biệt và kết nối giữa các lớp này là chìa khóa để làm chủ cấu hình OpenClaw.
