附录 B · 配置键索引

Agentao 读取的所有开关——先看环境变量，再看磁盘上的 JSON。除非标注必填，其余均为可选。

B.1 环境变量

LLM 凭据

LLM_PROVIDER 选一个提供商前缀（默认 OPENAI）。其余三个键按 {PROVIDER}_API_KEY、{PROVIDER}_BASE_URL、{PROVIDER}_MODEL 读。

键	必填	默认	说明
`LLM_PROVIDER`	—	`OPENAI`	选择 `{PROVIDER}_*` 前缀；任意大写名均可（如 `DEEPSEEK`、`ANTHROPIC`、`GEMINI`）
`{PROVIDER}_API_KEY`	必填	—	构造器 `api_key=` 可覆盖
`{PROVIDER}_BASE_URL`	必填	—	构造器 `base_url=` 可覆盖；默认是 OpenAI 兼容端点，`{PROVIDER}_API_FORMAT=anthropic-messages` 时是 API 根（`https://api.anthropic.com`）
`{PROVIDER}_MODEL`	必填	—	构造器 `model=` 可覆盖；运行时可用 `agent.set_model()` 切换
`{PROVIDER}_API_FORMAT`	—	`openai-completions`	对该块的端点说哪种线路协议（0.5.0）：`openai-completions`、`anthropic-messages`（Anthropic 的 Messages API）或 `openai-responses`（OpenAI 的 Responses API，0.5.3）。从不推断 —— 不看 URL、provider 名、模型名；未知值在启动时抛错。`/provider` 读取目标块的这个值，所以在不同协议的块之间切换时线路也跟着换；子代理按父级当前的线路构建。在 `anthropic-messages` 上不发送 `LLM_TEMPERATURE`，扩展思考通过 `LLM_EXTRA_BODY` 打开。等价于构造器 `api_format=`。完整说明：`docs/reference/configuration.zh.md` §2

失败即止规则： LLMClient.__init__ 在启动时立即检查。若 {PROVIDER}_API_KEY、{PROVIDER}_BASE_URL 或 {PROVIDER}_MODEL 任一缺失且未通过构造器传入，直接抛 ValueError。/provider 列表与切换命令同样执行此校验——三者必须全部设置，provider 才会出现在列表中并允许切换。

全局运行时

键	默认	含义
`LLM_TEMPERATURE`	不设	采样温度（0.0–2.0）。不设 = 不发送，由 provider 默认值决定（0.5.7；此前为 `0.2`）。畸形值在启动时抛错
`LLM_MAX_TOKENS`	未设	单次调用的 LLM completion tokens 上限。畸形值在启动时抛错
`LLM_EXTRA_BODY`	未设	JSON 对象，原样转发给 LLM `.create()` 的 SDK `extra_body` —— `reasoning_effort` / `top_p` / `seed` / `response_format` / provider 专有字段的逃生舱。等价于构造参数 `extra_body=`。例：`LLM_EXTRA_BODY='{"reasoning_effort":"high"}'`。与上面两个不同，畸形或合法但非对象的值会告警并跳过（不致命）；空/纯空白当未设（静默）。日志中凭据键脱敏
`LLM_PROMPT_CACHE`	关闭	显式 prompt 缓存断点（0.4.26）：`anthropic`，或 `off` / 空 / 未设。开启后，每个 agent 回合的请求最多带 3 个 Anthropic 风格的 `cache_control` 标记 —— system 消息、最后一个工具定义、稳定历史的末尾。需显式开启，绝不从 base URL 或模型名推断：只对你已确认会转发这个键的端点设置。未知值在启动时抛错。等价于构造参数 `prompt_cache=`。开启前要在端点上确认的事项见 `docs/reference/configuration.zh.md` §2
`LLM_PROMPT_CACHE_TTL`	`5m`	上述标记的保留时长提示：`5m` 或 `1h`。`LLM_PROMPT_CACHE` 关闭时不读取 —— 连校验也不做。等价于构造参数 `prompt_cache_ttl=`
`AGENTAO_CONTEXT_TOKENS`	`200000`	上下文预算；超出触发压缩
`AGENTAO_WORKING_DIRECTORY`	—	启动时覆盖工作目录（等价于构造器 `working_directory=`）
`AGENTAO_SCRUB_CHILD_ENV`	开启	shell 与 MCP 子进程是否继承 agentao 自己的 provider 凭据。默认会把 `HARNESS_ENV_KEYS`（`OPENAI_API_KEY`、`ANTHROPIC_API_KEY`、`GEMINI_API_KEY`、`LLM_EXTRA_BODY`……）、`{LLM_PROVIDER}_API_KEY`，以及值等于本进程用过的 key 的任何变量（`/provider`、`set_provider()` 之后，或 `api_key=` 取自你自己的变量时；短于 16 个字符的值不匹配）从子进程环境剔除。设为 `0`/`false`/`no`/`off` 恢复完整继承——在 agent 自己的 shell 里跑 `agentao run` 或任何调用 provider 的脚本时需要。只剔除 agentao 自己的 key；`AWS_*`、`GITHUB_TOKEN`、`DATABASE_URL` 原样保留。见 `capabilities/process.py::build_child_env`

内置工具读取的第三方键

键	使用方	作用
`GITHUB_TOKEN`	技能目录抓取器	提升 GitHub API 频控上限
`BOCHA_API_KEY`	`web_search` 工具	使用 Bocha Search API（结果质量更高）。不设置时自动回退到 DuckDuckGo，无需账号。

MCP 服务器和自定义工具通常有自己的 env 键——写在 .agentao/mcp.json 或自定义工具代码里，不在此表。

B.2 优先级

每个设置：构造器参数 > 环境变量 > 磁盘 JSON > 硬编码默认值。

磁盘 JSON 的合并规则因配置面而异：

sandbox.json — 仅用户级。<cwd>/.agentao/sandbox.json 会被忽略并记 warning（仓库带的或 agent 写的 {"enabled": false} 会关掉沙箱）。
mcp.json — 两个文件都加载；同名冲突时用户胜，项目级是仅可新增的（可声明新 server name，但不能覆盖用户级同名条目；冲突时打 warning 并跳过）。
permissions.json — 仅用户级。<cwd>/.agentao/permissions.json 故意不加载（一条 checked-in {"tool": "*", "action": "allow"} 会因首个命中即返回而当场作废用户策略）。模式预设规则最后跑（在 full-access / plan 模式下预设最先跑且不可覆盖）。
memory.db — 项目与用户两个 store 独立读取；prompt 渲染器同时可见两者；项目并不覆盖用户。
acp.json、settings.json、skills_config.json、AGENTAO.md — 仅项目级；不做合并。

B.3 磁盘 JSON 文件

JSON 配置文件位于 .agentao/ 目录（项目位于 <working_directory>/.agentao/，用户位于 ~/.agentao/）；项目级 AGENTAO.md 位于项目根。各配置面的合并优先级见 B.2。任何文件都可缺省。

文件	作用域	章节	作用
`mcp.json`	项目（仅可新增） + 用户	5.3	MCP 服务器（stdio / Streamable HTTP / SSE）
`permissions.json`	仅用户（项目级文件被忽略）	5.4	单工具权限规则
`sandbox.json`	仅用户（项目级文件被忽略）	6.2	Shell 沙箱 profile
`acp.json`	仅项目	3.2	ACP 子智能体注册表（Agentao 作为客户端时）
`settings.json`	仅项目	6.6	持久化的权限模式、built-in agents 开关、replay 块
`skills_config.json`	仅项目	5.2	已禁用技能列表（用 `/skills disable` 管理）
`AGENTAO.md`（否则 `AGENTS.md`）	仅项目	5.6	项目专属指令，注入到 system prompt 顶端；只在没有 `AGENTAO.md` 时读 `AGENTS.md`
`memory.db`	项目 + 用户	5.5	SQLite 持久化记忆（非 JSON；此处完整列出）

B.3.1 `mcp.json`

json

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "."],
      "env": { "LOG_LEVEL": "info" },
      "trust": false,
      "timeout": 30
    },
    "remote": {
      "type": "sse",
      "url": "https://api.example.com/sse",
      "headers": { "Authorization": "Bearer $API_TOKEN" },
      "timeout": 60
    }
  }
}

字段：

字段	类型	说明
`type`	string	传输方式选择：`"stdio"` / `"http"` / `"sse"`（别名 `"streamable-http"` / `"streamable_http"` 归一为 `"http"`）。省略时按推断：`command` = stdio，裸 `url` = Streamable HTTP
`command`	string	stdio 服务器——与 `url` 互斥
`args`	string[]	stdio 参数
`env`	object	会做 `$VAR` / `${VAR}` 展开
`cwd`	string	stdio 子进程的 cwd
`url`	string	URL 传输的服务器 URL（Streamable HTTP 或 SSE）
`headers`	object	URL 传输的请求头（`$VAR` 展开）
`trust`	bool	该服务器的工具跳过确认。当 `true` 时，server 的 `ToolAnnotations`（`readOnlyHint`、`destructiveHint`）也会被读取；`destructiveHint=true` 会重新引入对该 op 的确认。`trust` 为 `false` 时注解被完全忽略。
`timeout`	number（秒）或 `{startup, request}`	写数字限制连接和握手（默认 60）；`request` 限制每次工具调用（无默认）

支持三种 MCP 传输：stdio、Streamable HTTP、SSE。裸 url 默认使用 Streamable HTTP；旧版 SSE 端点需显式设置 "type": "sse"。

B.3.2 `permissions.json`

json

{
  "rules": [
    { "tool": "run_shell_command", "args": { "command": "^git " }, "action": "allow" },
    { "tool": "run_shell_command", "args": { "command": "rm\\s+-rf" }, "action": "deny" },
    { "tool": "write_file", "action": "ask" },
    {
      "tool": "web_fetch",
      "domain": { "allowlist": [".github.com"], "url_arg": "url" },
      "action": "allow"
    }
  ],
  "shell": { "dialect": "powershell" }
}

两个顶层键：rules 与 shell。其余键会报出点名的错误，而不是被忽略。

规则字段：

字段	类型	必填	说明
`tool`	string	是	工具名；通过 `re.fullmatch` 按正则匹配（用 `"*"` 通配）
`args`	object	否	`<arg_name>` → 正则的映射；全部条目都要 `re.search` 命中规则才生效
`domain`	object	否	仅 URL 类工具（`web_fetch`）；键：`url_arg`（默认 `"url"`）、`allowlist`、`blocklist`。`.` 开头的模式做后缀匹配（如 `.github.com` 命中 `api.github.com`），否则精确匹配
`action`	string	是	`"allow"` \| `"deny"` \| `"ask"`（大小写不敏感）

shell 块（0.4.22 新增，用户级，仅 Windows）：

键	类型	必填	说明
`dialect`	string	否	`"posix"` \| `"cmd"` \| `"powershell"` —— 该解释器读的语法。命令地板按它扫描，提示词里的 shell 指引也按它写。单独给它就够了：`{"dialect": "powershell"}` 就是打开 PowerShell 的常规写法
`path`	string	否	指定解释器的绝对路径。必须与 `dialect` 成对出现 —— 单独给 `path` 报错，因为没有谁能从文件名推出语法

{"dialect": "powershell"} 会自动发现 pwsh.exe，其次 powershell.exe；两者都没有则报错，绝不静默回落到 cmd。什么都不配置时，Windows 仍旧是 %COMSPEC% /c，与过去完全一致。在 macOS / Linux 上显式选择 powershell 或 cmd 报不支持的平台配置错误。完整行为（含启动与编码）见 docs/reference/configuration.zh.md §4。

mode 字段不写在 permissions.json 里 — 它属于 settings.json（B.3.5），运行时通过 /permissions 切换。模式取值：read-only、workspace-write、full-access、plan（小写连字符；plan 为内部模式）。

求值顺序：

read-only / workspace-write：[用户规则] → [当前模式预设]，命中即停。在 read-only 下只作用于 is_read_only 为 True 的工具；其他工具在查任何规则之前就被拒绝。
full-access / plan：[当前模式预设] → [用户规则]，预设不可覆盖。
都未命中 → 回退到该工具的 requires_confirmation 属性。

项目级 <cwd>/.agentao/permissions.json 不会被加载 —— 见 B.2。

B.3.3 `sandbox.json`

~/.agentao/sandbox.json：

json

{
  "enabled": true,
  "platform": "darwin",
  "default_profile": "workspace-write",
  "rules": [],
  "profiles_dir": "~/.agentao/sandbox-profiles",
  "workspace_root": null
}

内置 profile：readonly、workspace-write-no-network、workspace-write。 失败即禁用：profile 文件缺失会抛 SandboxMisconfiguredError，shell 工具直接拒绝运行。

B.3.4 `acp.json`

仅在 Agentao 作为 ACP 客户端时读取：CLI 的 /acp 命令（CLI · /acp）或宿主的 ACPManager（3.4）。只有项目级（<project>/.agentao/acp.json）。服务器放在顶层 servers 对象下，不是 mcpServers。大部分集成无需关心。

servers.{name} 下的每服务器键：

键	类型	默认	说明
`command`	string	—	必填
`args`	list[str]	—	必填
`env`	dict	—	必填；`$VAR` / `${VAR}` 会被展开
`cwd`	string	—	必填；相对路径相对项目根解析
`autoStart`	bool	`true`	由 `ACPManager.start_all()` 读取。CLI 从不自动启动。Registry 条目写为 `false`
`startupTimeoutMs`	int	`10000`	等待 `initialize` 回应的时长，实际不少于 30 秒。Registry 条目写为 `120000`
`requestTimeoutMs`	int	`60000`	单个请求的超时，也限制 CLI 里一轮 `/acp send`
`maxRecoverableRestarts`	int	`3`	子进程可恢复死亡后的自动重启上限；首次成功对话后清零
`capabilities`	dict	`{}`
`description`	string	`""`
`nonInteractivePolicy`	`{"mode": "reject_all" \| "accept_all"}`	`{"mode": "reject_all"}`	结构化对象（Week 3）。历史裸字符串形式在配置加载阶段直接报错，迁移见附录 E。

B.3.5 `settings.json`

项目级运行时设置。从 <working_directory>/.agentao/settings.json 读取。包含四块：持久化的权限模式、built-in 子智能体开关、后台唤醒开关、replay 块。

json

{
  "mode": "workspace-write",
  "agents": {
    "enable_builtin": false
  },
  "background_agents": {
    "auto_wake": true
  },
  "replay": {
    "enabled": false,
    "max_instances": 20,
    "capture_flags": {
      "capture_llm_delta": true,
      "capture_full_llm_io": false,
      "capture_tool_result_full": false,
      "capture_plugin_hook_output_full": false
    }
  }
}

顶层键：

键	类型	默认	说明
`mode`	string	`"workspace-write"`（缺省时）	持久化的最近一次权限模式，用于恢复路径和 `/permissions` 查看。允许值：`"read-only"`、`"workspace-write"`、`"full-access"`。（`"plan"` 为内部模式，由 `/plan` 流程设置，用户不应直接写入。）
`agents.enable_builtin`	bool	`false`	启用内置子智能体集。历史顶层别名 `enable_builtin_agents`（bool）仍被识别。
`background_agents.auto_wake`	bool	`true`（缺省时）	仅交互式 CLI。CLI 停在空提示符上、有后台子代理的更新排队时，自动跑一轮读取更新，不必再手动输入 `continue`。正在输入、有暂存图片、或处于 plan 模式时不触发；连续唤醒 3 次后暂停，直到你提交一行输入。设为 `false` 关闭；其他值会报告并按 `true` 处理。

Replay 键：

键	类型	默认	说明
`replay.enabled`	bool	`false`	为后续 session 开启记录。`/replay on` 和 `/replay off` 会写这个值。
`replay.max_instances`	int	`20`	`.agentao/replays/` 下的保留上限；不影响 `.agentao/sessions/`。`true` / `false`、非数字或小于 1 的值会被忽略（改用 20，`agentao doctor` 报错）；数字字符串或带小数的值会被转换，`agentao doctor` 给出警告。
`replay.capture_flags.capture_llm_delta`	bool	`true`	记录每次 LLM 调用新增的 messages。
`replay.capture_flags.capture_full_llm_io`	bool	`false`	deep capture 完整 LLM 输入/输出；按敏感内容处理。
`replay.capture_flags.capture_tool_result_full`	bool	`false`	在普通 replay 截断策略之外，deep capture 完整工具结果。
`replay.capture_flags.capture_plugin_hook_output_full`	bool	`false`	deep capture plugin hook 输出。

settings.json 格式错误时会回退到安全默认值，不阻塞启动。

B.4 构造器参数对应表

上面每个 env 或 JSON 键，Agentao(...) 都有对应参数：

JSON / env	构造器
`{PROVIDER}_API_KEY`	`api_key=`
`{PROVIDER}_BASE_URL`	`base_url=`
`{PROVIDER}_MODEL`	`model=`
`{PROVIDER}_API_FORMAT`	`api_format=`
`AGENTAO_WORKING_DIRECTORY`	`working_directory=`
`AGENTAO_CONTEXT_TOKENS`	`max_context_tokens=`
`mcp.json`	`extra_mcp_servers=`（叠加在文件之上）
`permissions.json`	`permission_engine=`
`sandbox.json`	无直接参数——策略在工具调用时读
`settings.json` replay 块	无直接参数——用 `/replay on/off` 或直接编辑文件

构造器永远胜出。SaaS 宿主按租户注入配置而不改 env 时很有用。

→ 附录 D · 错误码

附录 B · 配置键索引 ​

B.1 环境变量 ​

LLM 凭据 ​

全局运行时 ​

内置工具读取的第三方键 ​

B.2 优先级 ​

B.3 磁盘 JSON 文件 ​

B.3.1 mcp.json ​

B.3.2 permissions.json ​

B.3.3 sandbox.json ​

B.3.4 acp.json ​

B.3.5 settings.json ​

B.4 构造器参数对应表 ​

附录 B · 配置键索引

B.1 环境变量

LLM 凭据

全局运行时

内置工具读取的第三方键

B.2 优先级

B.3 磁盘 JSON 文件

B.3.1 `mcp.json`

B.3.2 `permissions.json`

B.3.3 `sandbox.json`

B.3.4 `acp.json`

B.3.5 `settings.json`

B.4 构造器参数对应表