企业官网建设流程全解析

如果你在一个需要走代理的企业网络里用 OpenCode 接 Antigravity Auth，你大概率会经历这么一幕：登录命令敲下去，浏览器弹出授权页，你点了“同意”，然后终端里彻底卡住，没有任何回调提示；或者干脆跳出一段error from provider (console)，末尾挂着一句opencode's free tier can only be used from within opencode。这篇文章就是把这类问题串起来讲清楚：OpenCode 的 Antigravity Auth 走的是标准 OAuth 认证，代理一介入，链路里几个不起眼的环节就会轮番出问题。我会从认证链路本身讲起，再给出一套可以照着抄的排查和配置步骤，覆盖本地开发机、WSL、远程服务器和 CI 环境。无论你是第一次跑opencode auth login，还是已经在生产环境里被回调地址折腾过，这篇文章都应该能帮你省下半天时间。

1. 代理环境下做 OAuth 认证，为什么这么容易翻车

1.1 OpenCode + Antigravity Auth 的认证链路长什么样

OpenCode 是终端里的 AI 编码代理，它能在你的代码仓库里读文件、改代码、跑命令。要接入模型服务，OpenCode 支持多种认证方式，其中 Antigravity Auth 走的是典型的 OAuth 2.0 Authorization Code + PKCE 流程。这个流程的设计初衷是为了不让用户把密码交给第三方 CLI 工具，而是由用户自己在浏览器里完成身份确认。

整个链路可以拆成六步，每一环都有可能出现问题：

1. OpenCode 启动一个本地 HTTP 回调服务，监听127.0.0.1上的某个随机端口。
2. OpenCode 打开系统浏览器，跳转到 Antigravity 的授权页面，URL 参数里带着client_id、redirect_uri、code_challenge等。
3. 你在浏览器里登录 Antigravity 账号，点击“授权”。
4. 浏览器把授权服务器返回的authorization code发送到第 1 步里的redirect_uri，也就是本地回调服务。
5. 本地回调服务收到 code 之后，用 code + PKCE verifier 向 Antigravity 的 token 端点换取 access token 和 refresh token。
6. OpenCode 把 token 落盘保存，后续请求模型服务都带上这个 token。

这套流程在普通网络环境里很顺滑，但一旦你被夹在企业代理后面，第 2 步、第 4 步、第 5 步都会变成雷区。

1.2 代理介入后，三个最容易出问题的环节

先说结论：代理环境下的 OAuth 故障，九成以上集中在这三个环节。

第一个是浏览器访问授权页。现在很多办公网络要求所有 HTTPS 流量都走统一出口代理，浏览器一般会自动使用系统代理设置，所以第 2 步通常能过。但如果你是在无头服务器上跑 OpenCode，连浏览器都没有，这一步直接就会卡死。

第二个是本地回调被代理拦截。OAuth 的redirect_uri一般是http://127.0.0.1:随机端口/callback。问题在于，如果你在环境变量里设置了HTTP_PROXY和HTTPS_PROXY，很多命令行工具和运行时会把所有请求都交给代理，包括发往127.0.0.1的回调请求。代理服务器收到一个http://127.0.0.1:45678/callback的请求，大概率是把它转发到外网茫茫互联网里去找目标，结果自然是找不到。本地回调服务等不到请求，终端就一直卡在 "Waiting for redirect..."。这个问题的根因很简单：缺少NO_PROXY，或者NO_PROXY里没写localhost和127.0.0.1。

第三个是服务端到 token 端点的请求被代理的 TLS 证书拦下。第 5 步里 OpenCode 作为客户端要向https://auth.antigravity.com之类的地址发请求。如果企业代理做了 SSL 解密，它会给所有经它中转的 HTTPS 连接换上一张企业自签 CA 证书。OpenCode 的运行时如果不信任这张 CA，就会报证书链错误，比如self-signed certificate in certificate chain或UNABLE_TO_VERIFY_LEAF_SIGNATURE，token 换不来，登录同样失败。

搞清楚了这三个环节，后面所有的排查其实都是在回答同一个问题：当前这个请求，到底应该走代理，还是应该绕过代理？

2. 动手之前：三分钟的“环境自检”

别急着敲登录命令，先花三分钟把环境摸清楚。我在帮同事处理这类问题时发现，大部分人失败是因为环境变量本身是乱的，而不是 OpenCode 配置有问题。

2.1 确认安装方式与命令行可达

先确认 OpenCode 的安装方式和版本。不同版本的 CLI 命令可能有细微差异，但一般都会有opencode auth这个子命令组。先跑一下：

opencode auth --help

如果提示找不到命令，先解决 PATH 问题。Windows 上常见的报错是cmd 使用 opencode 命令无效，多半是 npm 的全局 bin 目录不在 PATH 里；还有一种是node_modules\@opencode\cli\bin\opencode.exe 与你运行的 Windows 版本不兼容，这种情况通常是 Node 版本太旧，或者安装包下载不完整，升级到当前 LTS 版本的 Node 再重装一次基本能解决。

版本确认完了，再看安装来源。用 npm 装的、用官方安装脚本装的、还是直接下载二进制包的，这决定了后面排查代理时要改哪些配置。npm 装的需要额外注意 npm 自己的代理设置：

npm config get proxy npm config get https-proxy npm config get registry

如果这些是空的，而你又确定公司网络需要代理才能访问外网，那么 npm install 这一步就会很慢或直接失败，OpenCode 都装不上，后面认证更是无从谈起。用官方安装脚本的话，记得先看脚本是否依赖 curl 或 wget，这两个工具都会读环境变量里的代理配置。

2.2 把代理环境变量梳理清楚

接下来看当前 shell 里到底有哪些代理相关的变量。直接用命令打印：

env | grep -i proxy

你会看到四种常见变量：HTTP_PROXY、HTTPS_PROXY、ALL_PROXY、NO_PROXY。这里有两个容易踩的坑：

第一个坑是大小写。Linux 下的很多工具只认小写形式，但也有不少 Node.js 库和 Java 程序对大小写不敏感甚至只认大写。为了避免工具链之间互相打架，我习惯在~/.bashrc或~/.zshrc里同时导出大小写两套：

export http_proxy=http://proxy.corp.example:8080 export https_proxy=http://proxy.corp.example:8080 export HTTP_PROXY=$http_proxy export HTTPS_PROXY=$https_proxy

第二个坑是NO_PROXY。这个变量决定了哪些地址必须绕过代理直连。OAuth 本地回调能不能成功，全靠它：

export no_proxy=localhost,127.0.0.1,*.local,.corp.example export NO_PROXY=$no_proxy

注意：NO_PROXY里写不写*.corp.example取决于你公司内网域名长什么样。如果内网服务域名五花八门，就先别写太多通配，保持最小集合localhost,127.0.0.1最安全。因为如果NO_PROXY配得太宽，某些必须走代理才能访问的外部地址会被错误地绕过代理，结果是连接超时。

2.3 查看已有认证状态与配置文件

接下来看看 OpenCode 现在认不认你已经登录过。一般 CLI 都有类似的检查命令：

opencode auth list opencode auth status

如果显示没有活动的认证会话，那就需要登录。还需要确认配置文件的位置。OpenCode 配置通常在~/.config/opencode/opencode.json（Linux/macOS）或 Windows 用户目录下，里面记录了 provider 和 auth 块。如果你之前手动改过配置，先备份一下，然后看一眼是不是有残留的 auth 条目导致登录时走到了错误的 provider。

我见过一种典型情况：用户之前在 OpenCode 里配置了其他 provider，再跑opencode auth login时交互式菜单里选了 Antigravity，但配置文件里旧 provider 的apiKey还在，LLM 请求优先走了旧配置，看起来像 Antigravity 登录没生效。所以在自检阶段梳理配置文件，能避免后面产生“明明登录成功但模型不可用”的错觉。

3. 完整走一遍：代理环境下的 Antigravity Auth 登录

自检完毕，开始正式登录。这里我不假设你已经有一份完美的配置，而是按“最可能出问题”的顺序，一步步说清楚每个阶段应该看到什么、如果看不到该怎么处理。

3.1 启动登录，先搞清楚它监听哪个回调端口

启动登录命令：

opencode auth login

交互式菜单里选择 Antigravity Auth。这时候 OpenCode 会做两件事：拉起一个本地 HTTP 服务，然后尝试打开浏览器。如果是在无图形界面的服务器上，浏览器那一步会失败，但日志里一般会输出一个授权 URL，你可以手动复制到本地浏览器里打开。

重点来了：在这一步就要注意到回调端口。OpenCode 通常是随机选一个高端口号，比如 34251、51234，也可能固定 8899。日志一般会显示类似Listening on http://127.0.0.1:34251/callback的信息。记下这个地址，后面排查要用。

如果你用的是 Windows，有时候系统会自动弹窗问“是否允许此应用在防火墙中通信”，这个一定要允许，否则本地回调服务根本收不到连接。

3.2 让本地回环流量绕过代理（NO_PROXY 的关键作用）

前面说过，OpenCode 起了一个本地回调服务。浏览器在授权完成后会重定向到http://127.0.0.1:端口/callback。如果 OpenCode 自身的进程也设置了HTTPS_PROXY，Node.js 的 fetch 或底层 HTTP 客户端在发起回调监听时一般不受影响，但有些工具在回调之后还要向本地地址回发请求，这时候就可能被代理环境变量干扰。

最稳妥的做法是，在跑登录命令前，明确告诉运行时什么样的地址不要走代理：

export NO_PROXY=localhost,127.0.0.1,::1 export no_proxy=$NO_PROXY

很多 OpenCode 内置的依赖（比如 undici）对NO_PROXY的解析比较严格，它支持127.0.0.1也支持localhost，但如果你只写了localhost，请求目标是127.0.0.1时仍然可能被代理接管。所以我建议把两个都写上，IPv6 的::1也写上，虽然用得少，但能避免偶发问题。

还有个细节：如果你在浏览器里用的是系统代理，Windows 的“Internet 选项 -> 连接 -> 局域网设置”里的“为本地地址绕过代理服务器”勾选要打开。否则浏览器把http://127.0.0.1:34251/callback也交给了系统代理，结果一样是回调失败。

3.3 处理代理的 TLS 证书拦截

如果授权页能打开，浏览器里也点了同意，但 OpenCode 终端紧接着报 TLS 错误，那基本就是代理做了 SSL 解密。怎么判断？看报错信息里有没有certificate、SSL、SELF_SIGNED一类字样。

处理方式不是关掉证书校验，而是把企业代理的根 CA 证书加进 Node.js 的信任列表。Node.js 有一个专门的环境变量NODE_EXTRA_CA_CERTS，指向一个包含额外根证书的 PEM 文件：

export NODE_EXTRA_CA_CERTS=/etc/ssl/certs/corp-ca.pem

注意，这个变量只对 Node.js 进程生效，所以必须保证它在你启动 OpenCode 的同一个 shell 环境里。如果 OpenCode 是从桌面图标或 IDE 插件里启动的，你可能需要在系统环境变量里也加上这一项。

更通用一点的做法，是把企业 CA 装进系统证书库。Linux 上一般是把 CA 文件放到/usr/local/share/ca-certificates/然后运行update-ca-certificates。这样不仅 OpenCode，curl、git、npm 也都能信任这张证书。

我不建议设NODE_TLS_REJECT_UNAUTHORIZED=0。虽然它确实能绕过证书错误，让登录跑通，但相当于关掉了整个 Node 进程的 TLS 校验，后续所有 HTTPS 请求都可能被中间人攻击。用来临时定位问题可以，作为长期方案就算了。

3.4 登录成功后的 Token 存储与验证

登录成功时，OpenCode 一般会打印类似Authentication successful的信息。Token 会写入配置目录下的某个文件里，通常是~/.config/opencode/auth.json之类的文件。你可以看一下这个文件的权限：

ls -l ~/.config/opencode/auth.json chmod 600 ~/.config/opencode/auth.json

权限一定不能是 644，因为里面存的是 access token 和 refresh token，任何同机用户都能读走就麻烦了。

验证登录是否真正生效，最直接的办法是问 OpenCode 当前的认证信息：

opencode auth list

如果列表里出现 Antigravity 且状态不是 expired，基本就算成了。接下来随便跑一个简单的模型请求，能正常返回就说明从认证到模型调用的完整链路是通的。

4. 高频报错排查：从报错信息反推链路断点

这一节我把平时遇到频率最高的几个报错整理成了一张实战排查表。每个报错看起来吓人，但只要你知道它对应的是链路里的哪一环，处理起来其实很快。

4.1 error from provider: free tier can only be used from within opencode

这个报错我单独拿出来说，因为它的误导性最强。它看起来像代理问题、像网络问题，但实际上和代理一点关系都没有。

错误原文是opencode's free tier can only be used from within opencode。意思很明确：通过 Antigravity Auth 登录到 OpenCode 后获得的免费额度 Token，只能在 OpenCode 客户端内部使用，不能复制出来单独调用模型 API。很多人（包括我）第一次遇到时，会下意识地去检查代理配置，折腾半天才发现，是自己把登录后打印出来的 token 粘到 curl 脚本里测接口了。

正确理解是：OpenCode 的免费额度绑定的是 OpenCode 这个客户端环境。如果你想在脚本、curl、或者其他程序里直接调用 Antigravity 的模型接口，应该去 Antigravity 控制台创建一个独立的 API Key，而不是拿 OpenCode 的登录会话 Token 来用。这两个东西的权限边界完全不同：登录 Token 相当于“我是合法登录用户”，API Key 才相当于“我可独立调用服务”。

4.2 WSL 下 localhost 代理未镜像到 Linux 子系统

Windows + WSL2 的环境特别容易出这个问题。报错信息一般长这样：

wsl: 检测到 localhost 代理配置,但未镜像到 wsl。nat 模式下的 wsl 不支持 localhost 代理转发。

这句报错的本质是：WSL2 默认使用 NAT 网络模式，宿主机 Windows 上的代理设置（比如某些代理工具设置的 localhost 监听）不会自动出现在 WSL 的 Linux 网络栈里。你在 Windows 上跑opencode auth login时浏览器回调能成功，但同样命令在 WSL 里跑，回调请求就找不到本地的代理端口，或者反过来，WSL 内访问宿主机服务时地址完全不对。

有两个解决思路。

第一个是在 WSL 里显式设置代理地址，指向 Windows 宿主机的局域网 IP，而不是 localhost。先看宿主机的 IP：

# 在 WSL 里执行 ip route show | grep default

默认网关 IP 一般就是宿主机在 WSL 网络中的地址。然后设置：

export HTTPS_PROXY=http://<宿主机IP>:代理端口 export NO_PROXY=localhost,127.0.0.1

第二个是开启 WSL 的 mirrored 网络模式。Windows 11 较新的版本支持在.wslconfig里配置：

[wsl2] networkingMode=mirrored

然后重启 WSL。这个模式会把 localhost 变成互通地址，宿主机和 WSL 之间的代理转发更自然。但要注意，mirrored 模式不是所有环境都稳定，如果你公司网络环境和 Docker Desktop 有冲突，可能需要权衡。

4.3 回调地址被代理“吃掉”，终端卡在 waiting for callback

这是最经典的问题。我在第 1 节讲过原理，这里补充一个快速定位方法。

当 OpenCode 卡在等待回调时，你先不要关掉它，开另一个终端查看 127.0.0.1 上是否有进程在监听：

lsof -i :34251

其中 34251 换成 OpenCode 日志里显示的那个端口。如果监听进程存在，说明 OpenCode 本身没问题，问题出在请求根本没到达这个端口。这时候看一下浏览器授权完成后的地址栏，如果浏览器跳转到了一个看起来像外网的错误页，那就是系统代理把127.0.0.1劫持走了。

处理方式就两招：一是在代理环境变量里补NO_PROXY=localhost,127.0.0.1；二是把 Windows 的“局域网设置 -> 为本地地址绕过代理服务器”勾上。如果正在用某些带“全局模式”的本地代理工具，把它切回规则模式，别让它接管回环流量。

4.4 代理链路里的 TLS 证书链错误

这一类报错在日志里通常很显眼，因为 Node.js 会把整条证书链错误打出来。很多人的第一反应是export NODE_TLS_REJECT_UNAUTHORIZED=0，跑通了就再也不管。我强烈建议不要这样。

正确做法前面提过：找到企业的根 CA 证书，导出成 PEM 格式，然后配置NODE_EXTRA_CA_CERTS。如果你用的是 Charles 或 Fiddler 之类的调试工具做 HTTPS 抓包，它们的根证书同样需要加进信任列表。如果你只想用一次，也可以在命令行里临时指定证书参数，但更好的做法是把它固化到环境变量里，避免下次登录再次踩坑。

如果你不确定该信任哪张证书，可以在浏览器里打开授权页，点地址栏的小锁图标，查看证书链，把最顶层的根证书导出来。这通常就是需要加入信任的那张。

4.5 用抓包工具确认流量走向

当所有配置看起来都对、但登录就是失败时，抓包是最好的最终裁决手段。Charles、Fiddler 这类工具本质也是一个本地代理，你把 OpenCode 的流量指到它们的监听端口，就能看清回调请求到底去了哪里。

具体的做法是：把HTTPS_PROXY指向 Charles 的监听端口（比如http://127.0.0.1:8888），NO_PROXY暂时清空，然后重新跑opencode auth login。在 Charles 里能看到两部分流量：

• 到 Antigravity 授权服务器和 token 端点的请求；
• 浏览器回跳时发出的http://127.0.0.1:34251/callback请求。

如果第二条请求压根没有出现在 Charles 里，说明它没走这个代理，判断方向就要转向系统代理设置；如果它出现在 Charles 里并且报错找不到主机，那就坐实了“回环流量被代理带走”的问题。

用抓包工具还有一个额外作用：确认最终令牌请求里有没有携带正确的code。如果你看到 token 请求返回 400，多半是 PKCE verifier 或 authorization code 已经失效，重新跑一遍登录流程就能解决。

5. 远程主机、容器、CI：回调这条路走不通时的替代方案

本地开发机上 OAuth 用起来最顺，因为浏览器和 OpenCode 在同一台机器上，回调天然能到达。但换到远程开发服务器、Docker 容器或者 CI 环境，回调地址就会变成一个大麻烦。这一节讲的是在没有图形化浏览器的环境里，怎么让 OAuth 依然可用。

5.1 SSH 端口转发：把远程的回调端口搬回本地浏览器

远程开发机上没有浏览器，但你可以让 OAuth 回调“穿越” SSH 隧道，在本地浏览器的 127.0.0.1 上完成闭环。

思路是：在远程机器上启动opencode auth login，它会监听远程机器的某个端口，比如 8899。然后在本地机器上执行：

ssh -L 8899:127.0.0.1:8899 user@remote-server

这个命令把本地 8899 端口和远程 8899 端口打通。浏览器在授权完成后访问http://127.0.0.1:8899/callback，请求会通过 SSH 隧道被转发到远程机器的 8899 端口，OpenCode 就能收到回调。

这里要注意两点。第一，远程机器上同样要设置NO_PROXY=localhost,127.0.0.1，确保回调请求不会被远程机器上的代理变量带走。第二，本地浏览器如果开了系统代理，也要保证本地访问127.0.0.1时不走代理，否则流量根本进不了 SSH 隧道。

5.2 容器环境：尽量用 host 网络模式或设备码登录

Docker 容器里跑 OpenCode 的场景越来越多，但容器默认的 bridge 网络有一个问题：容器内监听的127.0.0.1:port和宿主机是不通的。你在宿主机浏览器里完成授权后，回调请求到了宿主机端口，但容器里根本没有服务在那个端口上，连接被直接拒绝。

最简单的方案是让容器使用 host 网络模式：

docker run --network host ...

这样容器内的127.0.0.1就是宿主机视角下的127.0.0.1，回调天然可达。如果因为安全和隔离要求不能开 host 网络，那就用端口映射，但要注意 OAuth 回调地址里写的是127.0.0.1，映射出来的端口和容器内的端口必须对应好。如果 OpenCode 支持设备码登录（device authorization grant），那更适合容器环境：终端显示一个用户码和一个授权 URL，你在任意一台有浏览器的机器上打开 URL、输入用户码，容器里的 OpenCode 自己轮询 token 端点，不需要回调地址参与，这基本是容器场景的最优解。

5.3 CI 无人值守环境：设备授权码与预置 Token

CI 里跑opencode auth login比较尴尬：没有浏览器，也没有人可以交互。两个可行方案。

第一个是设备授权码方案。操作起来类似刚才说的容器场景，CI 进程打印一个 URL 和用户码，操作者在自己电脑上打开 URL 完成授权。这个方案适合有人盯着 CI 的场合，比如发布流水线里的手动审批阶段。

第二个是预置 refresh token。你提前在本地完成一次登录，把生成的 refresh token 放到 CI 的环境变量或密钥管理服务里，CI 启动时 OpenCode 直接用 refresh token 换取 access token。这个方案完全无人值守，但要注意 refresh token 会过期，需要在过期前重新生成并更新密钥。不要直接把 access token 放到 CI 里，因为 access token 有效期短，过期后 CI 任务就会失败，而 refresh token 加刷新逻辑才是长久的做法。

5.4 进阶：用 Nginx 把 OAuth 回调“搬”到可控域名

如果你处于一个比较严格的内网环境，本地回环地址被禁用，或者 OAuth 客户端要求回调地址必须是 HTTPS 域名，那可以用 Nginx 反向代理把回调地址映射到你可控的域名上。

大致的思路是：在你有权配置 DNS 的域名（比如auth.corp.example）上，把流量反代到内网开发机的回调端口：

server { listen 443 ssl; server_name auth.corp.example; location /callback { proxy_pass http://192.168.1.10:8899; proxy_set_header Host $host; proxy_set_header X-Forwarded-Proto $scheme; } }

然后在 Antigravity 控制台的 OAuth 回调地址白名单里，把https://auth.corp.example/callback加进去。OpenCode 启动登录时，让它使用这个回调地址而不是默认的 localhost。这个方案把 OAuth 回调变成了标准的七层网络请求，不依赖回环地址，也不容易被子网隔离、防火墙策略误伤。

需要注意两点：一是回调地址必须和 OAuth 客户端里注册的地址精确匹配，多一个斜杠、少一个端口都会失败；二是 Nginx 要配置好长连接参数和worker_connections，否则多人同时在开发机上登录认证时，连接数上限可能会成为新的瓶颈。

6. 一点实操心得：把认证这件事做成“可重复执行”的流程

文章最后，分享几个我自己的经验。这些经验不完全来自文档，更多是在业务环境里反复踩坑后形成的习惯。

第一个习惯是建立“最小排查顺序”。我在遇到登录问题时，永远按照这个顺序检查：先确认本地回调端口有监听；再确认NO_PROXY包含127.0.0.1；然后确认代理证书是否被信任；最后才去怀疑 OpenCode 配置。按照这个顺序，大部分问题在第二步就能解决，根本走不到最后一步。

第二个习惯是把代理配置和 OpenCode 配置分开管理。我不会把export HTTPS_PROXY=...直接写死在~/.bashrc里，因为开发机同时要处理内网通信、本地调试和外部 API 调用，全局代理变量太容易误伤回环流量。我更倾向于写一个proxy.sh脚本，只有在需要走代理时才手动 source：

export HTTPS_PROXY=http://proxy.corp.example:8080 export NO_PROXY=localhost,127.0.0.1,::1

这样既能保证登录时环境正确，也不会让代理变量污染其他项目的运行。

第三个习惯是及时看 auth 文件。登录成功之后我会顺手看一眼配置目录下的认证文件，确认没有把 Token 提交到 Git 仓库，也会检查文件权限是不是 600。CI 环境里我会把认证方式尽量改造成设备码或 refresh token 模式，而不是尝试在流水线里模拟浏览器。

第四个习惯是耐心看日志。OpenCode 这类 CLI 工具通常有调试日志选项，环境变量或--verbose之类的参数能输出完整的 HTTP 请求细节。遇到玄学报错时，打开调试日志跑一遍登录，看到具体是哪个 URL 报错、返回什么状态码，往往比一遍遍猜代理配置要高效得多。

如果你也在代理网络里折腾 OpenCode 的 Antigravity Auth，希望这篇文章能帮你少走几个弯路。配置这事的本质不复杂：让该走代理的请求走代理，让该回本地的请求回本地，再把代理的证书信任问题解决掉，登录自然就通了。