@@ -20,6 +20,23 @@ In other words:
20202121Use [`openclaw acp`](/cli/acp) when OpenClaw should host a coding harness session itself and route that runtime through ACP.
222223+## Choose the right MCP path
24+25+OpenClaw has several MCP surfaces. Pick the one that matches who owns the agent runtime and who owns the tools.
26+27+| Goal | Use | Why |
28+| ------------------------------------------------------------------- | -------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
29+| Let an external MCP client read/send OpenClaw channel conversations | `openclaw mcp serve` | OpenClaw is the MCP server and exposes Gateway-backed conversations over stdio. |
30+| Save third-party MCP servers for OpenClaw-managed agent runs | `openclaw mcp add`, `set`, `configure`, `tools`, `login` | OpenClaw is the MCP client-side registry and later projects those servers into eligible runtimes. |
31+| Check a saved server without running an agent turn | `openclaw mcp status`, `doctor`, `probe` | `status` and `doctor` inspect config; `probe` opens a live MCP connection and lists capabilities. |
32+| Edit MCP config from a browser | Control UI `/mcp` | The page shows inventory, enablement, OAuth/filter summaries, command hints, and a scoped `mcp` editor. |
33+| Give Codex app-server a scoped native MCP server | `mcp.servers.<name>.codex` | The `codex` block only affects Codex app-server thread projection and is stripped before native config handoff. |
34+| Run ACP-hosted harness sessions | [`openclaw acp`](/cli/acp) and [ACP Agents](/tools/acp-agents-setup) | ACP bridge mode does not accept per-session MCP server injection; configure gateway/plugin bridges instead. |
35+36+<Tip>
37+If you are not sure which path you need, start with `openclaw mcp status --verbose`. It shows what OpenClaw has saved without starting any MCP servers.
38+</Tip>
39+2340## OpenClaw as an MCP server
24412542This is the `openclaw mcp serve` path.
@@ -449,6 +466,166 @@ openclaw mcp logout docs
449466openclaw mcp unset context7
450467```
451468469+### Common server recipes
470+471+These examples save server definitions only. Run `openclaw mcp doctor --probe` afterward to prove that the server starts and exposes tools.
472+473+<Tabs>
474+ <Tab title="Filesystem">
475+```bash
476+openclaw mcp add files \
477+ --command npx \
478+ --arg -y \
479+ --arg @modelcontextprotocol/server-filesystem \
480+ --arg "$HOME/Documents" \
481+ --include 'read_file,list_directory,search_files'
482+openclaw mcp doctor files --probe
483+```
484+485+Scope filesystem servers to the smallest directory tree that the agent should read or edit.
486+487+ </Tab>
488+ <Tab title="Memory">
489+```bash
490+openclaw mcp add memory \
491+ --command npx \
492+ --arg -y \
493+ --arg @modelcontextprotocol/server-memory
494+openclaw mcp probe memory --json
495+```
496+497+Use a tool filter if the server exposes write tools that should not be available to normal agents.
498+499+ </Tab>
500+ <Tab title="Local script">
501+```bash
502+openclaw mcp add local-tools \
503+ --command node \
504+ --arg ./dist/mcp-server.js \
505+ --cwd /srv/openclaw-tools \
506+ --env API_BASE=https://internal.example
507+openclaw mcp status --verbose
508+```
509+510+`doctor` checks that `cwd` exists and that the command resolves from the configured environment.
511+512+ </Tab>
513+ <Tab title="Remote HTTP">
514+```bash
515+openclaw mcp add docs \
516+ --url https://mcp.example.com/mcp \
517+ --transport streamable-http \
518+ --auth oauth \
519+ --oauth-scope docs.read \
520+ --timeout 20 \
521+ --connect-timeout 5 \
522+ --include 'search,read_*'
523+openclaw mcp doctor docs --probe
524+```
525+526+Use OAuth when the remote server supports it. If the server requires static headers, avoid committing literal bearer tokens.
527+528+ </Tab>
529+ <Tab title="Desktop/CUA">
530+```bash
531+openclaw mcp set cua-driver '{"command":"cua-driver","args":["mcp"]}'
532+openclaw mcp tools cua-driver --include 'list_apps,observe,click,type'
533+openclaw mcp doctor cua-driver --probe
534+```
535+536+Direct desktop-control servers inherit the permissions of the process they launch. Use narrow tool filters and OS-level permission prompts.
537+538+ </Tab>
539+</Tabs>
540+541+### JSON output shapes
542+543+Use `--json` for scripts and dashboards. Field sets can grow over time, so consumers should ignore unknown keys.
544+545+<AccordionGroup>
546+ <Accordion title="status --json">
547+```json
548+{
549+ "path": "/home/user/.openclaw/openclaw.json",
550+ "servers": [
551+ {
552+ "name": "docs",
553+ "configured": true,
554+ "enabled": true,
555+ "ok": true,
556+ "transport": "streamable-http",
557+ "launch": "streamable-http https://mcp.example.com/mcp",
558+ "auth": "oauth",
559+ "authStatus": {
560+ "hasTokens": true,
561+ "hasClientInformation": true,
562+ "hasCodeVerifier": false,
563+ "hasDiscoveryState": true,
564+ "hasLastAuthorizationUrl": false
565+ },
566+ "requestTimeoutMs": 20000,
567+ "connectionTimeoutMs": 5000,
568+ "toolFilter": {
569+ "include": ["search", "read_*"],
570+ "exclude": []
571+ },
572+ "supportsParallelToolCalls": true
573+ }
574+ ]
575+}
576+```
577+ </Accordion>
578+ <Accordion title="doctor --json">
579+```json
580+{
581+ "ok": false,
582+ "path": "/home/user/.openclaw/openclaw.json",
583+ "servers": [
584+ {
585+ "name": "docs",
586+ "ok": false,
587+ "issues": [
588+ {
589+ "level": "error",
590+ "message": "OAuth credentials are not authorized; run openclaw mcp login docs"
591+ }
592+ ]
593+ }
594+ ]
595+}
596+```
597+598+`doctor --json` exits nonzero when any enabled checked server has an error. Warnings are reported but do not make the command fail by themselves.
599+600+ </Accordion>
601+ <Accordion title="probe --json">
602+```json
603+{
604+ "path": "/home/user/.openclaw/openclaw.json",
605+ "generatedAt": "2026-05-31T09:00:00.000Z",
606+ "servers": {
607+ "docs": {
608+ "launch": "streamable-http https://mcp.example.com/mcp",
609+ "tools": 2,
610+ "resources": true,
611+ "prompts": false,
612+ "listChanged": {
613+ "tools": true,
614+ "resources": false,
615+ "prompts": false
616+ }
617+ }
618+ },
619+ "tools": ["docs__read_page", "docs__search"],
620+ "diagnostics": []
621+}
622+```
623+624+`probe` opens a live MCP client session. Use it for reachability and capability proof, not for static config audits.
625+626+ </Accordion>
627+</AccordionGroup>
628+452629Example config shape:
453630454631```json
@@ -538,6 +715,58 @@ Example:
538715539716Sensitive values in `url` (userinfo) and `headers` are redacted in logs and status output. `openclaw mcp doctor` warns when sensitive-looking `headers` or `env` entries contain literal values, so operators can move those values out of committed config.
540717718+### OAuth workflow
719+720+OAuth is for HTTP MCP servers that advertise the MCP OAuth flow. Static `Authorization` headers are ignored for a server while `auth: "oauth"` is enabled.
721+722+<Steps>
723+ <Step title="Save the server">
724+Add or update the server with `auth: "oauth"` and any optional OAuth metadata.
725+726+```bash
727+openclaw mcp set docs '{"url":"https://mcp.example.com/mcp","transport":"streamable-http","auth":"oauth","oauth":{"scope":"docs.read"}}'
728+```
729+730+ </Step>
731+ <Step title="Start login">
732+Run login to create the authorization request.
733+734+```bash
735+openclaw mcp login docs
736+```
737+738+OpenClaw prints the authorization URL and stores temporary OAuth verifier state under the OpenClaw state directory.
739+740+ </Step>
741+ <Step title="Finish with the code">
742+After approving in the browser, pass the returned code back to OpenClaw.
743+744+```bash
745+openclaw mcp login docs --code abc123
746+```
747+748+ </Step>
749+ <Step title="Check authorization">
750+Use status or doctor to confirm that tokens are present.
751+752+```bash
753+openclaw mcp status --verbose
754+openclaw mcp doctor docs --probe
755+```
756+757+ </Step>
758+ <Step title="Clear credentials">
759+Logout removes stored OAuth credentials but keeps the saved server definition.
760+761+```bash
762+openclaw mcp logout docs
763+```
764+765+ </Step>
766+</Steps>
767+768+If the provider rotates tokens or the authorization state gets stuck, run `openclaw mcp logout <name>`, then repeat `login`. `logout` can clear credentials for a saved HTTP server even after `auth: "oauth"` has been removed from config, as long as the server name and URL still identify the credential store entry.
769+541770### Streamable HTTP transport
542771543772`streamable-http` is an additional transport option alongside `sse` and `stdio`. It uses HTTP streaming for bidirectional communication with remote MCP servers.
@@ -587,6 +816,23 @@ The browser Control UI includes a dedicated MCP settings page at `/mcp`. It show
587816588817Use the page for operator edits and quick inventory. Use `openclaw mcp doctor --probe` or `openclaw mcp probe` when you need live server proof.
589818819+Operator workflow:
820+821+1. Open the Control UI and choose **MCP**.
822+2. Review the summary cards for total, enabled, OAuth, and filtered servers.
823+3. Use each server row for transport, auth, filter, timeout, and command hints.
824+4. Toggle enablement when you want to keep a definition but exclude it from runtime discovery.
825+5. Edit the scoped `mcp` config section for structural changes such as new servers, headers, TLS, OAuth metadata, or tool filters.
826+6. Choose **Save** to persist config only, or **Save & Publish** to apply through the Gateway config path.
827+7. Run `openclaw mcp doctor --probe` when you need live proof that the edited server starts and lists tools.
828+829+Notes:
830+831+- command snippets quote server names so unusual names remain copyable in a shell
832+- displayed URL-like values are redacted before rendering when they contain embedded credentials
833+- the page does not start MCP transports by itself
834+- active runtimes may need `openclaw mcp reload`, Gateway config publish, or process restart depending on which process owns the MCP clients
835+590836## Current limits
591837592838This page documents the bridge as shipped today.
此内容由惯性聚合(RSS阅读器)自动聚合整理，仅供阅读参考。 原文来自 — 版权归原作者所有。