opencode-permission

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

OpenCode Permission Manager

OpenCode 权限管理器

Manage

permission

rules in

~/.config/opencode/opencode.jsonc

. Add, remove, list, or format auto-approval rules for shell commands and tool invocations.

管理

~/.config/opencode/opencode.jsonc

中的

permission

规则，为Shell命令和工具调用添加、删除、列出或格式化自动批准规则。

Workflow

工作流程

Identify the rule string(s) and action from the user's request (e.g.,
```
"kubectl get *"
```
→
```
allow
```
)
Determine the subcommand:
```
add
```
/
```
remove
```
/
```
list
```
/
```
list-all
```
/
```
format
```

Run the bundled script:

bash

# 单条添加
uv run --script <skill-path>/scripts/manage_permission.py add "kubectl get *" --action allow

# 批量添加
uv run --script <skill-path>/scripts/manage_permission.py add "kubectl get *" "kubectl describe *" "kubectl logs *"

Confirm the change was written
Remind the user: 修改配置后需要重启 OpenCode 才能生效

从用户请求中识别规则字符串和操作（例如：
```
"kubectl get *"
```
→
```
allow
```
）
确定子命令：
```
add
```
/
```
remove
```
/
```
list
```
/
```
list-all
```
/
```
format
```

运行捆绑脚本：

bash

# 单条添加
uv run --script <skill-path>/scripts/manage_permission.py add "kubectl get *" --action allow

# 批量添加
uv run --script <skill-path>/scripts/manage_permission.py add "kubectl get *" "kubectl describe *" "kubectl logs *"

确认变更已写入
提醒用户：修改配置后需要重启 OpenCode 才能生效

Behaviors

功能特性

自动备份：
```
add
```
/
```
remove
```
/
```
format
```
操作会在写入前创建带时间戳的备份，文件名格式
```
opencode.jsonc.YYYYMMDDTHHMMSS.bak
```
，多次变更各自保留。
自动格式化：
```
add
```
/
```
remove
```
操作完成后自动规范 bash 段格式，保证每条规则独占一行。
批量添加：
```
add
```
接受多个位置参数，只需一次执行。

自动备份：
```
add
```
/
```
remove
```
/
```
format
```
操作会在写入前创建带时间戳的备份，文件名格式为
```
opencode.jsonc.YYYYMMDDTHHMMSS.bak
```
，多次变更各自保留备份。
自动格式化：
```
add
```
/
```
remove
```
操作完成后自动规范bash段格式，保证每条规则独占一行。
批量添加：
```
add
```
支持多个位置参数，只需一次执行即可完成多条规则添加。

Command Reference

命令参考

Add rules

添加规则

bash

undefined

bash

undefined

单条（默认 action=allow）

uv run --script manage_permission.py add "kubectl get *"

批量添加

uv run --script manage_permission.py add "kubectl get *" "kubectl describe *" "kubectl logs *"

指定 action

指定操作

uv run --script manage_permission.py add "git commit *" --action ask uv run --script manage_permission.py add "rm -rf *" --action deny

自定义配置路径

uv run --script manage_permission.py add "kubectl get *" --config /path/to/opencode.jsonc

undefined

uv run --script manage_permission.py add "kubectl get *" --config /path/to/opencode.jsonc

undefined

Remove a rule

删除规则

bash

uv run --script manage_permission.py remove "kubectl get *"

bash

uv run --script manage_permission.py remove "kubectl get *"

List rules

列出规则

bash

undefined

bash

undefined

List permission.bash only

仅列出 permission.bash 规则

uv run --script manage_permission.py list

List all permission categories (bash, read, edit, etc.)

列出所有权限分类（bash、read、edit等）

uv run --script manage_permission.py list-all

undefined

uv run --script manage_permission.py list-all

undefined

Format rules

格式化规则

bash

undefined

bash

undefined

格式化 bash 规则（一行一条，自动备份）

格式化bash规则（一行一条，自动备份）

uv run --script manage_permission.py format

undefined

uv run --script manage_permission.py format

undefined

Rule Format Reference

规则格式参考

Permission actions

权限操作

Value	Meaning
`allow`	Auto-execute, no confirmation needed
`ask`	Prompt for confirmation each time
`deny`	Block the command entirely

值	含义
`allow`	自动执行，无需确认
`ask`	每次执行前提示确认
`deny`	完全阻止命令执行

Wildcard syntax

通配符语法

Symbol	Meaning	Example
`*`	Matches zero or more characters	`"git *"` matches `git status` , `git diff --staged`
`?`	Matches exactly one character	`"ls ?"` matches `ls -l` but not `ls -la`

Important:

"git status"

only matches

git status

with no arguments. To match with arguments, use

"git status *"

符号	含义	示例
`*`	匹配零个或多个字符	`"git *"` 匹配 `git status` 、 `git diff --staged`
`?`	匹配恰好一个字符	`"ls ?"` 匹配 `ls -l` 但不匹配 `ls -la`

重要提示：

"git status"

仅匹配不带参数的

git status

。若要匹配带参数的命令，请使用

"git status *"

。

Available permission keys

可用权限键

Key	Matches	Description
`bash`	Shell command pattern	Command execution (e.g., `"kubectl get *"` )
`read`	File path	File reading operations
`edit`	File path	File modifications (edit/write/patch)
`glob`	Glob pattern	File wildcard search
`grep`	Regex pattern	Content search
`list`	Directory path	Directory listing
`task`	Subagent type	Subagent spawning
`lsp`	LSP query	Language server queries
`skill`	Skill name	Skill loading
`external_directory`	File path	Access outside working directory
`todowrite`	—	Todo writing (simple, no pattern matching)
`question`	—	Asking user questions (simple)
`webfetch`	URL	Web fetching (simple)
`websearch` / `codesearch`	Search query	Web/code search (simple)
`doom_loop`	—	Repeated tool call detection (simple)

Simple keys (no pattern matching) accept only

"allow"

"ask"

, or

"deny"

as a string value.

键	匹配对象	描述
`bash`	Shell命令模式	命令执行（例如： `"kubectl get *"` ）
`read`	文件路径	文件读取操作
`edit`	文件路径	文件修改操作（编辑/写入/补丁）
`glob`	通配符模式	文件通配符搜索
`grep`	正则表达式模式	内容搜索
`list`	目录路径	目录列表
`task`	子Agent类型	子Agent生成
`lsp`	LSP查询	语言服务器查询
`skill`	Skill名称	Skill加载
`external_directory`	文件路径	访问工作目录外的路径
`todowrite`	—	Todo写入（简单模式，无匹配）
`question`	—	向用户提问（简单模式）
`webfetch`	URL	网页内容获取（简单模式）
`websearch` / `codesearch`	搜索查询	网页/代码搜索（简单模式）
`doom_loop`	—	重复工具调用检测（简单模式）

简单键（无模式匹配）仅接受

"allow"

、

"ask"

或

"deny"

作为字符串值。

Rule matching logic

规则匹配逻辑

Last matching rule wins — more specific rules override
```
"*"
```
defaults
Common pattern: set
```
"*": "ask"
```
as fallback, then add specific
```
allow
```
rules
Supports
```
~
```
and
```
$HOME
```
path expansion for file-related keys

最后匹配的规则生效——更具体的规则会覆盖
```
"*"
```
默认规则
常见模式：设置
```
"*": "ask"
```
作为 fallback，然后添加具体的
```
allow
```
规则
支持文件相关键使用
```
~
```
和
```
$HOME
```
路径展开

Configuration file format

配置文件格式

Location:

~/.config/opencode/opencode.jsonc

(global) or

<project>/.opencode/opencode.jsonc

(project-level)

Format: JSONC (JSON with Comments) — supports
```
//
```
and
```
/* */
```
comments

Structure:

jsonc

{
  "permission": {
    "edit": "ask",
    "bash": {
      "*": "ask",
      "kubectl get *": "allow",
      "git status *": "allow"
    }
  }
}

Agent-level override: Rules can also be set per-agent in the
```
agent
```
section, which take precedence over global rules

位置：全局配置为

~/.config/opencode/opencode.jsonc

，项目级配置为

<project>/.opencode/opencode.jsonc

格式：JSONC（带注释的JSON）——支持
```
//
```
和
```
/* */
```
注释

结构:

jsonc

{
  "permission": {
    "edit": "ask",
    "bash": {
      "*": "ask",
      "kubectl get *": "allow",
      "git status *": "allow"
    }
  }
}

Agent级覆盖：规则也可以在
```
agent
```
部分按Agent单独设置，优先级高于全局规则

Examples

示例

Allow all kubectl read operations

允许所有kubectl读取操作

bash

uv run --script manage_permission.py add \
  "kubectl get *" \
  "kubectl describe *" \
  "kubectl logs *" \
  "kubectl top *" \
  "kubectl explain *" \
  "kubectl diff *" \
  "kubectl auth can-i *"

bash

uv run --script manage_permission.py add \
  "kubectl get *" \
  "kubectl describe *" \
  "kubectl logs *" \
  "kubectl top *" \
  "kubectl explain *" \
  "kubectl diff *" \
  "kubectl auth can-i *"

Allow git commit but require confirmation for push

允许git commit但要求确认push操作

bash

uv run --script manage_permission.py add "git commit *" --action allow
uv run --script manage_permission.py add "git push *" --action ask

bash

uv run --script manage_permission.py add "git commit *" --action allow
uv run --script manage_permission.py add "git push *" --action ask

Block dangerous commands

阻止危险命令

bash

uv run --script manage_permission.py add "rm -rf *" --action deny

bash

uv run --script manage_permission.py add "rm -rf *" --action deny

Format existing config

格式化现有配置

bash

uv run --script manage_permission.py format

bash

uv run --script manage_permission.py format

View current rules

查看当前规则

bash

uv run --script manage_permission.py list

bash

uv run --script manage_permission.py list

Notes

注意事项

Uses
```
json-five
```
(ModelLoader/ModelDumper) to preserve all existing comments during read-modify-write cycles.
New rules are appended to the end of
```
permission.bash
```
; after writing, the bash section is automatically formatted to one-rule-per-line.
```
add
```
/
```
remove
```
/
```
format
```
create a timestamped backup before writing (e.g.,
```
opencode.jsonc.20260428T153045.bak
```
).

使用
```
json-five
```
（ModelLoader/ModelDumper）在读取-修改-写入周期中保留所有现有注释。
新规则会追加到
```
permission.bash
```
的末尾；写入后，bash段会自动格式化为一行一条规则。
```
add
```
/
```
remove
```
/
```
format
```
操作在写入前会创建带时间戳的备份（例如：
```
opencode.jsonc.20260428T153045.bak
```
）。