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