ZClaw 🦞

The Engineering-First Headless Agent Framework: CLI, SDK, and Server. Stable, Scalable Automation for the Post-Vision Era.

🔗 GitHub Repository: https://github.com/hashangit/zclaw

ZClaw 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, ZClaw 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 ZClaw?

• 🐳 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).
• 📦 SDK & Server: TypeScript SDK for programmatic use, standalone HTTP/WebSocket server for remote access.
• 🛠 Skills System: Loadable skill packs with file references, custom tool registration, and extensible workflows.

Features

• 🤖 Multi-Provider Support: Switch between OpenAI, Anthropic Claude, GLM, or any OpenAI-compatible endpoint
• 🔄 Runtime Provider Switching: Change AI providers mid-conversation with /models command
• 📜 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.
• 📦 TypeScript SDK: Programmatic access via createAgent, createUseChat (React hook), streamText, generateText.
• 🖥 Server Mode: Standalone HTTP/WebSocket server with API key auth and session management.
• 🛠 Skills System: Loadable skill packs from directories with @path file references and custom tool creation.
• 🐚 Shell Approval: Interactive prompts or non-interactive modes via ZCLAW_SHELL_APPROVE env var.

Tech Stack

• Runtime: Node.js
• Language: TypeScript
• Architecture: Modular multi-adapter (core, CLI, SDK, server)
• Framework: Commander.js
• UI: Inquirer (interactivity), Chalk (styling), Ora (spinners)
• AI: Multi-Provider (OpenAI, Anthropic Claude, GLM, OpenAI-Compatible)

Installation

npm

npm install -g zclaw-core

pnpm

pnpm add -g zclaw-core

Homebrew (macOS & Linux)

brew tap hashangit/zclaw
brew install zclaw

Note: Requires Node.js 20 or later.

Server Binary

The zclaw-server binary is included for running the standalone HTTP/WebSocket server:

zclaw-server --port 7337 --generate-api-key

SDK Usage

Import the SDK in your TypeScript/JavaScript project:

npm install zclaw-core

// Main exports
import { createAgent, streamText, generateText } from 'zclaw-core';
// React hook
import { useAgent } from 'zclaw-core/react';
// Server utilities
import { createServer } from 'zclaw-core/server';

Development Installation

1. Clone the repository:

   git clone https://github.com/hashangit/zclaw.git
   cd zclaw

2. Install dependencies:

   pnpm install

3. Build the project:

   pnpm run build

4. Link globally (optional):

   pnpm link

Quick Start

1. Setup: Run the interactive setup wizard to configure your API keys and integrations.

   zclaw setup

   The wizard now supports configuring multiple providers (OpenAI, Anthropic, GLM) in a single session.

2. Run: Start the agent in interactive mode.

   zclaw

Usage

Interactive Mode

Simply run zclaw to enter the chat loop.

zclaw
> List all TypeScript files in the src folder.

Headless Mode (One-Shot)

Run a single command and exit.

zclaw "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).

zclaw "Refactor src/index.ts to use ES modules" -y

Provider Selection

Use a specific provider for a single command:

zclaw -p anthropic "Analyze this code for security issues"

Switch Providers Mid-Conversation

In interactive mode, type /models to switch between configured providers:

zclaw
> /models  # Select Anthropic from the list
> Now analyze this with Claude...

CLI Options

• -m, --model <model>: Specify the LLM model (default: gpt-4o).
• -p, --provider <provider>: Specify the LLM provider (openai-compatible, openai, anthropic, glm).
• -n, --no-interactive: Exit after processing the initial query (Headless mode).
• -y, --yes: Auto-confirm all tool executions (e.g., shell commands).
• --docker: Run in Docker-optimized non-interactive mode (auto-detected in containers).
• --generate-api-key: Generate an API key for server mode (use with zclaw-server).

Interactive Commands

• /models: Switch between configured providers during a conversation.
• /exit or /quit: End the session.

Configuration

ZClaw uses a hierarchical configuration system.

Priority Order (Highest to Lowest):

1. CLI Arguments: (e.g., -m gpt-4o)
2. Environment Variables: (OPENAI_API_KEY, .env file)
3. Project Config: (./.zclaw/setting.json in current directory)
4. Global Config: (~/.zclaw/setting.json)

Supported Configuration Keys (JSON)

Environment Variables:

• ZCLAW_SHELL_APPROVE: Shell command approval mode (auto, deny, or unset for interactive)
• ZCLAW_SKILLS_PATH: Directory containing custom skill packs
• OPENAI_API_KEY, ANTHROPIC_API_KEY, GLM_API_KEY: Provider API keys
• OPENAI_COMPAT_API_KEY, OPENAI_COMPAT_BASE_URL, OPENAI_COMPAT_MODEL: OpenAI-compatible provider settings

Multi-Provider Configuration:

• provider: Active provider type (openai-compatible, openai, anthropic, glm)
• models: Object containing per-provider configurations:

  {
    "models": {
      "openai-compatible": { "apiKey": "...", "baseUrl": "...", "model": "gpt-4o" },
      "openai": { "apiKey": "...", "model": "gpt-4o" },
      "anthropic": { "apiKey": "...", "model": "claude-sonnet-4-5-20250929" },
      "glm": { "apiKey": "...", "model": "sonnet" }
    }
  }

Legacy Keys (Backward Compatible):

• apiKey: Your OpenAI API Key (legacy, treated as openai-compatible).
• 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

Multi-Provider Configuration:

{
  "provider": "anthropic",
  "models": {
    "openai": { "apiKey": "sk-...", "model": "gpt-4o" },
    "anthropic": { "apiKey": "sk-ant-...", "model": "claude-sonnet-4-5-20250929" }
  }
}

Legacy Configuration (Still Supported): Create a file at .zclaw/setting.json:

{
  "model": "gpt-3.5-turbo",
  "baseUrl": "https://api.deepseek.com/v1"
}

⚠️ Security Warning: If you store your apiKey or secrets in .zclaw/setting.json, make sure to add .zclaw/ to your .gitignore file to prevent leaking secrets!

Integrations

Multi-Provider LLM Support

ZClaw supports multiple AI providers with seamless switching:

• OpenAI: GPT-4, GPT-3.5-turbo, and latest models
• Anthropic: Claude Sonnet, Haiku, Opus models
• GLM: Z.ai GLM-4.5, GLM-4.7, GLM-5.1 models
• OpenAI-Compatible: DeepSeek, LocalLLM, Ollama, LM Studio, and any OpenAI-compatible endpoint

Configure multiple providers during setup and switch between them using /models command or -p flag.

Web Search (Tavily)

ZClaw 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 [email protected] 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."

SDK & Programmatic Usage

ZClaw provides a TypeScript SDK for building agent-powered applications.

Basic Agent

import { createAgent } from 'zclaw-core';

const agent = await createAgent({
  provider: 'anthropic',
  model: 'claude-sonnet-4-5-20250929',
});

const result = await agent.chat('List all running Docker containers');
console.log(result.text);

Streaming

import { streamText } from 'zclaw-core';

const stream = await streamText('Analyze the logs for errors', {
  provider: 'openai',
});

for await (const chunk of stream.textStream) {
  process.stdout.write(chunk);
}

Structured Output

import { generateText } from 'zclaw-core';

const result = await generateText('Extract the top 3 issues from these logs', {
  provider: 'anthropic',
});
console.log(result.text);

React Hook

import { createUseChat } from 'zclaw-core/react';

const useChat = await createUseChat();

function AgentPanel() {
  const { messages, input, setInput, handleSubmit, isLoading } = useChat({
    api: '/api/chat',
  });

  return (
    <form onSubmit={handleSubmit}>
      <input value={input} onChange={(e) => setInput(e.target.value)} />
      <button type="submit" disabled={isLoading}>
        {isLoading ? 'Thinking...' : 'Send'}
      </button>
    </form>
  );
}

Custom Tools

import { createAgent, tool } from 'zclaw-core';

const agent = await createAgent({
  provider: 'openai',
  tools: [
    tool({
      name: 'check_disk',
      description: 'Check disk usage',
      parameters: {},
      execute: async () => {
        const usage = await getDiskUsage();
        return JSON.stringify(usage);
      },
    }),
  ],
});

Session Persistence

const agent = await createAgent({
  provider: 'anthropic',
  persist: 'my-session',          // Resume a previous session
});

Server Mode

Run ZClaw as a standalone HTTP/WebSocket server for remote agent access.

Starting the Server

# Start with default settings
zclaw-server

# Generate an API key
zclaw-server --generate-api-key

# Custom port
zclaw-server --port 8080

REST API

# Send a prompt
curl -X POST http://localhost:7337/api/chat \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "Check disk usage", "provider": "openai"}'

# List sessions
curl http://localhost:7337/api/sessions \
  -H "Authorization: Bearer YOUR_API_KEY"

WebSocket Streaming

const ws = new WebSocket('ws://localhost:7337/ws?token=YOUR_API_KEY');

ws.onopen = () => {
  ws.send(JSON.stringify({
    type: 'chat',
    message: 'Analyze the error logs',
    provider: 'anthropic',
  }));
};

ws.onmessage = (event) => {
  const chunk = JSON.parse(event.data);
  process.stdout.write(chunk.text);
};

Skills System

Skills are loadable packs that extend the agent with domain-specific tools and prompts.

Using Skills

# Built-in skills are loaded automatically
zclaw "Deploy the app to production"    # Uses docker-ops, k8s-deploy skills
zclaw "Analyze the nginx logs"          # Uses log-analyzer skill

Built-in Skills

• docker-ops: Docker container management and deployment
• k8s-deploy: Kubernetes deployment and orchestration
• log-analyzer: Log parsing, filtering, and anomaly detection

Custom Skills

Create a skill directory with a manifest and tool definitions:

my-skills/
  custom-deploy/
    skill.json          # Skill manifest
    instructions.md     # System prompt extension
    tools/              # Tool definitions
      deploy.ts

Configure the skills path:

export ZCLAW_SKILLS_PATH=/path/to/my-skills

@path File References

Skills can reference files using @path syntax in their instructions:

Read the deployment config at @path:./k8s/deployment.yaml and validate it.

Docker Support

ZClaw includes a production-ready Dockerfile (Node 20 Alpine) and docker-compose.yml for containerized deployment.

Quick Start with Docker

# Clone and build
git clone https://github.com/hashangit/zclaw.git
cd zclaw
docker build -t zclaw-server .

# Run the server
docker run -d -p 7337:7337 \
  -e OPENAI_API_KEY=sk-... \
  zclaw-server

# Or use Docker Compose
docker compose up -d

Docker-Optimized CLI Mode

Use --docker for non-interactive execution inside containers:

docker run --rm \
  -e OPENAI_API_KEY=sk-... \
  -e ZCLAW_SHELL_APPROVE=auto \
  zclaw-server zclaw "Check disk usage" --docker

ZClaw auto-detects Docker and non-interactive environments. When running in a container, it adjusts behavior accordingly (no interactive prompts, streamlined output).

Shell Approval in Containers

Set ZCLAW_SHELL_APPROVE to control how shell commands are approved without interactive prompts:

• auto: Automatically approve all commands (use in trusted/sandboxed environments)
• deny: Deny all shell command execution
• (unset): Interactive prompt (default, requires a TTY)

# docker-compose.yml example
services:
  zclaw:
    build: .
    ports:
      - "7337:7337"
    environment:
      - OPENAI_API_KEY=${OPENAI_API_KEY}
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
      - ZCLAW_SHELL_APPROVE=auto
      - ZCLAW_SKILLS_PATH=/app/skills

Non-Latin Font Issues in Screenshots

When running ZClaw inside a Docker container (especially Alpine or Debian Slim), screenshots of websites with non-Latin text (e.g., CJK characters) 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.

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

GitHub: https://github.com/hashangit/zclaw

Acknowledgments

ZClaw is a standalone project forked from the original AutoClaw project by tsingliuwin under the MIT License on March 31st, 2026.

We would like to express our sincere gratitude to tsingliuwin and all the contributors of the original AutoClaw project for their exceptional work and vision, which served as the foundation for this repository.