系统提示重写（GEMINI_SYSTEM_MD）

系统提示重写（GEMINI_SYSTEM_MD）

指导 Gemini CLI 的核心系统指令可以完全用您自己的 Markdown 文件替换。此功能通过 GEMINI_SYSTEM_MD 环境变量进行控制。

概述

GEMINI_SYSTEM_MD 变量指示 CLI 使用外部 Markdown 文件作为其系统提示，完全覆盖内置的默认提示。这是一个完整的替换，不是合并。如果您使用自定义文件，除非您自己包含，否则原始的核心指令都不会适用。

此功能适用于需要强制实施严格的项目特定行为或创建自定义角色的高级用户。

提示：您可以将当前的默认系统提示导出到文件中，先进行审查，然后选择性地修改或替换它（请参阅“导出默认提示”）。

如何启用

您可以在您的 shell 中临时设置环境变量，或者通过 .gemini/.env 文件持久化它。请参阅Persisting Environment Variables。

• 使用项目默认路径（.gemini/system.md）：

  • GEMINI_SYSTEM_MD=true 或 GEMINI_SYSTEM_MD=1
  • CLI 读取 ./.gemini/system.md（相对于您当前的项目目录）。

• 使用自定义文件路径：

  • GEMINI_SYSTEM_MD=/absolute/path/to/my-system.md
  • 支持相对路径，从当前工作目录解析。
  • 支持波浪线扩展（例如，~/my-system.md）。

• 禁用重写（使用内置提示）：

  • GEMINI_SYSTEM_MD=false 或 GEMINI_SYSTEM_MD=0 或取消设置变量。

如果启用了重写，但目标文件不存在，CLI 将会报错：missing system prompt file '<path>'。

快速示例

• 一次性会话使用项目文件：
  • GEMINI_SYSTEM_MD=1 gemini
• 为项目持久化使用 .gemini/.env：
  • 创建 .gemini/system.md，然后添加到 .gemini/.env：
    • GEMINI_SYSTEM_MD=1
• 在您的家目录下使用自定义文件：
  • GEMINI_SYSTEM_MD=~/prompts/SYSTEM.md gemini

UI 指示器

当 GEMINI_SYSTEM_MD 激活时，CLI 在 UI 中显示一个 |⌐■_■| 指示器，以表示自定义系统提示模式。

导出默认提示（推荐）

在覆盖之前，导出当前的默认提示，以便您可以查看所需的安全和工作流规则。

• 将内置提示写入项目默认路径：
  • GEMINI_WRITE_SYSTEM_MD=1 gemini
• 或者写入自定义路径：
  • GEMINI_WRITE_SYSTEM_MD=~/prompts/DEFAULT_SYSTEM.md gemini

这将创建文件并将当前的内置系统提示写入其中。

最佳实践：SYSTEM.md 对比 GEMINI.md

• SYSTEM.md（固件）：
  • 不可协商的操作规则：安全、工具使用协议、审批和保持 CLI 可靠的机制。
  • 在任务和项目之间保持稳定（或者在需要时按项目）。
• GEMINI.md（策略）：
  • 人设、目标、方法学和项目/领域上下文。
  • 每个任务都会演变；依赖 SYSTEM.md 以确保安全执行。

保持 SYSTEM.md 在安全和工具操作方面简洁但完整。让 GEMINI.md 专注于高级指导与项目细节。

故障排除

• 错误：missing system prompt file '…'
  • 确保引用的路径存在且可读。
  • 对于 GEMINI_SYSTEM_MD=1|true，在您的项目中创建 ./.gemini/system.md。
• 覆盖未生效
  • 确认变量已加载（使用 .gemini/.env 或在您的 shell 中导出）。
  • 路径从当前工作目录解析；尝试使用绝对路径。
• 恢复默认值
  • 取消设置 GEMINI_SYSTEM_MD 或将其设置为 0/false。