OpenCode 怎么开启网络搜索？websearch 启用、引擎选择与权限配置

你让 OpenCode 查最新文档，它却说自己不能联网；照着教程在配置文件里加了 "websearch": "allow"，重启后还是没有搜索工具。问题可能出在一个容易混淆的地方：允许搜索，不等于启用搜索工具。

开启 OpenCode 网络搜索，需要先满足工具的启用条件，再按需设置调用权限。如果还想固定使用 Exa 或 Parallel，则是另一项独立配置。下面按这个顺序整理 macOS 和 Windows 的操作步骤，最后说明怎么验证，以及 OpenCode v2 beta 是否需要改写配置。

最后核验：2026-09-09。本文的 v1 行为依据 OpenCode v1.18.30 源码与官方文档；v2 部分依据核验当日的 beta 迁移指南。启用条件见官方 websearch 文档。

1. 先启用 OpenCode 网络搜索

websearch 是 OpenCode 内置工具，默认连接 Exa 或 Parallel 提供的托管 MCP 服务，基本用法不需要自行申请 API Key，也不需要额外添加 MCP 配置。

在本文核验的 v1 版本中，满足以下任意条件，工具才会提供给模型：

• 当前模型使用 OpenCode 或 OpenCode Go provider；
• 启用环境变量 OPENCODE_ENABLE_EXA；
• 启用环境变量 OPENCODE_ENABLE_PARALLEL。

环境变量可以设为 1 或 true。使用其他 provider 的读者，可以先用下面的 Exa 命令验证；想用 Parallel，把变量名换成 OPENCODE_ENABLE_PARALLEL 即可。

macOS：先临时试用，再决定是否长期启用

打开终端，运行：

OPENCODE_ENABLE_EXA=1 opencode

这会立即为本次启动的 OpenCode 设置变量，不需要重开终端，也不会修改后续启动时的默认环境。

确认可用后，如果希望以后直接运行 opencode 就能搜索，在使用默认 zsh 的终端中执行一次：

echo 'export OPENCODE_ENABLE_EXA=1' >> ~/.zshrc

然后关闭并重新打开终端，再启动 OpenCode。也可以在当前终端执行 source ~/.zshrc 后重新启动。

如果你使用 bash，把启动文件换成适合自己 shell 的文件；macOS 的 bash 登录 shell 通常读取 ~/.bash_profile。已经写过这行配置，就直接修改原行，不必反复追加。

Windows：使用 PowerShell

打开 PowerShell，运行：

$env:OPENCODE_ENABLE_EXA = "1"
opencode

变量立即对当前 PowerShell 及它之后启动的程序生效，不影响其他已打开的窗口。

想保存到用户环境变量，执行：

[Environment]::SetEnvironmentVariable("OPENCODE_ENABLE_EXA", "1", "User")

然后重新启动终端应用和 OpenCode。如果新开的标签页仍读不到变量，退出整个 Windows Terminal 再打开；也可以先用上面的 $env: 命令给当前窗口赋值。

使用 CMD 的读者，可以通过 setx OPENCODE_ENABLE_EXA 1 保存用户变量，它不会更新当前窗口的环境。

如果你从桌面图标、编辑器或其他客户端启动 OpenCode，要确认实际运行 OpenCode 的进程继承了这些变量。 只写入 ~/.zshrc，不能保证所有图形界面启动方式都会读取它。

2. Exa 和 Parallel 怎么选？

OpenCode 对模型提供的是一个 websearch 工具，每次调用会选择一个后端。两个启用变量同时设置，不会让一次查询同时搜索两个引擎。

v1.18.30 的选择优先级如下：

想明确启用搜索并固定使用 Exa，macOS 可以这样启动：

OPENCODE_ENABLE_EXA=1 OPENCODE_WEBSEARCH_PROVIDER=exa opencode

固定使用 Parallel：

OPENCODE_ENABLE_PARALLEL=1 OPENCODE_WEBSEARCH_PROVIDER=parallel opencode

PowerShell 对应写法，例如 Parallel：

$env:OPENCODE_ENABLE_PARALLEL = "1"
$env:OPENCODE_WEBSEARCH_PROVIDER = "parallel"
opencode

注意，OPENCODE_WEBSEARCH_PROVIDER 只负责选择引擎。使用其他 provider 时，单独设置它并不能替代上一节的启用条件。

这项优先级依据固定版本的搜索实现。如果只是想快速开通，先用一个启用变量即可，不必把所有选项都配置一遍。

3. 工具可用后，再设置调用权限

权限决定模型调用工具时，是直接执行、先询问，还是拒绝。它不能把一个尚未启用的工具变成可用工具。

v1 使用 permission.websearch：

如果你希望模型查资料时直接搜索，可以配置为 allow。如果想先确认查询内容，使用 ask。

配置文件位置与最小示例

默认全局配置路径为：

• macOS：~/.config/opencode/opencode.json
• Windows：%USERPROFILE%\.config\opencode\opencode.json

也可以使用项目根目录的 opencode.json。自定义配置目录的读者应以自己的实际路径为准。

文件尚不存在时，先创建目录和文件，填入：

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "websearch": "allow"
  }
}

如果文件已经有配置，把 websearch 合并进现有的 permission 对象；没有 permission 时再新增。不要创建两个同名字段，也不要覆盖原来的 provider 或 MCP 配置。

例如，原来已经要求执行终端命令前询问，合并后可以是：

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

保存后重启 OpenCode。Windows 下确认文件名是 opencode.json，而不是 opencode.json.txt，并使用 UTF-8 编码。

按查询字符串设置权限

也可以使用通配规则：

{
  "permission": {
    "websearch": {
      "*": "ask",
      "documentation *": "allow"
    }
  }
}

这里匹配的是实际搜索字符串：以 documentation 开头的查询可自动放行，其余查询请求批准。它不会语义识别“这是在查文档”；例如中文查询“查询 Astro 官方文档”并不匹配这个英文前缀。

想继续整理其他工具权限和外部服务，可以参考本站的 OpenCode MCP 配置教程。

4. 怎么确认真的搜了？没生效怎么排查？

启动 OpenCode 后，明确要求它调用工具：

请使用 websearch 搜索今天的 AI 新闻，列出来源链接和发布日期。

检查界面里是否出现 websearch 的工具调用，以及调用是否成功返回结果。不同客户端的展示形式可能不同，有的会显示 Exa 或 Parallel 的工具标题。

回答里有链接，并不能单独证明它搜索过。 应以工具执行记录为准；出现调用记录但请求失败，也不代表搜索服务可用。

如果没看到成功调用，按下面的顺序排查：

1. 确认启用条件。 当前模型是否使用 OpenCode / OpenCode Go provider？否则，启动进程是否继承了启用变量？
2. 确认权限。 全局、项目或 agent 的配置里，是否拒绝了 websearch？
3. 确认调用。 模型可能没有主动搜索，先用上面的明确指令测试。
4. 确认网络和服务响应。 如果已经发起调用，检查超时、连接失败等具体错误，再决定是否切换引擎。

在实际启动 OpenCode 的终端里，可以查看变量。

macOS：

echo "$OPENCODE_ENABLE_EXA"
echo "$OPENCODE_ENABLE_PARALLEL"
echo "$OPENCODE_WEBSEARCH_PROVIDER"

PowerShell：

$env:OPENCODE_ENABLE_EXA
$env:OPENCODE_ENABLE_PARALLEL
$env:OPENCODE_WEBSEARCH_PROVIDER

不需要三个都有值，只要符合你的启用方式即可。这些输出只能证明当前终端的环境，不能证明另一个已启动进程也读取到了它们。

如果启动时报配置解析错误，按报错位置检查引号、逗号和括号，保留已有设置再修复。不要为了粘贴最小示例而清空整个配置文件。

websearch 和 webfetch 的区别

• websearch：查找信息来源，例如“这个库最近有什么版本更新”。
• webfetch：读取已知 URL，例如“帮我读一下这篇官方发布说明”。

两者可以连续使用：先搜索找到来源，再读取具体页面。允许 webfetch 不等于开启 websearch。

搜索可用且权限允许后，模型可能自行判断需要联网，不要求你每次都明确提出搜索。发给搜索服务的是工具实际提交的查询内容，因此也要注意模型是否把对话中的敏感细节写进了查询。

5. OpenCode v2 beta 需要重新配置吗？

截至本文核验日期，OpenCode v2 仍处于 beta，可以与 v1 并存：v1 使用 opencode，v2 使用 opencode2。

尝试 beta 的安装命令为：

npm install -g @opencode-ai/cli@beta
opencode2

仅为了尝试 v2，不需要把现有受支持的 v1 配置全部重写。 官方迁移指南说明，v2 会读取原有配置位置，并在内存中规范化受支持的 v1 字段；原生 v2 格式是可选迁移。

原生 v2 的权限使用有序 permissions 数组，例如：

{
  "permissions": [
    {
      "action": "websearch",
      "resource": "*",
      "effect": "allow"
    }
  ]
}

这仍然是权限规则，不能当作绕过搜索启用条件的开关。也不要把 v2 原生示例直接粘进仍由 v1 使用的配置中。

v2 的插件 API、服务端 API 和终端配置有单独的迁移要求，“兼容受支持的旧配置”不意味着旧插件也能直接运行。具体以官方 v2 迁移指南为准。

开启搜索最实用的顺序是：先用一条临时环境变量命令启动，确认工具成功返回结果，再保存长期配置。 引擎选择和调用权限按自己的需要补充即可。这样每一步都能验证，也更容易知道问题出在启用条件、权限还是网络连接上。