phpClaw, PHP 앱에 도구와 보안 갖춘 AI 에이전트 런타임 제공

Hacker News그저께조회 1

PHP 생태계에 AI 에이전트 실행 환경을 붙이려는 오픈소스 프로젝트 phpClaw가 공개됐다. MIT 라이선스로 배포되며, 핵심 코어는 특정 프레임워크에 의존하지 않는다. 설치부터 실행까지가 짧다. 컴포저로 패키지를 받고 빌더를 한 번 호출한 뒤 send()에 문장을 넘기면 에이전트가 응답을 돌려준다.

프로바이더 선택은 환경 변수에서 자동으로 이뤄진다. Anthropic, OpenAI, Groq, Gemini, Mistral, DeepSeek, Ollama 순으로 키를 확인해 처음 발견된 것을 쓰고, OpenAI 호환 커스텀 엔드포인트도 선택적으로 지정할 수 있다. 코드를 고치지 않고 provider()와 model()만 바꿔 모델을 갈아끼우는 구조다. 설정 파일이나 별도 프레임워크 학습이 필요 없다는 점을 전면에 내세운다.

에이전트의 실제 작업 능력은 도구 등록에서 나온다. 셸 명령, HTTP 요청, 파일 읽기, 데이터베이스 조회, 코드 검색 같은 도구가 준비돼 있고, 애플리케이션에 필요한 것만 레지스트리에 넣으면 된다. 그러면 에이전트가 추론하고 실행하고 결과를 관찰하는 ReAct 루프를 돌면서 어떤 도구를 어떤 순서로 쓸지 스스로 정한다. 반복 상한은 기본 20회이며, 모델이 필요할 때 load_skill 도구로 스킬을 불러오는 방식도 지원한다.

보안 계층이 기본값으로 켜져 있다는 점이 이 프로젝트의 차별점이다. 프롬프트 인젝션, 개인정보, 코드 인젝션, 유니코드, 호모글리프, 역할 전환, 파괴적 SQL, 메시지 길이를 다루는 8종 가드가 메시지가 프로바이더에 닿기 전에 걸러낸다. 여기에 선택형 레이트 리밋 가드가 더해진다. 도구 실행 결과는 가드 레지스트리 바깥에 있는 ToolOutputGuard가 조건 없이 정화하고, LLM 출력 정화도 기본 활성 상태다.

도구별 방어선도 구체적이다. ShellTool은 허용 목록에 있는 명령만 정확히 일치할 때 실행하고, 위험 명령 차단 목록은 재정의할 수 없게 고정돼 있다. HttpTool은 호스트명 접두사로 한 번 거른 뒤 해석된 IP 주소를 다시 검증해 DNS 리바인딩이나 CGNAT 우회를 막는다. 파일 읽기·쓰기 도구는 지정된 워크스페이스 루트에 가둬지고 .git, .ssh, wp-admin 같은 민감 경로와 자격 증명 파일은 무조건 거부한다.

기존 PHP 생태계와의 접점도 넓다. Laravel, Symfony, WordPress, Drupal, Magento, Joomla, OpenCart, PrestaShop용 어댑터 8종이 각 플랫폼의 관례에 맞춰 붙는다. Laravel은 아티즌, Symfony는 콘솔, WordPress는 WP-CLI, Drupal은 Drush 식으로 CLI 명령이 제공되고, 모든 어댑터가 동일한 3개 테이블 메모리 스키마를 공유한다. 다만 CMS용 어댑터는 해당 플랫폼의 확장 설치 방식 때문에 컴포저가 아닌 릴리스 페이지의 ZIP으로 배포된다.

MCP 지원도 포함된다. 별도 패키지가 기존 도구 레지스트리를 모델 컨텍스트 프로토콜로 노출해, Claude Desktop이나 Claude Code, Cursor 같은 MCP 클라이언트가 등록된 도구를 직접 호출할 수 있다. 도구 자체를 수정할 필요는 없고, 호출 인자에 대해서도 기본 가드가 동작한다.

한 번의 호출로 끝나지 않는 작업을 위한 구성도 갖췄다. 파이프라인은 프롬프트 템플릿, 에이전트, 구조화된 출력, 사용자 정의 콜러블을 재시도와 폴백과 함께 연결한다. 그래프는 노드의 루프와 분기, 사람의 개입을 위한 일시정지와 다른 프로세스에서의 재개, 인라인 또는 워커가 처리하는 팬아웃을 지원한다. 내부적으로는 가드·훅·메모리·프로바이더·스킬 5개의 정적 레지스트리와 루프 전반의 44개 훅으로 조립된다.

배경에는 PHP로 AI 기능을 붙일 때 늘 반복되던 작업이 있다. 프로바이더 HTTP 클라이언트를 붙이고, 도구 호출 루프를 직접 짜고, 프롬프트가 운영 환경에서 버티기를 기대하는 방식이다. phpClaw는 그 주변의 루프와 가드, 메모리, 프레임워크 연결을 미리 조립해 제공하겠다는 접근을 취한다.

주의할 점도 분명하다. 이 프로젝트는 RAG 프레임워크가 아니라고 스스로 선을 긋는다. 임베딩이나 벡터 스토어는 제공하지 않고, LLM에 도구와 메모리, 보안 통제를 쥐여주고 이를 파이프라인으로 엮는 데 초점을 맞춘다. 실행 환경은 ext-curl, ext-json, ext-mbstring 확장을 요구하며, 스트리밍과 도구 호출을 함께 쓰거나 프롬프트 캐싱, 확장 사고 같은 기능을 활용하려면 해당 프로바이더의 지원 범위를 확인해야 한다.