# 指令、审批与配置

设置写作偏好，选择助手何时询问，并配置可复用的项目规则。

为助手提供清晰的写作偏好，并选择它如何处理更改。指令描述你想要的工作；审批控制决定哪些工具操作可以继续进行。

![设置 → 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)，该策略是单独配置的。