phpClaw: Bộ máy chạy AI agent "chuẩn PHP" cho các ứng dụng thực tế

PHP 8.1+

Với các lập trình viên PHP, việc đưa AI vào ứng dụng lâu nay thường dừng ở mức "gọi API rồi tự viết vòng lặp". phpClaw xuất hiện để lấp khoảng trống đó: một runtime AI agent đầy đủ, xử lý sẵn vòng lặp ReAct, công cụ, bộ nhớ, bảo mật và phần kết nối framework. Dự án vừa được giới thiệu trên Hacker News và nhanh chóng thu hút sự chú ý của cộng đồng PHP.

Từ một dòng lệnh đến agent đầu tiên

Triết lý của phpClaw là tối giản tối đa. Chỉ cần cài qua Composer, khai báo một biến môi trường chứa API key và gọi send(), bạn đã có một agent hoạt động được.

composer require phpclaw/phpclaw
export ANTHROPIC_API_KEY="sk-ant-..."
$agent = PhpClaw\Claw::builder()->build();
echo $agent->send('Bạn có thể giúp gì cho tôi?')->text;

Builder sẽ tự động dò các biến môi trường theo thứ tự: ANTHROPIC_API_KEY, OPENAI_API_KEY, GROQ_API_KEY, GEMINI_API_KEY, MISTRAL_API_KEY, DEEPSEEK_API_KEY và cuối cùng là OLLAMA_HOST. Không cần file YAML, không phải học thêm framework agent, cũng không bị khóa cứng vào một nhà cung cấp nào.

Công cụ biến agent từ "nói suông" thành "làm thật"

Một agent không có công cụ chỉ có thể trò chuyện. phpClaw cung cấp sẵn các công cụ thiết yếu và cho phép đăng ký thêm theo nhu cầu của ứng dụng: chạy lệnh shell, gọi HTTP, đọc file, truy vấn cơ sở dữ liệu hay tìm kiếm trong mã nguồn.

$agent = Claw::builder()
    ->tools([
        new ShellTool(allowlist: ['ls', 'df', 'tail']),
        new HttpTool(),
        new FileReadTool(),
        new DatabaseQueryTool($pdo),
        new CodeSearchTool(),
    ])
    ->build();

Agent sẽ tự quyết định gọi công cụ nào, theo thứ tự nào, chạy vòng lặp ReAct (suy luận – hành động – quan sát – lặp lại) cho đến khi có câu trả lời hoặc chạm giới hạn số vòng. Cơ chế này hoạt động giống hệt nhau dù công cụ tác động lên shell, cơ sở dữ liệu, API HTTP hay chính mã nguồn của bạn.

Vì sao lại là phpClaw?

Giấy phép MIT

Theo nhóm phát triển, hầu hết hướng dẫn "AI trong PHP" đều kết thúc ở một HTTP client gắn vào API nhà cung cấp, cộng thêm vòng lặp gọi công cụ tự viết và hy vọng prompt sẽ trụ vững trên môi trường production. phpClaw đảm nhận phần runtime phía sau: vòng lặp, lớp bảo vệ, bộ nhớ và phần kết nối framework, tất cả đã được lắp ráp sẵn.

• Vòng lặp ReAct tích hợp sẵn: có giới hạn cứng số vòng lặp (max_iterations, mặc định 20), công cụ và bộ nhớ đều có thể cắm thêm.
• Pipeline và Graph: cho phép nối các bước, có retry và fallback; Graph hỗ trợ rẽ nhánh, tạm dừng chờ con người, resume ở tiến trình khác và fan-out cho worker.
• Linh hoạt nhà cung cấp: 7 nhà cung cấp được tự động nhận diện, kèm hỗ trợ endpoint tương thích OpenAI tùy chỉnh.
• Kiểm soát production: 8 lớp bảo vệ bật mặc định, cùng rate limiting như một guard tùy chọn.
• Trải nghiệm lập trình viên: stream theo từng token, prompt caching và extended thinking của Claude.

Điểm đáng chú ý là dự án không cố trở thành mọi thứ. phpClaw không phải framework RAG: không có embedding hay vector store. Mục tiêu của nó là cung cấp công cụ, bộ nhớ và kiểm soát bảo mật cho LLM gắn với ứng dụng thực tế của bạn.

Bảo mật là ưu tiên hàng đầu

Mọi tin nhắn đều đi qua chuỗi guard mặc định trước khi tới nhà cung cấp. ShellTool chỉ chạy những lệnh nằm trong allowlist (mặc định gồm ls, pwd, df, wc, date, uptime, hostname, whoami), so khớp chính xác và phân biệt hoa thường; một blocklist cố định các lệnh nguy hiểm được kiểm tra trước tiên và không thể ghi đè.

HttpTool chặn theo tiền tố hostname rồi kiểm tra lại từng địa chỉ IP đã phân giải, qua đó bịt lỗ hổng DNS-rebinding mà cách chặn theo tên miền đơn thuần bỏ sót. FileReadTool và FileWriteTool bị giới hạn trong thư mục workspace đã cấu hình, từ chối tuyệt đối các đường dẫn nhạy cảm như thông tin xác thực, khóa bí mật hay thư mục .git, .ssh, wp-admin.

Mọi thay đổi về phần lõi đều được khuyến nghị kiểm thử qua adapter. Bộ test dùng mock và stub cho HTTP client, Redis và hệ thống file, nên không cần kết nối mạng hay API key để chạy.

Hệ sinh thái adapter cho framework và CMS

phpClaw có 8 adapter chính thức, mỗi adapter kết nối theo đúng phong cách của nền tảng chủ nhà: Eloquent với Laravel, Doctrine với Symfony, WP-CLI với WordPress, Drush với Drupal, cùng các adapter cho Magento, Joomla, OpenCart và PrestaShop. Mọi adapter đều có giao diện chat admin hoặc CLI, và dùng chung một schema bộ nhớ gồm 3 bảng.

php artisan phpclaw "deploy staging và thông báo #ops"        # Laravel
bin/console phpclaw "kiểm tra mọi kết nối database"          # Symfony
drush phpclaw:run "liệt kê người dùng hoạt động gần đây"      # Drupal
wp phpclaw send "tóm tắt bài viết hôm nay"                    # WordPress

Riêng các adapter CMS được phân phối qua file ZIP trong mục Releases thay vì Composer, vì đó là cách các nền tảng đó cài đặt tiện ích mở rộng.

Gói kèm MCP Server

Package phpclaw/phpclaw-mcp đưa ToolRegistry hiện có của bạn lên Model Context Protocol, cho phép Claude Desktop, Claude Code, Cursor hoặc bất kỳ client tương thích MCP nào gọi trực tiếp công cụ của bạn, với các guard mặc định quét tham số của mọi lần gọi công cụ. Bản thân các công cụ không cần thay đổi gì.

Kiến trúc và khả năng mở rộng

Luồng xử lý đi theo thứ tự: Message → Guards (chặn injection/PII trước khi LLM nhìn thấy) → Hooks (44 sự kiện vòng đời) → Agent (vòng lặp ReAct: nhà cung cấp + công cụ + bộ nhớ + kỹ năng) → AgentResponse (văn bản, token, lời gọi công cụ, thời gian xử lý).

Năm registry tĩnh (GuardRegistry, HookRegistry, MemoryRegistry, ProviderRegistry, SkillRegistry) cùng ToolRegistry theo từng agent cho phép mở rộng mọi thành phần. Chỉ cần thả một class vào thư mục tương ứng của package lõi kèm attribute phù hợp, chạy composer dump-autoload là thành phần đó có hiệu lực.

Điều kiện và giấy phép

phpClaw yêu cầu PHP 8.1 đến 8.4, cùng các extension ext-curl, ext-json, ext-mbstring cho phần lõi. Dự án phát hành theo giấy phép MIT, không có tính năng nào bị khóa sau bản trả phí. Với các đội phát triển PHP đang muốn đưa AI agent vào sản phẩm thật một cách có kiểm soát, đây là lựa chọn đáng để thử nghiệm ngay.

Tổng lượt tải