URL: /guide/settings-reference

---
title: 配置文件参考
---

`.zapmyco/settings.toml` 是 Zapmyco 核心配置文件，**必须存在**才能运行 AI 相关命令。

> - macOS/Linux: `~/.zapmyco/settings.toml`
> - Windows: `%USERPROFILE%\.zapmyco\settings.toml`
>
> 若文件不存在，请先运行 `zapmyco init` 生成。

## 完整示例

```toml
[llm]

[llm.providers.deepseek]
apiKey = "${env.DEEPSEEK_API_KEY}"

[llm.providers.glm]
apiKey = "${env.GLM_API_KEY}"

[llm.models]
default = "deepseek-v4-flash"
advanced = "deepseek-v4-pro"
```

## 字段参考

### `[llm]`

LLM 配置总入口，所有供应商和模型设置均在此下定义。

| 字段 | 类型 | 必填 | 说明 |
|------|------|:----:|------|
| `providers` | 表 | 否 | AI 供应商 API 密钥配置 |
| `models` | 表 | 否 | 模型名称到内置模型的映射表 |

### `[llm.providers.<name>]`

供应商配置。`<name>` 由你自定义，例如 `deepseek`、`glm`。

| 字段 | 类型 | 必填 | 说明 |
|------|------|:----:|------|
| `apiKey` | 字符串 | 否 | API 密钥。支持 `${env.VAR}` 语法引用环境变量 |

### `[llm.models]`

模型配置档映射。**键**是你自定义的配置档名称（如 `default`），**值**是内置模型的名称。

```toml
[llm.models]
default = "deepseek-v4-flash"
advanced = "deepseek-v4-pro"
```

通过 CLI 选择配置档：

### `[permissions.commands]`

命令权限配置（白名单/黑名单）。匹配白名单的命令跳过用户确认直接执行，匹配黑名单的命令自动拒绝。

| 字段 | 类型 | 必填 | 说明 |
|------|------|:----:|------|
| `allow` | 字符串数组 | 否 | 自动放行的命令前缀列表（白名单） |
| `deny` | 字符串数组 | 否 | 自动拒绝的命令前缀列表（黑名单，优先于 allow） |

**匹配规则**：命令以列表中的条目开头即匹配（前缀匹配）。
例如 `"git status"` 会匹配 `git status`、`git status -s`、`git status --short` 等。

**黑名单优先**：如果一个命令同时匹配 allow 和 deny 列表，deny 优先生效。

**安全机制**：即使前缀匹配，如果命令中包含 `;` `|` `>` `<` `` ` `` `$` `&` 等 shell 控制运算符，
仍会要求用户确认，防止通过重定向/管道/命令链绕过安全检查。

**示例**：
```toml
[permissions.commands]
allow = [
    "git status",
    "git diff",
    "git log",
    "cargo check",
    "cargo clippy",
    "cargo fmt --check",
]
deny = [
    "rm -rf",
    "sudo",
]
```

> 内置已有绝对安全命令列表（`pwd`、`whoami`、`echo`、`ls`、`uname` 等），无需在 allow 中重复配置。
> allow 仅用于扩展内置列表之外的自定义命令。

```bash
zapmyco run --profile advanced '你的问题'
```

## `${env.VAR}` 语法

配置文件中可直接引用环境变量，避免在文件中明文存储密钥：

```toml
apiKey = "${env.DEEPSEEK_API_KEY}"
```

运行时 Zapmyco 会自动将 `${env.DEEPSEEK_API_KEY}` 替换为环境变量 `DEEPSEEK_API_KEY` 的值。

> 使用 `zapmyco settings` 查看配置时，环境变量引用会原样显示（不会脱敏），而明文密钥会被脱敏：`sk-***abcd`。

## 内置模型列表

Zapmyco 内置了 8 个供应商共 22 个模型，全部支持 Anthropic Messages API 格式：

| 供应商 | 模型数 | 代表模型 |
|--------|:------:|----------|
| DeepSeek | 2 | `deepseek-v4-flash`（推荐） |
| Anthropic | 4 | `claude-sonnet-4-6` |
| Qwen（通义千问） | 3 | `qwen3.7-max` |
| MiniMax | 3 | `MiniMax-M3`（1M 上下文，支持视觉） |
| GLM（智谱） | 4 | `glm-5.1` |
| Kimi（月之暗面） | 2 | `kimi-k2.6` |
| Doubao（火山引擎） | 2 | `doubao-seed-2-0-pro` |
| MIMO（小米） | 2 | `mimo-v2.5-pro` |

查看完整列表和详细信息：[内置模型](/guide/models)

## 配置优先级

Zapmyco 按以下顺序确定最终使用的配置（高优先级覆盖低优先级）：

1. **CLI 显式参数**（如 `--profile`）
2. **settings.toml** 中的值
3. **环境变量**（如 `DEEPSEEK_API_KEY`）
4. **内置默认值**（模型 `deepseek-v4-flash`）

## 相关命令

| 命令 | 说明 |
|------|------|
| `zapmyco init` | 交互式初始化向导，自动生成 settings.toml |
| `zapmyco settings` | 显示当前配置（密钥已脱敏） |
| `zapmyco settings path` | 显示 settings.toml 文件路径 |

## FAQ

### 为什么选择 TOML 而不是 JSON 或 YAML？

Zapmyco 最早使用 JSON 作为配置格式，在 v0.23.0 迁移到了 TOML，主要考虑：

| 对比项 | JSON | YAML | TOML |
|--------|:----:|:----:|:----:|
| 注释支持 | ❌ 不支持 | ✅ 支持 | ✅ 支持 |
| 键名引号 | 必须用 `"` | 不需要 | 不需要 |
| 缩进敏感 | ❌ | ✅ 是（容易出错） | ❌ |
| 类型系统 | 有限 | 丰富但有歧义 | 清晰且明确 |
| Rust 生态集成 | 需 serde_json | 需 serde_yaml | 原生 `toml` + serde |

TOML 在保持简洁可读的同时，避免了 YAML 的缩进陷阱，也补上了 JSON 缺少注释的短板，与 Rust/serde 生态的集成也十分成熟。