解决 ZhiFlo 连接问题

不要同时乱改几项设置。先看你眼前到底发生了什么，再一次只改一处。最省时间的顺序是：客户端有没有装好，配置有没有读到，Token 对不对，模型对不对，地址对不对，最后再看额度和网络。

第一步：命令都打不开

如果终端显示 command not found、not recognized 或类似信息，API 配置还没有开始生效。

1. 关闭安装前打开的旧终端窗口。
2. 重新打开 PowerShell 或 Terminal。
3. 运行客户端的 --version 命令。

能看到版本信息只表示安装完成。接下来仍需检查 provider、模型和实际回复。

第二步：保存后看不到 ZhiFlo

1. 确认配置保存在用户级正确路径，而不是另一个项目或用户目录。
2. 确认 Provider ID、JSON 键或 profile 文件名与指南完全一致。
3. 点击客户端中的 保存。
4. 执行单独的 启用 或设为当前模型动作。
5. 完全退出并重新打开客户端。

恢复后，提供方列表或模型选择器应出现 ZhiFlo 和完整模型 ID。

第三步：能看到 ZhiFlo，但仍使用旧模型

保存提供方不等于切换当前模型。回到模型选择器或 provider 卡片，选择 ZhiFlo 模型并确认当前启用状态，然后重开已经运行的命令行客户端。

第四步：返回 401

1. 确认使用的是 API 密钥页面创建的 Token，而不是网站登录密码。
2. 重新复制完整 Token，删除前后空格和换行。
3. 确认 Token 填在客户端的 API Key、API Token 或 Bearer Token 字段。
4. 在门户确认 Token 未过期、未撤销。

如果问题出现在 CC Switch + Codex，并且你以前手工设置过 CODEX_API_KEY，Codex 可能仍在读取这个旧凭据，而不是刚通过 CC Switch 导入的 Token。先在启动 Codex 的同一个终端清除它：

macOS、Linux 或 Bash：

unset CODEX_API_KEY
codex

PowerShell：

Remove-Item Env:CODEX_API_KEY -ErrorAction SilentlyContinue
codex

这只清除当前终端中的旧变量，不会删除 CC Switch 保存的提供方。Codex 能正常回复后，再决定是否从自己的 shell 配置中永久移除旧变量。

Claude Code 使用 ANTHROPIC_AUTH_TOKEN，不是 ANTHROPIC_API_KEY。

第五步：返回 404

先确认当前客户端要求的是 Base URL 还是完整 endpoint：

• OpenAI 兼容 Base URL 通常为 https://api.zhiflo.com/v1；
• 完整 Chat Completions endpoint 为 https://api.zhiflo.com/v1/chat/completions；
• Claude Code 的 ANTHROPIC_BASE_URL 为 https://api.zhiflo.com。

删除重复路径后保存并重开客户端。不要用随机加减 /v1 的方式连续尝试。

第六步：提示模型不存在

1. 用同一 Token 查看账户模型列表或请求 GET /v1/models。
2. 复制 data[].id 的完整值。
3. 更新 provider 设置中的模型 ID。
4. 保存 provider。
5. 在客户端中重新选择该模型。
6. 重新载入模型列表或重开客户端。

不要修改显示名称来代替模型 ID。

第七步：检查通过，但聊天没有回复

地址检查或 Key 检查只覆盖部分连接。继续确认：

1. 聊天页当前选择的是 ZhiFlo 模型；
2. Provider 已启用，不是只有一张已保存卡片；
3. Token 有可用额度，账户状态正常；
4. 客户端协议与该指南一致；
5. 用“只回答 OK”发送一条不含附件、工具或私人数据的最小消息。

第八步：配置修改没有生效

先保存，再启用或选择当前模型，最后完全重开客户端。OpenClaw 的运行中 Gateway 仍显示旧设置时，重启 Gateway 后再次查看 openclaw models status。

第九步：超时或无法连接

1. 在同一设备请求 https://api.zhiflo.com/v1/models，判断是否只有客户端失败。
2. 暂时移除自定义代理后重试一次，或确认代理允许访问 api.zhiflo.com。
3. 检查系统时间和证书提示。
4. 保留状态码、请求时间和已遮罩的地址供后续排查。

不要关闭认证、启用不安全远程访问、用管理员权限启动普通客户端，或把完整 Token 发给他人。

下一步：若已经得到 HTTP 状态码，打开 API 错误对照。