A local-first multi-agent app development platform, built on PenguinHarness
title: 配置参考 description: Adelie 的每一项设置及其默认值与限制,从环境变量到 Project、Agent、记忆、密钥保险柜和定时任务文件。
Adelie 的配置分三层:环境变量决定部署形态,Project 配置管理模型和凭证,Agent 配置定义单个 Agent 的行为。每个 Agent 还有自己的记忆、Vault 和定时任务状态文件。
环境变量
CLI 和服务器启动时会从工作目录加载 .env 文件。
| 变量 | 说明 | 默认值 |
|---|---|---|
ADELIE_HOME |
数据根目录 | ~/.adelie/data |
PORT |
Web 服务监听端口 | 7364 |
HOST |
Web 服务监听地址 | 127.0.0.1 |
ADELIE_WEB_DB |
服务器 SQLite 数据库路径 | <root>/web.db |
ADELIE_WEB_DIST |
前端静态资源目录 | 服务器包自带的 web-dist(源码检出中为 packages/web/dist) |
ADELIE_PREVIEW_ORIGIN |
提供 Workspace HTML 预览的源,例如 https://preview.example.com |
未设置:每次请求推导对应的回环地址 |
PENGUIN_GO_ORIGIN |
服务端发起 Penguin Go Key 授权时调用的可信源 | https://token.penguin.ooo |
MODELSCOPE_BRIDGE_URL |
服务端发起 ModelScope Key 授权时调用的授权中转层地址 | https://go.penguin.ooo/modelscope |
ADELIE_TRUST_PROXY |
设为 1 时信任 x-forwarded-proto 请求头 |
未设置:忽略请求头 |
ADELIE_SEED_ADMIN_PASSWORD |
预置内置管理员的固定初始密码(自动化测试 / e2e) | 未设置:生成随机密码 |
ADELIE_LANG |
CLI 语言(en / zh),用 penguin config lang 设置 |
en |
ADELIE_UPDATE_CHECK |
设为 off 时关闭 Web App 的新版本检查 |
启用 |
ADELIE_PLUGIN_MARKET |
设为 off 时插件市场只列出本次构建自带的插件,不查询 npm |
启用 |
PENGUIN_NO_LOGIN_SHELL_ENV |
设为任意非空值后,桌面应用在 macOS/Linux 上从图形界面启动时不再导入登录 shell 的环境变量 | 未设置:照常导入 |
ADELIE_SHELL |
运行 Agent 命令的 shell(可执行文件名或路径) | 未设置:自动选择,见工具与审批 |
ADELIE_CLI_ENTRY |
本安装提供给所运行 Agent 的 CLI 入口脚本(见 PATH 启动脚本) | 由 penguin server / penguin web 和桌面应用设置 |
说明:
- 旧拼写: 数据根与部署接线(
ADELIE_HOME、ADELIE_PROFILE、ADELIE_WEB_DIST、ADELIE_WEB_DB、ADELIE_CLI_ENTRY、ADELIE_PORT_FILE、ADELIE_DESKTOP_TOKEN、ADELIE_BUNDLED_SHELL)同时仍按改名前PENGUIN_*的拼写读取,两个都设置时新名优先(packages/core/src/state/boundary-env.ts)。上表其余变量是 Adelie 自己的,没有兼容别名:旧拼写不再被读取。 ADELIE_TRUST_PROXY:只在反向代理终结 TLS、并由代理自己设置或清除这个请求头时启用。启用后,会话 Cookie 会带上Secure标记,热更新的网络检查也能识别出 HTTPS。ADELIE_SEED_ADMIN_PASSWORD:不设置时,预置管理员时会生成一个随机密码,哈希后立即丢弃,没有人见过;账号通过首次登录链接认领。PENGUIN_GO_ORIGIN:它是服务端配置,不接受浏览器指定的端点。取值必须是不带路径的 HTTPS 源;只有localhost、127.0.0.1和[::1]这类集成环境可以用明文 HTTP。带路径、凭据、查询参数或 fragment 的取值会在启动时被拒绝。见连接账户。MODELSCOPE_BRIDGE_URL:与PENGUIN_GO_ORIGIN一样是服务端配置,不接受浏览器指定的端点。它必须是不带凭据、查询参数或 fragment 的 HTTPS 地址。不同之处是它允许带路径前缀,因为生产环境的中转层就挂在https://go.penguin.ooo/modelscope下。见连接账户。ADELIE_UPDATE_CHECK:设为off只关闭自动的版本检查,不影响其他对外请求:模型请求、已启用的远程控制连接、Key 授权和代理测试照常联网。ADELIE_PLUGIN_MARKET:插件市场的货架有两侧,一侧是本次构建自带的插件(本地读,不联网),另一侧是发布到 npm 的插件。服务器为此查一次 npm 的搜索接口,结果缓存十分钟(失败时缓存两分钟并沿用上一次的结果)。设为off后这一侧完全不查,货架只剩本地那一侧——断网或封闭环境里应当如此。见插件。PENGUIN_NO_LOGIN_SHELL_ENV:不设置时,导入只填补启动过程没有设置的变量。见桌面应用快速开始。ADELIE_CLI_ENTRY:服务器从源码检出启动时,会回退到检出目录中的packages/cli/dist/penguin.js。
Agent 所执行命令的环境
Agent 用 exec_command 运行的命令继承宿主环境,但有以下改动:
- 移除:
PORT、HOST、FORCE_COLOR、CLICOLOR_FORCE以及所有PENGUIN_*与ADELIE_*变量。这些变量配置的是 Adelie 本身,不是命令。如果不移除,exec_command启动的开发服务器会读到PORT,试图绑定本应留给 Adelie 的端口,而不是自己另选。 - 代理: 在服务器运行的 Session 中,由设置里的 Agent 环境使用代理 开关决定代理变量。关闭时移除
HTTP_PROXY、HTTPS_PROXY和ALL_PROXY;开启时注入已配置的代理地址,没有配置地址时透传宿主的变量。 - 密钥保险柜: 之后再叠加 Agent 的密钥保险柜,所以在保险柜里设置的
PORT或ADELIE_*变量确实能传给命令。 - 控制变量: 由服务器驱动的 Session 随后注入
ADELIE_API_URL、ADELIE_API_TOKEN、ADELIE_PROJECT_ID、ADELIE_AGENT_ID和ADELIE_SESSION_ID(公司模式下还有ADELIE_ORG_ID),Agent 自己发起的penguin调用因此能到达运行它的服务器。这些变量会覆盖密钥保险柜里的同名条目。见 CLI 参考。 - 强制:
GIT_EDITOR、GIT_TERMINAL_PROMPT、TERM、NO_COLOR、PAGER和GIT_PAGER始终取固定值,命令不会因为等待编辑器、凭证提示或分页器而卡住。任何来源都无法覆盖它们,密钥保险柜也不例外。
PATH 启动脚本
Agent 运行的每条命令,PATH 的第一位都是本安装自带的 penguin。服务器启动时会在 <root>/bin/penguin 写入一个启动脚本:脚本用服务器自己的 Node 运行 ADELIE_CLI_ENTRY 指向的 CLI 入口,并把这个目录放到每条命令 PATH 的最前面。这样,命令里调用的 penguin 就是 Agent 正在运行的这套 harness,无论机器上全局装的是什么版本。
这个目录既前置到环境变量里,也前置到 shell 内部,因为命令通过登录 shell 运行,而登录 shell 的 profile 常常随后重写 PATH。这也让它排在密钥保险柜里设置的 PATH 之前,而保险柜里的 PATH 原本会整体替换继承来的值。
启动脚本在每次启动时都会重写,因此安装位置移动后,下次启动会自动跟上。没有可指向的入口时就不写启动脚本,penguin 的解析结果与没有启动脚本时相同。
Workspace 预览源
ADELIE_PREVIEW_ORIGIN 与应用本身的源必须在主机名上不同,不能只是端口不同:Cookie 不区分端口,换个端口仍然共享同一个会话 Cookie。
- 本地使用: 保持不设置。应用会规范化到
localhost,预览由127.0.0.1提供,不需要配置,也不需要 DNS。 - 局域网地址或正式域名: 必须设置。否则预览会回退到同源沙箱,
localStorage、Cookie 和第三方嵌入都无法工作。使用正式域名时,会话 Cookie 要保持 host-only(不设Domain=),否则同级子域名会共享这个 Cookie。
值无法解析时,服务器会在启动时直接停止,而不是静默回退。
供应商凭证变量
模型条目没有内联 api_key 时,只在请求确实发往该供应商的官方端点时回退到供应商的环境变量:条目没有 base_url,或 base_url 是厂商自己的端点。*_BASE_URL 的值只在条目没有内联 base_url 时才会使用;自带 base_url 的条目一律不由环境变量覆盖,即使 OPENAI_BASE_URL 指向同一台服务器也不例外。其余条目——网关分组预置的端点、带自己端点的 custom、vLLM 与自建分组——必须有自己的 api_key,否则 Adelie 拒绝为它构建客户端;见设置 API key。
| 供应商 | API key | Base URL |
|---|---|---|
| deepseek | DEEPSEEK_API_KEY |
DEEPSEEK_BASE_URL |
| anthropic | ANTHROPIC_API_KEY |
ANTHROPIC_BASE_URL |
| openai、openrouter、fireworks、siliconflow、tokendance、opencode-go、qwen-pay-as-you-go、qwen-token-plan、modelscope、vllm、custom | OPENAI_API_KEY |
OPENAI_BASE_URL |
| penguin-go | PENGUIN_GO_API_KEY |
PENGUIN_GO_BASE_URL |
| minimax | MINIMAX_API_KEY |
MINIMAX_BASE_URL |
GEMINI_API_KEY |
GEMINI_BASE_URL |
|
| zhipu | ZAI_API_KEY |
ZAI_BASE_URL |
| moonshot | MOONSHOT_API_KEY |
MOONSHOT_BASE_URL |
openrouter、fireworks、siliconflow、tokendance、opencode-go、qwen-pay-as-you-go、qwen-token-plan、vllm 和 custom 这几组供应商使用 OpenAI 兼容协议,因此共用 OPENAI_* 变量——按上面的规则,它们的条目并不会回退到这对变量:变量里存的是你的 OpenAI key,而网关不是 OpenAI。opencode-go 分组中走 Anthropic Messages 的模型同理,其客户端读取的是 ANTHROPIC_*。ModelScope 也共用 OPENAI_*,因为它的分组凭据是 api-inference token,三条预置都固定使用通用 Responses 客户端;它的条目同样不会回退到这对变量。Penguin Go 中转分组单独使用一对自己的变量,应用因此不会为它推荐任何厂商凭证。MiniMax M3 的直连 Responses 客户端使用 MINIMAX_*,内置的 MiniMax 预设也已经固定为官方端点。供应商分组和内置模型目录见模型与供应商。
Project 配置
<root>/<project>/.project_config.toml 是 Project 唯一的配置文件:隐藏文件,以 0600 权限写入,凭证内联在模型条目上。模型的标识始终是 (provider, model_id) 这一对,绝不把字符串拼接成单个 id;指向这个文件的每处引用都同时带上两部分,也绝不会只凭 model_id 推断供应商。
| 键 | 类型 | 默认值 | 说明 |
|---|---|---|---|
name |
字符串 | — | Project 显示名;未设置时显示 id |
default_model |
成对引用 | — | 指向默认模型的 { provider, model_id } 成对引用;必须指向 models 里的条目 |
vision_model |
成对引用 | — | 为纯文本模型读取图像的视觉模型(read_file 会把图像交给它);成对引用 |
[default_chat] |
表 | — | 新对话的预填默认值;见新对话默认值 |
[command_policy] |
表 | 出厂规则集 | shell 命令的拒绝规则,先于审批模式生效;见命令策略 |
[plugins] |
表 | — | Project 要求的服务端插件;见插件 |
[[models]] |
表数组 | — | 可用的模型条目 |
模型条目
| 键 | 类型 | 默认值 | 说明 |
|---|---|---|---|
provider |
字符串 | — | 供应商分组;与 model_id 一起构成条目的唯一键 |
model_id |
字符串 | — | 上游请求 id,原样发给 AgentHub |
context_window |
数字 | — | 上下文窗口大小 |
client_type |
字符串 | 从 model_id 推断 |
AgentHub 客户端协议 |
display_name |
字符串 | 内置模型目录中的名称 | 显示名;与模型目录不同时才会持久化 |
vision |
布尔 | true |
模型是否接受图像输入 |
max_tokens |
数字 | Agent 的 model.max_tokens |
单个模型的最大输出 Token;设置后覆盖 Agent 的 model.max_tokens |
fast_mode |
布尔 | 关闭 | 单个模型的快速模式(供应商收取溢价的快速服务档位) |
pricing |
表 | — | 三档价格 cache_read / cache_write / output,以美元每百万 Token 计价(unit = "usd_per_mtok")。这里记的始终是牌价 |
api_key |
字符串 | 供应商的环境变量,仅限厂商自己的端点 | 内联凭证 |
base_url |
字符串 | 部分模型目录条目有预设 | 自定义 base URL |
created_at |
字符串 | — | api_key 的写入时间(ISO 8601);由界面层维护的展示字段 |
字段说明:
client_type:自定义端点使用通用协议客户端:openai-responses、ant-messages或openai-chat。Web 对话框能根据 base URL 识别用的是哪一种。0.4.2 之前的写法openai是openai-chat的废弃别名,读取时会规范化。fast_mode:只持久化true。只有 AgentHub 客户端能支持快速模式的模型才会提供这个选项,其他模型会拒绝携带它的请求。见模型。pricing:这里记的是牌价。正在进行的促销不写入这个文件:服务端把它保存在web.db里,计算成本时再从牌价中扣除。见价格与促销。base_url:内置模型目录为网关以及固定客户端的直连条目预设了这个字段,即 MiniMax M3 和 DeepSeek 的deepseek-flash。api_key:为空时,只在条目的端点是厂商自己的地址时回退到供应商的环境变量(见供应商凭证变量);网关、custom 与 vLLM 条目需要自己的 key。
default_model = { provider = "deepseek", model_id = "deepseek-flash" }
[[models]]
provider = "deepseek"
model_id = "deepseek-flash"
context_window = 1000000
vision = true
client_type = "deepseek-v4"
base_url = "https://api.deepseek.com"
api_key = "sk-..."
[models.pricing]
unit = "usd_per_mtok"
cache_read = 0.005714
cache_write = 0.285714
output = 1.142857
pricing.unit 目前始终是 usd_per_mtok(美元每百万 Token)。三档价格对应 token_usage 的三个计数器。
通过 CLI(penguin config model …)或 Web App 的「模型库」页面编辑这个文件。
[!WARNING] 服务运行期间不要手动编辑
.project_config.toml。模型无权读写这个文件。
新对话默认值
[default_chat] 块为 Web App 的新对话预填默认值,在 Project 设置 的 默认值 标签页管理。每个键都可选且相互独立;加载时发现无效的值会直接丢弃,不影响其他键。
| 键 | 类型 | 默认值 | 说明 |
|---|---|---|---|
agent_id |
字符串 | — | 新对话预选的 Agent;必须是已存在的 Agent |
workspace |
字符串 | 临时 Workspace | 预填的 Workspace 目录 |
approval_mode |
字符串 | allow-all |
预填的审批模式:allow-all、deny-all、read-only 或 always-ask |
thinking_level |
字符串 | — | 回退思考等级(low / medium / high / xhigh / max),供配置里没有设置 model.thinking_level 的 Agent 使用 |
默认模型不在这个块里:它仍然是顶层的 default_model。
插件
[plugins] 表列出 Project 要求的服务端插件,在插件市场页面管理。每个键是一个包名,值是形如 Cargo [dependencies] 的要求:
[plugins]
"@adelie/sandbox-bwrap" = "*"
"@scope/name" = "1.2.3"
"@scope/other" = { version = "1.2" }
"*"表示部署发布的任意版本。版本字符串和{ version = "…" }形式会作为要求保留下来;目前加载只看包名。- 服务器运行所有 Project 表的并集,因此任何一个 Project 要求的插件,都会为所有 Project 加载。
- 读取文件时,其他形式的条目会被丢弃,文件的其余部分照常加载。
plugins键不是表时,视为不要求任何插件。 - 空表照样写成空表,表示这个 Project 不要求任何插件。
命令策略
[command_policy] 块是 Project 为 shell 命令设下的护栏:一组在审批边界直接生效的拒绝规则。
| 键 | 类型 | 默认值 | 说明 |
|---|---|---|---|
enabled |
布尔 | 启用 | 总开关;只以 enabled = false 的形式存储 |
[[command_policy.rules]] |
表数组 | 出厂规则集 | 拒绝规则,按顺序匹配。存储为空列表表示没有规则;不存储列表则表示使用出厂规则集 |
每条规则包含以下键:
| 键 | 类型 | 默认值 | 说明 |
|---|---|---|---|
name |
字符串 | — | 在设置界面中标识这条规则 |
pattern |
字符串 | — | JavaScript 正则表达式源码,与空白符归一化后的命令匹配 |
description |
字符串 | — | 可选的描述 |
enabled |
布尔 | 启用 | 单条规则的开关 |
[command_policy]
enabled = true
[[command_policy.rules]]
name = "rm-recursive-force"
pattern = "…" # seeded from the factory set
description = "rm with recursive + force flags in one command (rm -rf and friends)"
[[command_policy.rules]]
name = "no-force-push"
pattern = "git push [^;|&]*--force"
enabled = false
打开 Web App 的 Project 设置,在 安全策略 标签页管理这套策略。只有 Project 所有者能编辑;成员看到的是当前生效的策略。
生效方式
- 检查范围: 两个会触达 shell 的工具:
exec_command的cmd(启动的命令)和input_command的chars(往运行中的命令键入的内容)。 - 生效时机:
Session.run会用策略包住注入的审批回调,所以只要命中规则,在任何审批模式下(allow-all也不例外)都会在询问宿主之前直接拒绝。 - 模型看到什么: 一行固定的
Tool call denied by policy.,与人为取消不同,模型会据此改变做法。 - 钩子: 策略的优先级高于 pre-tool-use 钩子的
allow。策略否决的调用,无论已安装的钩子给出什么答复,都保持禁止。 - 存放位置: 策略存放在 Project 配置里,而不是 Agent State 里,所以 Agent 通过自身设置修改配置时碰不到它。
- 修改何时生效: 策略属于严格层级的运行时参数,只在模型上下文开启时读取一次。改动要等运行中的 Session 下一次轮换(压缩)才生效,新对话则立即生效。
出厂规则
规则就是普通数据,没有特殊层级。出厂规则集会像模型预设一样预置到每个新建 Project 里:创建时复制一份,之后绝不重写。此后每条规则都能编辑、停用或删除,你也可以添加自己的规则。在预置机制上线之前创建的 Project(存储中没有 rules 列表)会按出厂规则集运作,直到第一次保存编辑、把列表写进去为止。设置页面上的 恢复默认 会把出厂规则集重新载入编辑器,保存后写回。
出厂规则集刻意保持精简,只覆盖那些原样执行就会造成破坏、且无法撤销的命令:
- 同时带递归和强制标志的
rm mkfs- 直接向块设备写入的
dd - 经典的 fork 炸弹
- 重定向到块设备的 shell 命令(
/dev/null这类仍然允许)
另有四条规则用 Windows 写法覆盖同样的场景,因为 exec_command 在 Windows 上可能解析为 pwsh 或 cmd:
- 递归强制删除(
Remove-Item -Recurse -Force、rd /s /q) - 卷格式化(
format C:、Format-Volume) - 裸盘覆写(
\\.\PhysicalDriveN、Clear-Disk) - cmd 版的 fork 炸弹
匹配规则
在规则运行之前,匹配逻辑会先归一化几种常见写法,避免直白的输入碰巧漏网。下面这些写法全部都能命中:
- 开头带路径(
/bin/rm) - 前面套了一层包装命令(
sudo、env、command、nice、xargs) - 命令词加了引号或反斜杠转义(
"rm"、r''m、\rm) - 原样传入的
sh -c 'rm -rf /'
归一化只删除引号。展开、替换、解码,一律不做。
策略不覆盖的范围
命令策略是一道防误操作的护栏,不是安全边界。这句话描述的是模式匹配能做到什么,不是对本实现的自谦。Shell 是一门编程语言,规则加得再多,也无法在程序运行前靠阅读它的文本来更准确地判断它会做什么。策略覆盖人和模型实际会敲出来的写法,到此为止:
- 运行时计算出来的命令不在覆盖范围内,以后也不会有。 例如:用
$IFS代替空格、变量或别名(X=rm; $X -rf /)、命令替换、eval、通过管道把 base64 送进 shell、python -c、经由管道调用的解释器。每一种都得配一条需要永久维护的模式,换来的只是「已覆盖」的假象。真想让命令跑起来的人,总有办法让它跑起来。 - MCP 工具是另一个层面。 策略只读
exec_command和input_command。MCP Server 自身的permission等级才是那个层面上的设置,但它只设定 Server 的工具向审批模式上报的等级,既不给 Server 加沙箱,也不限制工具运行时的行为(见工具与审批)。把 shell 文本匹配器扩展到任意 MCP 参数,只会给一个真正需要硬控制的层面再叠一道更弱的控制。 - 不在清单上的命令不覆盖。
shred、wipefs、find -delete、git clean -xfd、chmod -R 000 /都匹配不到任何出厂规则。为你的 Project 在意的命令自行添加规则。 - 它不是文件系统权限。 能写任意路径的工具仍然可以改写配置文件本身,改动在下一次轮换时生效。
这套策略确实换来的是:一条破坏性的单行命令,无论通过哪个触达 shell 的工具、写成 POSIX 还是 Windows 的形式、处于哪种审批模式,都不会因误操作而执行。这是一道减速带,而在不可逆的命令前面,减速带值得设置。至于真正的边界,也就是让进程无论执行什么都碰不到文件系统的其他部分,靠的是隔离机制(bubblewrap、dsh)。那是独立的另一层,这套策略补充它,而不是取代它。
Agent 配置
agent_state/system_config.yaml 定义一个 Agent 的行为。文件是 YAML 格式,在 Web App 中编辑时,注释会保留。
| 字段 | 默认值 | 说明 |
|---|---|---|
name |
— | Agent 显示名称;未设置时回退到 id |
description |
— | Agent 描述 |
version |
1 |
Agent State 版本(自然数),每次成功优化后递增 |
kernel_version |
当前内核版本 | 配置基于哪一代内置默认值(日期字符串) |
system_prompt |
内置模板 | 必填;唯一支持占位符替换的模板 |
max_turns |
-1 |
每个 Task 的最大 LLM 轮数 |
model.max_tokens |
32000 |
每次 Request 的输出 Token 上限 |
model.thinking_level |
medium |
每个模型上下文开启时使用的思考等级,除非 Session 钉住了等级 |
model.timeoutMs |
300000 |
每次 Request 的空闲时间预算,单位毫秒 |
compaction.max_context_length |
256000 |
触发压缩的上下文 Token 阈值 |
compaction.max_session_turns |
-1 |
Session 累计轮数阈值 |
compaction.mode |
summarize |
summarize / discard |
compaction.prompt |
内置模板 | summarize 模式压缩使用的提示词 |
memory.enabled |
true |
记忆是否进入上下文,以及是否准备记忆目录 |
memory.prompt |
内置模板 | {{MEMORY}} 块中始终注入的那一半;包含 {{USER_MEMORY_INDEX}} |
memory.workspace_prompt |
内置模板 | 仅在持久 Workspace 中追加;包含 {{WORKSPACE_MEMORY_INDEX}} 和 {{WORKSPACE_MEMORY_DIR}} |
vault.enabled |
true |
密钥保险柜小节是否进入上下文 |
vault.prompt |
内置模板 | {{VAULT}} 块;包含 {{VAULT_KEYS}} |
skills.enabled |
true |
技能小节是否进入上下文 |
skills.prompt |
内置模板 | {{SKILLS}} 块;包含 {{SKILL_METADATA}} |
schedules.enabled |
true |
定时任务小节是否进入上下文 |
schedules.prompt |
内置模板 | {{SCHEDULES}} 块,讲解基于文件的任务管理;包含 {{SCHEDULE_LIST}} |
hooks.enabled |
true |
是否在循环的钩子点运行已安装的钩子包 |
tools.builtin |
省略时为完整默认工具集 | 工具条目;一旦写入,就整体替换默认列表 |
tools.mcpServers |
[] |
MCP Server 配置(name + config) |
字段说明
kernel_version:在创建时、还原为默认配置时以及内核更新时打上标记。它与version无关,也不会因你的编辑而改变。值缺失说明配置早于这套机制,视为过时。max_turns:-1表示不限制;正整数则为单个 Task 的轮数上限。model.max_tokens:-1表示不设上限(使用供应商默认值)。每次请求都会把实际生效值限制在「模型context_window− 估算输入」以内,因此不会向窗口小的模型要求放不下的输出量。model.thinking_level:可选none/low/medium/high/xhigh/max。思考等级在一个模型上下文内固定,修改要等下一次压缩才生效。没有此字段时,采用 Project[default_chat]中的thinking_level;若仍未设置,则为medium。model.timeoutMs:等待下一个上游事件的最长时长,每收到一个事件就重新计时。它限制的不是请求总时长,而是两段等待:从建立连接到收到第一个事件,以及事件之间的空档。有的模型在思考阶段不向网络输出任何内容,整个思考期都落在第一段空档里,默认值已为这种情况留出余量。compaction.max_context_length:实际阈值取此值与「模型context_window− 2048」中较小的一个。因此窗口小的模型会在自己的窗口内触发压缩;窗口超过 258048 的模型则按此数值触发。没有context_window的模型条目按 128000 窗口处理。compaction.max_session_turns:-1表示不限制。*.prompt:各小节的提示词都能在对应的设置标签页编辑:两段记忆提示词在 记忆,vault.prompt在 密钥保险柜,skills.prompt在 技能,schedules.prompt在 定时任务。vault.enabled:关闭时,值仍会注入子进程环境,只是模型看不到键名列表。skills.enabled:关闭时,已安装的 Skill 仍可通过[use_skills]显式调用。schedules.enabled:关闭时,服务端仍会触发任务,只是模型不再了解任务系统。hooks.enabled:唯一没有提示词的小节,因为钩子包是脚本,不是上下文文本。关闭时,钩子包仍保持安装,只是不再有任何环节调用它们。tools.builtin:每个条目包含name/description/parameters/permission(r或rw)/forModel/timeoutMs/maxOutputLength/call_description。call_description是按工具控制调用参数description的开关;开启时调用必须带上这个参数;字段缺失则视为保留。tools.mcpServers:传输方式为stdio、http或sse,发现的工具以mcp__<server>__<tool>的形式加入工具集。config.permission(auto/r/rw,默认auto)为对应 Server 的所有工具固定审批等级,不再采信它们的readOnlyHint。见 MCP Server。
四个 compaction.* 字段是本文件中唯一即时生效的部分,运行中的对话无需等待。引擎会在每个压缩检查点重新读取这一节(每次请求上报 Token 用量之后,以及手动执行 /compact 时),因此保存的修改对已在运行的 Session 同样生效。其余内容都在模型上下文开启时读取,修改要到下一次压缩才生效。在 Web App 里,你还可以在上下文面板中拖动条上的虚线切刀来修改阈值。
工具权限与审批语义见工具与审批。
本文件不与默认值做深度合并。写出的键整体生效;只有省略的键,才会在用到时回退到上述默认值。system_prompt 必填,缺少此字段的文件无法加载,因此编辑其他字段时请保留完整生成的模板。下面是一个部分覆盖的示例,由 init 步骤生成的文件修改而来:
name: default_agent
description: General-purpose agent
version: 3
# Required: keep the full generated default template ({{AGENTS_MD}} and friends; elided here).
system_prompt: |
…
# -1 (the default) = unlimited; set a positive integer to cap the turns of a single Task.
max_turns: -1
model:
max_tokens: 32000
thinking_level: medium
timeoutMs: 300000
compaction:
max_context_length: 256000
max_session_turns: -1
mode: summarize
# Omitting the whole tools section = the full default toolset. Writing tools.builtin
# REPLACES the default list wholesale: carry the complete definition (including the
# parameters JSON Schema) for every tool you keep — see Tools & Approval.
内核更新
已有 Agent 始终按磁盘上的配置原样运行,新版代码的默认值绝不会自动合并进来。当内置默认值发生实质性变化时,配置的 kernel_version 会落后于当前内核,设置页面和智能体列表会显示更新提示。设置总览上有两个操作可以采纳当前默认值。
更新内核是一次无损合并,按设置标签页逐一进行(系统提示词、运行参数、工具、技能、记忆、密钥保险柜、定时任务):
- 配置里完全没有的标签页,或者哈希仍与某一已记录代的内置默认值一致的标签页,会按当前默认值重写。之后版本新增的工具,也是通过这条途径进入已有 Agent 的。
- 只要你以任何方式改动过,标签页就会完整保持不变,并列入结果。哪怕只改了一个内置工具,整个工具标签页也会保留:你新增的工具和删除的工具都原样留存,这个标签页也不再跟随新默认值,直到你执行还原为默认配置。
name、description、version、hooks和tools.mcpServers不属于任何标签页,更新永远不会碰它们。- 最后,配置会打上当前
kernel_version的标记。 - 匹配是保守的:只有哈希与某一已记录代一致的标签页才算旧默认值。代太老、不在记录之内的标签页,会当作自定义内容保留。
还原为默认配置的工作方式类似 Skill 更新:用当前默认值覆盖配置,只保留 name、description 和 version。其余全部替换,包括自定义系统提示词、工具列表、模型与压缩设置,以及 MCP Server。当内核更新的保守匹配留下旧字段时,用它做一次彻底刷新。
面向开发者的说明:
kernel_version由人工推进,且只在内置默认值发生实质性变化时更新,取当天日期。同一天的多次改动可能复用同一天的版本。- CI 中的固定哈希测试(
core/test/kernel-version.test.ts)会重新计算每个标签页的哈希,并与kernel-history.ts里的KERNEL_DEFAULT_TAB_HASHES比对。发现偏差时测试失败,并列出每个变动的标签页及所需的修改:递增KERNEL_VERSION,把这个标签页原先的哈希追加到KERNEL_SUPERSEDED_TAB_HASHES,再写入重新计算出的哈希。 - 已淘汰的哈希永久冻结:判断一个标签页是否仍是旧默认值,靠的就是它们。
系统提示词占位符
system_prompt 是唯一支持占位符替换的模板。可用占位符如下:
| 占位符 | 注入内容 |
|---|---|
{{AGENTS_MD}} |
AGENTS.md 全文 |
{{VAULT}} |
渲染后的 vault.prompt 块(密钥保险柜小节);vault.enabled 关闭时为空 |
{{SKILLS}} |
渲染后的 skills.prompt 块(技能小节);skills.enabled 关闭时为空 |
{{MEMORY}} |
渲染后的 memory.prompt 块,持久 Workspace 中还会加上 memory.workspace_prompt;记忆关闭时为空 |
{{SCHEDULES}} |
渲染后的 schedules.prompt 块(定时任务小节);schedules.enabled 关闭时为空 |
{{VAULT_KEYS}} |
在 vault.prompt 内:密钥保险柜的密钥名称列表(只有名称,每个密钥一行 - KEY) |
{{SKILL_METADATA}} |
在 skills.prompt 内:已安装 Skill 的元数据行 |
{{SCHEDULE_LIST}} |
在 schedules.prompt 内:当前的任务名称列表(每个任务一行 - name;没有任务时显示空列表说明) |
{{USER_MEMORY_INDEX}} |
在记忆提示词内:用户作用域的 MEMORY.md 索引(最多 200 行,总计不超过 25,000 字符) |
{{WORKSPACE_MEMORY_INDEX}} |
仅在 memory.workspace_prompt 内:Workspace 作用域的 MEMORY.md 索引(最多 200 行,总计不超过 25,000 字符) |
{{WORKSPACE_MEMORY_DIR}} |
仅在 memory.workspace_prompt 内:当前 Workspace 记忆目录的绝对路径 |
{{PLATFORM}} |
运行平台 |
{{OS_VERSION}} |
操作系统版本 |
{{DATE}} |
当前日期 |
{{PROJECT_DIR}} |
App Data Dir:Adelie 的应用数据根目录(即 Project 目录) |
{{AGENT_ID}} |
Agent id |
{{CWD}} |
Workspace 路径 |
{{PROVIDER}} |
模型供应商分组 |
{{MODEL_ID}} |
上游模型 id |
{{SESSION_ID}} |
Session id |
小节占位符。 密钥保险柜、技能、记忆、定时任务四个小节共用一套模式:一个占位符、一个开关、一段可编辑的提示词。模板里只保留 {{VAULT}} / {{SKILLS}} / {{MEMORY}} / {{SCHEDULES}} 占位符,小节文本放在对应的 *.prompt 键里(在设置标签页编辑),关闭 *.enabled 则整块为空。模板缺少其中某个占位符时,对应小节不会注入;相应的设置标签页会提供显式插入占位符或迁移旧版模板的操作。四个小节占位符在组装时最后展开,一趟完成。展开后的文本不会再次扫描,因此记忆索引或小节提示词里看起来像占位符的文本会按字面保留。
App Data Dir。 {{PROJECT_DIR}} 会以 App Data Dir 的名义展示给模型:这是 Adelie 的应用数据根目录,存放所有 Agent 的数据文件(agents/<agent_id>/…)和 Project 级数据。刻意不把它描述成 Project 或 Task 目录,避免模型误以为它是任务的工作目录(CWD)。
Windows 路径。 在 Windows 上,{{PROJECT_DIR}} 和 {{CWD}} 一律以正斜杠注入;core 为模型拼出的其他路径也是如此(附件行、目标模式的 goal 文件行、截断输出的恢复路径)。模型会把这种写法照搬进 JSON 工具参数和 shell 命令。Node 的 fs API 和包内工具所用的 Git Bash 都接受正斜杠,还能避开 JSON 反斜杠转义错误。
AGENTS.md。 agent_state/AGENTS.md 是开发者可编辑的指令文件,通过 {{AGENTS_MD}} 注入,默认为空。它也是优化器编辑最多的文件;参见自我进化。与 Agent State 的其余内容(包括 system_config.yaml)一样,它在每次模型上下文开启时读取:创建 Session 时读一次,压缩开启下一个上下文时再读一次。因此,修改会在运行中 Session 的下一次压缩时生效,而不只对新建 Session 生效,且绝不会影响正在运行的上下文。compaction 一节是例外;见上下文压缩。
旧版模板。 system_config.yaml 在创建 Agent 时写入,此后不会自动升级。在小节占位符出现之前创建的 Agent,模板里硬编码了 # Vault / # Skills 小节文本,并内联了 {{VAULT_KEYS}} / {{SKILL_METADATA}}。这类模板仍然可用:内联占位符照常替换,并遵守小节开关(开关关闭时替换为空字符串)。对应的设置标签页会提示旧版模板并提供一键迁移:把旧的默认小节文本原封不动地就地替换为新占位符,组装出的提示词保持不变。如果小节文本有过自定义,原样迁移便匹配不上,此时模板按缺少占位符处理,可在 # Environment 之前一键插入。
记忆
agent_state/memory/ 保存 Agent 在多次 Session 之间记住的内容:用户反馈、项目决策、工作惯例、外部系统的入口,也就是无法从 Workspace 或它的代码历史中重新推导的内容。记忆不是上下文压缩,压缩保留的是单个 Session 的短期状态。
记忆分两个作用域。两者都只属于一个 Agent,绝不与其他 Agent 共享:
- 用户作用域(
memory/user/):Agent 无论在哪里工作都成立的内容,比如用户是谁、长期偏好,以及不绑定某个代码库的参考资料。每个 Session 都会读取它,包括运行在临时 Workspace 里的 Session,因为这种 Session 没有别的地方可写。 - Workspace 作用域(
memory/<workspace_memory_key>/):关于某个 Workspace 的事实。同一 Agent 在同一 Workspace 中的 Session 共享这些内容;不同 Workspace 的主题文件彼此独立。
agent_state/memory/
├── user/ # user scope (no marker: it stands for no path)
│ ├── MEMORY.md # this scope's index
│ └── prefers-pnpm.md
└── my-app-a81f32c4/ # one Workspace
├── .workspace # the Workspace path this key stands for
├── MEMORY.md
└── testing-conventions.md
每个作用域都有自己的 MEMORY.md 索引,而且不同 Agent 绝不共享记忆,即使在同一个 Workspace 里也是如此。记忆存放在 Agent State 中,因此会随导出、导入和快照一起迁移。
[!WARNING] 能访问这个 Agent 的所有 Project 成员都能读到它的记忆。不要把凭证和敏感的个人数据存进去。
要读取或删除记忆,或者让 Agent 来修改,使用 Agent 设置的 记忆 标签页。
Workspace 记忆键
Workspace 记忆键的格式是 <safe-basename>-<8 hex of the real path's sha256>。
user是保留的目录名,这样做是安全的:生成的键都形如<base>-<8 hex>,一定包含连字符。- 标识就是目录本身,与 Git 无关。指向同一目录的两个符号链接解析出同一个键;移动或重命名目录会让它变成一个新 Workspace,旧记忆仍以旧键留在磁盘上。
- 临时 Workspace 由 Adelie 分配在
agents/<agent_id>/workspaces/下,完全没有 Workspace 作用域,子 Agent 继承时也不例外。临时 Workspace 按 Session 分配,之后不会再有 Session 在那里运行并读回内容。这种 Session 仍然会拿到用户作用域,它学到的东西本来也该存在那里。
主题文件
每个主题文件保存一个事实或主题,而不是每个 Task、Session 或日期一个文件,并带有 frontmatter:
---
name: testing-conventions
description: the project's test environment and verification rules
updated_at: 2026-08-07
---
- Integration tests connect to a real database; no mock repositories.
frontmatter 就只有这三个字段。记忆属于哪个作用域由所在目录决定,因此没有 type 字段;早期文件里遗留的 type: 行会当作未知字段忽略。
默认的记忆提示词告诉模型保存哪些内容:
- 用户是谁、希望 Agent 怎么工作,以及背后的原因
- 从代码推导不出的目标、决策和约束
- 指向外部系统、文档和资源的指引
它还列出了会产生这类事实的时刻:同一个请求第二次出现、一条超出当前任务仍然成立的纠正、不止一次提到的习惯或做法,或者一个不记住就得再问的可复用工作细节。重复只会让事实更明显;长期偏好只要清楚地说过一次就够了。分不清某件事值不值得保存时,Agent 会在对话里直接询问。
提示词明确排除以下内容:
- 代码、配置或 Git 历史里已经写明的事实
- 未经验证的猜测
- 对话记录摘录(即使用户要求保存,Agent 也只保存其中非显然的部分)
用户想保存的其他内容都可以存。对于纠正和决策,模型会加上 Why: 和 How to apply: 两行。事后证明有误的记忆会连同索引行一起删除。日期一律写绝对日期(YYYY-MM-DD),因为相对日期对后续 Session 毫无意义。
注入方式
只有索引会进入上下文,通过模板中的 {{MEMORY}} 占位符注入。每个 MEMORY.md 每行列出本作用域的一条记忆,格式为 - [Title](file.md) — hook,链接相对于作用域目录。模型更新文件时同步更新索引,删除也不例外,两者始终保持一致。
{{MEMORY}} 展开为:
memory.prompt:记忆的用途和保存方法,然后是一个## User memory小节,内含索引({{USER_MEMORY_INDEX}})。memory.workspace_prompt:仅当 Session 运行在持久 Workspace 中时存在,是一个包含{{WORKSPACE_MEMORY_INDEX}}的## Workspace memory小节。
这两段提示词都是 Agent 级配置,可在 记忆 标签页编辑,和模板其他小节一样按 Markdown 标题组织。User Memory Dir 一行是字面模板 <app_data_dir>/agents/<agent_id>/agent_state/memory/user,模型根据 Environment 小节自行解析。Workspace Memory Dir 一行则通过 {{WORKSPACE_MEMORY_DIR}} 直接渲染为解析后的路径,因为它的最后一段是 Workspace 记忆键,这是模型自己拼不出来的路径哈希。
限制:
- 索引为空时,会注入一条明确的「还没有保存任何内容」提示。
- 每个作用域的注入上限是 200 行(按惯例一条记忆一行),另外还有一个 25,000 字符的总量兜底上限,应对索引里出现几条超长行的情况。超过上限时,会附上一条截断说明,让模型自己去打开完整的
MEMORY.md。磁盘上的文件始终原样不动。 - 默认记忆提示词写明了行数上限,并要求索引行控制在约 150 字符以内,让模型在触及上限之前就把索引保持得很短。字符数兜底只存在于代码中。
- 模型按需读取主题正文。
这两段是各自独立的配置键,因为占位符替换不支持条件判断。临时 Workspace 绝不能收到 Workspace 小节(即它的目录行和选择作用域的规则),所以那一段在那里根本不会追加。Harness 只决定记忆存放在哪里,并把写入限制在这个范围内。判断什么值得保存、拆分主题、维护索引,这些都是模型的工作,用普通文件工具完成。
模板里没有 {{MEMORY}} 就不会注入任何记忆;在记忆功能发布之前创建的 Agent 就是例子。记忆 标签页会说明这一情况,并提供一个明确的一键操作:把占位符插入到 # Environment 之前,也就是默认模板中它所在的位置。任何内容都不会自动拼接进去。组装好的完整提示词记录在 session_meta 中。
Vault
agent_state/.vault.toml 是 Agent 级的环境变量密钥保险柜:一个隐藏文件,以 0600 权限写入。
- 键名必须匹配
^[A-Za-z_][A-Za-z0-9_]*$(即 shell 环境变量的命名规则)。值的长度上限为 8,192 个字符。 - 值只注入工具子进程的环境。这些值绝不会进入模型上下文,也不会出现在 Trace 里。
- 系统提示词里只显示键名。模板中的
{{VAULT}}占位符展开为vault.prompt,其中带有{{VAULT_KEYS}}键名列表,可在 密钥保险柜 标签页编辑。vault.enabled关闭时这一块为空:值仍会注入子进程,只是模型看不到键名。旧版模板里内联的{{VAULT_KEYS}}在同一个开关控制下仍会照常替换,标签页还提供一键迁移(参见系统提示词占位符)。 - 保存后的更改立即对新 Session 生效;正在运行的 Session 则在下一次压缩时生效,与其他 Agent State 的更改一样。无论在 Web App 里保存、通过 API 保存还是用 CLI 保存,行为都相同。
- 用
penguin config vault set/list/remove管理,或在 密钥保险柜 标签页操作。
定时任务
每个文件 agent_state/schedule/<name>.toml 描述一个定时任务,按设定的周期向 Agent 发送预设 Prompt。文件名就是任务的标识。定时任务只在 Web 服务(服务器运行时)运行期间执行。可以在 Agent 设置的 定时任务 标签页或对话页面管理,见定时任务。
| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
prompt |
字符串 | 必填 | 每次触发时发送的 Prompt |
enabled |
布尔 | false |
任务是否触发 |
start_at |
日期时间(ISO 8601) | 必填 | 首次触发时间 |
period |
字符串 | 省略表示一次性任务 | 执行周期,如 30m / 12h / 7d;最小 5 分钟 |
end_at |
日期时间(ISO 8601) | — | 结束时间;必须晚于 start_at |
session_id |
字符串 | — | 把任务绑定到一个已有 Session;与下面三个字段互斥 |
workspace |
字符串 | — | 新建 Session 模式使用的 Workspace |
provider / model_id |
字符串对 | Project 的默认模型 | 新建 Session 模式的成对模型引用 |
provider 和 model_id 要么都写,要么都不写。只写 model_id 的文件无效;两者都不写时使用 Project 的默认模型。
不会再触发的任务——已触发或已错过的一次性任务,以及已过 end_at 的任务——会由调度器原样移进 agent_state/schedule/expired/,见结束的任务会归档。
prompt = "Check yesterday's builds and summarize the failures"
enabled = true
start_at = 2026-08-01T09:00:00Z
period = "12h"
模板中的 {{SCHEDULES}} 占位符展开为 schedules.prompt。它教模型用自己的文件工具管理这些 TOML 文件:目录位置、字段规则、约 30 秒内自动生效,以及防止重复的规则。末尾通过 {{SCHEDULE_LIST}} 附上当前的任务名列表。这段提示词可在 定时任务 标签页编辑。schedules.enabled 关闭时这一块为空:服务器仍按计划触发任务,只是不再教模型这套任务系统。在这个机制出现之前创建的 Agent,模板里没有这个占位符,标签页提供一键插入。
设计原则
Agent 的行为完全由磁盘上可编辑的文件决定:Prompt、Skill 和配置都是数据,而不是代码。正因如此,Agent 才能改进 Agent:优化器编辑的正是你手动编辑的那些文件。参见自我进化和 CLI 参考。