---
title: "OpenCode serve 一直弹 Basic Auth 登录框 / 401 死循环：一步步排查与解法"
description: "跑 opencode serve 打开浏览器却一直弹 Basic Auth 登录框、页面转圈或持续 401。顺着环境变量、curl 验证、Network 请求和反向代理一路查下来，整理出四种最常见的坑与对应修法。"
url: https://codingpass.ai/zh/blog/opencode-serve-basic-auth-401-loop
language: zh-CN
updated: 2026-11-20
---
# OpenCode serve 401 死循环：登录框为什么关不掉

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

[CodingPass 团队](https://codingpass.ai/zh/about) 发布于 2026年11月20日 更新于 2026年11月20日 阅读约 5 分钟

在 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](https://github.com/anomalyco/opencode/issues/50370) 提的就是这事），服务端不会放行，也不会给出正常的登录引导，网页端就会一直停在转圈界面。

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

```
unset OPENCODE_SERVER_PASSWORD
unset OPENCODE_SERVER_USERNAME
opencode 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](https://github.com/anomalyco/opencode/issues/45856)），直接升级到最新版本再试。

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

有时第一次输完密码已经能打开界面，但一刷新页面弹窗又出来了。打开开发者工具的 Network 面板，常能看到 `/site.webmanifest` 或 `/global/health` 这类后续请求返回了 `401`，浏览器收到后又弹出原生 Basic Auth 框（[#18325](https://github.com/anomalyco/opencode/issues/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](https://github.com/anomalyco/opencode/issues/31254)），记得在连接命令里带上 `-p`（如果改过用户名再加 `-u`）：

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

## 常见场景速查

| 遇到的情况 | 先查这一项 |
| --- | --- |
| 本机使用未设密码却一直转圈 / 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 接入指南](https://codingpass.ai/zh/tools/opencode)。

作者 CodingPass 团队

CodingPass 由我们运营。每篇指南发布前，都会在对应工具的最新稳定版上实测一遍。发现内容过时了？写信到 [support@codingpass.ai](mailto:support@codingpass.ai)。

## 相关阅读。

指南

### [OpenCode 接入指南](https://codingpass.ai/zh/tools/opencode)

opencode.jsonc 的 provider 配置、各档位模型 ID 与常见报错排查。

规则

### [额度和上限怎么算](https://codingpass.ai/zh/usage-limits)

每个套餐、每个模型的额度和上限，以及 429 响应。

模型

### [全部模型](https://codingpass.ai/zh/models)

每个模型的 ID、所需档位和月度额度。
