夜雨聆风学习资料网

ARTICLE · 1011823

OpenCode 绿色安装教程(Windows)

发布时间：2026-09-16 02:58:03 最近访问：2026-09-16 02:58:02
OpenCode 绿色安装教程(Windows)
纯绿色安装

目标：把 OpenCode 装到非系统盘的自定义目录，所有配置、会话、缓存、状态文件统一收纳到指定路径，不污染 C:\Users\你的用户名\ 下的默认目录。适合喜欢"绿色便携 / 数据集中管理"的用户。

目录

  • 一、最终目录规划
  • 二、下载 OpenCode（CLI 版，非桌面版）
  • 三、配置环境变量
  • 四、创建 OpenCode 配置目录与配置文件
  • 五、下载并启动 OC Manager
  • 六、在 OC Manager 中配置供应商
  • 七、验证安装
  • 八、常见问题

一、最终目录规划

用途
路径（示例）
OpenCode 主程序
E:\AgentTool\bin\opencode.exe
OpenCode 全局配置
E:\AgentData\XDG\config\opencode\opencode.jsonc
会话 / 应用数据
E:\AgentData\XDG\data\
缓存
E:\AgentData\XDG\cache\
状态
E:\AgentData\XDG\state\
运行时
E:\AgentData\XDG\runtime\

工具目录统一挂在 AGENT_TOOL 环境变量下，配置类目录统一挂在 XDG_* 环境变量下。以后迁移或备份，只需拷贝这两个根目录。

二、下载 OpenCode（CLI 版，非桌面版）

  1. 打开 OpenCode 的 GitHub Releases 页面：https://github.com/anomalyco/opencode/releases/latest

  2. 在 Assets 里下载 Windows x64 的压缩包（当前最新版为 v1.18.30）：

    文件
    说明
    opencode-windows-x64.zip推荐，标准版，绝大多数 64 位 CPU 适用
    opencode-windows-x64-baseline.zip
    兼容版，老 CPU（不支持 AVX2 等新指令集）时使用

  3. 不要下载带 desktop 字样的文件，例如 opencode-desktop-*.exe / .dmg / .deb / .AppImage——那是图形桌面版，不是本教程要用的命令行版。

  4. 解压 zip，得到 opencode.exe，先放一边，第三步要用。

提示：baseline 版和标准版只有 CPU 指令集兼容性差异，功能完全一致。不确定时先用标准版，若启动报非法指令错误再换 baseline 版。

三、配置环境变量

按 Win + R → 输入 sysdm.cpl → 回车 → 高级 选项卡 → 环境变量。

3.1 新建 XDG 目录变量（用户变量区）

XDG 是 freedesktop.org 的 XDG Base Directory Specification（跨平台目录规范，不是 OpenCode 独有），OpenCode 支持用它来决定配置、数据、缓存等目录落点。

变量名
值（示例）
XDG_CONFIG_HOMEE:\AgentData\XDG\config
XDG_DATA_HOMEE:\AgentData\XDG\data
XDG_CACHE_HOMEE:\AgentData\XDG\cache
XDG_STATE_HOMEE:\AgentData\XDG\state
XDG_RUNTIME_DIRE:\AgentData\XDG\runtime

XDG_RUNTIME_DIR 是 v2 版本新增项，一并配上即可。

3.2 新建工具目录变量（其他agent用到的工具也可以放这）

变量名
值
AGENT_TOOLD:\AgentTool

3.3 把 opencode.exe 放进 bin 目录

  1. 在 D:\AgentTool 下新建 bin 文件夹；
  2. 将第二步解压出的 opencode.exe 复制到 D:\AgentTool\bin\。
  3. 升级时只需要重新下载opencode.exe进行替换即可

3.4 把 bin 目录加入 Path

在用户变量里选中 Path → 编辑 → 新建 → 填入：

%AGENT_TOOL%\bin

3.5 一键设置（PowerShell 替代方案）

若不想点图形界面，可用管理员权限打开 PowerShell 逐条执行（用户级即去掉 /M）：

setx XDG_CONFIG_HOME  "E:\data\AgentData\XDG\config"setx XDG_DATA_HOME    "E:\data\AgentData\XDG\data"setx XDG_CACHE_HOME   "E:\data\AgentData\XDG\cache"setx XDG_STATE_HOME   "E:\data\AgentData\XDG\state"setx XDG_RUNTIME_DIR  "E:\data\AgentData\XDG\runtime"setx AGENT_TOOL       "D:\Application\installfiles\AgentTool"

Path 追加（避免覆盖已有内容，先读取再写回）：

$p = [Environment]::GetEnvironmentVariable("Path", "User")[Environment]::SetEnvironmentVariable("Path", $p + ";%AGENT_TOOL%\bin", "User")

重要：设置完成后，关闭并重新打开 所有终端 / 资源管理器，环境变量才会生效。可用新开的 PowerShell 执行 echo $env:XDG_CONFIG_HOME 与 opencode --version 验证。

四、创建 OpenCode 配置目录与配置文件

  1. 在 E:\AgentData\XDG\config 下新建文件夹 opencode；
  2. 在 E:\AgentData\XDG\config\opencode\ 下新建文件 opencode.jsonc。

路径即：E:\AgentData\XDG\config\opencode\opencode.jsonc

先写入一个最小可用模板（后续在 OC Manager 里可视化编辑时会自动补全）：

{// OpenCode 配置架构地址，供编辑器提供补全提示"$schema":"https://opencode.ai/config.json"}

opencode.jsonc 支持 // 注释（jsonc = JSON with Comments）。若不想手写，也可以只建空文件，第五步的 OC Manager 保存供应商时会自动写入内容。

五、下载并启动 OC Manager

OC Manager 是 OpenCode 的可视化管理桌面端（启动服务、管理会话、配置供应商、OMO 模型映射、技能管理等一站搞定）。

  1. 打开项目 Releases 页面：https://github.com/Mrsandman327/OpenCode-Client/releases/latest
  2. 下载 Windows 版（oc-manager.exe），放到任意目录。
  3. 双击 oc-manager.exe 启动。
  4. 点击左侧 📂 工作区 → 顶部 ▶ 启动 OpenCode，状态栏显示「在线」即启动成功。

OC Manager 会自动探测本机已有的 opencode serve（默认端口 4096）并连接，无需手动开服务。

六、在 OC Manager 中配置供应商

点击左侧 🔌 供应商配置，进入后按以下步骤操作：

  1. 点击底部虚线 ➕ 添加供应商 卡片，新增一个供应商。

  2. 填写基础字段：

    字段
    说明
    示例
    key
    供应商标识（唯一）
    		deepseek
    名称
    显示名
    		DeepSeek
    baseURL
    请求地址
    		https://api.deepseek.com/v1
    API Key
    密钥，点 👁 可切换明文
    		sk-xxxxxxxx
    接口格式
    对应配置里的 npm 包
    多数第三方/中转站选 @ai-sdk/openai-compatible

  3. 添加模型：

    • 手动添加：点 + 添加，填模型 ID + 名称；
    • 自动拉取：点 📡 获取模型列表，调用该供应商 /models 接口，弹窗勾选即可。

  4. 模态能力配置（重要）：每个模型点「模态」按钮展开，勾选输入/输出能力（文本、图像、PDF、音频、视频）。中转站 / 第三方模型常被 OpenCode 误判为"不支持图像"——在这里手动勾上「图像」即可恢复识图能力。

  5. 打开卡片右上角 🔒 启用 开关（会写入 enabled_providers 列表）。

  6. 点击 💾 保存，软件会把配置写入第四步建的 opencode.jsonc。

保存后配置文件大致如下：

{"$schema":"https://opencode.ai/config.json","provider":{"deepseek":{"npm":"@ai-sdk/openai-compatible","name":"DeepSeek","options":{"baseURL":"https://api.deepseek.com/v1","apiKey":"sk-xxxxxxxx"},"models":{"deepseek-v4-pro":{"name":"DeepSeek-V4-Pro"},"deepseek-v4-flash":{"name":"DeepSeek-V4-Flash"}}}},"enabled_providers":["opencode"、"deepseek"]}

接口格式下拉对应的固定选项：@ai-sdk/openai、@ai-sdk/openai-compatible、@ai-sdk/anthropic、@ai-sdk/amazon-bedrock、@ai-sdk/google。历史配置中的自定义 npm 会显示"未匹配保留"，保存时原样写回，不会被覆盖。

七、验证安装

新开一个 PowerShell：

opencode --version# 能输出版本号，说明 PATH 生效echo$env:XDG_CONFIG_HOME# 应输出 E:\data\AgentData\XDG\config

确认配置目录落点正确：

dir E:\data\AgentData\XDG\config\opencode

应能看到 opencode.jsonc。随后在 OC Manager 里点 🌍 Web 服务 可开启浏览器 / 手机端访问，实现桌面、Web、手机三端同步。

八、常见问题

Q1：设置了环境变量但没生效？环境变量在进程启动时读取，务必重开终端和资源管理器（或注销/重启），旧窗口不会刷新。

Q2：opencode 命令找不到？检查 %AGENT_TOOL%\bin 是否已加入 Path、opencode.exe 是否确实在 bin 内、文件名是否为 opencode.exe（无多余后缀）。

Q3：启动报非法指令（Illegal instruction）？CPU 较老，换用 opencode-windows-x64-baseline.zip。

Q4：配置文件写在哪？全局配置 = %XDG_CONFIG_HOME%\opencode\opencode.jsonc；项目级配置 = 项目根目录下的 .opencode\opencode.jsonc。OC Manager 的供应商 / OMO 页面改的是全局配置。

Q5：会话数据存在哪？%XDG_DATA_HOME%（本教程即 E:\data\AgentData\XDG\data）。备份这个目录即可保留全部会话。

附：说明

  1. 工具目录环境变量统一为 AGENT_TOOL（避免大小写/拼写不一致导致 Path 引用失效）。
  2. Path 条目正确写法为 %AGENT_TOOL%\bin（%AGENT_TOOL% 与 bin 之间必须有反斜杠分隔）。
  3. opencode.exe 从 opencode-windows-x64.zip 解压获得；OC Manager 仓库地址为 https://github.com/Mrsandman327/OpenCode-Client。
  4. linux下绿色安装可参考这篇文章

相关学习资料