---
title: "System prompt override"
description: "Gemini CLI system prompt override 的用途和风险：什么时候需要替换系统指令，什么时候应该只用 GEMINI.md 或 custom command。"
verifiedAt: "2026-05-09"
---

System prompt override 是高级能力，用来替换或强调整体行为逻辑。大多数项目不需要一开始使用它。

> [!IMPORTANT]
> **优先级建议**：项目规则先用 `GEMINI.md`，重复任务先用 custom command。只有确实要重定义整体行为时，才考虑 system prompt override。

## 适合场景

- 企业统一 agent 行为。
- 特殊安全模式。
- 专门环境的固定协作协议。
- 需要严格替换默认风格或默认流程。

## 启用方式

官方入口是环境变量 `GEMINI_SYSTEM_MD`。它是完整替换，不是和内置 system prompt 合并。

- `GEMINI_SYSTEM_MD=1` 或 `true`：读取当前项目的 `./.gemini/system.md`。
- `GEMINI_SYSTEM_MD=/absolute/path/to/system.md`：读取指定文件。
- `GEMINI_SYSTEM_MD=0`、`false` 或 unset：恢复内置 prompt。

如果变量启用但目标文件不存在，CLI 会报 `missing system prompt file '<path>'`。启用成功后，界面会显示自定义 system prompt 指示符。

官方界面会显示 `|⌐■_■|` 这类指示符，提醒当前不是默认 system prompt。教程截图里如果出现这个标记，必须解释原因；否则读者会以为自己的 Gemini CLI 和教程界面不一致。

## 推荐流程

先导出官方默认 prompt，再做局部修改：

```text
GEMINI_WRITE_SYSTEM_MD=1 gemini
```

这会把内置 prompt 写到项目默认路径。不要从空白文件开始重写，除非你确实要完全承担工具协议、安全规则和行为边界的维护成本。

也可以把 `GEMINI_WRITE_SYSTEM_MD` 指向绝对路径导出到其他文件，再做 diff 对比。正式启用前，保留一份未修改的官方导出版本，方便后续官方升级后重新对比。

## 可用变量

自定义 system prompt 可以插入 Gemini CLI 运行时内容：

- `${AgentSkills}`：注入可用 skill。
- `${SubAgents}`：注入可用 sub-agent。
- `${AvailableTools}`：注入当前启用工具名。
- `${write_file_ToolName}`、`${run_shell_command_ToolName}` 这类变量：注入具体工具名。

这些变量适合保持 prompt 和实际工具名同步，避免工具名变化后 system prompt 失效。

不要把这些变量删光后手写工具名。工具集、skill、subagent 会随版本和配置变化，手写列表很快过期。需要删变量时，要明确你是在刻意禁用某类能力，而不是为了让 prompt 看起来更短。

## 风险

- 和官方默认行为冲突。
- 让模型忽略某些内置安全提示。
- 增加排错难度。
- 多工具共存时容易规则打架。
- 完整替换后，官方更新的默认行为不会自动进入你的 prompt。

## 使用建议

把 system prompt 当“固件”，只放不可协商的工具协议、安全要求和运行机制；把 `GEMINI.md` 当“项目策略”，放业务背景、代码风格、测试命令和项目边界。先在低风险项目验证，再推广到真实项目。任何 override 都要写清楚目标、范围和验证方式。

| 需求 | 优先工具 | 不建议直接用 system prompt 的原因 |
| --- | --- | --- |
| 项目代码风格 | `GEMINI.md` | 规则应随项目走，方便审查 |
| 重复发布流程 | Custom command | 这是任务模板，不是全局行为协议 |
| 临时让回答更短 | 当前 prompt | 不值得改运行时底层指令 |
| 企业统一安全协议 | System prompt override | 需要全局固定且不可协商 |
| 特定 agent 角色 | Skill / subagent / command | 通常不需要替换所有默认行为 |

如果必须使用 override，先从官方默认 prompt 导出后局部修改，并保留变更说明。不要把系统 prompt 当作“更强的 GEMINI.md”，否则后续官方默认行为变化、工具名变化、安全提示变化都要由你自己维护。

## 回退路径

出现异常时优先回退环境变量，而不是继续改 prompt：unset `GEMINI_SYSTEM_MD` 后重启 CLI，确认问题是否消失。如果问题消失，再对比 system prompt diff；如果仍然存在，说明根因在 settings、工具或项目上下文。

团队使用时建议把启用命令、导出命令、回退命令写在同一份文档里。system prompt override 属于运行时底层变更，不适合只靠口头约定传播。

## 验收方式

启用后先让 Gemini CLI 输出它能使用哪些工具、哪些安全规则必须遵守，再跑一个只读任务和一个需要确认的工具任务。确认默认安全边界仍然存在后，才把它放进团队项目。

## 接下来去哪

<Cards>
  <Card title="Themes" description="系统行为边界确认后，继续看 UI 主题和展示配置。" href="/docs/gemini-cli/official/02-context-config/27-themes" />
  <Card title="GEMINI.md" description="大多数项目规则应该回到 GEMINI.md，而不是替换 system prompt。" href="/docs/gemini-cli/official/02-context-config/21-gemini-md" />
  <Card title="Policy engine" description="企业级不可绕过规则，继续看 policy engine 和安全控制。" href="/docs/gemini-cli/official/06-security-enterprise/61-policy-engine" />
</Cards>

## 官方来源

- [Gemini CLI system prompt override](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/system-prompt.md)
