V2 共享服务与认证排障

核验日期：2026-10-15。 本文依据官方 CLI 文档↗和认证文档↗，没有在本站维护过程中启动 OpenCode 服务、读取用户凭据或调用模型。

# 终端连接的是哪个服务#

V2 默认寻找或启动当前用户共用的后台服务。会话、运行时配置、提供商、权限与工具执行由该服务管理。关闭一个终端窗口不等于服务结束。

在项目目录运行以下命令，分别表示默认服务、私有服务和指定地址；按需要选择一条：

bash
复制
opencode

bash
复制
opencode --standalone

bash
复制
opencode --server http://localhost:4096

--standalone 适合需要独立服务生命周期的验证或自动化场景，但不等于新账号、新数据库或完全隔离的配置。指定地址只适用于已经存在且你有权连接的服务。

# 登录成功后在哪里检查#

交互式登录可以使用 TUI 的 /connect，也可以在终端执行：

bash
复制
opencode auth login
opencode auth list

按提供商提示完成认证，再使用 /models 选择模型。V2 将保存的 API key / OAuth token 放在服务器 SQLite 数据库中；支持的旧 auth.json 会在迁移时导入，新登录和更新不再写回该文件。因此“旧 auth.json 没变化”不能作为登录失败的证据。官方存储说明↗提供路径诊断命令：

bash
复制
opencode debug paths db

默认本地发布版通常使用 ~/.local/share/opencode/opencode.db，路径会受环境变量和渠道影响，应以输出为准。远程连接时凭据属于相应服务器；不要直接编辑数据库来管理账号。

# 临时 export 为什么可能不生效#

提供商环境变量需要进入发出模型请求的服务器进程。在新终端中 export，不会改变已经运行的共享服务环境。可以按官方认证文档为共享服务设置托管环境，或者在独立服务启动前提供变量。

例如已通过本机安全方式注入 ANTHROPIC_API_KEY 后，再运行：

bash
复制
opencode --standalone

不要把真实密钥直接写进教程命令、shell 历史、Git 或公开日志。共享服务托管环境的设置会停止正在运行的服务，下次 OpenCode 命令再启动；操作前先确认其他会话是否依赖该服务。

另外，保存的账号优先于同提供商的环境连接。auth list 中 environment 类型不是保存账号，auth logout 不会删除环境变量；排查时区分两者。

# 配置没有生效时#

1. 核对 opencode --version 与实际可执行路径，确认运行的是 V2。
2. 确认使用默认服务、--standalone 还是 --server，在对应服务侧检查认证与环境。
3. 终端外观修改全局 cli.json；模型和权限检查 opencode.json(c)，详见迁移指南。
4. 仍有问题时记录版本、命令、脱敏错误及复现步骤，对照官方故障排除↗。不要用实际密钥作为问题描述的一部分。