05 — Tools (内置工具 + 权限)

源: https://opencode.ai/docs/zh-cn/tools/ 适用: 调整 opencode.json 的 permission 段,管控 LLM 能用什么工具

全局 permission

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "edit": "deny",
    "bash": "ask",
    "webfetch": "allow"
  }
}

值: "allow" / "ask" / "deny"。

Glob 通配符 (针对所有工具):

{ "permission": { "mymcp_*": "ask" } }   // 某 MCP server 全部工具需审批
{ "permission": { "mymcp*": false } }    // (在 tools 段) 全局禁用

tools 段控制可用性 (true/false),permission 段控制行为 (allow/ask/deny)。两者可叠加。

12 个内置工具

工具	用途	关键说明
`bash`	执行 shell 命令	—
`edit`	精确字符串替换	—
`write`	创建/覆盖文件	由 `edit` 权限控制 (含 edit/write/patch)
`read`	读文件 (支持行范围)	—
`grep`	ripgrep 内容搜索	遵循 `.gitignore`
`glob`	文件模式匹配 (按 mtime 排序)	遵循 `.gitignore`
`lsp`	跳转/引用/悬停/调用层次	需 `OPENCODE_EXPERIMENTAL_LSP_TOOL=true` 或 `OPENCODE_EXPERIMENTAL=true`
`patch`	应用补丁	由 `edit` 权限控制
`skill`	加载 SKILL.md	见 02-skills
`todowrite`	任务列表	默认对子代理禁用,要开 `agent.<name>.tools.todowrite: true`
`webfetch`	取网页	—
`websearch`	网络搜索 (Exa)	需 OpenCode 提供商,或 `OPENCODE_ENABLE_EXA=1\|true`
`question`	交互提问	—

特殊权限 (只接受 flat action, 不接受 per-pattern object)

todowrite
question
webfetch (在某些版本)
websearch (在某些版本)
doom_loop

→ 只能 "allow" / "ask" / "deny",不能 {"git *": "allow", ...}。

`.ignore` 覆盖 `.gitignore`

grep / glob 默认遵守 .gitignore。要强制搜 node_modules/ 等被忽略目录,加项目根 .ignore:

!node_modules/
!dist/
!build/

实战组合

Plan 代理只读:

{
  "permission": { "edit": "deny", "bash": "ask", "webfetch": "deny" },
  "agent": {
    "plan": {
      "permission": { "edit": "ask", "bash": "ask" }
    }
  }
}

全局禁 MCP,只给 review 代理开:

{
  "mcp": { "playwright": { "type": "local", "command": ["npx", "-y", "@playwright/mcp"] } },
  "tools": { "playwright_*": false },
  "agent": { "code-reviewer": { "tools": { "playwright_*": true } } }
}

让某代理能调指定子代理 (Task 权限):

{
  "agent": {
    "orchestrator": {
      "permission": {
        "task": { "*": "deny", "orchestrator-*": "allow", "code-reviewer": "ask" }
      }
    }
  }
}

规则最后匹配优先。orchestrator-planner 同时匹配 *(deny) 和 orchestrator-*(allow) → 第二个胜出 → allow。用户始终能用 @ 调任何子代理,即使被 task 权限拒绝。

内部机制

grep / glob 用 ripgrep,默认遵守 .gitignore。
MCP 工具以 <server>_<tool> 命名,glob 模式 mymcp_*。
权限 JSON 中对象型值,插入顺序敏感 — opencode 取最后匹配的规则,先放宽后放严。

验证清单

permission 值: allow / ask / deny,不是 true/false。
tools 段用 true/false,permission 段用三态字符串。
glob 模式放宽松规则前,具体规则后 (最后匹配优先)。
特殊权限 (todowrite/question/websearch) 不传对象。
退出重启 opencode。
实测: 启用规则下,代理能正常调;ask 时弹确认;deny 时直接拒绝。

3.6 KiB Raw Blame History