7.2 KiB
AutoClaw 🦞
The Engineering-First Headless Agent Framework: Stable, Scalable Automation for the Post-Vision Era.
English | 简体中文
🔗 GitHub Repository: https://github.com/tsingliuwin/autoclaw
AutoClaw is a high-stability, open-source automation framework specifically engineered for headless systems.
Unlike "screen-seeing" agents (such as OpenClaw) that rely on visual interpretation, AutoClaw is built on a foundation of precise command-driven execution. This makes it significantly more stable, robust from an engineering perspective, and easier to scale across complex environments—whether it's a local server, a CI/CD pipeline, or thousands of containerized nodes.
Why AutoClaw?
- 🐳 Docker Native: Built to run safely inside containers. Minimal footprint (Node.js/Alpine friendly).
- 🚀 Better Engineering: Operates via precise system APIs and shell commands rather than unstable visual recognition, ensuring deterministic outcomes.
- 🛡️ Superior Stability: Immune to issues like UI rendering, screen resolution, or network lag that plague vision-based agents.
- 📈 Massive Scalability: Low resource consumption allows orchestrating thousands of instances (e.g., in K8s) for true automation swarms.
- 🔌 Swarm Ready: Stateless design allows for easy orchestration via K8s, Docker Swarm, or simple shell loops.
- 🧩 Extensible Integrations: Built-in support for Web Search (Tavily), Email (SMTP), and Notification Webhooks (Feishu, DingTalk, WeCom).
Features
- 📜 Headless Execution: No browsers, no GUIs. Pure terminal efficiency.
- 🤖 Non-Interactive Mode: Intelligent flag handling (
-y,--no-interactive) for zero-touch automation. - 📂 Universal Control: From simple file I/O to complex system administration.
- 🧠 Context Aware: Detects container environments and provides accurate system time for relative date queries.
- 🌐 Web Search: Integrated with Tavily for real-time information retrieval.
- 🕒 Time Accuracy: Built-in tool to get precise system date and time for correct temporal context.
- 📧 Communication: Send emails and push notifications to chat groups automatically.
Tech Stack
- Runtime: Node.js
- Language: TypeScript
- Framework: Commander.js
- UI: Inquirer (interactivity), Chalk (styling), Ora (spinners)
- AI: OpenAI SDK (Compatible with DeepSeek, LocalLLM, etc.)
Installation
User Installation
Install globally via npm:
npm install -g autoclaw
Development Installation
- Clone the repository:
git clone https://github.com/tsingliuwin/autoclaw.git cd autoclaw - Install dependencies:
npm install - Build the project:
npm run build - Link globally (optional):
npm link
Quick Start
- Setup: Run the interactive setup wizard to configure your API keys and integrations.
autoclaw setup - Run: Start the agent in interactive mode.
autoclaw
Usage
Interactive Mode
Simply run autoclaw to enter the chat loop.
autoclaw
> List all TypeScript files in the src folder.
Headless Mode (One-Shot)
Run a single command and exit.
autoclaw "Check disk usage and save the report to usage.txt" --no-interactive
Auto-Confirm (CI/CD)
Automatically approve all tool executions (dangerous, use with caution or in sandboxes).
autoclaw "Refactor src/index.ts to use ES modules" -y
CLI Options
-m, --model <model>: Specify the LLM model (default:gpt-4o).-n, --no-interactive: Exit after processing the initial query (Headless mode).-y, --yes: Auto-confirm all tool executions (e.g., shell commands).
Configuration
AutoClaw uses a hierarchical configuration system.
Priority Order (Highest to Lowest):
- CLI Arguments: (e.g.,
-m gpt-4o) - Environment Variables: (
OPENAI_API_KEY,.envfile) - Project Config: (
./.autoclaw/setting.jsonin current directory) - Global Config: (
~/.autoclaw/setting.json)
Supported Configuration Keys (JSON)
apiKey: Your OpenAI API Key.baseUrl: Custom Base URL (e.g., for DeepSeek or LocalLLM).model: Default model to use.tavilyApiKey: API Key for Tavily Web Search.smtpHost,smtpPort,smtpUser,smtpPass,smtpFrom: SMTP Email settings.feishuWebhook,dingtalkWebhook,wecomWebhook: Notification webhooks.
Project-Level Config Example
Create a file at .autoclaw/setting.json:
{
"model": "gpt-3.5-turbo",
"baseUrl": "https://api.deepseek.com/v1"
}
⚠️ Security Warning: If you store your
apiKeyor secrets in.autoclaw/setting.json, make sure to add.autoclaw/to your.gitignorefile to prevent leaking secrets!
Integrations
Web Search (Tavily)
AutoClaw can search the web if you provide a Tavily API Key during setup or in config.
- Usage: "Search for the latest Node.js release notes."
Email (SMTP)
Configure SMTP settings to let the agent send emails.
- Usage: "Send an email to user@example.com with the summary of the log file."
Notifications (Feishu/DingTalk/WeCom)
Configure webhooks to receive alerts or reports in your team chat apps.
- Usage: "Notify the team on Feishu that the build has finished."
Date & Time
Built-in utility to provide the agent with the current system time, ensuring accurate handling of relative time requests.
- Usage: "What's the date today?" or "Remind me to check the logs next Monday."
Docker Support
Chinese Font Issues in Screenshots
When running AutoClaw inside a Docker container (especially Alpine or Debian Slim), screenshots of Chinese websites may display text as square boxes ("tofu") due to missing fonts. Emojis (e.g., 🔥) may also appear as squares.
Solution: Install CJK (Chinese/Japanese/Korean) and Emoji fonts in your container.
For Debian/Ubuntu:
apt-get update && apt-get install -y fonts-noto-cjk fonts-wqy-zenhei fonts-noto-color-emoji
For Alpine Linux:
apk add font-noto-cjk font-noto-emoji
License
MIT
Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
- Fork the Project
- Create your Feature Branch (
git checkout -b feature/AmazingFeature) - Commit your Changes (
git commit -m 'Add some AmazingFeature') - Push to the Branch (
git push origin feature/AmazingFeature) - Open a Pull Request