# Settings Guide Skill

> 当用户问 OpenLoaf 桌面端产品内的设置、偏好、API key、模型切换、主题 / 语言 / 快捷键 / 代理 / 备份、或相关故障（key invalid、model not found）该在哪配置、怎么配置时触发。**不用于**：项目里的代码配置文件如 tsconfig / .env（→直接用 Read/Edit）、一般编程问题（→直接回答）、系统级 OS 设置。

- Skill: `openloaf/settings-guide-skill` (Agent Skill)
- Install (CLI): `npx skillmds@latest add openloaf/settings-guide-skill`
- Raw SKILL.md: https://api.skillmd.com/api/skills/openloaf/settings-guide-skill/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: openloaf (https://skillmd.com/u/openloaf)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/openloaf/settings-guide-skill

---


# 设置引导（无直接工具）

## 工具清单

本 skill **无直接工具**。作用是告诉用户在桌面端 UI 中去哪里完成设置操作，并解释配置项背后的原理 — 相当于一份内置的可搜索产品手册。

## 配置地图

用户想改什么 → 告诉他去哪里：

| 需求 | 路径 |
|------|------|
| 语言/主题/快捷键 | 设置 → 基础设置 |
| 添加/编辑 AI Provider | 设置 → AI 模型 → Provider 管理 |
| 配置 API Key | 设置 → AI 模型 → 对应 Provider → 编辑 |
| 切换默认模型 | 设置 → AI 模型 → 模型选择 |
| 添加自定义模型 | 设置 → AI 模型 → 自定义模型（需兼容 OpenAI API 格式） |
| 项目路径/Git 设置 | 设置 → 项目 |
| 临时存储路径 | 设置 → 基础设置 → 临时存储路径 |
| 代理/Proxy 设置 | 设置 → 基础设置 → 网络代理 |
| 数据导出 | 设置 → 基础设置 → 数据管理 → 导出 |
| 备份与恢复 | 设置 → 基础设置 → 数据管理 → 备份 |
| 存储空间查看 | 设置 → 基础设置 → 存储空间 |

**兜底规则**：如果用户的需求不在上表中，引导用户到设置首页并使用搜索功能定位具体选项。

## 故障排查决策树

```
AI 无响应 / 报错
├── "API key invalid" → 设置 → AI 模型 → 检查对应 Provider 的 Key
├── "model not found" → Provider 的 baseURL 是否正确？自定义模型 ID 是否匹配？
├── 能发送但无回复 → 检查网络 / 代理设置，确认 Provider 服务可达
└── 回复乱码 → 换一个支持中文的模型

邮件/日历不工作
├── 未显示 → 设置中确认已启用对应账户
└── 同步失败 → 账户授权可能过期，重新授权

终端不工作
├── 无法打开 → 检查终端路径设置是否正确（设置 → 基础设置 → 终端）
├── 命令执行失败 → 确认 shell 路径和环境变量配置
└── 显示异常 → 尝试重启终端会话或清除终端缓存

编辑器问题
├── 无法保存 → 检查文件权限和磁盘空间
├── 语法高亮失效 → 确认文件类型识别正确，尝试手动选择语言模式
└── 代码补全不工作 → 确认 AI 模型配置正常，检查网络连接

文件管理器问题
├── 目录不显示 → 检查项目路径设置（设置 → 项目）
├── 文件操作失败 → 确认文件系统权限
└── 搜索无结果 → 确认搜索范围和索引状态

界面问题
├── 语言没切换 → 刷新页面或重启应用（缓存未更新）
├── 主题不生效 → 确认未设为"跟随系统"导致覆盖
└── Widget 加载失败 → 使用 WidgetCheck 查看编译错误
```

## 必须遵守的安全原则

- **绝不在对话中展示 API Key**。为什么？对话内容可能被日志记录或屏幕共享暴露。引导用户去设置 UI 中查看/修改。
- **Provider 变更后建议重启**。为什么？模型连接池在启动时初始化，运行时切换 Provider 可能不会立即生效。
- **模型切换影响全局**。切换默认模型会影响所有新对话，建议用户先在新对话中测试效果。

## 隐私说明（用户问及时告知）

- 所有数据本地存储（SQLite），不上传云端
- API Key 加密存储在本地数据库
- 仅在调用 AI API 和邮件/日历同步时联网

## 常见错误示范

| 错误回答 | 正确回答 |
|---------|---------|
| "去设置里找找看" | "设置 → AI 模型 → Provider 管理 → 点击对应 Provider → 编辑 API Key" |
| "你可以在设置中调整" | "设置 → 基础设置 → 网络代理，填入你的代理地址（如 http://127.0.0.1:7890）" |
| "应该能在某个地方改" | "设置 → 基础设置 → 主题，选择「深色」即可切换深色模式" |

## 回答策略

1. 先明确用户想改什么 → 查上方配置地图
2. 给出具体路径，不要说"去设置里找找"
3. 如果是排障 → 走决策树，逐步缩小范围
4. 涉及 API Key → 只说"请在设置 UI 中操作"，不要求用户贴 Key