accessing lan server from agent | Friends of the Crustacean 🦞🤝 | Page 1

rain fern Apr 16, 2026, 4:37 PM

#

my openclaw agent can not access the mcp server at lan. When I install the server on gateway it can access using 127.0.0.1 but if I move the server to another lan server (192.168.254.20) the agent can not ping. I turned off sandbox but it did not help. What's wrong ?

pulsar harnessBOT Apr 16, 2026, 4:37 PM

#

rain fern Apr 16, 2026, 4:39 PM

#

@krill ?

mint urchinBOT Apr 16, 2026, 4:43 PM

#

Let me verify the MCP transport path and the exact private-network guard, because this smells like SSRF protection, not sandboxing.

#

This is probably not sandbox.

I checked the current docs/code, and the remote MCP path is a gateway-side HTTP transport (sse or streamable-http), not an exec sandbox thing. Also, mcp.servers.* currently only exposes:

url
transport
headers
connectionTimeoutMs

So there is not an obvious MCP allowPrivateNetwork config knob to flip here.

What that usually means:

Your remote MCP server is only bound to loopback
- works on the same host via 127.0.0.1
- fails from another machine
- fix: bind it to 0.0.0.0 or 192.168.254.20, not 127.0.0.1

#

Firewall / port / routing issue
- OpenClaw does not need “ping”, it needs HTTP reachability
- from the gateway host, test the MCP endpoint directly:
```
curl -v http://192.168.254.20:<port>/...
nc -vz 192.168.254.20 <port>
```
- if that fails, it’s a network/server issue, not OpenClaw
If curl works but OpenClaw still fails
- then I’d suspect an MCP remote transport bug/regression
- I do not see a documented MCP private-LAN opt-in setting right now

Also, first please post:

#

openclaw --version

and, if possible, your mcp.servers.<name> config block with secrets redacted.

Docs I checked:

MCP CLI/docs: https://docs.openclaw.ai/cli/mcp
Network hub: https://docs.openclaw.ai/network
Sandbox explainer: https://docs.openclaw.ai/gateway/sandbox-vs-tool-policy-vs-elevated

If you paste the MCP URL shape plus the exact error from the gateway log, I can narrow it down fast.

#

Yep, I checked it 🙂

Short version, this is probably not sandbox.

If 127.0.0.1 works only when the MCP server is on the same box, but 192.168.254.20 fails from another box, the usual cause is:

the MCP server is bound to 127.0.0.1 only, not 0.0.0.0 / LAN IP
or a firewall / port / routing issue

OpenClaw’s remote MCP path is just HTTP (sse / streamable-http), so first test from the gateway host itself:

curl -v http://192.168.254.20:<port>/...
nc -vz 192.168.254.20 <port>

If that fails, it’s network/server-side, not OpenClaw.

#

Also please paste:

openclaw --version

and your mcp.servers.<name> block with secrets removed. If you send that, I’ll narrow it down.

rain fern Apr 16, 2026, 4:45 PM

#

mcp server is not bound to 127.0.0.1 , I can access its IP with curl from the terminal of the server on which the openclaw agent runs. So this is either a mac os firewall/ network issue, or some openclaw config

mint urchinBOT Apr 16, 2026, 4:46 PM

#

I’m going one layer deeper, because if curl from the same host works then it’s either MCP transport config or a runtime bug, not simple LAN reachability.

#

Yeah, if curl from the same host works, I would not blame macOS firewall first.

At that point the most likely OpenClaw-side issues are:

Wrong MCP transport

OpenClaw defaults remote MCP HTTP to sse
if your server is actually streamable HTTP, you must set:

{
  "mcp": {
    "servers": {
      "my-server": {
        "url": "http://192.168.254.20:PORT/mcp",
        "transport": "streamable-http"
      }
    }

#

     }
   }

Docs: https://docs.openclaw.ai/cli/mcp

Wrong endpoint path / missing headers
- curl http://192.168.254.20:PORT succeeding is not enough
- you need to curl the exact MCP endpoint with the same auth headers
- for example, many servers use /mcp, some SSE setups use a different path
OpenClaw bug/regression
- I checked the current schema/docs and I do not see an MCP-specific private-network knob under mcp.servers.*
- so if exact curl works and transport/path are correct, this starts looking like a real MCP runtime bug

What I’d check next:

#

openclaw --version
exact mcp.servers.<name> block, redacted

exact result of:

curl -v http://192.168.254.20:PORT/EXACT_MCP_PATH

with the same headers if needed

gateway log line containing:
- bundle-mcp: failed to start server
- or any ECONNREFUSED / ETIMEDOUT / 404 / 401

One big gotcha: if transport is omitted, OpenClaw uses sse. That’s the first thing I’d verify.

rain fern Apr 16, 2026, 4:50 PM

#

my openclaw agent says it can not ping (icmp) the server and can not reach the tcp port. ilkeraktuna@ilkers-Mac-mini ~ % openclaw --version
OpenClaw 2026.4.5 (3e72c03)
ilkeraktuna@ilkers-Mac-mini ~ % curl -v http://192.168.254.20:8124/api/mcp

Trying 192.168.254.20:8124...
Connected to 192.168.254.20 (192.168.254.20) port 8124

GET /api/mcp HTTP/1.1
Host: 192.168.254.20:8124
User-Agent: curl/8.7.1
Accept: /

Request completely sent off
< HTTP/1.1 401 Unauthorized
< WWW-Authenticate: Bearer resource_metadata="http://192.168.254.20:8124/.well-known/oauth-protected-resource"
< Content-Type: text/plain; charset=utf-8
< Referrer-Policy: no-referrer
< X-Content-Type-Options: nosniff
< Server:
< X-Frame-Options: SAMEORIGIN
< Content-Length: 17
< Date: Thu, 16 Apr 2026 16:49:21 GMT
<
Connection #0 to host 192.168.254.20 left intact
401: Unauthorized%

#

@mint urchin

mint urchinBOT Apr 16, 2026, 4:51 PM

#

That actually helps a lot. A 401 Unauthorized from curl means the LAN path is fine, so the “can’t ping / can’t reach TCP port” message is almost certainly a bad agent diagnosis, not the real root cause.

#

That 8124 /api/mcp URL looks a lot like Home Assistant, so I want to sanity-check whether it expects bearer auth plus streamable HTTP before I point you the wrong way.

#

Aha, this is not LAN reachability.

Your curl proves:

TCP connect to 192.168.254.20:8124 works
the MCP endpoint responds
the failure is auth, because it returns 401 Unauthorized

So the agent saying “can’t ping / can’t reach TCP port” is just a bad diagnosis.

Also, 8124 /api/mcp looks like Home Assistant MCP. For that, the important bits are:

Home Assistant MCP uses /api/mcp
it expects authentication
it uses streamable HTTP, not the default SSE

In OpenClaw, I would configure it like this:

#

{
  "mcp": {
    "servers": {
      "ha": {
        "url": "http://192.168.254.20:8124/api/mcp",
        "transport": "streamable-http",
        "headers": {
          "Authorization": "Bearer <HOME_ASSISTANT_LONG_LIVED_TOKEN>"
        }
      }
    }
  }
}

Two important gotchas here:

#

if transport is omitted, OpenClaw defaults to sse
current OpenClaw MCP config docs show static headers auth, not a full remote OAuth setup flow

So for Home Assistant, the safest path is usually a Long-Lived Access Token in the Authorization header.

Relevant docs:

OpenClaw MCP config: https://docs.openclaw.ai/cli/mcp
Home Assistant MCP server: https://www.home-assistant.io/integrations/mcp_server/

If you want, paste your current mcp.servers block, redacted, and I’ll sanity-check it line by line.

If this fixes it, please right-click the solution message → Apps → ✅ Mark Solution so Answer Overflow can index it for the next person. 🎉

#

Yep 🦐

The key signal is this line from your curl:

Connected to 192.168.254.20 ...
then 401 Unauthorized

So OpenClaw is not blocked from the LAN host. It’s reaching the server fine, but the MCP endpoint is rejecting the request.

I’d focus on:

transport: "streamable-http"
headers.Authorization: "Bearer ..."

If you paste your current mcp.servers entry, I can spot the bad bit fast.

rain fern Apr 16, 2026, 5:46 PM

#

look you are not evaluating the situation correctly. The curl output I supplied is the output of command you requested me to try. 401 is the response I got because I did not provide any auth header. That is normal. The problem is that the openclaw agent can not ping (icmp) or reach the tcp port with curl. So the problem is either openclaw config or mac os firewall/network issue

#

please accept that the openclaw agent is not able to reach the api endpoint by network and try to focus on solution to this.

mint urchinBOT Apr 16, 2026, 5:47 PM

#

You’re right, I conflated shell reachability with the agent runtime path. Thanks for calling that out.

The 401 only proved your terminal can reach the host. It does not prove the process behind the agent can.

The key question now is: which process is actually opening the MCP connection?

Two cases:

Embedded/OpenClaw runtime
- OpenClaw itself connects to mcp.servers.*.url
CLI backend with bundle MCP (codex-cli, claude-cli, gemini-cli, etc.)
- the backend process gets MCP config overlay and may be the thing trying to reach the remote MCP server
- in that case, turning off OpenClaw sandbox does not necessarily help

OpenClaw docs for that path: https://docs.openclaw.ai/gateway/cli-backends

#

Also, I checked the current MCP config shape and I do not see an MCP-specific LAN/private-network knob like mcp.servers.*.allowPrivateNetwork. So I don’t think there’s a hidden “allow LAN MCP” config switch you missed.

So the most likely buckets now are:

backend-owned sandbox/network restriction if you’re using a CLI backend
process-specific macOS restriction / third-party firewall
OpenClaw MCP runtime bug/regression

Most useful next info would be:

are you using the embedded agent or a CLI backend?
the exact redacted mcp.servers entry
the actual gateway log line around:
- bundle-mcp: failed to start server

If you paste those, I can stop guessing and narrow it properly.

#

Fair pushback. I accept the symptom: the OpenClaw agent process cannot reach the LAN endpoint, even though your shell can.

Given that, I would stop hunting for an auth issue and focus on process-specific networking.

Most likely fixes, in order:

If you’re using a CLI backend, fix the backend’s own network/sandbox
- OpenClaw sandbox off does not necessarily control the backend process
- if this is Codex/Claude Code/Gemini CLI with bundle MCP, the backend may be the thing that cannot reach LAN
If the gateway is running as a macOS service/LaunchAgent, run it from the same user session where curl works
- shell works
- service/agent process does not
- that strongly suggests a process-context issue, not general LAN failure
Immediate workaround: bridge the remote MCP server back to loopback
- since 127.0.0.1 works for OpenClaw, expose the LAN MCP server locally on the gateway host via an SSH tunnel/local proxy

#

then point mcp.servers.*.url back at 127.0.0.1

My recommendation: do #2 first, because it tells you fast whether this is a macOS service/process issue.

Also, I do not see a current OpenClaw config key like mcp.servers.*.allowPrivateNetwork, so I don’t think there’s a hidden “enable LAN MCP” switch you missed.

If you want, I can help you narrow it to one branch fast, but I need just one fact:

are you using the embedded OpenClaw agent, or a CLI backend?

rain fern Apr 16, 2026, 5:51 PM

#

how do I know that ? I asked the openclaw agent to use mcporter

mint urchinBOT Apr 16, 2026, 5:52 PM

#

Let me check the exact OpenClaw config key/docs for how backends are selected, so I can tell you the reliable way to verify it instead of guessing.

#

mcporter is not the agent backend. It’s a skill/tool runtime.

So, asking the agent to “use mcporter” does not tell us whether the session is:

the embedded OpenClaw agent
a CLI backend
an ACP runtime

Fastest ways to tell:

Run /acp status
- if that returns a backend/mode, you’re on ACP
- if it says unsupported / nothing ACP-related, you’re probably not
Run /status
- that shows the current session/runtime info

#

Check config
- agents.defaults.cliBackends → CLI backend configured
- acp.backend or agents.list[].runtime.acp.backend → ACP configured
- if neither applies, it’s usually the embedded agent

Also, docs-wise:

mcporter is documented as a core skill
CLI backends live under agents.defaults.cliBackends
ACP backends show up under acp.backend / runtime.acp.backend

So the short answer is: mcporter doesn’t answer the question.

If you paste the output of /acp status or /status, I can tell you which path you’re actually on and then focus the network fix there.

rain fern Apr 16, 2026, 5:54 PM

#

ACP error (ACP_SESSION_INIT_FAILED): Session is not ACP-enabled: agent:main:main
next: If this session is stale, recreate it with /acp spawn and rebind the thread. ------ 🦞 OpenClaw 2026.4.5 (3e72c03)
🧠 Model: ollama/minimax-m2.5:cloud · 🔑 api-key (ollama:default)
🧮 Tokens: 46k in / 524 out
📚 Context: 46k/205k (22%) · 🧹 Compactions: 0
🧵 Session: agent:main:main • updated just now
⚙️ Runtime: direct · Think: off
🪢 Queue: collect (depth 0)

mint urchinBOT Apr 16, 2026, 5:55 PM

#

We’ve got the key missing piece now: this is not ACP and the session is Runtime: direct. I’m checking one more thing before I answer, because that changes the diagnosis a lot.

#

That status output is the useful bit.

You’re on:

Session: agent:main:main
Runtime: direct
Not ACP

So this is not a separate ACP/CLI backend process, and I do not think there’s a hidden “allow LAN MCP” switch in OpenClaw for this path.

Given that, and given your shell can reach 192.168.254.20:8124, the practical suspect becomes the model/tool layer, not a separate network namespace.

Your status also shows an Ollama-backed model. OpenClaw’s Ollama docs explicitly warn:

if Ollama is configured through /v1, tool calling can break badly
use the native Ollama base URL, no /v1

#

Docs: https://docs.openclaw.ai/providers/ollama

So my concrete recommendation is:

Check your Ollama base URL
```
openclaw config get models.providers.ollama.baseUrl
```
If it ends in /v1, that’s wrong for OpenClaw tool calling.
Retry this test with a tool-reliable model/provider
- just for debugging
- because right now the “can’t ping / can’t curl” claim may be the model misreporting tool use, not an actual host network block
If you want the immediate workaround, use a local loopback forward
- since direct 127.0.0.1 works for OpenClaw, tunnel/proxy the LAN MCP server back to loopback and point mcp.servers.*.url there

#

So, shortest path from here: check models.providers.ollama.baseUrl first. If you paste that value, I can tell you immediately whether this is the broken /v1 path.

rain fern Apr 16, 2026, 5:58 PM

#

ollama base url is not v1 , and the model is tool reliable

mint urchinBOT Apr 16, 2026, 5:58 PM

#

I think I finally see a real OpenClaw-specific possibility that fits your symptoms. I’m checking the docs for it before I send you another wrong branch.

#

I think I finally found an actual OpenClaw config that matches your symptom.

If this is true:

agents.defaults.sandbox.mode = off
but tools.exec.host = sandbox

then exec fails closed, even in a direct session.

That would look exactly like:

your normal shell can curl the LAN host
but when the agent tries ping / curl through exec, it says it cannot reach it

OpenClaw docs/code on this are pretty explicit:

exec host=sandbox requires a sandbox runtime for this session
if sandbox mode is off and exec host is still sandbox, it fails

#

Please check:

openclaw config get tools.exec.host
openclaw sandbox explain --session agent:main:main

If tools.exec.host comes back as sandbox, fix it with:

openclaw config set tools.exec.host gateway
openclaw gateway restart

If you want the fully normal host-exec defaults back:

#

openclaw config set tools.exec.host gateway
openclaw config set tools.exec.security full
openclaw config set tools.exec.ask off
openclaw gateway restart

Docs:

This is the first OpenClaw-specific knob we’ve hit that really fits the “shell works, agent curl says no network” pattern. If you run those two checks and paste the output, I can confirm it quickly.

rain fern Apr 16, 2026, 6:02 PM

#

ilkeraktuna@ilkers-Mac-mini ~ % openclaw config get tools.exec.host

🦞 OpenClaw 2026.4.5 (3e72c03) — Claws out, commit in—let's ship something mildly responsible.

gateway
ilkeraktuna@ilkers-Mac-mini ~ % openclaw sandbox explain --session agent:main:main

🦞 OpenClaw 2026.4.5 (3e72c03) — Powered by open source, sustained by spite and good documentation.

Effective sandbox:
agentId: main
sessionKey: agent:main:main
mainSessionKey: agent:main:main
runtime: direct
mode: off scope: agent
workspaceAccess: none workspaceRoot: /Users/ilkeraktuna/.openclaw/sandboxes

Sandbox tool policy:
allow (default): exec, process, read, write, edit, apply_patch, image, sessions_list, sessions_history, sessions_send, sessions_spawn, sessions_yield, subagents, session_status
deny (default): browser, canvas, nodes, cron, gateway, feishu, googlechat, nostr, msteams, mattermost, nextcloud-talk, matrix, bluebubbles, line, zalo, zalouser, synology-chat, tlon, qa-channel, discord, imessage, irc, qqbot, signal, slack, telegram, twitch, whatsapp

Elevated:
enabled: true
channel: webchat
allowedByConfig: false
failing gates: allowFrom (tools.elevated.allowFrom.webchat)

Fix-it:

tools.sandbox.tools.allow
tools.sandbox.tools.alsoAllow
tools.sandbox.tools.deny
agents.list[].tools.sandbox.tools.allow
agents.list[].tools.sandbox.tools.alsoAllow
agents.list[].tools.sandbox.tools.deny
tools.elevated.enabled
tools.elevated.allowFrom.webchat

Docs: docs.openclaw.ai/sandbox

mint urchinBOT Apr 16, 2026, 6:03 PM

#

Thanks, that rules out the tools.exec.host branch too.

So at this point we’ve eliminated the obvious OpenClaw config causes:

ACP / CLI backend: no, this is Runtime: direct
Sandbox: off
tools.exec.host: gateway
Host LAN reachability: your shell can reach 192.168.254.20:8124

That leaves a pretty uncomfortable conclusion: this now looks like an OpenClaw bug or a mcporter/tool-subprocess bug, not a normal sandbox/network config issue.

I don’t have another documented “flip this config key” fix for you after those checks.

Practical options now

Best workaround right now

keep using a local loopback endpoint

#

forward/proxy the remote MCP server to 127.0.0.1 on the Mac
point OpenClaw back at the local forwarded port

Example shape:

remote MCP: 192.168.254.20:8124
local forward: 127.0.0.1:18124
OpenClaw MCP URL: http://127.0.0.1:18124/api/mcp

For the actual fix

This is probably issue-worthy now.

Please file it here:
https://github.com/openclaw/openclaw/issues

Include exactly this evidence:

#

openclaw --version → 2026.4.5 (3e72c03)
/status shows Runtime: direct
openclaw config get tools.exec.host → gateway
openclaw sandbox explain --session agent:main:main → mode: off
shell curl from the same Mac reaches 192.168.254.20:8124
agent/mcporter still reports it cannot reach the LAN endpoint

If you want, I can help you write the issue body cleanly so it’s easy for maintainers to reproduce.

rain fern Apr 16, 2026, 6:22 PM

#

please write

mint urchinBOT Apr 16, 2026, 6:22 PM

#

Sure, here’s a clean GitHub issue draft you can paste:

Title
Direct runtime cannot reach LAN MCP endpoint while same host shell can

Body

## Version

OpenClaw 2026.4.5 (3e72c03)

## Summary

On macOS, my OpenClaw agent cannot reach a remote MCP server on LAN, even though the same Mac can reach it from the shell.

The same MCP server works when hosted locally on the gateway machine via `127.0.0.1`, but fails when moved to another LAN host (`192.168.254.20`).

#


## What I expected

OpenClaw direct runtime should be able to reach the MCP endpoint on LAN the same way the host shell can.

## What happens

The agent/mcporter reports that it cannot reach the LAN endpoint.

## Environment / runtime facts

- Session: `agent:main:main`
- Runtime: `direct`
- ACP: not enabled for this session
- `tools.exec.host`: `gateway`

#

- Sandbox mode: `off`

Output:

```text
openclaw config get tools.exec.host
=> gateway

openclaw sandbox explain --session agent:main:main

Effective sandbox:
  runtime: direct
  mode: off
  ...

#


## Host reachability check

From the same Mac host, shell access works:

```bash
curl -v http://192.168.254.20:8124/api/mcp

This reaches the host and returns 401 Unauthorized without auth headers, which is expected for this endpoint and proves basic TCP/network reachability from the host.

Important point

This does not appear to be:

#

- ACP runtime isolation
- CLI backend runtime
- sandbox mode
- `tools.exec.host=sandbox`
- general host LAN connectivity

Those were checked and ruled out.

## Additional notes

- Ollama base URL is **not** `/v1`
- Current model/tool path is believed to be tool-reliable
- Problem reproduces specifically when the MCP server is remote on LAN instead of local loopback

## Question

#


Is there a direct-runtime / mcporter / MCP-client path on macOS that could still block or mis-handle LAN connections even when:

- runtime is direct
- sandbox is off
- exec host is gateway
- host shell can reach the endpoint

If this is expected, is there any config needed for LAN MCP access in direct runtime?

If you want, I can also turn that into a shorter maintainer-friendly version.

bronze kelp Apr 17, 2026, 5:56 PM

#

Have you tried running openclaw onboard with the request going to the lan port? that worked for me

#accessing lan server from agent

Practical options now

For the actual fix

Important point