mogick setup 无法完成或认证失败
本文处理 OAuth 设备码登录无法完成、认证凭据未生效、Token 过期或第三方 API Key 被其他凭据覆盖等问题。如果错误主要表现为连接超时、DNS 或代理失败，应转到网络问题排查；如果系统找不到 mogick 命令，请先处理安装与启动问题。
先运行认证诊断
mogick doctor重点查看报告中的 config、models 和 auth 检查项。如果认证看起来正常，但仍无法调用模型，再运行包含真实网络请求的检查：
mogick doctor --check-network根据现象选择对应的处理方式：
| 现象 | 从哪里开始排查 |
|---|---|
mogick setup 显示 URL 和设备码，但浏览器没有打开 | 浏览器没有打开 |
| 浏览器提示设备码无效、过期或授权未完成 | 设备码授权失败 |
setup 结束后没有找到 auth.json | 凭据没有写入预期目录 |
提示 Token 过期、INVALID_OAUTH_TOKEN 或反复要求登录 | OAuth Token 刷新失败 |
| 配置了 API Key，仍然返回 401 或认证失败 | API Key 没有生效 |
| 只有某个项目认证失败，其他目录正常 | 项目级凭据覆盖了全局凭据 |
| auth 正常，但 setup 最后的连接验证失败 | 区分认证与模型连接问题 |
浏览器没有打开
mogick setup 使用 OAuth 设备码流程。终端会显示授权 URL 和一次性设备码；即使浏览器没有自动打开，也可以手动完成：
- 保持当前
mogick setup进程运行。 - 复制终端中显示的完整 URL，在任意可用浏览器中打开。
- 输入终端显示的设备码并完成登录授权。
- 返回终端，等待 CLI 检测授权结果并写入凭据。
远程主机或 SSH 环境中，可以在本地电脑的浏览器打开该 URL。不要把设备码发送给其他人；设备码在有效期内可用于完成当前授权。
如果终端没有显示 URL 或设备码，结束本次流程后重新运行：
mogick setup设备码授权失败
如果浏览器提示设备码无效、已过期或授权未完成：
- 关闭当前失败的授权页面。
- 结束仍在等待的
mogick setup。 - 重新运行
mogick setup，使用新生成的 URL 和设备码。 - 完成授权后不要立即关闭终端，等待 CLI 输出最终结果。
设备码只能用于对应的一次 setup 流程。重新运行命令后，应使用新设备码，不要继续提交旧码。
如果浏览器显示账号或组织无权访问目标服务，这不是本地凭据文件问题，需要确认当前登录账号和服务权限。
凭据没有写入预期目录
默认情况下，OAuth 凭据写入：
<config-dir>/auth.json如果设置了 MOGICK_CONFIG_DIR，全局 auth.json 会写入该变量指定的目录。先运行 doctor 确认实际配置路径：
mogick doctor然后检查以下事项：
- doctor 显示的配置目录是否符合预期。
- 当前用户是否对该目录具有写权限。
auth.json是否存在 JSON 语法错误。- 是否误用另一个系统账号或 Shell 环境运行了 setup。
不要用管理员或 sudo 身份重新运行 setup 来掩盖目录权限问题，否则后续普通用户可能无法读取生成的凭据。修正目录归属或写权限后，再以日常使用 Mogick 的同一用户运行 mogick setup。
OAuth Token 刷新失败
Mogick 在 Access Token 到期时会使用 Refresh Token 自动续期。如果模型服务返回 INVALID_OAUTH_TOKEN，CLI 会强制刷新 Token，并自动重试当前请求一次。
如果重试后仍然失败：
mogick setup
mogick doctor重新授权会更新凭据；setup 还会补齐官方 Provider 和缺失的默认/轻量模型设置，保留已有 Provider 与显式模型选择。切换账号见退出登录与切换账号。
如果重新授权后仍反复提示登录，重点检查：
- doctor 的
auth项是否仍显示过期或无效。 - 当前工作目录是否存在优先级更高的项目级
.mogick/auth.json。 - 系统时间是否明显错误；OAuth Token 校验依赖有效时间戳。
- 调用失败是否实际来自网络、Provider 权限或模型配置，而不是 Token 本身。
API Key 没有生效
直连 OpenAI-compatible 第三方服务时，API Key 写入 auth.json：
{
"api_key": "<your-api-key>"
}运行时会优先使用有效的 OAuth Access Token，只有没有有效 OAuth Token 时才使用 api_key。因此，第三方服务返回 401 或认证失败时，需要确认实际生效的 auth.json 中是否还保留了其他 Provider 的 access_token 或 refresh_token。
处理前先备份凭据文件。第三方单 Provider 直连场景应按照配置第三方模型接入，在 auth.json 顶层保存 api_key，并核对 config.json 中的 llm.provider、llm.base_url、llm.model 和 llm.models[]。多 Provider 场景再使用 auth.providers.<provider-id>，详见认证与模型。
不要把 API Key 写入 config.json、命令参数、截图或问题描述。
项目级凭据覆盖了全局凭据
Mogick 可以同时存在两级认证文件：
| 位置 | 作用范围 | 优先级 |
|---|---|---|
<workspace>/.mogick/auth.json | 当前项目 | 高 |
<config-dir>/auth.json | 当前用户的所有项目 | 低 |
如果只在某一个项目中认证失败：
- 在失败的项目目录运行
mogick doctor，确认实际加载的认证文件。 - 检查项目下是否存在
.mogick/auth.json。 - 对照全局和项目文件的凭据类型，确认项目文件是否包含过期 Token、错误 API Key 或无效 JSON。
- 备份后修正不需要的项目级覆盖，再次运行 doctor。
不要提交任何层级的 auth.json 到版本控制。向他人展示配置时，只保留字段名，必须删除字段值。
区分认证与模型连接问题
mogick setup 在完成授权后还会验证 LLM 连接。因此，“setup 最后失败”不一定代表 OAuth 登录失败。
可以根据 doctor 结果区分：
| 检查结果 | 更可能的问题 |
|---|---|
auth 显示 Token 缺失、过期或刷新失败 | 认证问题，重新执行 setup 并检查凭据优先级 |
auth 正常，但 config 报错 | config.json 语法、字段或加载路径问题 |
auth 正常，但 models 或网络检查超时 | Provider 地址、代理、防火墙或服务可用性问题 |
返回 model not found 或类似 400 错误 | 模型 ID 或 Provider 配置问题，不应反复登录 |
| 返回 401 | 凭据无效，或请求使用了错误类型的凭据 |
| 返回 403 | 账号、组织或目标模型的访问权限不足，也可能是服务端策略限制 |
对于超时、DNS、代理和证书错误，先运行 mogick doctor --check-network 并核对模型服务地址。对于第三方模型 ID 和 Provider 配置，参见配置第三方模型接入。
生成诊断信息
如果仍无法定位，导出详细诊断：
mogick doctor --verbose --check-network --export ./mogick-auth-report.md
mogick doctor --verbose --logs-path ./mogick-auth.log提交问题时建议提供：
- 操作系统、安装方式和完整错误信息。
- 使用 OAuth 还是 API Key，不要提供凭据值。
- 完整错误信息和发生错误的阶段。
- doctor 中
config、models、auth的状态。 - 问题是否只在某个项目目录出现。
分享报告或日志前，必须隐藏 API Key、Access Token、Refresh Token、设备码、代理凭据、用户名和敏感路径。
确认问题已经解决
mogick doctor
mogick doctor --check-network
mogick run "Reply: authentication succeeded"预期结果是：doctor 的 auth 检查没有阻断性错误，网络检查可以完成认证请求，并且模型能够返回有效回复。
相关文档
路径占位符 <config-dir>、<db-path> 指当前 profile/通道实际生效的路径，见数据目录。