# 指示、核准與設定

設定寫作偏好、選擇助理何時詢問你，並設定可重複使用的專案規則。

為助理設定明確的寫作偏好，並選擇它如何處理變更。指示描述你想要的工作；核准控制項則決定哪些工具動作可以進行。

![設定 → AI 助理 → 指示。設定預設模型，寫下你的指示，再按儲存指示。PDF 頁面擷取選項位於文字欄位下方。](https://cdn.oleafly.com/images/screenshots/desktop/docs/settings-instructions-dark-window-v2.png#view=519,89,883,724)

## 預設對話模型

開啟 **設定 → AI 助理 → 指示**。選擇 **預設對話模型**，設定新聊天所使用的模型。清單中包含你已設定的供應商所啟用的模型。你仍然可以在個別對話中更改模型。

## 自訂指示

在 **自訂指示** 下輸入你的偏好，然後點選 **儲存指示**。研究稿件的一個實用起點如下：

```text title="寫作指示範例"
Use British English and preserve the terminology already used in the paper.
Keep citation keys, labels, equations, and numerical results unchanged unless
I explicitly ask you to edit them.
When a statement needs evidence, mark it for a source check. Do not invent
references or results.
Explain substantive changes briefly so I can review them.
```

讓這些指示具體到足以引導修訂，但不必重複整份專案簡介。它們是補充助理的內建行為，不會改變它的工具權限。

## 儲存指示

編輯後請點選 **儲存指示**。**已儲存** 指示器會確認已寫入。此欄位中尚未儲存的編輯不會成為你的新預設值。

## 允許 AI 擷取 PDF 頁面

啟用 **允許 AI 擷取 PDF 頁面**，讓助理可以用支援視覺的模型檢查算繪後的頁面。`verify_pdf_pages` 工具會把編譯後的頁面轉成點陣圖，以進行版面檢查。如果你不想把頁面影像傳送給已設定的供應商，請關閉此控制項。

## 查看工具目錄

在「指示」分頁中展開 **助理目前支援下列工具**。藉此查看助理能執行哪些工作，然後再要求一個成果，例如編譯某一節、檢查 PDF，或找出未解決的參照。

## 角色

![設定 → AI 助理 → 角色。「建立角色」位於清單上方；編輯與刪除控制項位在每個角色旁邊。](https://cdn.oleafly.com/images/screenshots/desktop/docs/settings-personas-dark-window-v2.png#view=519,89,883,902)

角色是有名稱的指示預設組。在 **設定 → AI 助理 → 角色** 下建立一個，然後在聊天輸入框中為特定類型的工作選用它。例如，可以保留一個簡潔的校對角色，以及另一個獨立的審稿人角色。

啟用中的角色會提供該對話的指示預設組，取代預設的自訂指示文字。角色也需要的任何常設偏好，請一併寫進去。角色只會改變引導內容，不會授予工具權限。

## 選擇核准模式

![開啟訊息輸入框下方的核准選單。所選的模式會以勾號顯示；請為你的專案選擇想要的政策。](https://cdn.oleafly.com/images/screenshots/desktop/docs/llama-approval-menu-dark-window-v2.png#view=1448,770,465,305)

使用聊天輸入框中的核准選擇器。你的選擇會儲存到目前的專案。

| 模式 | 行為 |
|---|---|
| **要求核准** | 歸類為讀取的工具可以執行；其他動作會先詢問 |
| **替我核准** | 讀取與網路工具可以執行；檔案變更與 shell 命令會先詢問 |
| **完整存取權** | 工具動作不需核准提示即可進行，但被 `deny` 規則封鎖的工具除外 |
| **自訂** | 套用已儲存的 `allow` 與 `deny` 規則，沒有規則的工具則使用標準風險政策 |

**替我核准** 是預設值。有些工具在運作過程中有自己的檢查。編譯與檢查 PDF 的處理方式，和寫入原始檔或執行 shell 命令不同。

## 核准建議的動作

在核准卡片上閱讀工具名稱與建議的操作。核准即可執行該動作；拒絕則不會套用建議的變更。如果要求的動作範圍太廣，可以用更窄的指示繼續對話。

## 此專案一律允許

在 **自訂** 模式下，於核准提示上使用 **此專案一律允許**，即可為該工具儲存一條規則。如果你預期某條規則會影響下一次執行，請先確認所選的模式。

## 檢視或移除規則

開啟專案後，前往 **設定 → AI 助理 → 供應商與金鑰**，捲動到 **工具核准**。每一列會顯示工具名稱，以及它是一律允許還是一律拒絕。移除規則後，該工具在自訂模式下會回到標準風險政策。

## 編輯 approvals.toml

位於 **工具核准** 下方的 **核准規則檔案** 用來編輯 `~/.oleafly/approvals.toml`。使用 **重新載入** 讀取目前的檔案，**捨棄變更** 放棄尚未儲存的編輯，或用 **插入範例** 從範例設定開始。**這個檔案如何運作** 會說明格式，並顯示目前開啟專案的 ID。儲存時會先驗證 TOML 再套用，規則從下一次工具呼叫起生效。

這個檔案有一個模式表，以及以 **專案資料夾 ID** 為鍵的工具規則表，而不是以顯示標題為鍵：

```toml title="~/.oleafly/approvals.toml"
["$approval_modes"]
"my-project-folder-id" = "custom"

["my-project-folder-id"]
write_file = "allow"
replace_in_file = "allow"
run_command = "deny"
delete_file = "deny"
```

請把 `my-project-folder-id` 換成你專案真正的資料夾 ID。專案 ID 就是 `~/.oleafly/projects` 底下的資料夾名稱。模式的值是 `ask-for-approval`、`approve-for-me`、`full-access` 和 `custom`。沒有列出的專案會使用「替我核准」。工具規則的值是 `allow` 和 `deny`。`deny` 規則在每種模式下都適用，包括完整存取權，所以被拒絕的工具絕不會執行。`allow` 規則只在自訂模式下適用。沒有規則的工具會使用一般風險政策。

以 `#` 開頭的註解在從設定儲存時會保留，但在核准卡片上選擇 **此專案一律允許** 會重寫檔案並移除這些註解。

請使用目錄中的確切工具名稱。常見名稱包括 `write_file`、`replace_in_file`、`create_file`、`rename_file`、`delete_file`、`run_command`、`compile`、`insert_figure` 和 `set_main_doc`。

## 我該使用哪個設定檔？

| 檔案 | 用途 |
|---|---|
| `~/.oleafly/config.json` | 應用程式設定，透過設定管理 |
| `~/.oleafly/approvals.toml` | 專案核准模式與各工具規則 |
| `~/.oleafly/agent.toml` | 進階的多代理程式限制與指示 |
| 你的外部代理程式設定，例如 `~/.codex/config.toml` | 該代理程式自己的設定與 MCP 連線 |

Oleafly 不會用單一的 `config.toml` 管理所有這些設定。供應商金鑰與應用程式偏好請使用設定介面；憑證另有獨立的加密儲存空間。請不要用簡短的範例取代你整份應用程式設定。

## 設定 agent.toml

進階使用者可以建立 `~/.oleafly/agent.toml`，調整助理的多代理程式設定。這些設定管理的是 Oleafly 自己的代理程式執行環境，與已連線 CLI 代理程式的設定是分開的。

```toml title="~/.oleafly/agent.toml"
maxAgentDepth = 2
maxConcurrentSubagents = 8
minWaitTimeoutMs = 1000
maxWaitTimeoutMs = 300000
defaultWaitTimeoutMs = 120000
waitAgentEnabled = true

usageHintText = """
Delegate independent checks with clear scopes. Keep writing decisions with
the parent agent, and close completed agents when their work is collected.
"""

subagentDeveloperInstructions = """
Work only on the assigned task. Report the files and evidence you inspected.
Do not spawn additional agents.
"""
```

### maxAgentDepth

限制巢狀深度。預設值是 `2`：一次執行的子代理程式不會再往下委派。可接受的最小值是 `1`。

### maxConcurrentSubagents

限制一個工作階段中同時執行的子代理程式數量。預設值是 `8`，最小值是 `1`。代理程式越多，模型用量可能越高；只有在工作確實可以各自獨立進行時，才調高這個上限。

### minWaitTimeoutMs

設定等待代理程式的下限，單位為毫秒。預設值是 `1000`。

### maxWaitTimeoutMs

設定等待代理程式的上限。預設值是 `300000`，也就是五分鐘。它不會低於最小值。

### defaultWaitTimeoutMs

設定預設的等待時間長度。預設值是 `120000`，也就是兩分鐘。數值會被限制在所設定的最小值與最大值之間。

### waitAgentEnabled

控制等待代理程式功能是否可用。預設值是 `true`。

### usageHintText

為父代理程式提供委派指引。上面的範例會用你自己的文字取代預設的指引。

### subagentDeveloperInstructions

為子代理程式提供指示。可用它說明範圍、回報的期望，以及是否適合再往下委派。

執行環境也接受這些鍵的 snake_case 寫法，例如 `max_agent_depth`。省略的欄位會使用預設值。檔案不存在或格式錯誤時，會退回預設值，所以請仔細檢查語法，並在變更設定後開始新的一次執行。

## 用小任務測試規則

1. 開啟一個練習專案，選擇 **要求核准**。
2. 提問：「請讀取主文件，並提出一個更清楚的標題。更改檔案之前先詢問我。」
3. 檢查建議的變更，然後核准或拒絕。
4. 切換到自訂模式之前，先在設定中檢視已儲存的規則。
5. 想在開始編輯之前先就幾個步驟達成共識時，請使用[計畫模式](/docs/ai-chat/#plan-before-editing)。

透過 Oleafly MCP 連線的外部助理，會使用 [MCP 伺服器的政策](/docs/mcp/#approvals-and-safety)，該政策是另外設定的。