238 lines
6.4 KiB
Plaintext
238 lines
6.4 KiB
Plaintext
---
|
||
title: 權限
|
||
description: 控制哪些操作需要批准才能運行。
|
||
---
|
||
|
||
OpenCode 使用`permission` 配置来决定给定的操作是否应自动运行、提示您或被阻止。
|
||
|
||
从 `v1.1.1` 开始，旧版配置 `tools` 布尔已被废弃，并已合并到 `permission` 中。仍支持旧版的 `tools` 配置以实现平滑兼容。
|
||
|
||
---
|
||
|
||
## 行動
|
||
|
||
每個權限規則解析為以下之一：
|
||
|
||
- `"allow"` — 尚未批准运行
|
||
- `"ask"` — 提示批准
|
||
- `"deny"` — 阻止该操作
|
||
|
||
---
|
||
|
||
## 配置
|
||
|
||
您可以全局設置權限（使用`*`），並覆蓋特定工具。
|
||
|
||
```json title="opencode.json"
|
||
{
|
||
"$schema": "https://opencode.ai/config.json",
|
||
"permission": {
|
||
"*": "ask",
|
||
"bash": "allow",
|
||
"edit": "deny"
|
||
}
|
||
}
|
||
```
|
||
|
||
您還可以一次設置所有權限：
|
||
|
||
```json title="opencode.json"
|
||
{
|
||
"$schema": "https://opencode.ai/config.json",
|
||
"permission": "allow"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 粒度規則（對象語法）
|
||
|
||
對於大多數權限，您可以使用對像根據工具輸入應用不同的操作。
|
||
|
||
```json title="opencode.json"
|
||
{
|
||
"$schema": "https://opencode.ai/config.json",
|
||
"permission": {
|
||
"bash": {
|
||
"*": "ask",
|
||
"git *": "allow",
|
||
"npm *": "allow",
|
||
"rm *": "deny",
|
||
"grep *": "allow"
|
||
},
|
||
"edit": {
|
||
"*": "deny",
|
||
"packages/web/src/content/docs/*.mdx": "allow"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
規則通過模式匹配進行評估，**最後匹配的規則獲勝**。常見的模式是將包羅萬象的 `"*"` 規則放在前面，然後再放置更具體的規則。
|
||
|
||
### 通配符
|
||
|
||
權限模式使用簡單的通配符匹配：
|
||
|
||
- `*` 匹配零個或多個任意字符
|
||
- `?` 恰好匹配一個字符
|
||
- 所有其他字符均按字面意思匹配
|
||
|
||
### 主目錄擴展
|
||
|
||
您可以在模式目录中使用 `~` 或 `$HOME` 来引用您的主目录。这对于 [`external_directory`](#external-directories) 规则特别有用。
|
||
|
||
- `~/projects/*` -> `/Users/username/projects/*`
|
||
- `$HOME/projects/*` -> `/Users/username/projects/*`
|
||
- `~` -> `/Users/username`
|
||
|
||
### 外部目錄
|
||
|
||
使用 `external_directory` 允许工具调用启动 OpenCode 的工作目录之外的路径。这适用于任何采用路径作为输入的工具（例如 `read`、`edit`、`list`、`glob`、`grep` 和许多Z`bash` 命令）。
|
||
|
||
主扩展（如`~/...`）仅影响模式的编写方式。它不会使外部路径成为当前工作空间的一部分，因此仍然必须通过 `external_directory` 允许工作目录之外的路径。
|
||
|
||
例如，这允许访问`~/projects/personal/`下的所有内容：
|
||
|
||
```json title="opencode.json"
|
||
{
|
||
"$schema": "https://opencode.ai/config.json",
|
||
"permission": {
|
||
"external_directory": {
|
||
"~/projects/personal/**": "allow"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
这里允许的任何目录都会继承与当前工作空间默认相同的值。自[`read`默认为`allow`](#defaults)起，也允许读取`external_directory`下面的边界，除非被覆盖。当工具应在这些路径中时添加显式规则，例如在保留读取的同时阻止编辑：
|
||
|
||
```json title="opencode.json"
|
||
{
|
||
"$schema": "https://opencode.ai/config.json",
|
||
"permission": {
|
||
"external_directory": {
|
||
"~/projects/personal/**": "allow"
|
||
},
|
||
"edit": {
|
||
"~/projects/personal/**": "deny"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
将列表重点放在受信任的路径上，并根据其他工具的需要分层额外的允许或拒绝规则（例如`bash`）。
|
||
|
||
---
|
||
|
||
## 可用權限
|
||
|
||
OpenCode权限由工具名称和一些安全防护措施决定：
|
||
|
||
- `read` — 读取文件（与文件路径匹配）
|
||
- `edit` — 所有文件修改（头部`edit`、`write`、`patch`、`multiedit`）
|
||
- `glob` — 文件通配符（匹配通配符模式）
|
||
- `grep` — 内容搜索（匹配正则表达式模式）
|
||
- `list` — 上市目录中的文件（与目录路径匹配）
|
||
- `bash` — 运行 shell 命令（匹配 `git status --porcelain` 等解析命令）
|
||
- `task` — 启动子代理（与子代理类型匹配）
|
||
- `skill` — 加载技能（与技能名称匹配）
|
||
- `lsp` — 运行 LSP 查询（当前非粒度）
|
||
- `todoread`、`todowrite` — 讀取/更新待辦事項列表
|
||
- `webfetch` — 获取 URL（与 URL 匹配）
|
||
- `websearch`、`codesearch` — 網頁/代碼搜索（与查询匹配）
|
||
- `external_directory` — 当工具访问项目工作目录外部的路径时触发
|
||
- `doom_loop` — 当相同的工具调用相同的输入重复 3 次时触发
|
||
|
||
---
|
||
|
||
## 預設值
|
||
|
||
如果您未指定任何内容，OpenCode分散许可的默认值开始：
|
||
|
||
- 大部分权限默认为`"allow"`。
|
||
- `doom_loop`和`external_directory`默认为`"ask"`。
|
||
- `read` 是 `"allow"`，但 `.env` 文件默认被拒绝：
|
||
|
||
```json title="opencode.json"
|
||
{
|
||
"permission": {
|
||
"read": {
|
||
"*": "allow",
|
||
"*.env": "deny",
|
||
"*.env.*": "deny",
|
||
"*.env.example": "allow"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## “問”的作用是什麼
|
||
|
||
当 OpenCode 提示批准时，UI 会提供清晰的结果：
|
||
|
||
- `once` — 仅批准此请求
|
||
- `always` — 批准与建议模式匹配的未来请求（对于当前 OpenCode 会话的其余部分）
|
||
- `reject` — 拒绝请求
|
||
|
||
`always` 将批准的模式集由该工具提供（例如，bash 批准通常将安全端口（如 `git status*`）列入白名单）。
|
||
|
||
---
|
||
|
||
## 代理商
|
||
|
||
您可以覆盖每个代理的权限。代理权限与全局配置合并，代理规则优先。 [了解更多](/docs/agents#permissions)关于代理权限。
|
||
|
||
:::笔记
|
||
有关更详细的模式匹配示例，请参见上面的 [粒度规则（对象语法）](#granular-rules-object-syntax) 部分。
|
||
:::
|
||
|
||
```json title="opencode.json"
|
||
{
|
||
"$schema": "https://opencode.ai/config.json",
|
||
"permission": {
|
||
"bash": {
|
||
"*": "ask",
|
||
"git *": "allow",
|
||
"git commit *": "deny",
|
||
"git push *": "deny",
|
||
"grep *": "allow"
|
||
}
|
||
},
|
||
"agent": {
|
||
"build": {
|
||
"permission": {
|
||
"bash": {
|
||
"*": "ask",
|
||
"git *": "allow",
|
||
"git commit *": "ask",
|
||
"git push *": "deny",
|
||
"grep *": "allow"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
您还可以在 Markdown 中配置代理权限：
|
||
|
||
```markdown title="~/.config/opencode/agents/review.md"
|
||
---
|
||
description: Code review without edits
|
||
mode: subagent
|
||
permission:
|
||
edit: deny
|
||
bash: ask
|
||
webfetch: deny
|
||
---
|
||
|
||
Only analyze code and suggest changes.
|
||
```
|
||
|
||
:::提示
|
||
对参数的命令使用模式匹配。 `"grep *"` 允许 `grep pattern file.txt`，而 `"grep"` 单独会阻止它。像 `git status` 这样的命令适用于默认行为，但在传递参数时需要显式许可（如 `"git status *"`）。
|
||
:::
|