# Connect OpenClaw to Coconut

Use these instructions when the user requests this connection.

## Before configuration

Check the installed OpenClaw version and command help. Preserve existing server entries. Inspect the current Coconut entry before adding or replacing it. Stop if the installed host lacks native HTTP MCP OAuth support.

## Configure the connection

Merge configuration examples into the existing file. Do not replace the complete file. Do not add an Authorization header for native OAuth. Coconut uses the mcp_access scope, PKCE S256, and dynamic client registration.

Register Coconut:

```bash
openclaw mcp set coconut '{"url":"https://coconutapp.xyz/api/mcp","transport":"streamable-http","requestTimeoutMs":300000,"auth":"oauth","oauth":{"scope":"mcp_access"}}'
```

## Sign in and choose access

Run `openclaw mcp login coconut`. Complete browser consent. This setup uses the gateway operator connection. Review who can use that gateway before granting access.

Let the human sign in and choose the workspace, brand, and access level. Never request credentials in chat. Never approve consent for the human. Keep tokens and callback URLs out of prompts, command arguments, and logs.

For a remote host, confirm that the browser can reach its callback listener. Use the host's documented secure forwarding method. If that path is unavailable, stop and report the missing requirement. Do not submit a callback code through a command argument. Coconut does not provide device authorization.

For a local development server on another machine, check the configured app origin in the actual consent browser. Forward the same laptop and server port. Check the sign-in redirect and consent page before starting login. Server health alone does not prove browser access. The OAuth callback listener can require a separate forward.

## Check the tools

Run `openclaw mcp doctor coconut --probe`. Then ask the agent to discover Coconut tools and call `workspace_get` with `{}`. Registry status alone does not prove runtime access.

Check the returned Workspace, Brand, capabilities, and expiry. Report the discovered tool names. The default profile contains 47 business tools plus two connection and evidence helpers. Discovery can return a smaller grant. Do not enable feature flags or widen access to obtain missing tools.

Report any failure with the failing step and safe error code. Do not claim a working connection from registration or a tool count. Wait for the user's requested workflow before changing Coconut data. After an unknown mutation result, read current state and operation_receipts before retrying.

A rejected request includes a safe code, an explanation, and a recovery instruction. For INPUT_INVALID, read invalidFields and the discovered input schema. Correct the fields before another request. Do not repeat the same invalid input. Stop automatic retries after scope or credential rejection. A recovery instruction does not expand the grant or authorize another mutation.

For EXTERNAL_LIMIT_EXCEEDED, read limit.bucketKind, limit.used, limit.limit and limit.resetAt. Wait retryAfterSeconds, then send the same request with the same idempotency key. Only writes count: reads never use this budget. Each credential and client may make 250 writes per UTC hour. Agents for the same actor and Workspace share 500 writes per UTC hour. The Workspace shares 1,000 writes per UTC hour. Completed idempotent replays do not count again. Another connection does not reset shared limits.

## Check unattended access

A first successful read proves that connection only. Before unattended use, repeat the read after the access token expires. Start a new process with the same profile. Check the Workspace, Brand, credential, capabilities, and a second read. Let the client refresh its own tokens. Never copy or edit tokens to run this check.

Use a separate grant and separate token storage for each agent installation. Two agents can select the same Workspace and Brand. Workers with shared token storage must coordinate refresh across processes. Copying one token file to another host can cause refresh replay and revoke that grant.

Record the client version, SDK version when available, server release, UTC time, failing step, safe OAuth error, and request ID. Keep authorization URLs, callback URLs, headers, tokens, and token hashes out of the report. A refresh rejection occurs before a tool call and needs separate evidence.

Recheck this lifecycle after an OAuth, grant, SDK, installer, token-storage, or host-configuration change. Documentation describes the connection method. It does not establish native acceptance for an untested client version.

## References

- OpenClaw: https://docs.openclaw.ai/cli/mcp/transports
- Coconut tool reference: https://coconutapp.xyz/docs/mcp-tools/overview
- Coconut access controls: https://coconutapp.xyz/docs/mcp-tools/governance
- Detailed host guide: https://coconutapp.xyz/docs/agent-setup/openclaw