配置参考

MateClaw 的配置分为 Spring Boot 标准配置和 MateClaw 自定义配置两部分。本文档详细说明所有配置项。

环境变量

变量名	必需	默认值	说明
`DASHSCOPE_API_KEY`	否	-	阿里云 DashScope API 密钥（也可在 UI 的设置 → 模型管理中配置）
`SERPER_API_KEY`	否	-	Serper 搜索 API 密钥（已迁移至系统设置，环境变量仅作初始值）
`TAVILY_API_KEY`	否	-	Tavily 搜索 API 密钥（已迁移至系统设置，环境变量仅作初始值）
`MYSQL_HOST`	否	`localhost`	MySQL 主机地址（Docker 部署）
`MYSQL_PORT`	否	`3306`	MySQL 端口
`MYSQL_DATABASE`	否	`mateclaw`	MySQL 数据库名
`MYSQL_USERNAME`	否	`root`	MySQL 用户名
`MYSQL_PASSWORD`	否	-	MySQL 密码

设置方式：

bash

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

# Windows PowerShell
$env:DASHSCOPE_API_KEY="sk-your-key"

# 或写入 .env 文件（Docker 部署）
echo "DASHSCOPE_API_KEY=sk-your-key" >> .env

服务器基础配置

yaml

server:
  port: 18088                    # 服务端口
  servlet:
    context-path: /              # 上下文路径

spring:
  application:
    name: mateclaw-server        # 应用名称
  profiles:
    active: dev                  # 激活的 Profile（dev / mysql）

端口说明

环境	端口	说明
本地开发后端	18088	Spring Boot 服务
本地开发前端	5173	Vite 开发服务器
Docker 部署	18080	对外暴露端口

数据库配置

H2 数据库（开发环境）

默认 Profile 使用 H2 文件数据库，无需安装额外数据库：

yaml

spring:
  datasource:
    url: jdbc:h2:file:./data/mateclaw;MODE=MySQL;AUTO_SERVER=TRUE
    driver-class-name: org.h2.Driver
    username: sa
    password:
  h2:
    console:
      enabled: true              # 启用 H2 控制台
      path: /h2-console          # 控制台路径
      settings:
        web-allow-others: false  # 是否允许远程访问

H2 使用 MySQL 兼容模式（MODE=MySQL），确保 SQL 语法与 MySQL 一致。

MySQL 数据库（生产环境）

激活 mysql Profile 切换到 MySQL：

yaml

spring:
  profiles:
    active: mysql
  datasource:
    url: jdbc:mysql://${MYSQL_HOST:localhost}:${MYSQL_PORT:3306}/${MYSQL_DATABASE:mateclaw}?useUnicode=true&characterEncoding=utf-8&useSSL=false&serverTimezone=Asia/Shanghai
    driver-class-name: com.mysql.cj.jdbc.Driver
    username: ${MYSQL_USERNAME:root}
    password: ${MYSQL_PASSWORD:}

启动前需创建数据库：

sql

CREATE DATABASE mateclaw DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;

MyBatis Plus 配置

yaml

mybatis-plus:
  mapper-locations: classpath*:/mapper/**/*.xml
  global-config:
    db-config:
      id-type: auto               # 主键策略
      logic-delete-field: deleted  # 逻辑删除字段
      logic-delete-value: 1       # 删除标记值
      logic-not-delete-value: 0   # 未删除标记值
  configuration:
    map-underscore-to-camel-case: true  # 驼峰映射

JWT 认证配置

yaml

mateclaw:
  auth:
    jwt:
      secret: your-jwt-secret-key-at-least-32-characters-long
      expiration: 86400000       # Token 有效期（毫秒），默认 24 小时
      refresh-window: 3600000    # 滑动窗口续签时间（毫秒），默认 1 小时

滑动窗口续签机制：当 Token 剩余有效期小于 refresh-window 时，系统会在响应头中返回新 Token，前端自动替换。

WARNING

生产环境务必修改 secret，确保长度不少于 32 个字符。

AI 模型配置

DashScope（默认）

yaml

spring:
  ai:
    dashscope:
      api-key: ${DASHSCOPE_API_KEY}
      chat:
        options:
          model: qwen-max         # 默认模型
          temperature: 0.7        # 温度参数
          max-tokens: 4096        # 最大输出 Token 数

Ollama（本地模型）

yaml

spring:
  ai:
    ollama:
      base-url: http://localhost:11434
      chat:
        options:
          model: qwen2.5:14b
          temperature: 0.7

OpenAI 兼容接口

适用于 Kimi、DeepSeek、Anthropic、Gemini、MiniMax 等兼容 OpenAI 接口的供应商：

yaml

spring:
  ai:
    openai:
      api-key: your-api-key
      base-url: https://api.deepseek.com  # 供应商 API 地址
      chat:
        options:
          model: deepseek-chat

常用供应商 base-url：

供应商	Base URL
DeepSeek	`https://api.deepseek.com`
Kimi (Moonshot)	`https://api.moonshot.cn/v1`
Anthropic	`https://api.anthropic.com`
MiniMax	`https://api.minimax.chat/v1`

TIP

模型配置也可以在系统运行后，通过管理界面的「模型管理」页面动态配置，无需重启应用。配置保存在 mate_model_config 和 mate_model_provider 表中。

Agent 配置

yaml

mateclaw:
  agent:
    default-type: react            # 默认 Agent 类型（react / dynamic）
    max-iterations: 20             # ReAct 循环最大迭代次数
    timeout: 300000                # Agent 执行超时（毫秒），默认 5 分钟

会话窗口配置

yaml

mateclaw:
  conversation:
    max-history: 50                # 每次对话携带的最大历史消息数
    context-window: 10             # 上下文窗口大小（发送给 LLM 的消息数）
    title-auto-generate: true      # 是否自动生成会话标题

工具配置

yaml

mateclaw:
  tool:
    guard:
      enabled: true                # 是否启用工具审批机制
      auto-approve:                # 自动审批的工具列表
        - DateTimeTool
        - WebSearchTool
        - DocumentExtractTool
    shell:
      allowed-commands:            # ShellExecuteTool 允许的命令白名单
        - ls
        - cat
        - grep
        - find
        - wc
      timeout: 30000               # 命令执行超时（毫秒）

MCP 服务器配置

MCP 服务器可在配置文件中预设，也可通过管理界面动态添加：

yaml

mateclaw:
  mcp:
    servers:
      - name: filesystem           # 服务器名称
        transport: stdio           # 传输类型：stdio 或 sse
        command: npx               # 启动命令
        args:                      # 命令参数
          - "@anthropic/mcp-filesystem"
          - "/path/to/workspace"
      - name: custom-server
        transport: sse
        url: http://localhost:3001/sse  # SSE 端点地址

搜索工具配置

搜索工具已迁移至 系统设置 页面，支持在 UI 中动态配置，修改后即时生效，无需重启。

可配置项：

设置项	说明
启用搜索	是否启用搜索工具
搜索提供商	`serper`（Google Serper）或 `tavily`（Tavily）
失败回退	主提供商失败时自动尝试另一个
Serper API Key	从 serper.dev 获取
Serper 接口地址	默认 `https://google.serper.dev/search`
Tavily API Key	从 tavily.com 获取
Tavily 接口地址	默认 `https://api.tavily.com/search`

TIP

搜索配置存储在 mate_system_setting 表中，通过 设置 → 系统设置 → 搜索服务 管理。API Key 在前端以脱敏形式回显，保存时仅在输入新值时覆盖。

日志配置

yaml

logging:
  level:
    root: INFO
    vip.mate: DEBUG                # MateClaw 业务日志级别
    org.springframework.ai: DEBUG  # Spring AI 日志级别
  file:
    name: logs/mateclaw.log        # 日志文件路径

跨域配置

开发环境下前端运行在 5173 端口，需要跨域支持：

yaml

mateclaw:
  cors:
    allowed-origins:
      - http://localhost:5173
      - http://localhost:18088
    allowed-methods:
      - GET
      - POST
      - PUT
      - DELETE
    allowed-headers:
      - "*"
    allow-credentials: true

完整配置示例

以下是一份用于本地开发的完整配置参考：

yaml

server:
  port: 18088

spring:
  datasource:
    url: jdbc:h2:file:./data/mateclaw;MODE=MySQL;AUTO_SERVER=TRUE
    driver-class-name: org.h2.Driver
    username: sa
    password:
  h2:
    console:
      enabled: true
      path: /h2-console
  ai:
    dashscope:
      api-key: ${DASHSCOPE_API_KEY}
      chat:
        options:
          model: qwen-max
          temperature: 0.7

mateclaw:
  auth:
    jwt:
      secret: mateclaw-dev-secret-key-change-in-production
      expiration: 86400000
  agent:
    default-type: react
    max-iterations: 20
  conversation:
    max-history: 50
    context-window: 10
  tool:
    guard:
      enabled: true
  # 搜索配置已迁移至系统设置页面，无需在此配置

logging:
  level:
    vip.mate: DEBUG

下一步

Agent 引擎 — Agent 类型与运行机制
工具系统 — 工具配置与使用
MCP 协议 — MCP 服务器配置详解

配置参考 ​

环境变量 ​

服务器基础配置 ​

端口说明 ​

数据库配置 ​

H2 数据库（开发环境） ​

MySQL 数据库（生产环境） ​

MyBatis Plus 配置 ​

JWT 认证配置 ​

AI 模型配置 ​

DashScope（默认） ​

Ollama（本地模型） ​

OpenAI 兼容接口 ​

Agent 配置 ​

会话窗口配置 ​

工具配置 ​

MCP 服务器配置 ​

搜索工具配置 ​

日志配置 ​

跨域配置 ​

完整配置示例 ​

下一步 ​

配置参考

环境变量

服务器基础配置

端口说明

数据库配置

H2 数据库（开发环境）

MySQL 数据库（生产环境）

MyBatis Plus 配置

JWT 认证配置

AI 模型配置

DashScope（默认）

Ollama（本地模型）

OpenAI 兼容接口

Agent 配置

会话窗口配置

工具配置

MCP 服务器配置

搜索工具配置

日志配置

跨域配置

完整配置示例

下一步