System prompt override

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，再做局部修改：

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 都要写清楚目标、范围和验证方式。

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

回退路径

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

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

验收方式

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

接下来去哪

官方来源

• Gemini CLI system prompt override