---
title: "Settings"
description: "Gemini CLI settings.json 的职责、用户级和项目级配置边界，以及模型、工具、MCP、checkpoint、权限等配置应该怎么放。"
verifiedAt: "2026-05-09"
---

`settings.json` 是 Gemini CLI 的行为配置入口。它适合放模型、工具、MCP、checkpoint、权限、UI 和其他 CLI 行为开关。

> [!IMPORTANT]
> **不要把项目规则和行为开关混在一起**：项目规则优先写 `GEMINI.md`，CLI 行为开关写 `settings.json`。

## 配置入口

Gemini CLI 可以通过 `/settings` 图形化编辑设置，也可以直接改 JSON 文件。官方路径是：

- 用户级：`~/.gemini/settings.json`
- 工作区级：`<project>/.gemini/settings.json`

工作区级会覆盖用户级。这个规则决定了团队项目的推荐做法：个人偏好放用户级，项目约束放仓库内 `.gemini/settings.json`。

| 层级 | 适合放什么 | 不适合放什么 |
| --- | --- | --- |
| 用户级 `~/.gemini/settings.json` | 主题、个人默认模型、通知、Vim mode | 团队必须共享的 MCP 和权限策略 |
| 项目级 `.gemini/settings.json` | MCP server、审批模式、上下文文件名、安全边界 | 个人 token、本机路径、私有账号信息 |
| 临时 CLI 参数 | 一次性模型、输出格式、当前任务的 sandbox 设置 | 长期团队规范 |

## 常见配置领域

- `general.defaultApprovalMode`：默认工具审批模式。日常项目用 `default`，只读规划用 `plan`，不要把 `yolo` 当团队默认值。
- `model.name`、`model.maxSessionTurns`、`model.compressionThreshold`：模型、会话轮数和上下文压缩阈值。
- `context.fileName`：自定义上下文文件名，比如同时读取 `AGENTS.md`、`CONTEXT.md`、`GEMINI.md`。
- `context.fileFiltering.respectGitIgnore`：是否让上下文检索尊重 `.gitignore`。
- `mcpServers`：项目 MCP 入口，适合放需要随项目一起共享的服务定义。
- `security.*`：YOLO 禁用、永久授权、扩展来源、文件夹信任、环境变量脱敏等安全开关。
- `telemetry.*`：OpenTelemetry、本地日志或 Google Cloud telemetry 相关设置。
- `ui.*`：主题、页脚、模型信息、上下文百分比、可访问性等显示行为。

## 放置策略

用户级设置只放“我个人在哪个项目都想要”的偏好，例如主题、Vim mode、通知、默认模型。项目级设置只放“换一个人拉仓库也应该一致”的约束，例如 MCP server、工具审批、上下文文件名、安全边界、checkpoint 策略。

密钥不要写进 `settings.json`。Gemini API key、Google Cloud project、Vertex AI 开关这类运行差异，用环境变量或本机凭据管理。`settings.json` 进仓库前要按公开资产标准复查，避免把账号、路径、内部服务地址泄露出去。

## 最小项目模板

真实项目可以先从小模板开始：

```json
{
  "general": {
    "defaultApprovalMode": "default"
  },
  "context": {
    "fileName": ["GEMINI.md"]
  },
  "security": {
    "disableYoloMode": true
  }
}
```

需要团队共享 MCP 时，再补 `mcpServers`。需要自动化时，再补 `output.format`、headless 参数或 telemetry。不要一次复制官方完整 reference；字段越多，排错越难。

## 改配置的顺序

配置改动建议按这个顺序推进：

1. 先确定这是个人偏好还是项目约束。
2. 再决定写用户级、项目级，还是只用本次 CLI 参数。
3. 修改后重启或重新进入 Gemini CLI。
4. 用 `/settings` 检查最终生效值。
5. 用一个最小任务触发相关行为，确认不是只写了文件但没有生效。

如果配置项涉及安全、MCP、工具审批或 telemetry，不要只看 JSON 是否合法。必须实际触发一次对应能力：比如让工具请求 shell 执行、查看 MCP server 列表，或确认 telemetry 目标没有把私有内容打出去。

## 验收方式

改完后重启 Gemini CLI，进入项目目录运行 `/settings` 检查实际生效值。再让 Gemini CLI 执行一个只读任务，确认它加载的是项目级 MCP、项目级上下文文件名和预期审批模式。涉及安全项时，用一个会触发工具调用的任务验证是否仍然要求确认。

## 接下来去哪

<Cards>
  <Card title="GEMINI.md" description="配置负责行为开关，项目规则继续沉淀到 GEMINI.md。" href="/docs/gemini-cli/official/02-context-config/21-gemini-md" />
  <Card title="Memory management" description="继续看哪些长期事实该进 memory，哪些只该写项目文件。" href="/docs/gemini-cli/official/02-context-config/22-memory-management" />
  <Card title="Sandbox" description="安全相关设置要和 sandbox、approval mode 一起验证。" href="/docs/gemini-cli/official/06-security-enterprise/60-sandbox" />
</Cards>

## 官方来源

- [Gemini CLI settings](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/settings.md)
- [Gemini CLI configuration reference](https://github.com/google-gemini/gemini-cli/blob/main/docs/reference/configuration.md)
