提交背景:2026-09-28,Pantheogen 项目。用户要求「开启全程自动审批」,在项目
opencode.jsonc写入"permission": "allow"(schema 合法,等价「全放行」)后,agent 访问工作区外目录仍需授权。本文档定位根因、给出证据并提改进建议,供 OpenFeel 维护者参考。 关联:docs/06-openfeel-tooling-feedback.md(CLI 工具链视角)。
opencode.jsonc 设置 "permission": "allow"。openfeel-* 子 agent)访问工作区外目录(如 C:\Users\Liuary\Dev\Third\godot\...)时仍被要求授权,项目级配置无法实现「全程免审」。permission 覆盖顶层 permission(opencode 语义,主因)OpenFeel 由 openfeel setup 部署的 9 个 agent 定义(~/.config/opencode/agents/*.md)各自内联了一个 permission: 白名单。以 feel.md 为例:
permission:
bash: allow
read: allow
glob: allow
grep: allow
task: allow
todowrite: allow
skill: allow
webfetch: allow
opencode 规则是「per-agent permission: 覆盖顶层 permission:」。因此项目里的 "permission": "allow" 对这些 agent 不生效。
external_directory9 个 agent 的 permission 块均未包含 external_directory 键。该键不继承顶层 allow,回落到内置默认值 ask → 访问工作区外目录即触发授权询问。
opencode 仅在启动时读取配置,任何改动须退出并重启才生效。
openfeel setup 管理、可能被覆盖。ask 与「自动化流水线」定位相悖。| # | 建议 | 说明 |
|---|---|---|
| 1 | agent 模板补 external_directory |
在 ~/.config/opencode/agents/*.md 的 permission: 中显式声明 external_directory(如 allow,或留可配置项),随 openfeel setup 部署 |
| 2 | 文档化「agent 级覆盖顶层」语义 | 在 AGENTS.md / 部署说明中明确:改审批行为须改 agent 定义,顶层 permission 对已定义 agent 无效 |
| 3 | 提供项目级外部目录入口 | 例如让 openfeel setup 读取项目的 external_directory / references 并生成 per-agent 覆盖模板 |
| 4 | openfeel setup 保留用户自定义 |
避免用户手改 agent 文件后被后续 setup 覆盖 |
| 5 | (可选)区分只读/写外部访问 | 默认放行只读外部访问、写入才询问,可兼顾安全与效率 |
在项目 opencode.jsonc 的 agent.<name>.permission 中,为 9 个 agent 镜像全局白名单并追加 external_directory: allow:
"agent": {
"feel": {
"permission": {
"bash": "allow", "read": "allow", "glob": "allow", "grep": "allow",
"task": "allow", "todowrite": "allow", "skill": "allow", "webfetch": "allow",
"external_directory": "allow"
}
},
"openfeel-executor": { "permission": { "bash": "allow", "read": "allow", "glob": "allow", "grep": "allow", "task": "allow", "external_directory": "allow" } }
// …其余 agent 同理
}
为什么镜像全量键:项目级与全局级配置理论上 deep-merge,但若某实现为「替换」语义,仅写 external_directory 会丢失原有 bash/read/... 白名单;镜像可对两种语义都安全。
注意:此方案仍属项目级规避,未改动全局 agent 文件;若 OpenFeel 采纳建议 1,本规避即可移除。
OpenFeel 把 permission 内联进每个 agent 定义,导致项目级 permission 被 agent 级覆盖,且模板遗漏 external_directory——用户无法在项目内实现「全程自动审批」。建议在 agent 模板补 external_directory 并文档化覆盖语义。
本文档为 Feel 总统领的一手问题定位,供 OpenFeel 项目维护者参考。
本节为追加的勘误,不改写上文原文。依据:
.openfeel/plan/v1/stage-44/op-001-findings.md(隔离 HOME 实测 + 二进制取证 +opencode run行为判别器)、v1.1.2-stage-44 审查官独立复验(R-①/R-②/R-③)、测试官 E2E(RUN 1~8)。 适用范围:以下结论仅对opencode-ai@1.18.33成立,未覆盖其它版本——opencode 版本间权限语义的可迁移性未经验证。
external_directory: "allow"(单值)与 {"*": "allow"}(对象)均被 schema 接受且生成同一规则;单值形式经行为级实测生效(框架统一取单值)。write 非授权键、edit 才是:授权键为 edit(write/patch 工具映射到 edit 权限);permission: {write: "deny"} 不生效(tools.write 仍为 true),{edit: "deny"} 才拦截 ⇒ OpenFeel openfeel-utility 模板的 write 已改为 edit。external_directory 平台默认 ask:内置默认 {"*":"ask"} + opencode 内部 tool-output / %TEMP%\opencode 目录 allow;不存在「对所有 agent 自动追加 external_directory:{"*":"allow"}」——自动追加的 allow 仅限 opencode 自身内部目录,对用户任意外部路径无效。⇒ 框架补键是行为变更(ask → allow),不是单纯「显式化」。.md 与配置文件按权限键深合并、同名键 .md 优先:顶层 permission 与 agent.<name>.permission 对 .md 未声明的键生效;对 .md 已声明的键无法覆盖 ⇒ 唯一项目级收紧入口 = 项目 .opencode/agent/<name>.md(可整体覆盖全局同名 agent)。permission: "allow" 会覆盖 external_directory:求值以 findLast(最后匹配者胜)+ 规则 permission 字段通配匹配("*" 匹配任意权限名),顶层 *:allow 位于内置默认之后,故对 external_directory 生效 ⇒ 实测「项目顶层 permission: "allow" + 无 external_directory 键的 agent」访问外部目录免询问(含真实 9-agent 形态)。| 原文 | 实测(1.18.33) | 裁定 |
|---|---|---|
§二.1「agent 级 permission 覆盖顶层 permission」 |
仅对同名键成立(.md 后置胜出);未声明键顶层规则生效 |
过度概括 |
§二.2「external_directory 不继承顶层 allow,回落内置默认 ask」 |
不成立:顶层 permission: "allow" 对 external_directory 生效,外部目录免询问 |
❌ 推翻 |
| §二.3「配置不热重载」 | 未单独实测,作为现象的可能解释保留 | 未验证 |
| §五「镜像全量键」规避方案 | 无效:合并为按键深合并、.md 优先,项目 opencode.jsonc 无法覆盖 .md 已声明的键 |
方案失效 |
成因说明(诚实记录):本次实测未能复现用户在 Pantheogen 项目报告的现象(写入项目顶层
permission: "allow"后仍需授权)。§二.3(配置未热重载)、项目配置未加载、或用户配置文件差异均为未验证的候选解释,本文不推定成因。
permission: 块补 external_directory: "allow"(单值),openfeel-utility 的 write → edit;.opencode/agent/<name>.md)+ 受管区边界」已文档化至根 AGENTS.md 权限模型节、agents-md/{zh-CN,en}.md 与 .openfeel/manual/core/permission.md;op-001-findings.md 的场景 A~F 重新复验。