Windows 下 opencode 配置 Tavily 笔记

使用设备：笔记本，Windows 11。

目的：给 opencode 配好 Tavily，让它能做联网搜索、网页提取、站点抓取和深度研究，同时不污染系统 Python。

参考资料：

Tavily 官网

opencode 官网

下面路径按本机环境记录，其他电脑把 C:\Users\1 换成自己的用户目录即可。

一、先说最终效果

配置完成后，主要有三个位置：

1
2
3
C:\Users\1\.config\opencode\skills\tavily\SKILL.md
C:\Users\1\.config\opencode\tools\tavily-venv
C:\Users\1\.config\opencode\bin\tvly.cmd

分别对应：

  • skills\tavily\SKILL.md：opencode 的 Tavily skill 描述文件。
  • tools\tavily-venv：Tavily CLI 的独立 Python 虚拟环境。
  • bin\tvly.cmd：暴露给 opencode 调用的包装脚本。

这样做的好处是：tvly 可以正常被 opencode 调用，但 Tavily CLI 的依赖不会装进系统 Python。

二、确认 Tavily skill 已存在

先检查全局 skill 目录中有没有 Tavily：

1
Test-Path -LiteralPath "C:\Users\1\.config\opencode\skills\tavily\SKILL.md"

如果返回：

1
True

说明 skill 文件已经存在，可以继续往下做。

如果返回 False，需要先补齐 Tavily skill。本文后面默认这个文件已经存在。

三、创建 Tavily 独立虚拟环境

1. 创建 opencode 工具目录
1
New-Item -ItemType Directory -Path "C:\Users\1\.config\opencode\tools" -Force

这个目录专门放 opencode 自己要用的 CLI 工具，不和系统工具混在一起。

2. 创建 Tavily venv
1
python -m venv "C:\Users\1\.config\opencode\tools\tavily-venv"

这里用系统里的 python 创建 venv，但后续安装包只装进这个 venv。

3. 安装 Tavily CLI
1
& "C:\Users\1\.config\opencode\tools\tavily-venv\Scripts\python.exe" -m pip install --upgrade pip tavily-cli

验证 venv 内的 tvly 是否可用：

1
& "C:\Users\1\.config\opencode\tools\tavily-venv\Scripts\tvly.exe" --version

若能输出版本号，例如：

1
tavily-cli 0.1.2

说明 CLI 已经安装成功。版本号以实际输出为准。

四、创建 tvly 包装脚本

1. 创建 bin 目录
1
New-Item -ItemType Directory -Path "C:\Users\1\.config\opencode\bin" -Force
2. 新建 tvly.cmd

创建文件：

1
C:\Users\1\.config\opencode\bin\tvly.cmd

写入下面内容：

1
2
@echo off
"%USERPROFILE%\.config\opencode\tools\tavily-venv\Scripts\tvly.exe" %*

这个脚本的作用是：当系统或 opencode 执行 tvly 时，实际运行 venv 里的 tvly.exe。

五、把 opencode bin 加入 PATH

需要把下面目录加入用户 PATH：

1
C:\Users\1\.config\opencode\bin

PowerShell 示例：

1
2
3
4
5
6
7
$binDir = "C:\Users\1\.config\opencode\bin"
$userPath = [Environment]::GetEnvironmentVariable('Path', 'User')
$entries = if ([string]::IsNullOrWhiteSpace($userPath)) { @() } else { $userPath -split ';' }
if ($entries -notcontains $binDir) {
  $newPath = (@($binDir) + $entries | Where-Object { $_ }) -join ';'
  [Environment]::SetEnvironmentVariable('Path', $newPath, 'User')
}

当前终端如果还没有加载新的 PATH，可以临时加一下：

1
$env:Path = "C:\Users\1\.config\opencode\bin;$env:Path"

验证命令来源：

1
where.exe tvly

理想结果：

1
C:\Users\1\.config\opencode\bin\tvly.cmd

如果不是这个路径，说明 PATH 优先级可能不对，或者之前装过其他来源的 tvly。

六、检查 Tavily 登录状态

先看当前认证状态：

1
tvly --status --json

未登录时一般类似：

1
{"version": "0.1.2", "authenticated": false}

这说明 CLI 已经能跑，但是还没有登录 Tavily。

七、登录 Tavily

1. 浏览器 OAuth 登录
1
tvly login

根据提示在浏览器里完成认证。

成功后可能会看到类似：

1
2
> Authenticated via OAuth
  Token stored in ~/.mcp-auth/
2. API key 登录

如果不想走浏览器，也可以用 API key：

1
tvly login --api-key tvly-你的key

注意：不要把自己的 API key 写进博客、截图、Git 仓库或公开会话里。

3. 再次验证
1
2
tvly --status --json
tvly auth --json

理想结果类似：

1
{"version": "0.1.2", "authenticated": true}
1
{"authenticated": true, "source": "OAuth (~/.mcp-auth/)"}

只要 authenticated 是 true，就说明 Tavily 认证没问题。

八、Windows 下 tvly login 的 npx 问题

1. 报错现象

Windows 上执行：

1
tvly login

可能会报：

1
FileNotFoundError: [WinError 2] 系统找不到指定的文件。

这不一定是没有安装 Node.js。

常见原因是 Tavily CLI 的 OAuth 流程内部调用了：

1
subprocess.Popen(["npx", "-y", "mcp-remote", "https://mcp.tavily.com/mcp"])

但在 Windows 里，实际可执行文件通常是 npx.cmd，Python 的 subprocess.Popen(["npx", ...]) 不一定能正确命中。

2. 先确认 npx 是否存在
1
where.exe npx

如果能看到类似：

1
D:\Portable\nodejs\npx.cmd

说明本机有 npx.cmd，可以只修补 Tavily venv 内部逻辑，不要动系统 Python。

3. 修改 Tavily CLI 的 auth.py

需要修改的文件：

1
C:\Users\1\.config\opencode\tools\tavily-venv\Lib\site-packages\tavily_cli\commands\auth.py

在 login 函数的 OAuth 分支中，把直接调用 npx 的逻辑改成优先查找 npx.cmd：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
import os
import shutil
import subprocess
import time

npx = shutil.which("npx.cmd" if os.name == "nt" else "npx") or shutil.which("npx")
if not npx:
    err_console.print()
    err_console.print("  [#FAA2FB]> Error:[/#FAA2FB] npx was not found in PATH.")
    err_console.print("  Install Node.js or use: tvly login --api-key tvly-YOUR_KEY")
    err_console.print()
    raise SystemExit(3)

proc = subprocess.Popen(
    [npx, "-y", "mcp-remote", "https://mcp.tavily.com/mcp"],
    stdin=subprocess.DEVNULL,
    stdout=subprocess.DEVNULL,
    stderr=subprocess.DEVNULL,
)

修补后做语法检查：

1
& "C:\Users\1\.config\opencode\tools\tavily-venv\Scripts\python.exe" -m py_compile "C:\Users\1\.config\opencode\tools\tavily-venv\Lib\site-packages\tavily_cli\commands\auth.py"

没有输出一般就是通过。

然后再登录：

1
tvly login

这个修补只影响当前 tavily-venv，不改系统 Python。以后升级 tavily-cli 后如果又复现，可能需要重新检查一次。

九、验证 opencode 可以调用 Tavily

最终检查这几条：

1
2
3
4
where.exe tvly
tvly --version
tvly --status --json
tvly auth --json

期望看到的关键点：

1
2
C:\Users\1\.config\opencode\bin\tvly.cmd
tavily-cli 0.1.2
1
{"version": "0.1.2", "authenticated": true}
1
{"authenticated": true, "source": "OAuth (~/.mcp-auth/)"}

如果已经打开的 opencode 会话找不到 tvly，重启 opencode 或重新打开终端，让新的 PATH 生效。

十、为什么不要直接 pip install

图省事的话可能会直接这样装：

1
python -m pip install tavily-cli

不推荐。

如果没有 venv，这会把包安装进系统 Python 或用户 Python，后面容易出现这些问题：

  • site-packages 被污染。
  • Scripts 目录出现来源不清的 CLI。
  • httpx、rich、tiktoken 等依赖版本可能和其他工具冲突。
  • 之后很难判断某个命令到底来自哪个 Python 环境。

更安全的结构是：

1
2
3
opencode tools venv -> 安装 tavily-cli
opencode bin wrapper -> 暴露 tvly 命令
系统 Python -> 保持干净

十一、清理和排查命令

如果怀疑装错了环境，可以用这些命令定位：

1
2
3
4
5
where.exe tvly
where.exe python
where.exe pip
python -m pip show tavily-cli tavily-python httpx rich tiktoken
python -s -m pip show tavily-cli tavily-python httpx rich tiktoken

判断原则：

  • where.exe tvly 应该指向 C:\Users\1\.config\opencode\bin\tvly.cmd。
  • tavily-cli 应该只出现在 C:\Users\1\.config\opencode\tools\tavily-venv。
  • 系统 Python 和用户 Python 不应该有 Tavily CLI 带入的一堆依赖。

如果需要清理 pip 缓存：

1
python -m pip cache purge

注意：清理缓存不等于卸载包。真装错环境时，还需要先确认包在哪个 Python 里，再决定是否卸载。

十二、最后记两条命令

配置完之后，平时主要看这两条就够了：

1
2
where.exe tvly
tvly --status --json

只要 tvly 来自：

1
C:\Users\1\.config\opencode\bin\tvly.cmd

并且认证状态为：

1
{"authenticated": true}

就说明 Tavily 已经可以被 opencode 使用。

至此，Windows 下给 opencode 配置 Tavily 的流程就整理完了。后面如果 Tavily CLI 更新后修掉 npx 问题，可以把第八部分删掉或改成补充说明。