【排坑复盘】WSL + Fish + OpenCode 接入火山方舟 OpenAI 兼容模型全流程

环境：WSL + Fish Shell
工具：OpenCode AI 编程助手目标：稳定接入火山方舟 OpenAI 兼容接口关键词：OpenCode 配置、火山方舟、WSL 排坑、Fish Shell 兼容

一、前言

最近在 WSL + Fish Shell 环境下配置 OpenCode，接入火山方舟的 OpenAI 兼容模型时，踩了大量环境兼容坑。典型报错包括：

bad file reference 文件明明存在却提示不存在
Fish 脚本语法报错
配置文件路径、权限、解析各种不生效

折腾一圈后终于稳定跑通。本文把问题原因、坑点、最终可直接复用的配置完整复盘，帮后来者少走弯路。

二、先讲通用标准：普通 Linux 下 OpenCode 配置放哪、怎么写

不管是 Ubuntu、Debian 还是 CentOS，标准 Linux 环境的规则是统一的，先把这套学会，再看 WSL 差异。

1. 标准路径（必记）

# 主配置：模型、提供商、默认模型
~/.config/opencode/opencode.json

# 认证密钥：存放 API Key 等敏感信息
~/.local/share/opencode/auth.json

~ 代表当前用户家目录：/home/你的用户名/
目录不存在时，手动创建即可

2. 标准 Linux 下推荐写法（规范、安全）

2.1 auth.json

{
  "volc-ark": {
    "type": "api",
    "key": "你的火山方舟 API Key"
  }
}

2.2 opencode.json（引用式，安全规范）

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "volc-ark": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "火山方舟",
      "options": {
        "baseURL": "https://ark.cn-beijing.volces.com/api/v3",
        "apiKey": "{file:~/.local/share/opencode/auth.json#volc-ark.key}"
      },
      "models": {
        "ep-xxxx-xxxx": {"name": "doubao1.6_lite"},
        "ep-xxxx-xxxx": {"name": "智能模型路由(语言)"},
        "ep-xxxx-xxxx": {"name": "doubao_code"},
        "ep-xxxx-xxxx": {"name": "DeepSeekR1"},
        "ep-xxxx-xxxx": {"name": "生成音图(1.5pro)"},
        "ep-xxxx-xxxx": {"name": "pc-agent-loop(seed2.0)"},
        "ep-xxxx-xxxx": {"name": "doubao_1.6"}
      }
    }
  },
  "model": "volc-ark/ep-xxxx-xxxx",
  "small_model": "volc-ark/ep-xxxx-xxxx"
}

2.3 权限设置（标准 Linux 必须）

mkdir -p ~/.config/opencode
mkdir -p ~/.local/share/opencode

chmod 600 ~/.local/share/opencode/auth.json
chmod 644 ~/.config/opencode/opencode.json

三、本次问题与报错汇总

配置过程中主要遇到三类典型错误：

1. 文件引用解析失败

1 2	Configuration is invalid: bad file reference: {file:/xxx/auth.json#volc-ark.key} does not exist

明明文件、路径、权限都正确，OpenCode 就是读不到。

2. Fish Shell 脚本语法不兼容

1	Expected a string, but found a redirection

直接复制 Bash 风格的 << 'EOF' 脚本在 Fish 下直接报错。

3. WSL 路径/权限行为异常

~ 解析不稳定
Windows 编辑器保存会带 BOM 头导致 JSON 解析失败
chmod 600 在 WSL 挂载目录下不一定被识别

四、根本原因总结

OpenCode 的 {file:...#key} 引用机制在 WSL 下存在兼容问题
Fish Shell 不兼容 Bash 的 Here-Document 语法
WSL 文件系统权限与 Linux 原生行为不一致
跨环境叠加后，复杂引用方案极易失效

最终结论：复杂方案 ≠ 稳定方案。简化配置反而一次成功。

五、WSL + Fish 下最终稳定方案（可直接复制）

5.1 配置文件路径

1 2	# 主配置文件（必须） ~/.config/opencode/opencode.json

5.2 最终稳定版 opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "volc-ark": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "火山方舟",
      "options": {
        "baseURL": "https://ark.cn-beijing.volces.com/api/v3",
        "apiKey": "此处填写你自己的火山方舟 API Key"
      },
      "models": {
        "ep-xxxx-xxxx": {"name": "doubao1.6_lite"},
        "ep-xxxx-xxxx": {"name": "doubao_code"},
        "ep-xxxx-xxxx": {"name": "DeepSeekR1"},
        "ep-xxxx-xxxx": {"name": "doubao_1.6"}
      }
    }
  },
  "model": "volc-ark/ep-xxxx-xxxx",
  "small_model": "volc-ark/ep-xxxx-xxxx"
}

5.3 关键要点

使用 @ai-sdk/openai-compatible 适配器
火山方舟统一接入地址：https://ark.cn-beijing.volces.com/api/v3
WSL+Fish 环境下：直接填写 apiKey 最稳定
放弃 auth.json 引用，避免解析兼容问题
模型名为自定义别名，方便在 CLI 中识别

六、验证是否配置成功

保存后执行：

1 2	opencode --model opencode /models

出现模型列表、无报错 → 配置成功。

七、标准 Linux vs WSL + Fish 对比总结

项	标准 Linux	WSL + Fish
配置路径	完全一致	完全一致
推荐写法	`{file:}` 引用 auth.json	直接写 apiKey
权限	`chmod 600` 必须	可不用，依赖系统兼容
Fish 脚本	可用 Bash 写法	必须用 Fish 兼容写法
稳定性	高	引用式不稳定，直写稳定

八、WSL + Fish 配置 OpenCode 铁律

以后再配模型，记住这 5 条，基本不会踩坑：

标准 Linux 推荐用 auth.json 引用，更安全
WSL+Fish 直接写 API Key，最稳定
不要直接复用 Bash 脚本，Fish 语法不兼容
配置文件必须放在 ~/.config/opencode/
复杂配置不行时：简化！简化！简化！

九、复盘思考

这次排坑本质是跨环境工具链兼容问题：
WSL 文件系统 + Fish 语法差异 + OpenCode 引用解析，三者叠加导致配置反复失败。

而真正有效的解法，并不是“更规范、更高级”，而是在当前环境下稳定可跑。很多时候工程问题的最优解，不是追求完美架构，而是先跑通，再优化。

十、适用场景

标准 Linux（Ubuntu/Debian/CentOS）
WSL1 / WSL2
Fish Shell / Bash
OpenCode
火山方舟 OpenAI 兼容接口
其他 OpenAI 兼容模型平台（可同理迁移）

Computer Science

OpenCode接入火山方舟