Troubleshoot ZhiFlo connection problems

Do not change several settings at once. Start with the exact symptom in front of you, then change one thing at a time. The fastest order is: is the client installed, did it load the configuration, is the Token correct, is the model correct, is the address correct, then check quota and network.

Step 1: the command will not start

If the terminal reports command not found, not recognized, or similar text, the API configuration has not been reached yet.

1. Close terminal windows that were open before installation.
2. Open a new PowerShell or Terminal window.
3. Run the client’s --version command.

A version number confirms installation only. You still need to see the provider, select a model, and receive a reply.

Step 2: ZhiFlo does not appear after saving

1. Confirm that the file is in the correct user-level path, not another project or user’s directory.
2. Match the Provider ID, JSON key, or profile filename exactly to the guide.
3. Select Save.
4. Perform the separate Enable or current-model action.
5. Exit and reopen the client completely.

After recovery, the provider list or model picker should show ZhiFlo and the complete model ID.

Step 3: ZhiFlo is visible, but the old model is still active

Saving a provider does not always select it. Return to the model picker or provider card, make the ZhiFlo model current, and reopen any command-line client that was already running.

Step 4: the request returns 401

1. Use the Token created on API Keys, not your portal sign-in password.
2. Copy the complete Token again and remove surrounding whitespace or newline characters.
3. Put it in the client’s API Key, API Token, or Bearer Token field.
4. Confirm in the portal that it is active and has not expired.

If this happens with CC Switch + Codex and you previously set CODEX_API_KEY by hand, Codex may still read that old credential instead of the Token you just imported through CC Switch. Clear it in the same terminal that will start Codex:

macOS, Linux, or Bash:

unset CODEX_API_KEY
codex

PowerShell:

Remove-Item Env:CODEX_API_KEY -ErrorAction SilentlyContinue
codex

This removes the old variable only from the current terminal; it does not delete the provider saved by CC Switch. After Codex replies normally, decide whether to remove the old variable permanently from your shell configuration.

Claude Code uses ANTHROPIC_AUTH_TOKEN, not ANTHROPIC_API_KEY.

Step 5: the request returns 404

Identify whether the field expects a Base URL or a full endpoint:

• An OpenAI-compatible Base URL is usually https://api.zhiflo.com/v1.
• The full Chat Completions endpoint is https://api.zhiflo.com/v1/chat/completions.
• Claude Code uses https://api.zhiflo.com for ANTHROPIC_BASE_URL.

Remove the duplicate path, save, and reopen the client. Avoid repeatedly adding and removing /v1 without checking the field type.

Step 6: the model does not exist

1. Use the same Token to view the account model list or call GET /v1/models.
2. Copy a complete data[].id.
3. Update the model ID in the provider settings.
4. Save the provider.
5. Select that model again in the client.
6. Reload the model list or reopen the client.

Changing a display name does not change the model ID.

Step 7: a credential check passes, but chat has no reply

An address or API-key check covers only part of the path. Continue with these checks:

1. The chat screen currently has the ZhiFlo model selected.
2. The provider is enabled, not merely saved.
3. The Token has quota and the account is active.
4. The protocol matches the client guide.
5. Send “Reply with OK only” without attachments, tools, or private data.

Step 8: configuration changes do not take effect

Save first, enable or select the current model, then reopen the client completely. If a running OpenClaw Gateway still shows old settings, restart it and run openclaw models status again.

Step 9: the request times out or cannot connect

1. Request https://api.zhiflo.com/v1/models from the same device to see whether only the client fails.
2. Temporarily remove a custom proxy for one attempt, or confirm that it allows api.zhiflo.com.
3. Check the system clock and any certificate warning.
4. Keep the timestamp, status, and redacted address for further diagnosis.

Do not disable authentication, enable insecure remote access, run an ordinary client as administrator, or give anyone the full Token.

Next: if you have an HTTP status, open the API error map.