opencode --version# 或which opencode

如果还没装：

npm install -g opencode@latest# 确认 PATHopencode --versionStep 1：把 Agnes Key 放进环境变量（别硬编码到 config 里）

nano ~/.bashrc

在末尾加一行（把 sk-你的真实Key替换掉）：

export AGNES_API_KEY="sk-你的Key"

保存后：

source ~/.bashrc# 验证echo $AGNES_API_KEY

⚠️ 如果 OpenCode 跑在桌面启动器里（不继承 shell env），建议同时也写进：

nano ~/.config/environment.d/opencode.confAGNES_API_KEY=sk-你的Key

OpenCode 通过 AI SDK 的 @ai-sdk/openai-compatible包对接任意 OpenAI 兼容接口：

# 先找到 opencode 的 node_modules 位置opencode config --path 2>/dev/null || true# 直接让 opencode 自己管理依赖（推荐）# 建一个临时 package.json 让 npm 装进 opencode 的 scopeOPCODE_DIR="$HOME/.local/share/opencode"cd "$OPCODE_DIR"npm install @ai-sdk/openai-compatible

如果上面路径不对，更简单粗暴的方法——直接全局装让 OpenCode 能 resolve：

npm install -g @ai-sdk/openai-compatibleStep 3：写 OpenCode 配置文件（核心）----事实证明：通过环境变量传递api key,不可能！！！api key要硬写入opencode.json!

否则，api key不会自动被上传！参见下面的兜底方案！

nano ~/.config/opencode/opencode.json

完整替换为以下内容（直接整段复制粘贴）：（"apiKey": "env.AGNES_API_KEY"，硬编码可以成功，否则报错！）

{ "$schema": "https://opencode.ai/config.json", "provider": { "agnes": { "npm": "@ai-sdk/openai-compatible", "name": "Agnes AI", "options": { "baseURL": "https://apihub.agnes-ai.com/v1", "apiKey": "env.AGNES_API_KEY" }, "models": { "agnes-2.0-flash": { "name": "Agnes 2.0 Flash", "limit": { "context": 256000, "output": 65536 } } } } }, "model": "agnes-2.0-flash"}

保存退出（Ctrl O→ Enter→ Ctrl X）

# 确保环境变量在这个终端生效source ~/.bashrc# 启动 OpenCodeopencode

进去之后，输入这个内置命令看模型列表：

/models

你应该能看到：

✓ agnes-2.0-flash (Agnes AI)

直接问一句测试：

用 Python 写一个函数，判断字符串是否是回文如果 opencode启动报找不到 @ai-sdk/openai-compatible

说明 OpenCode 的 module resolve 没找到全局包。用这个兜底方案——把 key 直接写进 options（仅当你不在多用户机器上时）：

nano ~/.config/opencode/opencode.json

{ "$schema": "https://opencode.ai/config.json", "provider": { "agnes": { "npm": "@ai-sdk/openai-compatible", "name": "Agnes AI", "options": { "baseURL": "https://apihub.agnes-ai.com/v1", "headers": { "Authorization": "Bearer sk-你的Key" } }, "models": { "agnes-2.0-flash": { "name": "Agnes 2.0 Flash", "limit": { "context": 256000, "output": 65536 } } } } }, "model": "agnes-2.0-flash"}排障速查

报错

原因

修法

Cannot find package '@ai-sdk/openai-compatible'

npm 包不在 OpenCode 的 resolve 路径

npm install -g @ai-sdk/openai-compatible或按上面的 headers 兜底

models must be an object/ config parse error

JSON 语法错（多了逗号/少括号）

把 JSON 粘到 https://jsonlint.com校验

选了模型但 401

AGNES_API_KEY没传进来

echo $AGNES_API_KEY→ 空的就重新 source ~/.bashrc

选了模型但 404

baseURL 写成了 …/v1/chat/completions

改回 https://apihub.agnes-ai.com/v1

OpenCode 启动后底部/侧边显示当前模型为 agnes-2.0-flash，对话正常回复——就说明 Agnes 已经完全跑在 OpenCode 上了