OpenCode IDE 插件代理 / 环境变量配置方案

蓓蕾心晴

发布于 2026-08-27 08:33:14

130

解决「终端 opencode 能正常与 AI 对话，但 IDE 插件报错 Error from provider (Console): Upstream request failed: Endpoint is unavailable.」的问题。

一、问题背景与根因

现象：终端直接输入 opencode 可以正常对话；在 IDE（VSCode 等）的 opencode 插件里对话报 Endpoint is unavailable。

根因（三层）：

opencode 的 IDE 插件 = IDE 进程拉起一个 opencode serve 子进程，该子进程只继承 IDE 进程的环境变量，不继承终端环境。
macOS 上从 Dock / 启动台启动的 GUI 应用（VSCode、Cursor…）不会读取 ~/.zshrc / ~/.bashrc，只读取系统 launchd 会话级环境。
因此终端里生效的代理变量、OPENAI_BASE_URL 等在 IDE 插件子进程里全部缺失 → 插件连不上模型端点 → 报错。

一句话：终端能用的变量，IDE 插件读不到。

二、解决方案总览

把 ~/.zshrc 中 opencode 需要的关键环境变量，提升到系统 GUI 会话级（launchctl setenv），并加一个 LaunchAgent 开机自动注入。这样任何 IDE（VSCode / Cursor / Windsurf …）只要在变量注入后启动，其插件子进程都能读到，与终端环境一致，无需逐个 IDE 配置。

三、完整配置步骤

第 1 步：在 shell 配置中写入代理变量（终端用）

编辑 ~/.zshrc，文件末尾追加：

# === 系统代理（供 IDE 插件后台子进程读取） ===
# START PROXY
export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890
export ALL_PROXY=socks5://127.0.0.1:7890
# opencode 官方要求：本地 server 连接必须绕过代理，防止路由循环
export NO_PROXY=localhost,127.0.0.1
# END PROXY

使其生效：

source ~/.zshrc

端口 7890 是 *** 系代理客户端的默认混合端口，请按你的实际代理端口修改。

第 2 步：写入系统 GUI 会话级环境（当前登录会话立即生效）

launchctl setenv HTTP_PROXY "http://127.0.0.1:7890"
launchctl setenv HTTPS_PROXY "http://127.0.0.1:7890"
launchctl setenv ALL_PROXY "socks5://127.0.0.1:7890"
launchctl setenv NO_PROXY "localhost,127.0.0.1"
launchctl setenv OPENAI_BASE_URL "https://ai.tokencloud.ai"   # 按需

验证：

launchctl getenv HTTP_PROXY

关键点：launchctl setenv 只对之后新启动的 GUI 应用生效；正在运行的旧应用不继承，需要完全退出重开。

第 3 步：创建开机自启任务（重启后仍保留）

新建文件 ~/Library/LaunchAgents/com.user.opencode-env.plist，内容：

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.user.opencode-env</string>
    <key>ProgramArguments</key>
    <array>
        <string>/bin/zsh</string>
        <string>-lc</string>
        <string>source ~/.zshrc 2>/dev/null; launchctl setenv HTTP_PROXY "$HTTP_PROXY"; launchctl setenv HTTPS_PROXY "$HTTPS_PROXY"; launchctl setenv ALL_PROXY "$ALL_PROXY"; launchctl setenv NO_PROXY "$NO_PROXY"; launchctl setenv OPENAI_BASE_URL "$OPENAI_BASE_URL";</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
</dict>
</plist>

加载自启任务：

launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.user.opencode-env.plist

该任务每次登录时自动从 ~/.zshrc 读取最新值并注入 GUI 会话。以后修改 .zshrc 的代理值即可，无需改 plist。

第 4 步：完全重启 IDE

完全退出 IDE（VSCode 用 Cmd+Q，不是关窗口），再重新打开。
到插件里发一条消息验证。

四、换 IDE / 新机器如何使用

只要在环境变量注入之后启动的 IDE，插件直接可用，无需逐个配置。
每个 IDE 需安装对应的 opencode 插件；若插件提示找不到 opencode，在插件设置里把 binaryPath 指向 ~/.opencode/bin/opencode，或确保 opencode 在系统 PATH。
新机器照搬：第 1 → 2 → 3 → 4 步即可。

五、验证方法

# 1. 验证终端变量
source ~/.zshrc && echo $HTTP_PROXY

# 2. 验证 GUI 会话变量（对之后启动的 GUI 应用生效）
launchctl getenv HTTPS_PROXY

# 3. 验证自启任务已加载
launchctl list | grep opencode-env

六、回滚 / 卸载

# 1. 卸载自启任务并删除文件
launchctl bootout gui/$(id -u) ~/Library/LaunchAgents/com.user.opencode-env.plist
rm ~/Library/LaunchAgents/com.user.opencode-env.plist

# 2. 清除 GUI 会话变量
launchctl unsetenv HTTP_PROXY
launchctl unsetenv HTTPS_PROXY
launchctl unsetenv ALL_PROXY
launchctl unsetenv NO_PROXY
launchctl unsetenv OPENAI_BASE_URL

# 3. 删除 ~/.zshrc 里的 # START PROXY 段（含 NO_PROXY）

七、注意事项

代理端口：7890 需要代理客户端（*** 系）在运行才真正走代理；未运行时这些变量不生效、程序直连（当前终端即直连可用）。
NO_PROXY 必须设置：opencode 的 TUI / 服务与本地 127.0.0.1 通信，必须绕过代理，否则形成路由循环。
launchctl setenv 是会话级：重启后由 LaunchAgent 自动重新注入，无需手动重复执行。
仍报 provider (Console) 的话：可能是 opencode 的 "Console" provider 服务端临时故障（2026-08-26 已有大量用户反馈同样报错），在插件模型选择器里手动切换到 opencode/* 模型即可；或等待 opencode 修复。

本文参与腾讯云自媒体同步曝光计划，分享自作者个人站点/博客。

原始发表：2026-08-26，如有侵权请联系 cloudcommunity@tencent.com 删除

配置