User Guide
This guide is for people who want to use MateClaw as a product, not hack on the source code.
If your goal is to get from install to first useful conversation as quickly as possible, start here.
The Fast Path
- Install the desktop app or open a running deployment
- Log in with the default account
- Add one model provider
- Send your first message
- Create or customize an agent
- Add tools, skills, memory, or Wiki knowledge as needed
That is the whole product arc.
Install and Launch
Desktop App
Download the latest installer from GitHub Releases.
MateClaw desktop bundles JRE 21 + backend runtime, so users do not need to install Java separately.
First Launch
The app may take 10 to 30 seconds to fully initialize on first run. After startup, log in with:
| Field | Value |
|---|---|
| Username | admin |
| Password | admin123 |
Change the default password after your first login.
Configure the First Model
No AI product exists until the model is reachable.
Go to:
Settings -> Models
Then configure at least one provider.
Recommended options:
- DashScope for a simple cloud start
- Ollama if you want local model usage
- OpenAI / Anthropic / Gemini / DeepSeek / Kimi / MiniMax / Zhipu / OpenRouter if those are already part of your stack
You can start with one provider and add more later.
Understand the Product Surface
1. Chat
This is where you directly interact with agents.
Use it when you want:
- direct questions
- multi-turn work
- tool-using tasks
- file-based requests
2. Agents
This is where you define how the AI behaves.
An agent combines:
- system instructions
- model choice
- tool availability
- memory behavior
- role/personality
If Chat is the interaction surface, Agents is the operational layer.
3. Workspace and Memory
This is where continuity lives.
Use it when you want the system to retain:
- user preferences
- durable notes
- recurring context
- long-horizon knowledge
4. Skills and MCP
This is where capability expands.
Use it when you want the agent to do more than the default system can do out of the box.
5. Wiki Knowledge Base
This is where raw material becomes structured knowledge.
Use it when you want to:
- upload notes and documents
- digest source material into linked pages
- let agents read knowledge on demand instead of re-reading raw files
Your First Useful Setup
If you want a practical first configuration, do this:
Setup A: Personal Assistant
- configure one strong model provider
- use the default chat agent
- enable search if you need live information
- let the memory system start accumulating context
Setup B: Team Knowledge Assistant
- create a dedicated agent
- create a Wiki knowledge base
- ingest product docs, notes, PDFs, or DOCX files
- let the agent use Wiki tools when answering questions
Setup C: Tool-Using AI Worker
- create a role-specific agent
- add relevant skills
- connect MCP servers
- tune approval rules in Security
Files and Uploads
MateClaw supports file-based work inside the product.
Typical use cases:
- attach files in chat
- upload documents into a Wiki knowledge base
- maintain workspace memory files
For PDFs and scanned content, the platform supports text extraction and OCR fallback where applicable.
Security and Approval
MateClaw is designed for real operations, which means safety controls matter.
Use Security when you need to:
- require approval for sensitive tools
- block dangerous file access
- inspect audit logs
- manage tool guard policies
The goal is simple: strong capability without silent risk.
Data and Persistence
MateClaw stores working data locally or in your chosen deployment database, including:
- conversations
- agent configuration
- model/provider settings
- memory artifacts
- Wiki knowledge
- tool/security configuration
Back up your data directory or database before major upgrades.
What to Do Next
After your first successful setup, the usual progression is:
- Create specialized agents
- Install skills
- Connect MCP services
- Build a Wiki knowledge base
- Expand to channels
- Tighten security and approval rules
If you need installation steps, go to Quick Start.
If you need conceptual grounding, go back to Introduction.