配置 — MCP、技能和插件

扩展接口：mcp.*、skills.*、plugins.* 和 canvas.*。

完整的键索引以及其他顶级配置域，请参阅配置参考。

MCP¶

OpenClaw 管理的 MCP 服务器定义位于 mcp.servers 下，供嵌入式 OpenClaw 和其他运行时适配器使用。openclaw mcp list、show、set 和 unset 可管理此配置块，而无需连接到服务器。Fetch 示例需要 uv/uvx。

{
  mcp: {
    servers: {
      docs: {
        command: "uvx",
        args: ["mcp-server-fetch"],
      },
      remote: {
        url: "https://example.com/mcp",
        transport: "streamable-http", // streamable-http | sse
        requestTimeoutMs: 20000,
        connectionTimeoutMs: 5000,
        supportsParallelToolCalls: true,
        headers: {
          Authorization: "Bearer ${MCP_REMOTE_TOKEN}",
        },
        auth: "oauth",
        oauth: {
          identity: "per-requester", // shared | per-requester; default: shared
          scope: "docs.read",
        },
        sslVerify: true,
        clientCert: "/path/to/client.crt",
        clientKey: "/path/to/client.key",
        toolFilter: {
          include: ["search_*"],
          exclude: ["admin_*"],
        },
        // Optional Codex app-server projection controls.
        codex: {
          agents: ["main"],
          defaultToolsApprovalMode: "approve", // auto | prompt | approve
        },
      },
    },
  },
}

mcp.servers：面向会暴露已配置 MCP 工具的运行时，提供命名的 stdio 或远程 MCP 服务器定义。远程条目使用 transport: "streamable-http" 或 transport: "sse"；type: "http" 是 CLI 原生别名，openclaw mcp set 和 openclaw doctor --fix 会将其规范化为规范的 transport 字段。
mcp.servers.<name>.enabled：设置为 false 可保留已保存的服务器定义，同时将其排除在嵌入式 OpenClaw MCP 发现和工具投影之外。
mcp.servers.<name>.requestTimeoutMs：每个服务器的 MCP 请求超时时间，单位为毫秒（默认 60 秒）。未设置时，会话开始时的工具列表使用 10 秒。
mcp.servers.<name>.connectionTimeoutMs：每个服务器的连接超时时间，单位为毫秒。
mcp.servers.<name>.supportsParallelToolCalls：可选的并发提示，供可以选择是否发出并行 MCP 工具调用的适配器使用。
mcp.servers.<name>.auth：对于需要 OAuth 的 HTTP MCP 服务器，设置为 "oauth"。运行 openclaw mcp login <name> 可将令牌存储在 OpenClaw 状态中。
mcp.servers.<name>.oauth：可选的 OAuth 作用域、重定向 URL 和客户端元数据 URL 覆盖。
mcp.servers.<name>.oauth.identity：凭据所有权。省略它或设置为 "shared" 表示由操作员管理的凭据；设置为 "per-requester" 可为每个经过身份验证的发送方隔离凭据。按请求方的 OAuth 需要 HTTP 服务器 URL，不能使用 oauth.authProfileId，并且其回调需要 gateway.publicOrigin。
mcp.servers.<name>.sslVerify、clientCert、clientKey：用于私有端点和双向 TLS 的 HTTP TLS 控制。
mcp.servers.<name>.toolFilter：可选的按服务器工具选择。include 将发现的 MCP 工具限制为匹配的名称；exclude 隐藏匹配的名称。条目可以是精确的 MCP 工具名称或简单的 * 通配符。具有资源或提示的服务器还会生成实用工具名称（resources_list、resources_read、prompts_list、prompts_get），这些名称使用相同的过滤器。
mcp.servers.<name>.codex：可选的 Codex app-server 投影控制。此配置块仅作为 Codex app-server 线程的 OpenClaw 元数据；它不会影响 ACP 会话、通用 Codex harness 配置或其他运行时适配器。非空的 codex.agents 会将服务器限制为列出的 OpenClaw agent ID。空的、空白的或无效的限定 agent 列表会被配置验证拒绝，并由运行时投影路径省略，而不是变为全局。 codex.defaultToolsApprovalMode 会为对应服务器输出 Codex 原生的 default_tools_approval_mode。OpenClaw 在向 Codex 传递原生 mcp_servers 配置之前会移除 codex 配置块。省略该配置块可让服务器继续投影给每个 Codex app-server agent，并保持 Codex 默认的 MCP 审批行为。
会话范围的 MCP 运行时会在轮次之间保持存活，包括静默期以及工具返回后的后台服务器工作。会话重置/删除或压缩 ID 轮换、显式 Stop 以及 Gateway 关闭会使它们退役，并终止其拥有的 stdio 子进程。在存活的会话中完成一个轮次不会使其运行时退役。没有存活运行时会话的分离一次性运行拥有其 MCP 生命周期，并在运行结束时使其运行时退役；仅保留的转录记录不会让它们保持存活。
mcp.sessionIdleTtlMs：可选的空闲驱逐时间，单位为毫秒。未设置或 0 会保持上述会话生命周期。正的有限值会启用驱逐；小数部分向下取整。例如，mcp: { sessionIdleTtlMs: 3600000 } 会在未使用一小时后驱逐。启用期间，扫描每分钟运行一次，并保留活动租约和待处理的获取。此覆盖不会将运行拥有的运行时延长到运行结束之后，也不会阻止显式清理。Doctor 会保留此键。如果之前的 doctor --fix 移除了它，请从配置备份中恢复预期值；被删除的值无法推断。
每个 Gateway 最多允许 256 个具有服务器连接的 OpenClaw 管理的 MCP 运行时，跨会话和请求方分区，包括正在创建和清理中的运行时。达到上限时，现有运行时保持存活，新的准入会失败，并记录一条日志消息，提示你停止或重置未使用的会话。一个运行时可以拥有多个已配置的服务器连接。没有可用 MCP 服务器且仅有登录目录的会话不会消耗此限制。原生客户端运行时管理自己的边界。
MCP 配置更改只会使已更改或已移除的服务器连接退役。未更改的服务器保留其传输和工具目录；活动运行可以继续调用它们的工具和资源。下一轮次的发现会根据新配置创建已更改的服务器。插件重新加载也会使被替换插件或其解析器拥有的连接退役。请求方登录工具会在运行时替换后的下一条消息上刷新。
运行时发现还会通过丢弃受影响服务器的缓存目录来遵循 MCP 工具列表变更通知。提供资源或提示的服务器会获得用于列出/读取资源以及列出/获取提示的实用工具。重复的工具调用失败会短暂暂停受影响的服务器，然后再尝试下一次调用。

有关运行时行为，请参阅 MCP 和 CLI 后端。

技能¶

{
  skills: {
    allowBundled: ["gemini", "peekaboo"],
    load: {
      extraDirs: ["~/path/to/agent-scripts/skills"],
      allowSymlinkTargets: ["~/path/to/skills"],
    },
    install: {
      preferBrew: true,
      nodeManager: "npm", // npm | pnpm | yarn | bun
      allowUploadedArchives: false,
    },
    entries: {
      "image-lab": {
        apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" }, // or plaintext string
        env: { GEMINI_API_KEY: "GEMINI_KEY_HERE" },
      },
      peekaboo: { enabled: true },
      sag: { enabled: false },
    },
  },
}

allowBundled：仅针对捆绑技能的可选允许列表（不影响受管/工作区技能）。
load.extraDirs：额外的共享技能根目录（优先级最低）。
load.allowSymlinkTargets：当符号链接位于其配置的源根目录之外时，技能符号链接可以解析到的受信任真实目标根目录。
install.preferBrew：为 true 时，在 brew 可用时优先使用 Homebrew 安装器，然后再回退到其他安装器类型。
install.nodeManager：metadata.openclaw.install 规范中的 Node 安装器偏好（npm | pnpm | yarn | bun）。
install.allowUploadedArchives：允许受信任的 operator.admin Gateway 客户端安装通过 skills.upload.* 暂存的私有 zip 归档（默认：false）。这仅启用已上传归档路径；常规 ClawHub 安装不需要它。
entries.<skillKey>.enabled: false 会禁用某个技能，即使它是捆绑的或已安装的。
entries.<skillKey>.apiKey：为声明主要环境变量（明文字符串或 SecretRef 对象）的技能提供便捷配置。
limits.maxCandidatesPerRoot、limits.maxSkillsLoadedPerSource、limits.maxSkillsInPrompt、limits.maxSkillsPromptChars、limits.maxSkillFileBytes：限制技能发现以及面向模型的技能提示。
Skill Workshop 自主/审批设置（workshop.autonomous.mode、workshop.approvalPolicy、workshop.maxPending、workshop.maxSkillBytes）记录在技能配置中。

插件¶

{
  plugins: {
    enabled: true,
    allow: ["voice-call"],
    deny: [],
    load: {
      paths: ["~/path/to/oss/voice-call-plugin"],
    },
    entries: {
      "voice-call": {
        enabled: true,
        hooks: {
          allowPromptInjection: false,
        },
        config: { provider: "twilio" },
      },
    },
  },
}

从 ~/.openclaw/extensions 和 <workspace>/.openclaw/extensions 下的包或捆绑目录加载，外加 plugins.load.paths 中列出的文件或目录。
将独立插件文件放在 plugins.load.paths 中；自动发现的扩展根目录会忽略顶层 .js、.mjs 和 .ts 文件，因此这些根目录中的辅助脚本不会阻止启动。
发现机制接受原生 OpenClaw 插件，以及兼容的 Codex 捆绑包和 Claude 捆绑包，包括无清单的 Claude 默认布局捆绑包。
在默认的混合重载模式下，常规插件策略、条目和发现路径更改会热重载插件运行时。条目配置更改会替换受影响的实例。在编辑源代码或清单后，请使用 openclaw plugins reload <id>；活动插件仍可以声明会触发重启的配置前缀。请参阅应用更改并检查。
allow：可选允许列表（仅加载列出的插件）。deny 优先。
plugins.entries.<id>.apiKey：插件级 API 密钥便捷字段（如果插件支持）。
plugins.entries.<id>.env：插件作用域的环境变量映射。
plugins.entries.<id>.hooks.allowPromptInjection：为 false 时，核心会阻止修改提示的钩子，例如 before_prompt_build。适用于原生插件钩子以及受支持的捆绑包提供的钩子目录。
plugins.entries.<id>.hooks.allowConversationAccess：为 true 时，受信任的非捆绑插件可以从类型化钩子（例如 before_model_resolve、agent_turn_prepare、before_prompt_build、before_agent_reply、llm_input、llm_output、before_agent_run、before_agent_finalize 和 agent_end）读取原始会话内容。它还会授予有界、调用作用域的 session_end 已结束转录读取器；仅元数据的 session_end 处理器无需该授权即可继续注册。
plugins.entries.<id>.subagent.allowModelOverride：明确信任此插件为后台子代理运行请求每次运行的 provider 和 model 覆盖。
plugins.entries.<id>.subagent.allowedModels：受信任子代理覆盖的规范 provider/model 目标可选允许列表。仅当你有意允许任意模型时，才使用 "*"。
plugins.entries.<id>.llm.allowModelOverride：明确信任此插件为 api.runtime.llm.complete 请求模型覆盖。
plugins.entries.<id>.llm.allowedModels：受信任模型覆盖的规范 provider/model 目标可选允许列表。仅当你有意允许任意模型覆盖时，才使用 "*"。
plugins.entries.<id>.llm.allowedCompletionModels：应用于每个插件 LLM 补全的可选允许列表，包括主机解析的默认值和覆盖值。仅当你有意允许任意模型时，才使用 "*"。
plugins.entries.<id>.llm.allowAuthProfileOverride：明确信任此插件为隔离的 api.runtime.llm.complete 执行选择非默认身份验证配置文件。直接的 model@profile 调用仍受模型覆盖策略约束。
plugins.entries.<id>.llm.allowAgentIdOverride：明确信任此插件针对非默认代理 ID 运行 api.runtime.llm.complete。
plugins.entries.<id>.config：插件定义的配置对象（在可用时由原生 OpenClaw 插件模式验证）。
通道插件的账户/运行时设置位于 channels.<id> 下，并应由所属插件清单中的 channelConfigs 元数据描述，而不是由中央 OpenClaw 选项注册表描述。

Codex harness 插件配置¶

捆绑的 codex 插件管理位于 plugins.entries.codex.config 下的原生 Codex app-server harness 设置。有关完整配置范围，请参阅 Codex harness 参考；有关运行时模型，请参阅 Codex harness。

codexPlugins 仅适用于选择原生 Codex harness 的会话。它不会为 OpenClaw 提供商运行、ACP 会话绑定或任何非 Codex harness 启用 Codex 插件。

{
  plugins: {
    entries: {
      codex: {
        enabled: true,
        config: {
          codexPlugins: {
            enabled: true,
            allow_all_plugins: true,
            allow_destructive_actions: "auto",
            plugins: {
              "google-calendar": {
                enabled: true,
                marketplaceName: "openai-curated",
                pluginName: "google-calendar",
                allow_destructive_actions: false,
              },
            },
          },
        },
      },
    },
  },
}

plugins.entries.codex.config.codexPlugins.enabled：为 Codex harness 启用原生 Codex 插件/应用支持。默认值：false。
plugins.entries.codex.config.codexPlugins.allow_all_plugins：在每个新的原生 Codex 线程中，公开当前可访问的、已连接到经过身份验证的 Codex 账户的所有应用。默认值：false。
plugins.entries.codex.config.codexPlugins.allow_destructive_actions：为已配置的插件应用 elicitation（征询）设置默认破坏性操作策略。使用 true 可在不提示的情况下接受安全的 Codex 审批模式，使用 false 可拒绝它们，使用 "auto" 可将 Codex 必需的审批路由到 OpenClaw 插件审批，或使用 "ask" 对每个插件写入/破坏性操作进行提示，而不使用持久审批。 "ask" 模式会在 Codex 线程启动前，清除受影响应用的持久 Codex 按工具审批覆盖，并为该应用选择人工审批审核员。默认值：true。
plugins.entries.codex.config.codexPlugins.plugins.<key>.enabled：当全局 codexPlugins.enabled 也为 true 时，启用已配置的插件条目。显式条目的默认值为 true。
plugins.entries.codex.config.codexPlugins.plugins.<key>.marketplaceName：稳定的市场标识，对于每个已解析条目，必须与 pluginName 一起提供。支持 Codex 已可发现的任何有效市场，包括 "openai-curated"、"openai-bundled"、 "openai-primary-runtime"、"workspace-directory" 以及仓库本地市场标识。缺少任一标识字段的条目将被忽略。
plugins.entries.codex.config.codexPlugins.plugins.<key>.pluginName：稳定的 Codex 插件标识，必须与 marketplaceName 一起提供。对于插件标识符带有市场限定符的市场，请使用 Codex 报告的精确标识。 /codex plugins available 会列出可发现的标识，所有者或 operator.admin 可以使用 /codex plugins install <plugin>@<marketplace> 安装其中一个。
plugins.entries.codex.config.codexPlugins.plugins.<key>.allow_destructive_actions：按插件的破坏性操作覆盖。省略时，使用全局 allow_destructive_actions 值。按插件值接受相同的 true、false、"auto" 或 "ask" 策略。

每个使用 "ask" 的已准入插件应用都会将该应用的审批请求路由到人工审核员。其他应用和非应用线程审批会保留其已配置的审核员，因此混合插件策略不会继承 "ask" 行为。

codexPlugins.enabled 是全局启用指令。迁移写入的显式插件条目会保留持久的精选安装和修复资格。所有者或 operator.admin 可以使用 /codex plugins install <plugin>@<marketplace> 添加其他已发现的插件；Codex 仍然控制上游安装和连接器身份验证。缺少精确标识、安装或可访问应用所有权的插件会失败关闭。plugins["*"] 不受支持，本地 marketplacePath 值有意不作为配置字段，因为它们是主机特定的。有关 app-server 版本和就绪要求，请参阅原生 Codex 插件。

app/installed 就绪检查（带有来自批量 app/read 的授权元数据）会缓存一小时，并在过期时异步刷新。Codex 线程应用配置在 Codex harness 会话建立时计算，而不是在每一轮计算；更改原生插件配置后，请使用 /new、/reset 或重启网关。

codexPlugins.allow_all_plugins 会将当前每个可访问的账户应用快照到每个新的原生 Codex 线程。它不会安装插件或应用，且不可访问的应用仍会被排除。账户应用使用全局 codexPlugins.allow_destructive_actions 策略。当同一应用同时存在于两条路径中时，显式插件条目优先。如果 app/installed 无法读取，则整个账户的公开范围会失败关闭。

plugins.entries.firecrawl.config.webFetch：Firecrawl 网页抓取提供商设置。
apiKey：可选的 Firecrawl API 密钥，用于更高限制（接受 SecretRef）。回退到 plugins.entries.firecrawl.config.webSearch.apiKey 或 FIRECRAWL_API_KEY 环境变量。
baseUrl：Firecrawl API 基础 URL（默认：https://api.firecrawl.dev；自托管覆盖必须指向私有/内部端点）。
onlyMainContent：仅从页面提取主要内容（默认：true）。
maxAgeMs：最大缓存时长（毫秒）（默认：172800000 / 2 天）。
timeoutSeconds：抓取请求超时时间（秒）（默认：60）。
plugins.entries.xai.config.xSearch：xAI X Search（Grok 网页搜索）设置。
enabled：启用 X Search 提供商。
model：用于搜索的 Grok 模型（例如 "grok-4.3"）。
plugins.entries.memory-core.config.dreaming：记忆 dreaming 设置。有关阶段和阈值，请参阅 Dreaming。
enabled：dreaming 主开关（默认 false）。
frequency：每次完整 dreaming 扫描的 cron 周期（默认为 "0 3 * * *"）。
model：可选的 Dream Diary 子代理模型覆盖。需要 plugins.entries.memory-core.subagent.allowModelOverride: true；与 allowedModels 搭配使用以限制目标。模型不可用错误会使用会话默认模型重试一次；信任或允许列表失败不会静默回退。
阶段策略和阈值是实现细节（不是面向用户的配置键）。
完整的记忆配置位于记忆配置参考：
memory.search.*
agents.entries.*.memory.search.* 用于按代理覆盖
memory.citations
plugins.entries.memory-core.config.dreaming
已启用的 Claude 捆绑插件也可以从 settings.json 提供嵌入的 OpenClaw 默认值；OpenClaw 会将其作为已净化的代理设置应用，而不是作为原始 OpenClaw 配置补丁。
plugins.slots.memory：选择活动的记忆插件 id，或使用 "none" 禁用记忆插件。
plugins.slots.contextEngine：选择活动的上下文引擎插件 id；除非你安装并选择另一个引擎，否则默认为 "legacy"。

参见插件。

{
  plugins: {
    entries: {
      canvas: {
        config: {
          host: {
            enabled: true, // set false, or use OPENCLAW_SKIP_CANVAS_HOST=1
          },
        },
      },
    },
  },
}

host.enabled 是唯一的 Canvas 主机开关，默认启用。它控制 /__openclaw__/canvas/ 下的托管小部件文档以及 /__openclaw__/a2ui/ 下的 A2UI 渲染器资源。
仅本地：保持 gateway.bind: "loopback"（默认）。
非 loopback 绑定：这些路由需要 Gateway 身份验证（token/password/trusted-proxy），与其他 Gateway HTTP 表面相同。
Node WebView 通常不会发送身份验证头；在 macOS 节点完成配对并连接后，Gateway 会通告一个节点范围的 pluginSurfaceUrls.canvas 能力 URL。
能力 URL 绑定到当前活动的节点 WS 会话，并会很快过期。不会使用基于 IP 的回退。
host.enabled 在默认混合重载模式下通过 Canvas 插件热生效。OPENCLAW_SKIP_CANVAS_HOST 环境变量覆盖仍需要重启 Gateway。

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 cl/openclaw

配置 — MCP、技能和插件

MCP¶

技能¶

插件¶

Codex harness 插件配置¶

Canvas 小部件展示器¶