How to Configure a Proxy in OneClaw: Fixing the Unrecognized key: "proxy" Error and Setting Up Port 17890

Introduction

A common issue many users encounter when working with OneClaw or OpenClaw is networking.

You may run into questions such as:

  • Why can’t OneClaw connect to the model provider?
  • Why does proxy configuration seem to have no effect?
  • Why does adding a proxy field trigger an error?
  • Where should proxy settings actually be configured?

At first glance, this looks like a simple networking problem. In practice, however, it often leads users into unnecessary troubleshooting loops.

This guide walks through a real-world configuration scenario and explains, in plain language:

  • Why the proxy configuration fails
  • What the Unrecognized key: "proxy" error actually means
  • Why system proxy settings often work better
  • How environment variables solve the problem
  • How to correctly switch from port 7897 to 17890
  • What to check when changes still do not take effect

The goal here is practical troubleshooting—not theory.

The First Sign Something Is Wrong

A common starting point looks like this.

A user adds a proxy configuration to the OneClaw config file:

{
  "proxy": {
    "enabled": true,
    "proxyUrl": "http://127.0.0.1:17890"
  }
}

After reloading, OneClaw returns:

[reload] config reload skipped (invalid config):
Unrecognized key: "proxy"

At this point, many users assume:

  • The JSON syntax is incorrect
  • The configuration location is wrong
  • The program failed to reload
  • The formatting is broken

But the actual meaning is much simpler.

OneClaw does not recognize the proxy field in the current configuration schema.

In other words:

The problem is not formatting. The application simply does not accept that key.

This distinction matters because it changes the troubleshooting direction completely.

Instead of continuing to rewrite JSON configurations, the better approach is to move proxy handling outside of the config file.

Understanding Why the Proxy Configuration Fails

Let’s look at an important part of the configuration:

"gateway": {
  "mode": "local"
}

The key detail here is:

"mode": "local"

This indicates that OneClaw is running in local gateway mode.

In practical terms, that means:

  • Network traffic depends on the local runtime
  • Requests are affected by the operating system environment
  • Proxy behavior is more closely tied to system networking

This explains something that confuses many users:

Why does editing the config file fail while enabling a system proxy suddenly works?

The answer is simple:

OneClaw is more likely to inherit networking behavior from the operating system than from unsupported configuration keys.

Why System Proxy Settings Often Work Better

If you are using a local proxy tool, such as a desktop accelerator or tunneling application, the easiest solution is usually:

Let the operating system handle the proxy.

Instead of searching for an internal “proxy settings” menu inside OneClaw.

A typical workflow looks like this:

  1. Open your proxy application
  2. Enable System Proxy
  3. Or enable TUN Mode
  4. Completely restart OneClaw

That final step is important.

Many desktop applications read networking settings only during startup.

This means:

Closing the window is not always enough.

The application may still be running in the background using old settings.

A full exit and relaunch is usually required.

Why Environment Variables Often Work More Reliably

Once it becomes clear that:

Unrecognized key: "proxy"

is a configuration limitation, the next practical solution is:

Environment variables.

You can think of environment variables as instructions that tell an application:

“If you need network access, use this route.”

In local proxy setups, traffic is usually routed through:

127.0.0.1

This refers to:

The local machine itself.

The port number identifies where the proxy service is listening.

Switching from Port 7897 to Port 17890

In this troubleshooting case, the proxy port changed from:

7897

to:

17890

This matters more than many users expect.

Every previous reference to:

7897

must be updated.

Otherwise, OneClaw continues attempting to connect to the old endpoint.

Typical symptoms include:

  • Request timeouts
  • Failed model responses
  • Connection errors
  • Unresponsive API calls

Even when everything else appears correct.

Correct Proxy Format for Port 17890

If your local proxy listens on:

127.0.0.1:17890

Then your HTTP/HTTPS proxy format should look like this:

http://127.0.0.1:17890

For SOCKS proxies:

socks5://127.0.0.1:17890

A common mistake is mixing protocols.

For example:

Using:

http://127.0.0.1:17890

when the proxy expects SOCKS traffic.

Or:

socks5://127.0.0.1:17890

when the service expects HTTP traffic.

The result is often confusing because:

The port is technically correct, but the connection still fails.

Setting Up a Proxy on macOS

For macOS users, environment variables are often the most reliable approach.

Run:

launchctl setenv HTTP_PROXY http://127.0.0.1:17890
launchctl setenv HTTPS_PROXY http://127.0.0.1:17890
launchctl setenv ALL_PROXY socks5://127.0.0.1:17890

After applying these settings:

  1. Fully quit OneClaw
  2. Reopen the application

This step is necessary because OneClaw may only read networking variables during launch.

Simply minimizing or closing the window may not refresh the connection settings.

Setting Up a Proxy on Windows

Windows users can configure environment variables using PowerShell:

setx HTTP_PROXY http://127.0.0.1:17890
setx HTTPS_PROXY http://127.0.0.1:17890
setx ALL_PROXY socks5://127.0.0.1:17890

After running these commands:

Restart OneClaw.

In some cases, signing out and back into Windows may also help refresh environment variables.

Why the Proxy Still Does Not Work After Restarting

If networking still fails after configuration, the problem usually falls into one of a few categories.

1. OneClaw Never Fully Closed

This is surprisingly common.

For many desktop applications:

Closing the window does not actually terminate the process.

The application may still be running in the background.

As a result:

Old networking settings remain active.

The fix:

Fully quit OneClaw before reopening it.

2. System Proxy Was Never Enabled

If your proxy application supports:

  • System Proxy
  • TUN Mode

make sure at least one is enabled.

Otherwise:

Even correctly configured environment variables may not route traffic as expected.

The result often looks like:

Everything appears configured correctly, but requests still fail.

3. The Port Number Was Never Updated

Another common issue occurs when:

The proxy application changes from:

7897

to:

17890

but OneClaw still references:

7897

This creates a silent failure.

The application keeps sending requests to a port that no longer exists.

How to Confirm the Proxy Is Working

A simple indicator is behavior.

If OneClaw previously experienced:

  • Model timeout errors
  • Failed API responses
  • No network connectivity

and suddenly begins responding normally after configuration changes:

The proxy is likely working.

You should also verify the listening address:

127.0.0.1:17890

to confirm that your local proxy service is actively running there.

Without an active listener:

OneClaw has nowhere to send traffic.

Why Continuing to Edit the proxy Field Is Usually a Dead End

Once you see:

Unrecognized key: "proxy"

the situation becomes fairly clear.

The current configuration does not support:

"proxy": {}

Continuing to experiment with variations such as:

"proxyUrl"

or guessed networking keys usually creates more confusion.

A better approach is:

Move proxy handling to the system layer.

This tends to be simpler, more stable, and easier to troubleshoot.

Frequently Asked Questions

Does OneClaw support proxy settings inside the JSON config?

Based on the observed behavior in this setup:

The current configuration rejects:

"proxy": {}

and returns:

Unrecognized key: "proxy"

This indicates that the field is not supported.

Why does OneClaw still time out after configuring a proxy?

Check these items first:

  1. Did you fully restart OneClaw?
  2. Is system proxy enabled?
  3. Is your local proxy application running?
  4. Did the port change?
  5. Are you using:
127.0.0.1:17890

instead of an outdated value?

Where should port 17890 be configured?

If you are using environment variables:

HTTP:

http://127.0.0.1:17890

SOCKS:

socks5://127.0.0.1:17890

Why did the proxy stop working after changing ports?

Because OneClaw may still be pointing to the old port.

For example:

Old:

7897

New:

17890

Every reference must be updated.

Why didn’t changes apply after closing the app?

Because:

The app may still be running in the background.

A full exit is usually required.

Final Thoughts

When troubleshooting networking problems in OneClaw, a practical order of operations is:

  1. Confirm the proxy application is running
  2. Verify the listening port
  3. Enable system proxy or TUN mode
  4. Configure environment variables
  5. Fully restart OneClaw
  6. Stop editing unsupported proxy fields

Most importantly:

If you see:

Unrecognized key: "proxy"

treat it as a signal to change direction.

Rather than repeatedly editing JSON files, moving proxy handling to the operating system layer is usually faster, more predictable, and significantly easier to debug.