autoclaw

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, .env file)
• Project Config: (./.autoclaw/setting.json in 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 apiKey or secrets in .autoclaw/setting.json, make sure to add .autoclaw/ to your .gitignore file 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 [e-mail] 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

GitHub: https://github.com/tsingliuwin/autoclaw