登录选套餐
博客 · 接入指南

OpenCode serve 401 死循环:登录框为什么关不掉

启动 opencode serve 打开网页端,经常会撞上浏览器反复弹出 Basic Auth 登录框、或者页面一直转圈报 401。明明没设密码、或者输对了密码还是进不去,顺着环境变量和请求头查一遍就能定位。

在 OpenCode 2.x 上启动 opencode serve 或 opencode web,打开浏览器往往会遇到两种让人抓狂的情况:要么根本没设过密码,页面却一直卡在加载界面,控制台里一排 401 Unauthorized;要么明明设了密码也输对了,浏览器还是每隔几秒重新弹出 HTTP Basic Auth 登录框。

如果只在浏览器里一遍遍重输密码,很难看出问题出在哪。把浏览器放到一边,按“环境变量 → curl 直连 → 浏览器 Network → 代理层”的顺序查一遍,很快就能把卡死的原因拆出来。

动手排查前先记住两点:把 OPENCODE_SERVER_PASSWORD 设成空字符串("")和彻底 unset 不是一回事;只要开启了服务端密码,OpenCode 默认用户名是固定的 opencode。

第一步:查环境变量里是不是留了空值

很多人以为“没设密码”就等于无鉴权。实际上如果 .env 或 ~/.zshrc 里留了一行 OPENCODE_SERVER_PASSWORD="",或者在部分 2.x 版本里撞上未设密码仍返回 401 的 bug(仓库里 anomalyco/opencode#50370 提的就是这事),服务端不会放行,也不会给出正常的登录引导,网页端就会一直停在转圈界面。

本地或可信内网里不需要密码时,不要把变量留空,启动前直接清干净:

unset OPENCODE_SERVER_PASSWORDunset OPENCODE_SERVER_USERNAMEopencode serve

第二步:先用 curl 测,别和浏览器死磕

如果确实需要开启密码保护,浏览器弹框一直失败时,最容易忽略的是用户名。OpenCode 开启 OPENCODE_SERVER_PASSWORD 后,默认用户名固定是 opencode(对应 OPENCODE_SERVER_USERNAME),而不是你的 macOS / Linux 系统用户名,也不能留空。

排错时先在终端里把用户名和密码环境变量都设上:

export OPENCODE_SERVER_USERNAME="opencode"export OPENCODE_SERVER_PASSWORD="your-password"opencode serve

接着在另一个终端用 curl 直接打 /global/health,绕开浏览器缓存和密码管理器:

curl -i -u opencode:your-password http://127.0.0.1:4096/global/health
  • 如果 curl 返回 200,说明服务端和凭据都没问题,卡住的是浏览器端或外层代理。
  • 如果 curl 在 v2 serve 上照样回 401,说明当前装的这个版本本身 Basic Auth 校验有 bug(见 #45856),直接升级到最新版本再试。

第三步:看浏览器 Network,确认是不是刷新触发了重复弹窗

有时第一次输完密码已经能打开界面,但一刷新页面弹窗又出来了。打开开发者工具的 Network 面板,常能看到 /site.webmanifest 或 /global/health 这类后续请求返回了 401,浏览器收到后又弹出原生 Basic Auth 框(#18325)。再加上多数浏览器密码管理器对原生 Basic Auth 弹窗支持很差,自动填进旧密码或空用户名,表面上就像死循环一样关不掉。

第四步:检查外层反代,以及 CLI attach 参数

还有一个常见陷阱是“双重鉴权”:如果 opencode serve 挂在 Nginx、Caddy 或 Cloudflare Access 后面,代理层已经加了一层登录保护,而 OpenCode 自己又开着 OPENCODE_SERVER_PASSWORD,两边返回的 WWW-Authenticate 头会互相覆盖,浏览器就会在两套认证之间无限循环。这种部署下,把 opencode serve 绑在 127.0.0.1 并 unset 掉它自己的密码变量,只保留代理层鉴权即可。

另外,如果报错不是出在浏览器,而是另一个终端跑 opencode attach 或外部 SDK 突然全部 401(见 #31254),记得在连接命令里带上 -p(如果改过用户名再加 -u):

opencode attach http://localhost:4096 -p your-password

常见场景速查

OpenCode serve 401 与 Basic Auth 弹窗排查清单
遇到的情况先查这一项
本机使用未设密码却一直转圈 / 401确认没有残留 OPENCODE_SERVER_PASSWORD="",启动前执行 unset
浏览器输对密码仍然弹回用户名填 opencode,并用 curl -u opencode:... 先验证服务端
挂在 Nginx / Caddy / Cloudflare Access 后循环弹窗去掉 OpenCode 自身的密码变量,只让反代负责鉴权
opencode attach 或 SDK 报 401补上 -p <密码>,或在客户端里直接带上 Basic Auth 头

最后顺带提醒一句:OPENCODE_SERVER_PASSWORD 管的是 OpenCode 本地 HTTP 服务本身的访问权限,和你的模型 API Key 无关。如果用 CodingPass 跑模型,Key 还是用 opencode service set env CODINGPASS_API_KEY cp-live-... 写进后台服务,详细配置见 OpenCode 接入指南。

出发

服务端鉴权和模型 Key 分开管。

本地跑通 opencode serve 之后,把 provider 指向 CodingPass,按量使用 Claude、GPT 与开源模型,不用再和服务端弹窗较劲。

  • 每个响应都带请求 ID
  • 用量不超过 5% 可全额退款
  • 不会意外扣费
选 GoOpenCode 指南

每月 $10,直到你取消。