DEV Community

steven x
steven x

Posted on

FastClaw 5-Minute Quick Start: From Installation to Your First Task

#ai #openclaw #fastclaw #agents

FastClaw is a lightweight Python AI Agent assistant built on the FastMind framework. This guide will take you from zero to hero in 5 minutes, covering installation, configuration, and your first task.

Prerequisites

  • Python 3.10+
  • pip package manager
  • An OpenAI-compatible API Key (DeepSeek recommended)

Step 1: Install FastClaw

Method 1: Clone from GitHub (Recommended) 

# Clone the project
git clone https://github.com/kandada/fastclaw.git
cd fastclaw

# Create virtual environment (optional but recommended)
python -m venv .venv
source .venv/bin/activate  # Linux/Mac
# or .venv\Scripts\activate  # Windows

# Install dependencies
pip install -r requirements.txt
Enter fullscreen mode Exit fullscreen mode

Method 2: Quick Install Script 

# One-line installation script
curl -sSL https://raw.githubusercontent.com/kandada/fastclaw/main/install.sh | bash
Enter fullscreen mode Exit fullscreen mode

Step 2: Configure LLM API

FastClaw supports all OpenAI-compatible APIs. We'll use DeepSeek as an example:

Get API Key

  1. Visit DeepSeek website
  2. Register and log in
  3. Create a new API Key in the API Keys page

Configure FastClaw

Edit the configuration file:

vim workspace/data/agents/main_agent/metadata.json
Enter fullscreen mode Exit fullscreen mode

Modify the content to:

{
  "llm": {
    "api_key": "your_deepseek_api_key_here",
    "base_url": "https://api.deepseek.com/v1",
    "model": "deepseek-chat"
  }
}
Enter fullscreen mode Exit fullscreen mode

Other Supported LLMs

FastClaw supports all OpenAI-compatible interfaces:

  • Kimi: base_url: "https://api.moonshot.cn/v1", model: "kimi-k2.5"
  • Minimax: base_url: "https://api.minimax.chat/v1", model: "MiniMax-M2.7"
  • OpenAI: base_url: "https://api.openai.com/v1", model: "gpt-5.4"
  • Local models: Any locally deployed model supporting OpenAI format

Step 3: Start FastClaw

Start Web Service 

# Start service (default port 8765)
python main.py start

# Or run in background
nohup python main.py start > fastclaw.log 2>&1 &
Enter fullscreen mode Exit fullscreen mode

Verify Service 

# Check service status
curl http://localhost:8765/health

# View logs
tail -f fastclaw.log
Enter fullscreen mode Exit fullscreen mode

After service starts, open http://localhost:8765 to access the Web UI.

Step 4: Using Web UI

Interface Overview

FastClaw Web UI has three main tabs:

  1. Chat: Interactive chat interface
  2. Cron: Scheduled task management
  3. Settings: System settings

First Conversation

  1. Open http://localhost:8765
  2. Type a message in the Chat page input box
  3. Press Enter to send, Shift+Enter for new line

Example Conversation:

You: Hello, FastClaw!
FastClaw: Hello! I'm FastClaw, your AI assistant. I can help you execute commands, manage files, and automate tasks. How can I assist you today?

You: Show files in current directory
FastClaw: Executing run_shell("ls -la")
(Shows current directory file list)
Enter fullscreen mode Exit fullscreen mode

Step 5: Basic Functionality Experience

1. File Operations 

You: Show README.md file content
FastClaw: Executing run_shell("cat README.md")

You: Create test.txt file in current directory
FastClaw: Executing run_shell("echo 'Test content' > test.txt")
Enter fullscreen mode Exit fullscreen mode

2. System Information 

You: Check system memory usage
FastClaw: Executing run_shell("free -h")

You: Check disk space
FastClaw: Executing run_shell("df -h")
Enter fullscreen mode Exit fullscreen mode

3. Network Requests 

You: Get current time
FastClaw: Executing run_shell("date")

You: Query weather (requires network)
FastClaw: Executing run_shell("curl wttr.in/London?format=3")
Enter fullscreen mode Exit fullscreen mode

Step 6: Using Skills System

View Available Skills 

You: What skills are available?
FastClaw: Executing run_skills("__list__")
Enter fullscreen mode Exit fullscreen mode

Use Built-in Skills 

You: Get current time
FastClaw: Executing run_skills("current_time")

You: Send Feishu message
FastClaw: Executing run_skills("feishu", {"message": "Test message"})
Enter fullscreen mode Exit fullscreen mode

Step 7: Create Scheduled Tasks

Create via Web UI

  1. Switch to Cron tab
  2. Click "New Task"
  3. Fill task information:
    • Name: Daily Report
    • Cron Expression: 0 9 * * * (9 AM daily)
    • Agent: main_agent
    • Command: Generate today's work report
  4. Click Save

Create via Configuration File

Edit workspace/data/cron/tasks.json:

{
  "tasks": [
    {
      "name": "Daily Report",
      "cron": "0 9 * * *",
      "agent": "main_agent",
      "session_id": "daily_report",
      "command": "Generate today's work report and save to file",
      "enabled": true
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

Cron Expression Examples

Expression Meaning
*/5 * * * * Every 5 minutes
0 * * * * Every hour
0 9 * * * Daily at 9 AM
0 9 * * 1-5 Weekdays at 9 AM
0 9,18 * * * Daily at 9 AM and 6 PM

Step 8: Advanced Features Exploration

1. Session Management 

# List all sessions
python main.py session list

# Export session history
python main.py session export default
Enter fullscreen mode Exit fullscreen mode

2. Command Line Interface 

# Start CLI interaction
python main.py chat

# New session
python main.py chat --new

# Specific session
python main.py chat --session-id my_session
Enter fullscreen mode Exit fullscreen mode

3. Skill Development

Create custom skills:

# Create skill directory
mkdir -p workspace/skills/user/my_skill

# Create skill description
cat > workspace/skills/user/my_skill/SKILL.md << EOF
# My Skill

## Description
My custom skill example

## Parameters
- param1: Parameter 1 description
- param2: Parameter 2 description
EOF

# Create skill implementation
cat > workspace/skills/user/my_skill/main.py << EOF
async def execute(param1: str = "", param2: str = "") -> str:
    return f"Skill executed with params: {param1}, {param2}"
EOF
Enter fullscreen mode Exit fullscreen mode

Step 9: Troubleshooting

Common Issues

1. Service Startup Failure 

# Check port usage
lsof -i:8765

# Check dependencies
pip list | grep fastmind

# View detailed logs
python main.py start --verbose
Enter fullscreen mode Exit fullscreen mode

2. API Connection Failure

  • Check if API Key is correct
  • Check network connection
  • Try other LLM providers

3. Permission Issues 

# Check file permissions
ls -la workspace/

# Fix permissions
chmod -R 755 workspace/
Enter fullscreen mode Exit fullscreen mode

Debug Mode 

# Enable debug logging
export FASTCLAW_LOG_LEVEL=DEBUG
python main.py start
Enter fullscreen mode Exit fullscreen mode

Step 10: Production Deployment

Using systemd (Linux) 

# Create service file
sudo cat > /etc/systemd/system/fastclaw.service << EOF
[Unit]
Description=FastClaw AI Assistant
After=network.target

[Service]
Type=simple
User=fastclaw
WorkingDirectory=/opt/fastclaw
ExecStart=/opt/fastclaw/.venv/bin/python main.py start
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
EOF

# Start service
sudo systemctl daemon-reload
sudo systemctl enable fastclaw
sudo systemctl start fastclaw
Enter fullscreen mode Exit fullscreen mode

Using Docker 

FROM python:3.9-slim

WORKDIR /app
COPY . .

RUN pip install -r requirements.txt

EXPOSE 8765
CMD ["python", "main.py", "start"]
Enter fullscreen mode Exit fullscreen mode

Best Practices

1. Security Configuration

  • Use environment variables for API Keys
  • Limit accessible directories
  • Regularly update dependencies

2. Performance Optimization

  • Use lightweight LLM models
  • Set appropriate context length
  • Enable automatic context unloading

3. Backup Strategy 

# Backup configuration and data
tar -czf fastclaw_backup_$(date +%Y%m%d).tar.gz workspace/
Enter fullscreen mode Exit fullscreen mode

Next Steps

Learning Resources

  1. Official Documentation: Project README.md
  2. Code Examples: Core implementation in core/app.py
  3. Community Support: GitHub Issues and Discussions

Advanced Topics

  1. Custom Agents: Create agents with specific personalities
  2. Third-party Integrations: Connect to databases, message queues, etc.
  3. Performance Monitoring: Add monitoring and alerts
  4. Cluster Deployment: Multi-node high-availability deployment

Contribution Guide

  1. Report Issues: GitHub Issues
  2. Submit PRs: Follow code standards
  3. Write Documentation: Help improve documentation
  4. Share Use Cases: Share your experience

Summary

Through this tutorial, you have completed:

  1. ✅ FastClaw installation and configuration
  2. ✅ LLM API setup
  3. ✅ Basic functionality usage
  4. ✅ Scheduled task creation
  5. ✅ Troubleshooting methods

FastClaw's design philosophy is "simple yet powerful." With minimal configuration and intuitive interface, it makes AI Agent technology accessible to everyone. Whether you're a developer, operations engineer, or regular user, you can quickly get started and leverage its value.

Start your AI Agent journey today!

Related Links

If you encounter any issues during use, feel free to submit Issues on GitHub or participate in community discussions. FastClaw is an open-source project, and your feedback and contributions will help make it better!

Top comments (0)