MateClaw

English

中文

English

中文

Appearance

FAQ ​

Common questions and solutions for MateClaw.

Installation & Setup ​

Q: What Java version do I need? ​

Java 17 or higher. MateClaw uses features introduced in Java 17 (sealed classes, text blocks, records). Verify with:

bash
java -version

Q: How do I get a DashScope API key? ​

  1. Go to the Alibaba Cloud DashScope console
  2. Sign up or log in
  3. Navigate to API Keys and create a new key
  4. After startup, go to Settings > Model Management, select DashScope, and enter the API key

Q: Can I use MateClaw without DashScope? ​

Yes. Configure Ollama for fully local operation with no cloud API:

yaml
spring:
  ai:
    ollama:
      base-url: http://localhost:11434
      chat:
        options:
          model: qwen2.5:7b

MateClaw no longer requires setting DASHSCOPE_API_KEY as an environment variable to start. All model provider API keys can be configured after startup through the Settings > Model Management page.

Q: The backend fails to start with a port conflict ​

Another process is using port 18088. Either stop that process or change the port:

bash
mvn spring-boot:run -Dspring-boot.run.arguments="--server.port=19090"

Q: H2 database lock error on startup ​

This happens when a previous instance did not shut down cleanly. Delete the lock file:

bash
rm -f data/mateclaw.mv.db.lock
# Or delete the entire data directory to start fresh:
rm -rf data/

Authentication ​

Q: What are the default credentials? ​

Username: admin, Password: admin123

Q: My JWT token keeps expiring ​

MateClaw implements sliding-window renewal. If you are making API calls manually (e.g., with curl), check the X-New-Token response header and use the new token for subsequent requests.

Q: How do I change the admin password? ​

Through the Settings page in the UI, or directly in the database:

sql
-- The password should be BCrypt-encoded
UPDATE mate_user SET password = '$2a$10$...' WHERE username = 'admin';

Models ​

Q: How do I use GPT-4 with MateClaw? ​

Add OpenAI as a provider through the Settings page or application.yml:

yaml
spring:
  ai:
    openai:
      api-key: ${OPENAI_API_KEY}
      base-url: https://api.openai.com

Then create a model config in the UI pointing to gpt-4o.

Q: Ollama models are slow ​

Local model performance depends on your hardware. Tips:

  • Use smaller models (7B instead of 14B) on machines with less RAM
  • Ensure Ollama has GPU access (check with ollama ps)
  • Increase Ollama's memory limit if available
  • Use qwen2.5:7b as a good balance of speed and quality

Q: Can I use multiple model providers simultaneously? ​

Yes. Configure multiple providers and assign different model configs to different agents. Each agent can use a different model.

Search & Tools ​

Q: How do I switch the search provider (Serper/Tavily)? ​

Search provider configuration has been moved to the UI. Go to the System Settings page, find the search configuration section, select your preferred provider (Serper or Tavily), enter the corresponding API key, and save. No configuration files or environment variables need to be modified.

Q: How do I configure MCP servers? ​

Use the MCP Servers management page in the frontend. From there you can add, edit, and remove MCP server connections. Three transport modes are supported: stdio, streamable_http, and sse. Once configured, tools provided by the MCP server are automatically registered in the system. Changes to MCP configuration take effect without restarting the application -- the system reconnects automatically.

Q: How do I add a custom tool? ​

Create a Spring @Component with @Tool-annotated methods:

java
@Component
public class MyCustomTool {

    @Tool(description = "Get weather information")
    public String getWeather(String city) {
        // Implementation
        return "Sunny, 25C";
    }
}

The tool is automatically registered on startup. See Tool System for a full example.

Q: WebSearchTool returns empty results ​

Ensure you have set either SERPER_API_KEY or TAVILY_API_KEY:

bash
export SERPER_API_KEY=your-serper-key
# OR
export TAVILY_API_KEY=your-tavily-key

You can also configure the search API key through the System Settings page.

Q: ToolGuard keeps blocking my tool calls ​

If you want to disable approval for specific tools in a development environment:

yaml
mateclaw:
  tool:
    guard:
      enabled: false    # Disable entirely (not recommended for production)

Or configure auto-approve patterns for safe commands. See Security.

Memory ​

Q: Memory is not working ​

Troubleshooting steps:

  1. Confirm that automatic memory extraction is enabled. Check that mate.memory.autoSummarizeEnabled is set to true
  2. Verify that memory-related toggles are enabled on the System Settings page
  3. Check the logs for any memory extraction errors
  4. Ensure the model in use has sufficient context length for memory extraction
yaml
mate:
  memory:
    autoSummarizeEnabled: true

Q: Memory consolidation tasks are not running ​

Memory consolidation is driven by CronJob seed data and runs automatically at 2:00 AM daily. Check the mate_cron_job table for memory consolidation task records and verify their status is enabled.

Agents ​

Q: Agent stuck in RUNNING state ​

Possible causes and solutions:

  1. Tool call timeout: The agent is waiting for a tool to return results. Check whether the tool is functioning correctly
  2. Max iterations exceeded: The agent's ReAct loop has hit the maxIterations limit. Increase this value in the agent configuration
  3. Awaiting approval: ToolGuard has paused execution pending user approval. Check the chat interface for pending approval requests
  4. Review logs: Enable DEBUG logging to diagnose where the agent is stuck
    bash
    mvn spring-boot:run -Dspring-boot.run.arguments="--logging.level.vip.mate.agent=DEBUG"
  5. If the agent is truly stuck, reset its state through the API

Channels ​

Q: DingTalk/Feishu webhook is not receiving messages ​

Common causes:

  1. Your server is not publicly accessible (IM platforms need to reach your webhook URL)
  2. HTTPS is required for most platforms -- use a reverse proxy with TLS
  3. The verification token is incorrect -- check your channel configuration
  4. The bot has not been added to the group or does not have message permissions

Q: Can I use multiple channels at the same time? ​

Yes. Each channel is independent and can be configured with a different agent. Messages from DingTalk and Telegram can be handled by different agents simultaneously.

Data Backup ​

Q: How do I backup data? ​

H2 database (development):

Copy the ./data/mateclaw.mv.db file directly. Stop the service first to avoid data inconsistency.

bash
# Copy after stopping the service
cp ./data/mateclaw.mv.db ./backup/mateclaw-$(date +%Y%m%d).mv.db

MySQL database (production):

Use mysqldump:

bash
mysqldump -u root -p mateclaw > mateclaw-backup-$(date +%Y%m%d).sql

Docker environment:

bash
docker exec mateclaw-mysql mysqldump -u root -p${MYSQL_ROOT_PASSWORD} mateclaw > backup.sql

Desktop App ​

Q: Desktop app won't start ​

The installer bundles a JRE, so you typically do not need to install Java separately.

Troubleshooting steps:

  1. Review application logs:
    • macOS: ~/Library/Logs/MateClaw/
    • Windows: %APPDATA%/MateClaw/logs/
    • Linux: ~/.local/share/MateClaw/logs/
  2. Try launching from a terminal to see console output
  3. Confirm port 18088 is not in use by another process
  4. API keys can be configured after startup through Settings > Model Management -- no need to set environment variables in advance

See the troubleshooting section in Desktop Application for more details.

Q: How do I update the desktop app? ​

MateClaw desktop supports automatic updates. On startup, the app automatically checks GitHub Releases for a new version. When an update is found, a notification appears in the interface to download and install it. You can also manually download the latest version from the Releases page and install it over the existing version.

Docker ​

Q: Docker containers fail to start ​

Check the logs:

bash
docker compose logs mateclaw-server
docker compose logs mateclaw-mysql

Common issues:

  • MySQL not ready yet -- the server may start before MySQL is fully initialized. It should retry automatically.
  • Port conflicts -- ensure ports 18080 and 3306 are free
  • Missing .env file -- copy .env.example to .env and fill in required values

Q: How do I access the database in Docker? ​

bash
docker exec -it mateclaw-mysql mysql -u root -p mateclaw

Debugging ​

Q: How do I enable DEBUG logging? ​

yaml
logging:
  level:
    vip.mate: DEBUG
    org.springframework.ai: DEBUG

Or via command line:

bash
mvn spring-boot:run -Dspring-boot.run.arguments="--logging.level.vip.mate=DEBUG"

Q: How do I access the H2 console? ​

The H2 web console is enabled by default in development:

  1. Visit http://localhost:18088/h2-console
  2. JDBC URL: jdbc:h2:file:./data/mateclaw
  3. Username: sa
  4. Password: (empty)

Q: How do I inspect SSE streaming events? ​

Use the browser DevTools Network panel:

  1. Open DevTools (F12)
  2. Switch to the Network tab
  3. Filter by EventStream type
  4. Send a message and observe the SSE event stream

Or use curl:

bash
curl -N -H "Authorization: Bearer <token>" \
  "http://localhost:18088/api/v1/chat/1/stream?conversationId=1"

Frontend ​

Q: The frontend shows a blank page after build ​

Ensure the build output is in the correct location:

bash
cd mateclaw-ui
pnpm build
ls ../mateclaw-server/src/main/resources/static/
# Should contain index.html and asset files

Q: Dark mode is not persisting ​

The theme preference is stored in localStorage. If you are clearing browser data, the preference is lost. Check that your browser allows localStorage for the site.

Next Steps ​