zeroclaw-labs/zeroclaw · error · anyhow::Error

OpenAI Codex endpoint override must use http:// or https://

Error message

OpenAI Codex endpoint override must use http:// or https://

What it means

The openai-codex endpoint override parsed successfully as a URL, but its scheme is neither http nor https (e.g. file://, unix://, ftp://), which reqwest cannot use for the Responses API call. build_responses_url enforces the scheme right after parsing, before appending the /responses path.

Source

Thrown at crates/zeroclaw-providers/src/openai_codex.rs:178

    let candidate = base_or_endpoint.trim();
    if candidate.is_empty() {
        anyhow::bail!("OpenAI Codex endpoint override cannot be empty");
    }

    let mut parsed = reqwest::Url::parse(candidate).map_err(|_| {
        ::zeroclaw_log::record!(
            WARN,
            ::zeroclaw_log::Event::new(module_path!(), ::zeroclaw_log::Action::Reject)
                .with_outcome(::zeroclaw_log::EventOutcome::Failure)
                .with_attrs(::serde_json::json!({"candidate": candidate})),
            "openai_codex: endpoint override is not a valid URL"
        );
        anyhow::Error::msg("OpenAI Codex endpoint override must be a valid URL")
    })?;

    match parsed.scheme() {
        "http" | "https" => {}
        _ => anyhow::bail!("OpenAI Codex endpoint override must use http:// or https://"),
    }

    let path = parsed.path().trim_end_matches('/');
    if !path.ends_with("/responses") {
        let with_suffix = if path.is_empty() || path == "/" {
            "/responses".to_string()
        } else {
            format!("{path}/responses")
        };
        parsed.set_path(&with_suffix);
    }

    parsed.set_query(None);
    parsed.set_fragment(None);

    Ok(parsed.to_string())
}

View on GitHub (pinned to 88bb9c8533)

Solutions

1. Use an http:// or https:// URL; for local proxies use http://127.0.0.1:<port>.
2. Fix typoed schemes in the override value.
3. Remove the override entirely to restore the default OpenAI Responses endpoint.

Example fix

# before
[providers.models.openai-codex.main]
api_url = "unix:///run/codex-proxy.sock"

# after
[providers.models.openai-codex.main]
api_url = "http://127.0.0.1:8080"

let ok = url.starts_with("https://") || url.starts_with("http://");
if !ok {
    return Err(anyhow::anyhow!("endpoint override must be http(s)"));
}

When it happens

Trigger: provider_api_url set to a unix socket path (unix:///var/run/...), a file:// path, or a copy-pasted internal address with a protocol prefix reqwest does not speak.

Common situations: Pointing the codex provider at a local proxy via a socket path; typoed scheme (htps://, https:/); pasting a scraping/proxy target URL that uses a custom scheme.

Related errors

• OpenAI Codex endpoint override cannot be empty
• Custom model_provider `{prefix}:<url>` requires a URL beginn
• unsupported URL scheme: {}
• Only http:// or https:// URLs are allowed
• Only http:// and https:// URLs are allowed

AI-assisted analysis of zeroclaw-labs/zeroclaw@88bb9c8533 (2026-08-23). Data as JSON: /api/errors/d782a11713c2e2b1. Report an issue: GitHub.