opencode 自用安装及使用笔记

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

目的：记录一下 Windows 下 opencode 的安装、全局配置、skill 路径、Tavily 联网工具、session 管理和隐私设置，后面换电脑或重装时可以直接照着配。

参考资料：

opencode 官网

下面内容以个人 Windows 环境为主，路径里的用户名按自己的电脑替换。

一、安装和启动

1. 使用 npm 安装

先确认电脑里已经有 Node.js 和 npm，然后在 cmd 或 PowerShell 中执行：

1
2
# 全局安装 opencode
npm i -g opencode-ai

安装完成后可以查看入口和版本：

1
2
where.exe opencode
opencode --version

若能返回 opencode 路径和版本号，说明安装没问题。

2. 在项目目录启动

进入需要让 opencode 处理的工程目录，再打开 cmd 或 PowerShell：

1
2
# 在当前工程目录启动 opencode
opencode

这样 opencode 会以当前文件夹作为工作区。不同项目建议分别启动，规则和 session 会更清楚。

3. 开启 Web 模式

如果需要在局域网或 ZeroTier 这类网络里远程访问，可以开启 web 服务：

1
2
3
4
5
6
:: 设置登录用户名和密码
set "OPENCODE_SERVER_USERNAME=自定义用户名"
set "OPENCODE_SERVER_PASSWORD=自定义密码"

:: 监听所有网卡，端口为 4096
opencode web --hostname 0.0.0.0 --port 4096

然后再通过 ZeroTier 等方式访问对应机器的 4096 端口。

注意：不要把这个端口直接暴露到公网。密码也不要用简单密码，否则相当于把本机项目目录交出去。

二、全局配置与规则文件

opencode 的全局配置目录通常在：

1
C:\Users\<你的用户名>\.config\opencode

常用文件和目录：

1
2
3
C:\Users\<你的用户名>\.config\opencode\opencode.jsonc
C:\Users\<你的用户名>\.config\opencode\AGENTS.md
C:\Users\<你的用户名>\.config\opencode\skills

其中：

  • opencode.jsonc：全局运行配置，例如 provider、share 策略等。
  • AGENTS.md：全局规则文件，适合放语言要求、工作习惯、禁止事项等。
  • skills：全局 skill 目录，每个 skill 通常是一个文件夹，里面有 SKILL.md。

如果只想让规则在某个项目里生效，可以把 AGENTS.md 放在项目根目录。

全局规则修改后，建议重启 opencode 或开启新会话，确保新规则重新加载。

三、全局 skill 路径

opencode 的全局 skill 路径格式如下：

1
C:\Users\<你的用户名>\.config\opencode\skills\<skill-name>\SKILL.md

例如本机的两个 skill：

1
2
C:\Users\1\.config\opencode\skills\tavily\SKILL.md
C:\Users\1\.config\opencode\skills\python-environment-safety\SKILL.md

本机额外添加了一个 python-environment-safety skill，用来约束 opencode 使用 Python 时的环境隔离策略。

简单理解就是：让 opencode 能调用 Python 工具，但不要顺手把系统 Python 弄乱。

四、Python 工具隔离原则

opencode 使用 Python 很方便，但不建议直接污染系统 Python 或用户 Python。

推荐规则：

  • 不直接执行没有隔离的 pip install。
  • opencode 自用 Python CLI 工具统一放进独立虚拟环境。
  • 长期工具放在 C:\Users\1\.config\opencode\tools\<tool-name>-venv。
  • 暴露命令时只在 C:\Users\1\.config\opencode\bin 中放包装脚本。
  • 临时脚本和中间文件放在 C:\Users\1\AppData\Local\Temp\opencode。

例如 Tavily CLI 的隔离结构：

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

这样可以让 tvly 被 opencode 调用，同时不把 tavily-cli、httpx、rich、tiktoken 等依赖装进系统 Python。

五、Tavily 配置笔记

Tavily 用于联网搜索、网页提取、站点抓取和深度研究。

本机已单独整理文章：

1
D:\Website\Blog\source\_posts\Tavily.md

常用验证命令：

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

理想状态：

1
2
where.exe tvly -> C:\Users\1\.config\opencode\bin\tvly.cmd
authenticated -> true

Windows 上如果 tvly login 报 FileNotFoundError: [WinError 2]，常见原因是 Tavily CLI 内部调用 npx，但 Windows 实际可执行文件是 npx.cmd。

处理思路：只修补 Tavily venv 内部的 CLI 逻辑，让它优先查找 npx.cmd，不要动系统 Python。

六、Share Session 的隐私含义

TUI 里的 /share 或 Share Session 会把当前会话生成公开链接。

官方说明中，分享后会：

  • 创建唯一公开 URL。
  • 同步 conversation history 到 OpenCode 服务器。
  • 通过 opncd.ai/s/<share-id> 访问。

默认模式是 manual，也就是不会自动分享。只有手动执行 /share 才会分享。

如果想彻底禁用分享，可以在 opencode.jsonc 中设置：

1
2
3
{
  "share": "disabled"
}

不要分享包含 API key、token、私有代码、敏感路径或敏感终端输出的会话。

如果已经分享，TUI 中可以使用：

1
/unshare

七、session 管理

opencode 的 session 数据存在全局数据库中：

1
C:\Users\1\.local\share\opencode\opencode.db

查看数据库路径：

1
opencode db path

TUI 中的 /sessions 更适合切换当前目录或当前项目内的 session：

1
/sessions

快捷键：

1
ctrl+x l

如果要跨文件夹查看所有 session，用 CLI 更准确：

1
opencode session list --format json --max-count 100

如果想看到更新时间、目录、标题和 session id：

1
opencode db "SELECT datetime(time_updated/1000, 'unixepoch', 'localtime') AS updated, directory, title, id FROM session ORDER BY time_updated DESC LIMIT 100" --format json

如果只想看哪些目录打开过 opencode：

1
opencode db "SELECT directory, COUNT(*) AS sessions FROM session GROUP BY directory ORDER BY MAX(time_updated) DESC" --format json

恢复某个 session：

1
opencode --session <sessionID>

跨目录恢复时，更稳妥的写法是显式带上原目录：

1
opencode "D:\对应目录" --session <sessionID>

八、常用排查命令

1. 查看 opencode 入口
1
2
where.exe opencode
opencode --version
2. 查看 CLI 帮助
1
2
3
4
opencode --help
opencode session --help
opencode db --help
opencode export --help
3. 导出 session
1
opencode export <sessionID>

导出时如需脱敏：

1
opencode export <sessionID> --sanitize

九、配置建议

个人使用时，建议按下面的方式整理：

  • 全局习惯写入 C:\Users\1\.config\opencode\AGENTS.md。
  • 项目专用规则写入项目根目录的 AGENTS.md。
  • Python CLI 工具统一隔离到 C:\Users\1\.config\opencode\tools。
  • 命令包装脚本统一放到 C:\Users\1\.config\opencode\bin。
  • 敏感项目建议在 opencode.jsonc 中设置 "share": "disabled"。

至此，opencode 在 Windows 下的基础使用流程就整理完了。后面如果继续折腾 provider、MCP 或更多 skills，再单独补充。