# 03 · 首次启动配置

第一次跑起来后，桌宠窗口是空的、聊天面板提示「请先到配置中心填写 API key」。下面按顺序做三件事就完事了。

## 1. 准备 Live2D 模型文件

EzVibeR+ 不带任何 Live2D 模型，**需要你自己准备**。

### 1.1 模型目录结构

把模型文件（一般是 `.moc3` + `*.model3.json` + textures + motions + expressions）放在任意一个本地目录，比如：

```
~/Live2D-Models/
  ├── shizuku/
  │   ├── shizuku.moc3
  │   ├── shizuku.model3.json
  │   ├── textures/
  │   ├── motions/
  │   └── expressions/
  ├── march7th/
  │   ├── ...
  └── ...
```

> 一个模型子目录里**至少**要有 `<name>.moc3` 和 `<name>.model3.json`。

### 1.2 在配置中心设置模型目录

1. **右键系统托盘图标** → 选 **「配置中心」**
2. 在顶部 **「本地模型路径」** 框旁边点 **「选择本地模型」**，选你那个 `~/Live2D-Models` 根目录
3. 弹窗问"模型目录变更，需要重启软件!!!" → 点 **确认**，软件会自动重启
4. 重启后桌宠窗口会出现第一个模型（**随机选** `model3.json` / `model.json` 之一）

> ⚠️ **改模型目录必须重启**，因为 web_server 在启动时绑定到那个目录下的文件。

### 1.3 多模型 / 换模型

- **加网络模型**：在配置中心点 **「添加网络模型」**，粘贴 URL（多个用逗号分隔）。例如：
  ```
  https://cdn.jsdelivr.net/gh/guansss/pixi-live2d-display/test/assets/shizuku/shizuku.model.json
  ```
- **随机换一个**：在桌宠窗口右侧浮动工具栏上点 **👁 眼睛** 按钮
- **手动加载某个**：在配置中心的模型列表里点 **「加载」**

> 💡 模型列表会从你 `model_dir` 里**所有子目录**的 `*.model3.json` / `*.model.json` / `index.json` 自动收集。

## 2. 配置 LLM（可选但强烈推荐）

不配 LLM 也可以跑，但聊天面板只能看到桌宠自己的本地提醒气泡。

### 2.1 打开 LLM 设置

配置中心 → 下滑到 **「🤖 LLM 对话设置」** 区。

| 字段 | 必填 | 说明 |
|---|---|---|
| **Provider** | ✅ | `openai`（含 OpenAI 兼容服务）或 `anthropic` |
| **Model** | ✅ | 模型名，例如 `gpt-4o-mini` / `claude-3-5-sonnet-20241022` / `deepseek-chat` |
| **API Key** | ✅ | 你的 API key |
| **Base URL** | 可选 | 默认 `https://api.openai.com`（OpenAI）或 `https://api.anthropic.com`（Anthropic）。自部署网关改成对应 URL，比如 `http://localhost:11434/v1`（ollama 兼容）/ `https://api.deepseek.com/v1` |

填完点 **「保存 LLM 配置」**。

> ⚠️ **改完必须重启软件**。LLM 客户端在启动时一次性创建，不监听配置文件变更。

### 2.2 我能接哪些服务？

任意实现 **OpenAI Chat Completions 协议** 或 **Anthropic Messages 协议** 的服务都行：

| Provider 选项 | 兼容服务举例 |
|---|---|
| `openai` | OpenAI 官方、Azure OpenAI、OpenRouter、DeepSeek、Moonshot、智谱 GLM（兼容端点）、自部署 vLLM / Ollama（`/v1` 端点） |
| `anthropic` | Anthropic 官方 Claude |

### 2.3 验证配置

重启后在聊天面板顶部应该看到状态点变绿，文字变成 `openai / gpt-4o-mini` 之类的当前模型。发条消息测一下。

> ❌ 状态点红色 = **API key 未配置**
> 🟠 状态点橙色 = **正在思考（LLM 调用中）**
> 🟢 状态点绿色 = **就绪**

详细 LLM 配置（含错误码解释、协议差异）见 [07-LLM对话.md](07-LLM对话.md)。

## 3. 桌面提醒行为（默认已可）

健康提醒的默认规则在第一次启动时**自动写好**：

| 名称 | 触发频率 | 备注 |
|---|---|---|
| `remind_water` | 90 秒 | **当前是开发用短间隔**，生产请改成 45 分钟（2700 秒） |
| `remind_stretch` | 180 秒 | 同上，建议改 60 分钟（3600 秒） |
| `remind_test` | 120 秒 | 用于验证系统通知是否生效，触发时弹个"测试通知" |

调整方法见 [06-健康提醒.md](06-健康提醒.md)。

## 4. 检查清单

- [ ] 桌宠窗口能看见 Live2D 模型
- [ ] 右键托盘能看到「显示/隐藏/配置/健康提醒/关闭」5 项
- [ ] 点桌宠身体触发截图（气泡出现，附带预览图）
- [ ] 聊天面板能打字、能切换会话、能搜索、能导出
- [ ] 等 1-2 分钟看会不会自动弹一条提醒气泡 + 系统通知
- [ ] 改了 LLM Key 后发消息能收到回复

## 5. 配置文件长啥样

主配置存在 `~/.live2D/live2d.conf.json`（**注意大小写 D**，Linux 大小写敏感）。改完不一定需要重启——但**改 LLM 相关字段必须重启**。

```jsonc
{
  "port": 0,                            // web_server 端口（0=系统分配）
  "model_dir": "/home/you/Live2D-Models",
  "width": 600,                          // 桌宠窗口宽
  "height": 480,                         // 桌宠窗口高
  "x": 100, "y": 120,                    // 桌宠窗口位置
  "check_update": false,                 // 启动时检查更新
  "remote_list": [],                     // 远程模型 URL 列表
  "model_block": true,                   // 桌宠背景半透明遮罩（视觉）
  "auto_start": false,                   // 开机自启
  "memory_enabled": true,                // RAG 记忆（实际不生效，见 FAQ）
  "llm_provider": "openai",
  "llm_model": "gpt-4o-mini",
  "llm_api_key": "sk-...",
  "llm_base_url": "https://api.openai.com",
  "behaviors": [ ... ]                   // 健康提醒规则列表
}
```

> 改坏就删掉这个文件，会自动重建默认值。

---

下一步：[04-桌宠窗口使用.md](04-桌宠窗口使用.md) — 开始玩桌宠。