# 配置参考

**MateClaw 有三个配置位：`application.yml`、环境变量、数据库。**

大部分设置在 `application.yml`（Spring Boot 默认配置文件）里，敏感值通过环境变量覆盖。你想要**运行时修改**的东西——模型供应商、搜索 key、功能开关——存在 `mate_system_setting` 表里，通过设置页面编辑。

深入的主题有自己的页面——Tool Guard 规则在 [安全与审批](./security)，模型供应商在 [模型配置](./models)，记忆调优在 [记忆系统](./memory)。

---

## Profile

| Profile | 数据库 | 激活方式 |
|---------|--------|----------|
| `default` | H2 文件 `./data/mateclaw` | 不用做什么 |
| `mysql` | MySQL 8.0+ | `spring.profiles.active=mysql` 或环境变量 |
| `postgres` | PostgreSQL 16+ | `SPRING_PROFILES_ACTIVE=postgres` |
| `kingbase` | KingbaseES | `SPRING_PROFILES_ACTIVE=kingbase`（需按需驱动） |

公开 Docker Compose 自动激活 `postgres`。桌面版使用 `default`；`mysql` profile 继续支持已有或自管部署。

---

## 核心 `application.yml` 分段

### Server

```yaml
server:
  port: 18088                    # HTTP 端口
  servlet:
    context-path: /
```

### 数据库 —— H2（开发）

```yaml
spring:
  datasource:
    url: jdbc:h2:file:./data/mateclaw;MODE=MYSQL
    username: sa
    password:
    driver-class-name: org.h2.Driver
  h2:
    console:
      enabled: true              # /h2-console 可访问（生产环境关掉）
```

### 数据库 —— MySQL（支持的自管部署）

```yaml
spring:
  profiles:
    active: mysql
  datasource:
    url: jdbc:mysql://localhost:3306/mateclaw?useSSL=false&serverTimezone=UTC
    username: root
    password: ${DB_PASSWORD}
    driver-class-name: com.mysql.cj.jdbc.Driver
```

### AI 模型 —— 在 UI 里管，不在 YAML 里

::: tip
**模型配置 100% 通过 UI 管理。** 不要在 `application.yml` 里放 `spring.ai.*` 块——每个供应商、每个 key、每个模型配置都住在 `设置 → 模型` 里，底层存在 `mate_model_provider` 和 `mate_model_config` 表。
:::

**模型供应商、Key 与模型记录以数据库配置为准。** 新装实例登录后到「设置 → 模型 → 添加供应商」添加第一个供应商。`DASHSCOPE_API_KEY` 仍可作为 DashScope 自动配置的兼容回退，但不替代管理界面的供应商配置；不要假设其他供应商会读取同名环境变量。完整参考在 [模型配置](./models)。

### 虚拟线程（JDK 21）

```yaml
spring:
  threads:
    virtual:
      enabled: true
```

已默认开启。Tomcat 请求线程、`@Scheduled`、`@Async` 全部运行在虚拟线程上。SSE 长连接不再占平台线程，I/O 密集型异步任务（记忆提取、审计、技能安装等）不再排队。

### Spring AI 可观测性

```yaml
spring:
  ai:
    chat:
      observations:
        log-prompt: false       # 不把 prompt 写进 span（安全）
        log-completion: false   # 不把 completion 写进 span
```

开启后，`/actuator/metrics/gen_ai.client.operation` 和 `/actuator/metrics/gen_ai.client.token.usage` 自动记录每次 LLM 调用的延迟和 token 消耗。需要 `spring-boot-starter-actuator` 依赖（已内置）。

### 上下文窗口

```yaml
mate:
  agent:
    conversation:
      window:
        default-max-input-tokens: 128000
        compact-trigger-ratio: 0.75
        preserve-recent-pairs: 2
        summary-max-tokens: 300
```

细节在 [记忆系统](./memory)。

### 记忆提取和整合

```yaml
mate:
  memory:
    auto-summarize-enabled: true
    min-messages-for-summarize: 4
    min-user-message-length: 10
    skip-cron-conversations: true
    summary-max-tokens: 1000
    max-transcript-messages: 30
    cooldown-minutes: 5
    emergence-enabled: true
    emergence-day-range: 7
```

### LLM Wiki

```yaml
mate:
  wiki:
    enabled: true
    max-chunk-size: 30000
    max-context-chars: 10000
    max-pages-per-raw: 15
    max-parallel-raw-materials: 3
    max-parallel-phase-b-pages: 3
    auto-process-on-upload: true
    upload-dir: ./data/wiki-uploads
```

细节在 [LLM Wiki](./wiki)。

### Tool Guard（基于规则）

Tool Guard 的全局开关、默认策略和规则**不在 application.yml 里配置**——它们存在数据库（`mate_tool_guard_config` / `mate_tool_guard_rule`），通过管理台的「安全」页或 REST 编辑：

| 方法 | 路径 | 作用 |
|---|---|---|
| `GET` / `PUT` | `/api/v1/security/guard/config` | 全局开关 + 默认策略（`allow` / `deny` / `require_approval`） |
| `GET` | `/api/v1/security/guard/rules/builtin` | 内置规则 |
| `GET` / `POST` | `/api/v1/security/guard/rules` | 列出 / 新增自定义规则 |
| `PUT` | `/api/v1/security/guard/rules/{ruleId}` | 修改规则 |
| `PUT` | `/api/v1/security/guard/rules/{ruleId}/toggle` | 启停单条规则 |

每条规则按工具名 + 参数模式匹配，命中后给出 `allow` / `deny` / `require_approval` 动作，按优先级排序。细节在 [安全与审批](./security)。

### File Guard

File Guard 分两层：

1. **允许 / 禁止路径规则**——和 Tool Guard 一样存数据库、走管理台「安全」页，REST 为 `GET` / `PUT /api/v1/security/guard/config/file-guard`，**不在 application.yml 里**。
2. **全局兜底沙箱根**——唯一写在 application.yml 里的部分。当某个会话没有配置 per-workspace base path 时，文件 / Shell 工具被限制在这个根目录内（fail-closed 默认）：

```yaml
mateclaw:
  workspace:
    sandbox:
      enabled: true                       # 设 false 恢复旧的不受限行为
      root: ${user.dir}/data/workspace    # 兜底沙箱根，启动时自动创建
```

环境变量覆盖：`MATECLAW_WORKSPACE_SANDBOX_ENABLED` / `MATECLAW_WORKSPACE_SANDBOX_ROOT`。

### JWT 认证

```yaml
mateclaw:
  jwt:
    secret: ${JWT_SECRET:your-secret-key-at-least-32-characters-long}
    expiration: 86400000
```

::: warning
生产环境必须改默认 JWT secret。至少 32 字符。用环境变量，**不要 commit**。
:::

### 技能工作空间

```yaml
mateclaw:
  skill:
    workspace:
      root: ${user.home}/.mateclaw/skills
      auto-init: true
      delete-policy: archive
      bundled-skills-path: skills
```

### 多模态默认供应商

```yaml
mate:
  image:
    default-provider: dashscope
  video:
    default-provider: dashscope
  tts:
    default-provider: cosyvoice
  stt:
    default-provider: paraformer
  music:
    default-provider: dashscope
```

细节在 [多模态创作](./multimodal)。

---

## 环境变量

::: warning LLM Key 以管理界面为准
供应商、Key 和模型记录以「设置 → 模型」里的数据库配置为主。`DASHSCOPE_API_KEY` 仅保留为 DashScope 自动配置的兼容回退；不要假设其他供应商会读取同名环境变量。
:::

| 变量 | 必填 | 用途 |
|------|------|------|
| `SERPER_API_KEY` | — | Google Serper 搜索 key（搜索工具暂未迁到 UI） |
| `TAVILY_API_KEY` | — | Tavily 搜索 key（同上） |
| `JWT_SECRET` | — | JWT 签名密钥（生产推荐） |
| `MATECLAW_CORS_ALLOWED_ORIGINS` | — | CORS 白名单（生产推荐） |
| `DB_PASSWORD` / `DB_ADMIN_PASSWORD` | Docker | PostgreSQL 应用账号 / 引导管理员密码（必须不同） |
| `DB_USERNAME` / `DB_ADMIN_USERNAME` | — | PostgreSQL 应用账号 / 引导管理员账号 |
| `DB_HOST` / `DB_PORT` / `DB_NAME` | — | 数据库地址、端口与库名 |
| `SPRING_PROFILES_ACTIVE` | — | Docker Compose 自动设为 `postgres`；自管部署也可用 `mysql` / `kingbase` |

### 怎么设

**Linux / macOS：**

```bash
export JWT_SECRET=your-production-secret-at-least-32-chars
export SERPER_API_KEY=your-serper-key   # 可选
```

**Windows（PowerShell）：**

```powershell
$env:JWT_SECRET = "your-production-secret-at-least-32-chars"
```

**Docker（`.env` 文件）：**

```properties
DB_PASSWORD=secure-password-here
DB_ADMIN_PASSWORD=different-secure-password-here
JWT_SECRET=your-production-secret-at-least-32-chars
```

启动后到 `http://localhost:18080`，`admin / admin123` 登录，「设置 → 模型 → 添加供应商」配第一家 LLM。

---

## 数据库 schema 初始化

MateClaw 用 **Flyway** 管理 schema 迁移：

1. `db/migration/h2/V*__*.sql`——H2 方言的迁移脚本
2. `db/migration/mysql/V*__*.sql`——MySQL 方言的迁移脚本
3. 迁移完成后加载种子数据（`db/data-*.sql`），幂等执行

启动时 Flyway 根据 active profile 自动选择正确的方言路径。每次启动时先做一次 `repair`，再 `migrate`——checksum 变更和部分失败的迁移自动修复（对桌面端离线升级用户尤其重要）。

### 表约定

- 所有表前缀 `mate_`
- `snake_case` 列、`camelCase` Java 字段（MyBatis Plus 自动映射）
- 每张表都有 `create_time`、`update_time`、`deleted`
- 逻辑删除：`deleted = 0` 活跃，`deleted = 1` 软删除

### 开发模式下连 H2

[http://localhost:18088/h2-console](http://localhost:18088/h2-console)：

| 字段 | 值 |
|------|----|
| JDBC URL | `jdbc:h2:file:./data/mateclaw` |
| 用户名 | `sa` |
| 密码 | *（空）* |

### 切到 MySQL

```sql
CREATE DATABASE mateclaw CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
```

```bash
export SPRING_PROFILES_ACTIVE=mysql
export DB_PASSWORD=your-password
mvn spring-boot:run
```

---

## 运行时设置（`mate_system_setting`）

**不想重启就能改**的东西住在这里：

| Key | 类型 | 用途 |
|-----|------|------|
| `default_agent_id` | Long | 不指定时用的 Agent |
| `default_model_config_id` | Long | 默认模型配置 |
| `max_conversation_turns` | Integer | 每次对话的最大轮数 |
| `enable_memory` | Boolean | 启用记忆提取 |
| `search_enabled` | Boolean | 网页搜索工具的全局开关 |
| `search_provider` | String | `serper` / `tavily` / `duckduckgo` / `searxng` |
| `search_fallback_enabled` | Boolean | 失败时走下一个 provider |
| `serper_api_key` | String | Serper key（UI 脱敏） |
| `tavily_api_key` | String | Tavily key（UI 脱敏） |
| `language` | String | `zh-CN` / `en-US` 默认 UI 语言 |
| `stream_enabled` | Boolean | SSE 流式输出 |
| `debug_mode` | Boolean | UI 里显示额外调试信息 |

这些全都可以在 `设置 → 系统` 里编辑。改动**立刻生效不需要重启**。

### 搜索服务配置

网页搜索配置已从 `application.yml` 迁移到**系统设置**页面。改动立刻生效。

::: tip
API key 在 UI 里**脱敏显示**。保存时，**只有填了新值才会覆盖**。留空表示"保留已有的 key"。
:::

---

## 日志

```yaml
logging:
  level:
    vip.mate: INFO
    vip.mate.agent: DEBUG
    vip.mate.agent.graph: DEBUG
    org.springframework.ai: INFO
    root: INFO
```

深度排查时把 `vip.mate` 设成 `TRACE`。日志量很大——**生产环境别开着**。

---

## CORS

开发环境：Vite 开发服务器通过 proxy 处理。生产环境：前端内嵌在 JAR 里，不需要 CORS。

单独部署前端的话：

```yaml
mateclaw:
  cors:
    allowed-origins:
      - http://localhost:5173
      - https://your-domain.com
```

---

## 配置优先级

设置按以下顺序解析（**优先级从高到低**）：

1. **环境变量**
2. **命令行参数**（`--server.port=9090`）
3. **`application-{profile}.yml`**
4. **`application.yml`**
5. **数据库 `mate_system_setting`**（运行时可编辑的值）

---

## 下一步

- [模型配置](./models)——供应商和模型配置细节
- [安全与审批](./security)——JWT、Tool Guard、File Guard、审计日志
- [记忆系统](./memory)——记忆调优参数
- [LLM Wiki](./wiki)——`mate.wiki` 配置块
- [多渠道接入](./channels)——渠道特定配置