Frequently Asked Questions

General Questions

What is Weaver?

Weaver is an ultra-efficient AI agent orchestration service designed for high-density, low-latency deployment. Built from the ground up in Go, it enables the deployment of isolated, task-specific agents within Docker containers at scale.Key Features:

Fast: <1s boot time per agent
Lightweight: <10MB RAM footprint per agent
Isolated: Workspace-based directory isolation with strict Docker boundaries
Universal: Multi-channel gateway support (Telegram, Discord, Slack, etc.)
Efficient: Optimized for high-density managed services

How is Weaver different from other AI agent frameworks?

Weaver is specifically optimized for efficiency and scale:

10x-100x lighter than heavyweight agent frameworks
Sub-second boot times vs multi-second initialization
Native multi-channel support with unified tool protocol
Built in Go for performance and resource efficiency
Workspace isolation for secure multi-tenant deployments

See our efficiency comparison diagrams in the main documentation.

What AI models does Weaver support?

Weaver supports multiple AI providers:

Gemini (Google) - Recommended: gemini-3-flash-preview
OpenAI (GPT-4, GPT-3.5-turbo, etc.)
Anthropic (Claude models)
OpenRouter (Multiple model access)
Groq (Fast inference)
Zhipu (Chinese language models)
vLLM (Self-hosted models)

The default configuration is optimized for gemini-3-flash to balance speed and cost.

Is Weaver open source?

Yes! Weaver is open source under the MIT License. You can:

Use it freely in commercial projects
Modify and customize it for your needs
Contribute back to the community
Deploy it on your own infrastructure

See our GitHub repository for the source code.

Getting Started

How do I install Weaver?

Weaver can be deployed in multiple ways:Docker (Recommended):

docker run --rm \
  -v $(pwd)/workspaces/task-1:/root/.weaver/workspace \
  -e GEMINI_API_KEY=$GEMINI_API_KEY \
  operatoronline/weaver agent -m "Your task here"

From Source:

git clone https://github.com/operatoronline/weaver.git
cd weaver
go build -o weaver ./cmd/weaver
./weaver agent -m "Your task here"

See the Quickstart guide for detailed instructions.

What are the system requirements?

Weaver is designed to be lightweight:Minimum:

512MB RAM per agent
100MB disk space
Linux, macOS, or Windows (with Docker)
Docker (for containerized deployments)

Recommended:

1GB RAM for gateway + multiple agents
1GB disk space
Linux or macOS for best performance
Go 1.21+ (for development)

How do I configure Weaver?

Configuration is managed via config/config.json:

{
  "agents": {
    "defaults": {
      "model": "gemini-3-flash-preview",
      "workspace": "~/.weaver/workspace"
    }
  },
  "providers": {
    "gemini": {
      "api_key": "your-api-key"
    }
  }
}

See Configuration for all available options.

Do I need Docker?

Docker is recommended but not required:

With Docker: Better isolation, easier deployment, production-ready
Without Docker: Direct binary execution, simpler for development

For production deployments and multi-tenant scenarios, Docker provides essential isolation.

Architecture & Design

What is the Weaver architecture?

Weaver uses a gateway-agent architecture:

Gateway: Central dispatcher that routes messages from external channels to agents
Agents: Isolated, task-specific workers that process requests
Workspaces: Dedicated file system areas for each agent’s context
Channels: Communication adapters (Telegram, Discord, etc.)

Agents are spawned on-demand and isolated via Docker containers or directory boundaries.

How does workspace isolation work?

Each agent gets its own workspace directory:

~/.weaver/workspace/
├── agent-1/
│   ├── AGENTS.md    # Agent coordination notes
│   ├── NEST.md      # Canvas/UI state
│   ├── USER.md      # User context
│   ├── TOOLS.md     # Tool usage history
│   └── memory/      # Persistent memory
└── agent-2/
    └── ...

This ensures:

Security: Agents can’t access each other’s data
Context: Each agent maintains its own working memory
Persistence: State survives across sessions

What is the Canvas tool?

The Canvas tool provides direct manipulation of the Nest UI:

Create and update nodes in the visual interface
Organize agent outputs visually
Link related information
Provide rich, interactive feedback to users

It’s part of the Operator Online ecosystem for enhanced agent-human collaboration.

How are channels implemented?

Channels are adapters that connect external platforms to Weaver:Each channel:

Receives messages from its platform (Telegram, Discord, etc.)
Normalizes them into a common format
Routes them through the gateway
Delivers responses back to the platform

Supported channels: Telegram, Discord, WhatsApp, Feishu, QQ, DingTalk, MaixCam

Development & Customization

How do I add a new tool?

Tools are defined in the agent’s tool registry:

Implement your tool function in Go
Register it with the tool system
Define its schema for the AI model
The agent can now use it automatically

See Development Guide for detailed instructions.

Can I use custom AI models?

Yes! You can use:

Self-hosted models via vLLM
Custom endpoints with compatible APIs
Local models with appropriate adapters

Configure them in config.json under the vllm provider with your custom endpoint.

How do I contribute to Weaver?

We welcome contributions!

Fork the repository
Create a feature branch
Make your changes (with tests)
Format code: make fmt
Submit a pull request

See our Contributing Guide for detailed instructions.

Is there a plugin system?

Currently, Weaver uses:

Skills: Reusable tool sets (in development)
Channel adapters: Platform integrations
Tool registration: Custom tool additions

A more formal plugin system is on the roadmap.

Migration & Integration

How do I migrate from OpenClaw?

Weaver includes a built-in migration tool:

weaver migrate --from ~/.openclaw --to ~/.weaver

This will:

Convert your OpenClaw configuration
Migrate workspace files and memory
Preserve agent context
Backup existing Weaver data

See the OpenClaw Migration Guide for details.

Can Weaver integrate with existing systems?

Yes! Weaver supports:

REST APIs: Call external services from agents
Webhooks: Receive events from external systems
Message queues: Integration via channels
Database access: Through custom tools

The gateway architecture makes it easy to add new integration points.

Does Weaver support multi-tenancy?

Yes! Weaver is designed for high-density deployments:

Workspace isolation per user/tenant
Resource limits via Docker
Access control via channel allow lists
Shared gateway with isolated agents

This is how weaver.onl provides managed services.

Performance & Scaling

How many agents can I run simultaneously?

With Weaver’s efficiency:

8GB RAM: ~80 concurrent agents (100MB each)
16GB RAM: ~160 concurrent agents
32GB RAM: ~320 concurrent agents

Actual numbers depend on workload and tooling complexity.

What is the typical response latency?

Weaver is optimized for low latency:

Agent boot: <1 second
Gateway routing: <10ms
Tool execution: Varies by tool
AI inference: Depends on provider (gemini-flash is fastest)

Total typical latency: 2-5 seconds including AI inference.

How do I optimize resource usage?

Best practices:

Use gemini-3-flash for cost/speed balance
Enable workspace cleanup for inactive agents
Set max_tool_iterations limits
Use Docker resource limits in production
Monitor with built-in metrics (coming soon)

Troubleshooting

Agent won't start - what should I check?

Common issues:

API keys: Verify they’re set correctly in config.json
Permissions: Check workspace directory permissions
Docker: Ensure Docker daemon is running (if using containers)
Ports: Make sure gateway port (default 8080) isn’t in use
Logs: Check ~/.weaver/logs/ for error details

How do I debug agent behavior?

Debugging tools:

Logs: Check agent logs in the workspace
Dry run: Use --dry-run flag to simulate without execution
Verbose mode: Enable with -v or --verbose
Tool history: Review TOOLS.md in the workspace
Memory inspection: Check memory/ directory contents

Where can I get help?

Support channels:

GitHub Issues: Bug reports and feature requests
Developer Discord: For active contributors (after first merged PR)
Email: [email protected] for general inquiries
Documentation: Check guides and API references

Commercial & Licensing

Can I use Weaver commercially?

Yes! Weaver is licensed under MIT, which allows:

Commercial use
Modification
Distribution
Private use

No attribution required, but appreciated!

Is there a managed service?

Yes! weaver.onl provides managed Weaver hosting:

No infrastructure management
Automatic scaling
Pre-configured channels
Professional support

Or self-host for free using the open source version.

What is Operator Online?

Operator Online is the organization behind Weaver:

Maintains the open source project
Provides managed services
Builds the AI ecosystem (AIEOS, Nest, etc.)
Supports the community

Learn more at operator.onl.

Still have questions?

Open an issue on GitHub or email us at [email protected]

Community

Migration

Frequently Asked Questions

General Questions

Getting Started

Architecture & Design

Development & Customization

Migration & Integration

Performance & Scaling

Troubleshooting

Commercial & Licensing

Still have questions?

Build docs developers (and LLMs) love

Community

Migration

​General Questions

​Getting Started

​Architecture & Design

​Development & Customization

​Migration & Integration

​Performance & Scaling

​Troubleshooting

​Commercial & Licensing

Still have questions?

Build docs developers (and LLMs) love

General Questions

Getting Started

Architecture & Design

Development & Customization

Migration & Integration

Performance & Scaling

Troubleshooting

Commercial & Licensing