Introduction
Current AI assistant services on the market often operate like “black boxes,” where users cannot know how their personal data is stored and used, nor can they easily customize or extend their functionalities. To address this lack of transparency and control, an open-source project called AgentClaw has emerged. This project aims to provide a lightweight, fully local AI Agent framework that allows users to control the AI’s memory, personality, and skills through simple text files, achieving true data sovereignty.
Architecture Breakdown: A Modular “Brain” Based on the File System
AgentClaw’s core design philosophy is to make the AI Agent’s “brain” transparent. Its architecture is divided into three layers: an optional Next.js frontend, a FastAPI backend as the core service, and a LangChain Agent runtime responsible for task execution.
Its most distinctive feature is the composition of the System Prompt. Each time a user interacts with the Agent, the backend dynamically integrates six Markdown files from the local file system to construct a complete System Prompt. This design makes the Agent’s core configuration intuitive and easy to modify.
These six files define different aspects of the Agent:
- SKILLS_SNAPSHOT.md: An auto-generated list of skills that informs the Agent of its capabilities.
- SOUL.md: Sets the Agent’s personality, tone, and core traits.
- IDENTITY.md: Defines the Agent’s self-awareness, including its operating environment and file paths.
- USER.md: Stores user background information and preferences to help the Agent provide personalized services.
- AGENTS.md: Specifies the Agent’s code of conduct and protocols, such as rules for skill invocation and memory updates.
- MEMORY.md: Serves as the Agent’s long-term memory, recording key information from conversations.
By directly editing these Markdown files, users can precisely control the Agent’s behavior patterns and knowledge boundaries, completely breaking free from blind reliance on cloud services.
Three-Tier Loading Mechanism: An Extensible Skill System
To address the difficulties of extending skills in traditional Agents and the high consumption of the Context Window, AgentClaw adopts an innovative “three-tier loading” skill mechanism. Under this system, skills are no longer hard-coded backend functions but exist as “manuals” (SKILL.md) in separate folders.
The mechanism works as follows:
- Tier 1 Loading: On startup, the system scans all skill folders, extracting only the skill names and brief descriptions to generate
SKILLS_SNAPSHOT.md. This is injected into the System Prompt at a very low Token cost.
- Tier 2 Loading: When the Agent determines a user request requires a specific skill, it first calls the built-in
read_file tool to read the corresponding skill’s SKILL.md file. This allows it to understand the specific execution steps and required parameters.
- Tier 3 Loading: Following the instructions in
SKILL.md, the Agent calls the underlying core tools (like fetch_url or terminal) to complete the task.
For example, to query the weather, the Agent first locates the get_weather skill through the skills snapshot, then reads its SKILL.md file, and finally calls the fetch_url tool with the URL format specified in the file to retrieve the data. This design allows new skills to be added simply by creating a new folder and a Markdown document, without modifying or restarting the core backend code, achieving true hot-swappable functionality.
Core Toolset and Security Considerations
AgentClaw comes with four built-in core tools that provide underlying support for all skills, while also incorporating necessary security measures.
read_file: As the “eyes” of the skill system, this tool is strictly restricted to preset directories like skills, workspace, and memory. It uses path validation to prevent potential directory traversal attacks, ensuring the security of the local file system.fetch_url: Used to access web resources. It integrates the html2text library to automatically convert fetched HTML content into a more concise Markdown format, which can save up to 70% on Token consumption, improving information processing efficiency and cost-effectiveness.terminal: Grants the Agent the ability to execute Shell commands, but it is also the riskiest tool. To mitigate this, the system has a built-in blacklist of high-risk commands (e.g., rm -rf, sudo) for initial blocking. In a production environment, it is strongly recommended to run the Agent inside a sandboxed container like Docker for more thorough isolation.python_repl: Provides a Python code execution environment, suitable for data computation, processing, and analysis tasks. It also shares the necessity of being run in an isolated environment.
Practice and Outlook
To deploy AgentClaw from scratch, developers need to set up a Python 3.10+ environment, install dependencies like FastAPI and LangChain, and configure the API keys for a large language model (such as DeepSeek, Claude 3.5 Sonnet, or the GPT series). The crucial step is to correctly initialize AGENTS.md, clearly defining the skill invocation protocol and forcing the Agent to “read the manual before acting.” This is the core constraint for ensuring successful execution of complex tasks.
The Agent’s operational status is pushed to the frontend in real-time via FastAPI’s Server-Sent Events (SSE) interface. This allows developers to clearly observe every tool call (tool_start, tool_end) and the model’s thought process, achieving end-to-end transparent tracking.
Currently, the project has established a solid backend foundation. Future development directions include:
- Frontend Interface: Developing a Next.js-based chat interface for visual interaction, memory editing, and skill management.
- Knowledge Base Integration (RAG): Using tools like LlamaIndex to enable the Agent to retrieve from local document libraries, turning it into a true personal knowledge assistant.
- Browser Automation: Integrating tools like Playwright to allow the Agent to operate a browser for complex tasks such as filling out online forms and scraping data.
- Session Persistence: Saving the in-memory conversation history to local files to achieve memory retention across sessions.
