---
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="/zh-Hant/docs/gemini-cli/official/02-context-config/27-themes" />
  <Card title="GEMINI.md" description="大多數專案規則應該回到 GEMINI.md，而不是替換 system prompt。" href="/zh-Hant/docs/gemini-cli/official/02-context-config/21-gemini-md" />
  <Card title="Policy engine" description="企業級不可繞過規則，繼續看 policy engine 和安全控制。" href="/zh-Hant/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)
