OpenCode 接入指南
opencode.jsonc 的 provider 配置、各档位模型 ID 与常见报错排查。
启动 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 servecurl 测,别和浏览器死磕如果确实需要开启密码保护,浏览器弹框一直失败时,最容易忽略的是用户名。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/healthcurl 返回 200,说明服务端和凭据都没问题,卡住的是浏览器端或外层代理。curl 在 v2 serve 上照样回 401,说明当前装的这个版本本身 Basic Auth 校验有 bug(见 #45856),直接升级到最新版本再试。有时第一次输完密码已经能打开界面,但一刷新页面弹窗又出来了。打开开发者工具的 Network 面板,常能看到 /site.webmanifest 或 /global/health 这类后续请求返回了 401,浏览器收到后又弹出原生 Basic Auth 框(#18325)。再加上多数浏览器密码管理器对原生 Basic Auth 弹窗支持很差,自动填进旧密码或空用户名,表面上就像死循环一样关不掉。
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| 遇到的情况 | 先查这一项 |
|---|---|
| 本机使用未设密码却一直转圈 / 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 接入指南。
本地跑通 opencode serve 之后,把 provider 指向 CodingPass,按量使用 Claude、GPT 与开源模型,不用再和服务端弹窗较劲。