How to configure ZeroClaw parameters?

[callmeitachi]

Hello everyone, I would like to ask how to configure ZeroClaw to use a model that is internally deployed within our company. I've been working on this for days but still haven't been able to get it working. The API endpoints for our internal models may require additional custom headers in requests, although the underlying calling interface is basically the same. How should I configure this? To be honest, I find the configuration documentation somewhat ambiguous and unclear. Could the documentation be improved to make it more comprehensive and complete?

[starkmarkus]

If your internal endpoint is OpenAI-compatible, I think the first thing to try is the custom model provider slot rather than creating a new provider.

The config shape should be roughly:

[providers.models.custom.internal]
uri = "https://your-internal-gateway.example.com/v1"
model = "your-model-name"
api_key = "your-token-or-placeholder"

[agents.default]
model_provider = "custom.internal"
risk_profile = "default"

[risk_profiles.default]
# your existing risk settings here

The important parts are:

[providers.models.custom.internal]

where custom is the provider type and internal is just your local alias, and:

model_provider = "custom.internal"

in the agent config.

If your endpoint follows the normal OpenAI-compatible shape:

POST /v1/chat/completions

or similar, then uri should normally be the base URL, for example:

uri = "https://your-internal-gateway.example.com/v1"

not the full /chat/completions path, unless ZeroClaw’s current custom provider expects otherwise in your version.

The harder part is your “additional custom headers” requirement. I would not assume that arbitrary provider request headers are currently configurable. There was already a feature request for custom headers, and that sounds very close to your use case. If your internal gateway requires something like:

X-Tenant-Id: ...
X-Company-Auth: ...
X-Model-Routing: ...

then the current config may not be enough unless your version has added a provider-level headers field.

A practical workaround is to put a small internal proxy in front of your model endpoint:

ZeroClaw -> local/internal proxy -> company model gateway

The proxy can add the required custom headers and forward the request to your real internal model endpoint. Then ZeroClaw only needs to talk to a normal OpenAI-compatible endpoint with uri + api_key.

So my suggested debugging order would be:

1. Test the internal endpoint directly with curl using the exact headers your company requires.
2. Configure ZeroClaw with [providers.models.custom.] and uri/model/api_key.
3. Run a simple CLI/agent request and check the ZeroClaw logs for the actual provider error.
4. If the only missing piece is custom headers, use a small proxy for now or open/track a provider-level custom-headers feature request.

I also agree that the documentation could be clearer here. It would help to have one complete example for:

• OpenAI-compatible internal gateway;
• custom base URL;
• custom model name;
• required auth token;
• optional custom headers;
• agent config pointing to that provider.

So the short answer is: use a custom OpenAI-compatible provider if the API shape matches OpenAI, but if your company endpoint requires arbitrary extra headers, that may need either a proxy workaround or a ZeroClaw config enhancement.

[callmeitachi]

I saw in the ZeroClaw documentation that there is a configuration for the extra_headers field, but there are no specific examples telling me how to edit it in the configuration file. So it's possible that when I configured extra_headers earlier, the format I wrote was incorrect, causing ZeroClaw to fail to recognize it. Now I am able to run the built-in models without having to define the Provider myself in the code. Next, I will try to apply ZeroClaw to work automation, and I hope ZeroClaw can truly be helpful for my work!

[starkmarkus]

Good catch - if extra_headers exists, this was probably just a TOML format issue.

I would expect it inside the provider block, e.g.:

extra_headers = { "X-Tenant-Id" = "tenant", "X-Company-Auth" = "value" }
A complete docs example for internal OpenAI-compatible gateways would defintely help future users.