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

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

## 全局 permission

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

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

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

```json
{ "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`:

```gitignore
!node_modules/
!dist/
!build/
```

## 实战组合

**Plan 代理只读**:

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

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

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

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

```json
{
  "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 取**最后匹配**的规则,先放宽后放严。

## 验证清单

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