第24章 OpenCode 策略(Policies)管理指南
Policies 决定 OpenCode 是否允许对特定命名资源执行操作。它们定义在 policies 字段下,也可由已连接的 OpenCode Console 工作区下发。
Policies 与 Permissions(权限)是分开的。Permissions 是针对每个 Agent 的工具规则,可以允许、拒绝或询问。Policies 是二元的,从不提示用户,且只会收紧 Permissions 和 Providers 原本允许的范围。
要在所有地方拒绝某个 Provider,只需在 opencode.jsonc 中添加一条语句:
{
"$schema": "https://opencode.ai/config.json",
"policies": [{ "action": "provider.use", "resource": "openai", "effect": "deny" }],
}
被拒绝的 Provider 会从目录和模型选择中消失,即使它拥有有效的凭证。
早期版本从 experimental.policies 读取 Policies。该键仍然有效,并与 policies 合并:
{
"experimental": {
"policies": [{ "action": "provider.use", "resource": "openai", "effect": "deny" }],
},
}
每条语句包含三个字段:
| Field | Values | Meaning |
|---|---|---|
action |
provider.use, tool.use, integration.connect, integration.use, mcp.use, skill.use, plugin.use, websearch.use |
受控的操作 |
resource |
字符串或通配符模式 | 语句适用的对象;具体取决于 action |
effect |
allow, deny |
当语句匹配时的决策结果 |
验证失败的语句会被丢弃,并在服务器日志中记录警告,其余列表项照常生效。编辑 deny 语句后,请检查日志。
Resources 使用与 Permissions 相同的整值通配符:* 匹配零个或多个字符,? 匹配一个字符。
{
"policies": [{ "action": "provider.use", "resource": "company-*", "effect": "deny" }],
}
这会拒绝 company-us 和 company-eu。以 * 结尾的模式也匹配不带参数的值,因此 shell:git push * 也覆盖单独的 git push。
当多条语句匹配时,最后一条生效。没有优先级规则,因此请将宽泛的语句放在前面,例外情况放在后面。如果没有匹配项,则允许该操作。
{
"policies": [
{ "action": "provider.use", "resource": "*", "effect": "deny" },
{ "action": "provider.use", "resource": "anthropic", "effect": "allow" },
],
}
此时只有 Anthropic 可用。
provider.use 控制 Provider 是否完全可用。Resource 是 Provider ID:anthropic、openai、opencode,或 providers 中的自定义 ID。
{
"providers": {
"company-ai": {
"package": "@opencode/ai/providers/openai-compatible",
"settings": { "baseURL": "https://ai.company.example/v1" },
},
},
"policies": [
{ "action": "provider.use", "resource": "*", "effect": "deny" },
{ "action": "provider.use", "resource": "company-ai", "effect": "allow" },
],
}
providers 条目配置端点,而语句使其成为 OpenCode 唯一使用的 Provider。无论 Provider 是通过目录数据、环境变量、保存的账户、内置插件还是配置得知,策略都适用。请改用 provider.use,而不是 V1 的 enabled_providers 和 disabled_providers 列表。V1 文件仍会加载;参见“从 V1 迁移”。
tool.use 语句硬性拒绝权限检查。Resource 是 <action>:<value>,并与工具检查的所有资源进行匹配。
{
"policies": [
{ "action": "tool.use", "resource": "shell:git push *", "effect": "deny" },
{ "action": "tool.use", "resource": "edit:*.env", "effect": "deny" },
{ "action": "tool.use", "resource": "webfetch:*", "effect": "deny" },
],
}
被拒绝的检查会以“Blocked by configuration policy”失败,而不是提示用户。它在 Agent 规则和已保存的批准之后应用,因此同时覆盖“ask”和“Always allow”批准。
| Pattern | Blocks |
|---|---|
shell:* |
所有 shell 命令 |
read:*/.ssh/* |
读取 SSH 材料 |
external_directory:* |
对 Location 或 worktree 之外的任何访问 |
subagent:general |
启动一个 subagent |
github_delete_repository:* |
一个 MCP 工具 |
* |
所有未被明确拒绝的内容 |
tool.use 语句的 allow 永不授予访问权限。它只是解除之前更宽泛的 deny,之后由 Agent 自身的规则决定。
{
"policies": [
{ "action": "tool.use", "resource": "shell:*", "effect": "deny" },
{ "action": "tool.use", "resource": "shell:git status *", "effect": "allow" },
],
}
git status 回退到 Agent 的 shell 规则;其他所有命令都被阻止。
Integration 是你通过 /connect 连接的任何内容:OpenCode Console(opencode)、Provider(如 anthropic)、Web 搜索服务(如 exa),或知名配置源(如 https://ai.acme.com)。登录到 MCP 服务器不受 integration policies 影响;请使用 mcp.use 控制 MCP 服务器。
integration.connect 控制 /connect 列出哪些集成以及哪些可以连接。Resource 是集成 ID。
integration.use 控制集成提供的所有内容:其 Providers 和模型、Web 搜索,以及 Console 工作区或知名源下发的 MCP 服务器和配置。Resource 是 <integration>#<account>,其中 account 是连接的组织或账户 ID,例如 opencode#org_01M3CAP8H43Z49CER6NT0Y3ZF1。如果没有连接的账户,则使用裸集成 ID:登出的免费层是 opencode,ANTHROPIC_API_KEY 环境变量是 anthropic,来自 opencode.json 的 Provider 则是其 Provider ID。
这个 MDM 策略要求一个 Console 工作区,且不允许其他任何内容:
{
"policies": [
{ "action": "integration.connect", "resource": "*", "effect": "deny" },
{ "action": "integration.connect", "resource": "opencode", "effect": "allow" },
{ "action": "integration.use", "resource": "*", "effect": "deny" },
{ "action": "integration.use", "resource": "opencode#org_01M3CAP8H43Z49CER6NT0Y3ZF1", "effect": "allow" },
],
}
/connect 只提供 Console 以便成员登录。免费层、个人 Console 账户、其他组织、环境变量 API 密钥以及来自 opencode.json 的 Providers 均不可用。工作区的 Providers、MCP 服务器和 Web 搜索正常工作,且在 Console 中更改它们无需新的 MDM 配置文件。只有托管策略才能扣留集成下发的 MCP 服务器和配置;其自身策略无论如何都会持续生效。
| Action | Resource |
|---|---|
mcp.use |
按配置名称指定的 MCP 服务器 |
skill.use |
按 ID 指定的 Skill |
plugin.use |
按无版本包名或绝对路径指定的 Plugin |
{
"policies": [
{ "action": "mcp.use", "resource": "*", "effect": "deny" },
{ "action": "mcp.use", "resource": "github", "effect": "allow" },
{ "action": "plugin.use", "resource": "opencode-acme-cli", "effect": "deny" },
],
}
被拒绝的 MCP 服务器或 Skill 会被移除,被拒绝的 Plugin 不会被加载,无论其配置方式如何。
在 OpenCode 2.2.3 之前,integration.use 通过 mcp:、skill: 或 plugin: 前缀覆盖 MCP 服务器、Skills 和 Plugins。带前缀的语句仍会加载,并转换为 mcp.use、skill.use 或 plugin.use。没有这些前缀的语句(包括裸 *)现在适用于 integrations。宽泛的 deny,例如:
{ "action": "integration.use", "resource": "*", "effect": "deny" }
不再阻止 MCP 服务器、Skills 或 Plugins。而是阻止所有 Providers(包括免费层),除非后续语句允许某个 integration。要保持旧语义,请替换为:
{
"policies": [
{ "action": "mcp.use", "resource": "*", "effect": "deny" },
{ "action": "skill.use", "resource": "*", "effect": "deny" },
{ "action": "plugin.use", "resource": "*", "effect": "deny" },
],
}
例外情况也以同样方式移动:integration.use mcp:github 变为 mcp.use github,skill:team:review 变为 skill.use team:review。早于 2.2.3 的客户端会忽略 integration.connect、integration.use(其新语义)、mcp.use、skill.use 和 plugin.use,因此如果你依赖它们,请要求使用 2.2.3 或更高版本。
websearch.use 控制 websearch 工具可用的 Web 搜索 Providers。Resource 是 Provider ID:opencode(来自 Console 的 OpenCode Web Search)、内置 Provider(如 exa、firecrawl、parallel、tavily 或 tinyfish),或 Plugin 添加的 Provider ID。
{
"policies": [
{ "action": "websearch.use", "resource": "*", "effect": "deny" },
{ "action": "websearch.use", "resource": "opencode", "effect": "allow" },
],
}
被拒绝的 Provider 会被移除,即使它们无需 API 密钥即可工作(如 Exa 和 TinyFish)。当所有 Provider 都被拒绝时,websearch 工具不再提供。早于 2.2.6 的客户端会忽略 websearch.use。
普通设置让最近的配置获胜。Policies 则相反:来自更广泛配置的语句在后续评估,因此覆盖较窄的配置。托管配置和已连接的 Console 始终优于用户和项目文件。
| Authority | Source |
|---|---|
| 1 (highest) | macOS managed preferences (/Library/Managed Preferences/ai.opencode.managed.plist) |
| 2 | System opencode.json(c) (/Library/Application Support/opencode, /etc/opencode, %ProgramData%\opencode) |
| 3 | Connected OpenCode Console workspace |
| 4 | Global ~/.config/opencode/opencode.json(c) |
| 5 | Direct opencode.json(c); 外层目录优先于内层 |
| 6 (lowest) | .opencode/opencode.json(c); 外层目录优先于内层 |
仓库无法重新启用你全局拒绝的 Provider:
// ~/.config/opencode/opencode.jsonc
{
"policies": [{ "action": "provider.use", "resource": "openai", "effect": "deny" }],
}
// project/opencode.jsonc
{
"policies": [{ "action": "provider.use", "resource": "openai", "effect": "allow" }],
}
openai 保持被拒绝状态。在同一个文件内,语句保持其书写顺序。
OpenCode Console 上的工作区会将其 Providers 和 Tools 策略编译为工作区配置中的常规 policies 语句。OpenCode 合并该配置的方式类似于排在托管首选项和系统文件之下的配置文件,因此组织拒绝无法被仓库或用户允许解除,而组织允许则解除较低权限的拒绝。托管首选项和系统文件仍优先于工作区。这些语句的拒绝会指明工作区:
Blocked by Acme's policy
语句遵循连接的账户。
| Event | Result |
|---|---|
| Console policy changes | 在下次获取时应用,大约每分钟一次 |
| Switch to another workspace | 语句被该工作区的语句替换 |
| Disconnect | 语句被清除 |
| Console unreachable | 该连接的最后一个语句保持生效 |
Console 插件和策略插件无法从 plugins 中禁用;参见“Plugin 控制”。