OpenClaw agents inherit wrong provider base URLs: complete diagnosis and fix

Problem statement: you create a new OpenClaw agent, and it immediately fails with 404 errors or empty responses. The agent can't reach providers, requests go to malformed URLs, and the issue appears to propagate from existing agents to new ones automatically.

Why this breaks multi-agent deployments

Multi-agent setups in OpenClaw are designed to inherit configuration patterns, which is efficient when the base configuration is correct. When the base configuration contains a malformed provider URL, every new agent inherits the problem, creating a cascade of failures across your deployment.

The particularly dangerous aspect is silent failure. Agents may appear to start successfully, show healthy status indicators, and only fail when attempting to make provider requests. This makes diagnosis difficult because the problem is not visible until runtime execution reaches an external API call.

Evidence from the field

Based on recent reports, this pattern typically involves:

• Newly-created agents failing provider requests immediately after creation.
• 404 errors or connection refused when agents attempt to reach providers.
• Base URLs in models.json containing provider-specific paths that shouldn't be there.
• Custom baseURL configurations that worked for one provider breaking others.
• Copying configuration from one agent to another propagating the issue.
• Gateway status showing healthy despite agent-level provider failures.
• Existing agents may continue working if they don't use the misconfigured provider.

How to recognize inherited baseURL issues

• You created a new agent and it fails immediately with provider errors.
• Agent logs show 404 or connection errors for provider URLs.
• The URL in error messages includes unexpected path segments.
• Existing agents using the same provider may also be affected.
• Issue appeared after creating a new agent or copying agent configuration.
• Provider dashboard shows no incoming requests (requests going to wrong URL).
• Restarting the agent or gateway doesn't resolve the issue.

Root causes that match this incident shape

1) Provider-specific path leakage in base URL

The most common cause is a base URL that includes provider-specific path segments. For example, configuring https://api.example.com/v1/chat/completions as the base URL instead of https://api.example.com/v1. When the agent adds its own path for specific endpoints, the URLs become malformed.

2) Cross-provider configuration copying

When creating new agents based on existing ones, provider-specific base URLs may be copied to agents that use different providers. Each provider has its own required base URL structure, and copying between them creates mismatches.

3) Custom baseURL overrides not updating after provider changes

If you manually configured a custom base URL for a provider and later changed which provider an agent uses, the old base URL may persist. The agent points to the old provider's endpoint while trying to use the new provider's models, resulting in 404 errors.

4) Agent template with embedded base URLs

Some deployments use agent templates or configuration scripts that embed specific base URLs. When these templates are used to create new agents, hardcoded URLs may not match the actual providers being used.

Diagnostic steps to identify the problem

Step 1: Locate the agent's models.json file

Each agent has its own models.json configuration file. You need to find this file to inspect the configured base URLs and identify incorrect values.

# Find agent configuration directories
openclaw agents list

# Locate models.json for a specific agent
# Typical path: ~/.openclaw/agents/[agent-name]/models.json
# Or in your workspace: ./agents/[agent-name]/models.json

Step 2: Inspect the baseURL values

Open the models.json file and look for baseURL entries. Check whether they include provider-specific paths that should be handled dynamically by OpenClaw rather than hardcoded.

# Check models.json content
cat ~/.openclaw/agents/your-agent/models.json | grep -i baseurl

# Look for common problems:
# - Full endpoint paths like ".../chat/completions" instead of base ".../v1"
# - Provider names embedded in URLs
# - HTTP vs HTTPS mismatches
# - Typos in domain names

Step 3: Compare with working agents

If you have other agents using the same provider successfully, compare their models.json files with the failing agent. Differences in baseURL configuration will reveal the problem.

# Side-by-side comparison
diff working-agent/models.json failing-agent/models.json

Step 4: Verify provider documentation

Check the provider's documentation for the correct base URL format. Most providers document whether you should use the base API path or a specific endpoint URL.

Resolution strategies

Strategy 1: Fix the base URL in models.json

Edit the agent's models.json file and correct the baseURL to use the provider's documented base API path, removing any endpoint-specific segments that OpenClaw should handle dynamically.

# Example correction for a typical OpenAI-compatible provider:
# WRONG (includes endpoint path):
"baseURL": "https://api.example.com/v1/chat/completions"

# CORRECT (base API path only):
"baseURL": "https://api.example.com/v1"

# Edit the file:
nano ~/.openclaw/agents/your-agent/models.json

Strategy 2: Remove custom baseURL to use provider default

If the custom baseURL is unnecessary, remove it entirely to let OpenClaw use the provider's default base URL. This is the safest approach when you don't have a specific reason to override the default.

# Remove the baseURL entry from models.json
# This allows OpenClaw to use provider defaults
# Edit models.json and delete the baseURL line for affected providers

Strategy 3: Update agent creation process

If you use scripts or templates to create agents, update them to avoid copying provider-specific base URLs between different providers. Ensure each agent uses the correct base URL for its configured providers.

Strategy 4: Restart or reload configuration

After editing models.json, you may need to restart the agent or create a new session for changes to take effect, depending on your OpenClaw configuration and whether hot reload is enabled.

# Try new session first (safer, preserves running instance)
# OpenClaw may pick up changes automatically

# If changes don't take effect, restart gateway:
openclaw gateway restart

# Verify agent can reach providers:
openclaw prompt "test" --agent your-agent

Strategy 5: Prevent recurrence with provider-specific templates

Create separate agent templates for each provider you use, each with the correct base URL for that provider. When creating new agents, start from the template matching the provider you plan to use.

Verification checklist after applying fixes

• You located and inspected the agent's models.json file.
• You identified incorrect baseURL values in the configuration.
• You corrected the baseURL to use provider-documented base paths.
• You removed unnecessary endpoint-specific path segments.
• You tested the agent with a simple prompt after the fix.
• You verified provider requests are reaching correct endpoints.
• You updated agent creation processes to prevent recurrence.

Common mistakes that make this harder to resolve

1. Mistake: assuming the provider is down when seeing 404 errors.
   Correction: 404 on a specific endpoint usually means the URL is malformed, not that the provider is down.
2. Mistake: repeatedly recreating the agent without fixing the base configuration.
   Correction: if the source configuration is broken, recreating agents will propagate the same issue. Fix the root first.
3. Mistake: not checking models.json when agents fail silently.
   Correction: agent configuration files are where provider URLs are stored. Inspect them directly.
4. Mistake: using full endpoint URLs as base URLs.
   Correction: base URLs should point to the API base path, not specific endpoints.

Provider-specific base URL reference

When to escalate or consider alternatives

If you've corrected the base URLs and agents still fail to reach providers, the issue may be in network routing, firewall rules, or the provider itself. Verify connectivity with curl from the same environment where OpenClaw runs to isolate infrastructure issues from configuration issues.

For teams managing multiple agents across different providers, consider managed hosting where provider configuration is handled through tested interfaces rather than manual file editing. This reduces the risk of configuration errors propagating across your deployment.

FAQ

Do I need to restart the gateway after editing models.json?

Try starting a new session first. Many OpenClaw configurations pick up changes automatically. If the agent still fails after starting a new session, then restart the gateway.

Can I have different base URLs for different providers?

Yes. Each provider in models.json can have its own baseURL configuration. The key is ensuring each baseURL contains only the base API path for that specific provider, not endpoint-specific paths.

What should I link to next if I want help with agent configuration?

See OpenClaw memory files explained for more on agent configuration, OpenClaw setup guide for provider configuration basics, or hosting comparison to understand managed alternatives.

Fix once. Stop recurring agent base URL configuration.

If this keeps coming back, you can move your existing setup to managed OpenClaw cloud hosting instead of rebuilding the same stack. Import your current instance, keep your context, and move onto a runtime with lower ops overhead.

• Import flow in ~1 minute
• Keep your current instance context
• Run with managed security and reliability defaults

If you would rather compare options first, review OpenClaw cloud hosting or see the best OpenClaw hosting options before deciding.

Import your current OpenClaw instance in 1 click Keep self-hosted: apply fix checklist