MateClaw

中文

English

中文

English

Appearance

常见问题（FAQ） ​

本文档收录 MateClaw 使用过程中的常见问题及解决方案。

启动问题 ​

Q: 启动时报错模型调用失败 ​

MateClaw 启动不再要求必须设置 DASHSCOPE_API_KEY 环境变量。所有模型供应商的 API Key 均可在启动后通过 设置 → 模型管理 页面配置。

解决方案：

  1. 启动系统后，进入 设置 → 模型管理
  2. 找到你要使用的模型供应商（如 DashScope），点击编辑
  3. 填入 API Key 并保存

如果你仍然希望通过环境变量配置：

bash
# macOS / Linux
export DASHSCOPE_API_KEY=sk-your-dashscope-key

# Windows
set DASHSCOPE_API_KEY=sk-your-dashscope-key

如果没有 DashScope API Key，可以在阿里云百炼平台注册获取。

Q: 端口 18088 被占用 ​

解决方案：

bash
# 查找占用端口的进程
lsof -i :18088         # macOS / Linux
netstat -ano | findstr 18088  # Windows

# 终止进程后重新启动
kill -9 <PID>          # macOS / Linux
taskkill /PID <PID> /F # Windows

或修改端口号：

yaml
# application.yml
server:
  port: 18089

Q: H2 数据库文件锁定错误 ​

错误信息：Database may be already in use: "Locked by another process"

原因： 上次进程未正常退出，H2 文件锁未释放。

解决方案：

bash
# 1. 确保没有其他 MateClaw 实例在运行
ps aux | grep mateclaw

# 2. 删除锁文件
rm ./data/mateclaw.lock.db

# 3. 重新启动
mvn spring-boot:run

Q: 启动时数据库初始化失败 ​

解决方案：

  1. 检查 db/schema.sql 和 db/data.sql 文件是否存在
  2. 确认 H2 文件权限正确
  3. 如果是全新安装，删除 ./data/ 目录后重新启动

模型问题 ​

Q: 模型调用超时 ​

错误信息：Read timed out 或 Connection timed out

可能原因及解决方案：

  1. 网络问题：检查是否能访问模型 API 地址

    bash
    curl https://dashscope.aliyuncs.com/compatible-mode/v1/models

  2. 超时配置：增大请求超时时间

    yaml
    mateclaw:
  llm:
    timeout: 120  # 秒

  3. 代理设置：如果使用代理，确认 Java 代理配置

    bash
    mvn spring-boot:run -Dhttps.proxyHost=127.0.0.1 -Dhttps.proxyPort=7890

Q: API Key 无效或余额不足 ​

解决方案：

  1. 确认 API Key 正确（注意前后空格）
  2. 登录对应平台检查账户余额
  3. 检查 API Key 权限是否包含所使用的模型
  4. 尝试在平台控制台直接调用 API 验证

Q: Ollama 模型连接失败 ​

解决方案：

bash
# 确认 Ollama 服务正在运行
ollama list

# 检查端口是否可达
curl http://localhost:11434/api/tags

# 如果不在本机，确认 Ollama 监听地址
OLLAMA_HOST=0.0.0.0:11434 ollama serve

搜索与工具 ​

Q: 如何切换搜索提供商（Serper/Tavily）？ ​

搜索提供商的配置已迁移到 UI 中。进入「系统设置」页面，在搜索配置区域选择所需的搜索提供商（Serper 或 Tavily），填入对应的 API Key 并保存即可。无需修改配置文件或环境变量。

Q: 如何配置 MCP 服务器？ ​

通过前端的「MCP 服务器」管理页面进行配置。在该页面可以添加、编辑和删除 MCP 服务器连接，支持 stdio、streamable_http 和 sse 三种传输方式。配置完成后，MCP 服务器提供的工具会自动注册到系统中。修改 MCP 配置后无需重启应用，系统会自动重连。

Q: 如何添加自定义工具？ ​

创建一个 Spring @Component 类，在其方法上使用 Spring AI 的 @Tool 注解：

java
@Component
public class MyCustomTool {

    @Tool(description = "查询天气信息")
    public String getWeather(String city) {
        // 实现逻辑
        return "晴天，25°C";
    }
}

工具会在应用启动时自动注册。详见工具系统文档。

Q: WebSearchTool 返回空结果 ​

确认已设置搜索 API Key：

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

也可以在「系统设置」页面中配置搜索 API Key。

记忆系统 ​

Q: 记忆功能不工作 ​

排查步骤：

  1. 确认记忆自动提取功能已启用。检查配置项 mate.memory.autoSummarizeEnabled 是否为 true
  2. 在「系统设置」页面中确认记忆相关开关已开启
  3. 检查日志中是否有记忆提取相关的错误信息
  4. 确认使用的模型支持足够的上下文长度来进行记忆提取
yaml
mate:
  memory:
    autoSummarizeEnabled: true

Q: 记忆整合任务没有执行 ​

记忆整合通过 CronJob 种子数据驱动，每天凌晨 2:00 自动执行。检查 mate_cron_job 表中是否存在记忆整合相关的定时任务记录，确认其状态为启用。

Agent 问题 ​

Q: Agent 卡在 RUNNING 状态 ​

可能原因及解决方案：

  1. 工具调用超时：Agent 在等待某个工具返回结果。检查该工具是否正常运行
  2. 超过最大迭代次数：Agent 的 ReAct 循环超过了 maxIterations 限制。可以在 Agent 配置中调大该值
  3. 等待审批：ToolGuard 暂停了执行，等待用户审批工具调用。检查聊天界面是否有待审批的请求
  4. 查看日志：开启 DEBUG 日志排查具体卡住的环节
    bash
    mvn spring-boot:run -Dspring-boot.run.arguments="--logging.level.vip.mate.agent=DEBUG"
  5. 如果 Agent 确实卡死，可以通过 API 重置其状态

前端问题 ​

Q: CORS 跨域错误 ​

浏览器控制台报错：Access to XMLHttpRequest has been blocked by CORS policy

解决方案：

  1. 开发环境：确认 Vite 代理配置正确

    typescript
    // vite.config.ts
proxy: {
  '/api': {
    target: 'http://localhost:18088',
    changeOrigin: true,
  }
}

  2. 确认后端已启动：访问 http://localhost:18088/api/v1/auth/login 确认后端可用

  3. 直接访问后端：如果不使用 Vite 代理，确认后端 CORS 配置允许前端地址

Q: pnpm install 安装失败 ​

解决方案：

bash
# 清除缓存
pnpm store prune

# 删除 node_modules 重新安装
rm -rf node_modules pnpm-lock.yaml
pnpm install

# 如果是网络问题，使用国内镜像
pnpm config set registry https://registry.npmmirror.com
pnpm install

Q: 前端构建失败（vue-tsc 类型错误） ​

解决方案：

bash
# 单独运行类型检查定位错误
npx vue-tsc --noEmit

# 如果是新拉取的代码，确保依赖完整
pnpm install
pnpm build

数据备份 ​

Q: 如何备份数据？ ​

H2 数据库（开发环境）：

直接复制 ./data/mateclaw.mv.db 文件即可。建议在服务停止后复制，避免数据不一致。

bash
# 停止服务后复制
cp ./data/mateclaw.mv.db ./backup/mateclaw-$(date +%Y%m%d).mv.db

MySQL 数据库（生产环境）：

使用 mysqldump 导出：

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

Docker 环境：

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

调试 ​

Q: 如何开启 DEBUG 日志？ ​

yaml
# application.yml
logging:
  level:
    vip.mate: DEBUG
    org.springframework.ai: DEBUG

或者通过命令行参数：

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

Q: 如何访问 H2 控制台？ ​

开发环境下 H2 Web 控制台默认启用：

  1. 访问 http://localhost:18088/h2-console
  2. JDBC URL：jdbc:h2:file:./data/mateclaw
  3. 用户名：sa
  4. 密码：（空）

在 H2 控制台中可以直接执行 SQL 查询，方便调试数据问题。

Q: 如何查看 SSE 流式事件？ ​

使用浏览器开发者工具的 Network 面板：

  1. 打开 DevTools（F12）
  2. 切换到 Network 标签
  3. 筛选 EventStream 类型
  4. 发送一条消息，观察 SSE 事件流

或使用 curl：

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

账户问题 ​

Q: 忘记了管理员密码 ​

解决方案：

  1. 访问 H2 控制台（见上方）
  2. 执行 SQL 重置密码：
    sql
    UPDATE mate_user SET password = '<bcrypt-hash>' WHERE username = 'admin';
  3. 使用 BCrypt 工具生成密码哈希，或直接重置为默认值

如果使用 MySQL，使用对应的数据库客户端执行上述 SQL。

Q: 如何创建新用户？ ​

当前版本通过 API 创建用户：

bash
curl -X POST http://localhost:18088/api/v1/users \
  -H "Authorization: Bearer <admin-token>" \
  -H "Content-Type: application/json" \
  -d '{"username": "newuser", "password": "password123"}'

桌面应用 ​

Q: 桌面应用无法启动 ​

安装版已捆绑 JRE，通常无需单独安装 Java。

排查步骤：

  1. 查看应用日志：
    • macOS：~/Library/Logs/MateClaw/
    • Windows：%APPDATA%/MateClaw/logs/
    • Linux：~/.local/share/MateClaw/logs/
  2. 尝试从终端启动应用以查看控制台输出
  3. 确认端口 18088 未被其他进程占用
  4. API Key 可在启动后通过 设置 → 模型管理 配置，无需提前设置环境变量

详见桌面应用文档的故障排除章节。

Q: 如何更新桌面应用？ ​

MateClaw 桌面版支持自动更新。应用启动时会自动检查 GitHub Releases 是否有新版本，发现后在界面中提示下载安装。你也可以手动前往 Releases 页面 下载最新版本覆盖安装。

部署问题 ​

Q: Docker 启动失败 ​

解决方案：

bash
# 检查 .env 文件是否正确配置
cat .env

# 查看容器日志
docker compose logs mateclaw

# 确认 MySQL 已就绪
docker compose logs mysql

# 重新构建
docker compose down
docker compose up -d --build

Q: MySQL 连接被拒绝 ​

确认 Spring Profile 设置为 mysql：

bash
# docker-compose.yml 中
environment:
  - SPRING_PROFILES_ACTIVE=mysql
  - SPRING_DATASOURCE_URL=jdbc:mysql://mysql:3306/mateclaw
  - SPRING_DATASOURCE_USERNAME=root
  - SPRING_DATASOURCE_PASSWORD=${MYSQL_ROOT_PASSWORD}