进阶 opencode.ai 2026-11-11 16:13:22 · 17 阅读

第15章 网络:配置代理与认证

网络 设置标准的代理变量,并排除环回地址。OpenCode 在 CLI 和其后台服务之间使用本地 HTTP 连接,因此当 CLI 环境中配置了代理时,必须排除环回地址。

Terminal export HTTP_PROXY=http://proxy.example.com:8080 export HTTPS_PROXY=http://proxy.example.com:8080 export NO_PROXY=localhost,127.0.0.1,::1

opencode HTTP_PROXY 处理 HTTP 目标,HTTPS_PROXY 处理 HTTPS 目标。代理 URL 本身在这两个变量中都可以使用 http://。NO_PROXY 是一个逗号分隔的主机名和地址列表,这些地址将直接连接,不经过代理。

Shell 导出的环境变量仅在服务从该 Shell 启动时才对后台服务生效。请将变量持久化到托管服务配置中,以便后续服务启动时使用相同的网络设置。

Terminal opencode service set env HTTP_PROXY http://proxy.example.com:8080 opencode service set env HTTPS_PROXY http://proxy.example.com:8080 opencode service set env NO_PROXY localhost,127.0.0.1,::1 opencode service start

修改托管环境变量会停止正在运行的服务。运行 service start 会用新的环境重新启动服务。

如果 CLI Shell 设置了代理,也要在该 Shell 中保留 NO_PROXY,因为托管服务变量仅适用于服务器进程,而不适用于 CLI 进程。

使用 service unset env 移除已持久化的变量:

Terminal opencode service unset env HTTPS_PROXY

对于接受 URL 凭据的代理,请在需要认证的每个代理 URL 中包含用户名和密码。对凭据中的 @、: 和 / 等字符进行百分号编码。

Terminal export HTTPS_PROXY='http://user:p%40ssword@proxy.example.com:8080'

对于后台服务,请持久化完整的 URL。该值存储在私有的服务配置中,并通过 opencode service get env 显示,因此请勿分享该输出。

Terminal opencode service set env HTTPS_PROXY 'http://user:p%40ssword@proxy.example.com:8080'

如果代理或目标使用由私有证书颁发机构签名的证书,请将 NODE_EXTRA_CA_CERTS 设置为 PEM 文件。额外的权威证书会在进程启动时添加到运行时信任存储中。

Terminal export NODE_EXTRA_CA_CERTS=/etc/company/ca.pem opencode --standalone

对于后台服务,持久化文件路径,然后重启服务:

Terminal opencode service set env NODE_EXTRA_CA_CERTS /etc/company/ca.pem opencode service start

防病毒软件的“HTTPS 扫描”或“加密连接扫描”(如卡巴斯基、Avast、ESET 等)以及企业 SSL 检查代理会用它们自己的证书替换服务器证书。OpenCode 会拒绝该证书,导致请求失败,并出现如下错误:

self signed certificate in certificate chain SELF_SIGNED_CERT_IN_CHAIN CERT_NOT_YET_VALID CERT_SIGNATURE_FAILURE

通过以下两种方式之一修复:

在防病毒设置中,将 opencode.ai 和 *.opencode.ai 排除在 HTTPS 扫描之外。如果直接连接提供商,也请添加提供商的 API 主机,例如 api.anthropic.com。

将检查证书颁发机构导出为 PEM 文件,并通过 NODE_EXTRA_CA_CERTS 信任它,如“证书”部分所示。

--standalone 和 serve 使用其自身进程的环境。opencode service set env 不会配置这些进程。

Terminal HTTP_PROXY=http://proxy.example.com:8080 \ HTTPS_PROXY=http://proxy.example.com:8080 \ NO_PROXY=localhost,127.0.0.1,::1 \ opencode --standalone

对前台服务器应用相同的模式:

Terminal HTTPS_PROXY=http://proxy.example.com:8080 \ NO_PROXY=localhost,127.0.0.1,::1 \ opencode serve

应用设置后,检查 CLI 是否能到达后台服务:

Terminal opencode api get /api/info

成功的健康检查响应验证了本地客户端到服务的连接。运行一个常规的提供商请求,以验证服务的出站代理和证书路径。

评论 (0)