[OpenClaw 文档]工具--技能

本文档汇总了 OpenClaw 官方文档站 工具 > 技能 子模块下的全部 5 篇内容，源自 docs.openclaw.ai/zh-CN。

📄 创建技能

原文：https://docs.openclaw.ai/zh-CN/tools/creating-skills

Skills 教会智能体如何以及何时使用工具。每个技能都是一个目录，
其中包含一个带有 YAML frontmatter 和 Markdown 指令的 SKILL.md 文件。

有关 Skills 如何加载和优先排序，请参阅 Skills。

创建你的第一个技能

Skills 位于你的工作区中。创建一个新文件夹：

```bash
mkdir -p ~/.openclaw/workspace/skills/hello-world
```

在该目录中创建 SKILL.md。frontmatter 定义元数据，
Markdown 正文包含给智能体的指令。

```markdown
---
name: hello-world
description: A simple skill that says hello.
---

# Hello World Skill

When the user asks for a greeting, use the `echo` tool to say
"Hello from your custom skill!".
```

技能 `name` 使用由小写字母、数字和连字符组成的连字符命名法。
保持文件夹名称与 frontmatter `name` 一致。

你可以在 frontmatter 中定义自定义工具 schema，或指示智能体
使用现有系统工具（例如 exec 或 browser）。Skills 也可以
随插件一起提供，并与它们所记录的工具放在一起。

启动一个新会话，让 OpenClaw 载入该技能：

```bash
# From chat
/new

# Or restart the gateway
openclaw gateway restart
```

验证该技能已加载：

```bash
openclaw skills list
```

发送一条应该触发该技能的消息：

```bash
openclaw agent --message "give me a greeting"
```

或者直接与智能体聊天并请求问候语。

技能元数据参考

YAML frontmatter 支持这些字段：

最佳实践

• 保持简洁 —— 指示模型要做_什么_，而不是如何成为 AI
• 安全优先 —— 如果你的技能使用 exec，请确保提示不会允许来自不受信任输入的任意命令注入
• 本地测试 —— 分享前使用 openclaw agent --message "..." 进行测试
• 使用 ClawHub —— 在 ClawHub 浏览和贡献技能

Skills 存放位置

相关

• Skills 参考 —— 加载、优先级和门控规则
• Skills 配置 —— skills.* 配置 schema
• ClawHub —— 公共技能注册表
• 构建插件 —— 插件可以随附 Skills

📄 斜杠命令

原文：https://docs.openclaw.ai/zh-CN/tools/slash-commands

命令由 Gateway 网关处理。大多数命令必须作为以 / 开头的独立消息发送。仅主机 bash 聊天命令使用 ! <cmd>（/bash <cmd> 是别名）。

当某个对话或线程绑定到 ACP 会话时，普通后续文本会路由到该 ACP harness。Gateway 网关管理命令仍保持本地处理：/acp ... 始终到达 OpenClaw ACP 命令处理器，而只要该表面的命令处理已启用，/status 加 /unfocus 就会保持本地处理。

有两个相关系统：

独立的 /... 消息。


/think、/fast、/verbose、/trace、/reasoning、/elevated、/exec、/model、/queue。

- 指令会在模型看到消息之前从消息中移除。
- 在普通聊天消息中（不是仅含指令的消息），它们会被视为“行内提示”，并且**不会**持久化会话设置。
- 在仅含指令的消息中（消息只包含指令），它们会持久化到会话，并回复确认。
- 指令只会应用于**已授权发送者**。如果设置了 `commands.allowFrom`，它就是唯一使用的允许列表；否则授权来自渠道允许列表/配对加上 `commands.useAccessGroups`。未授权发送者的指令会被当作纯文本处理。

仅限允许列表内/已授权发送者：/help、/commands、/status、/whoami（/id）。

它们会立即运行，在模型看到消息之前被移除，剩余文本会继续经过正常流程。

配置

{
  commands: {
    native: "auto",
    nativeSkills: "auto",
    text: true,
    bash: false,
    bashForegroundMs: 2000,
    config: false,
    mcp: false,
    plugins: false,
    debug: false,
    restart: true,
    ownerAllowFrom: ["discord:123456789012345678"],
    ownerDisplay: "raw",
    ownerDisplaySecret: "${OWNER_ID_HASH_SECRET}",
    allowFrom: {
      "*": ["user1"],
      discord: ["user:123"],
    },
    useAccessGroups: true,
  },
}

启用聊天消息中的 /... 解析。在没有原生命令的表面（WhatsApp/WebChat/Signal/iMessage/Google Chat/Microsoft Teams）上，即使你将它设为 false，文本命令仍然可用。


注册原生命令。Auto：对 Discord/Telegram 启用；对 Slack 关闭（直到你添加斜杠命令）；对没有原生支持的提供商忽略。设置 channels.discord.commands.native、channels.telegram.commands.native 或 channels.slack.commands.native 可按提供商覆盖（布尔值或 "auto"）。在 Discord 上，false 会在启动期间跳过斜杠命令注册和清理；之前注册的命令可能会保持可见，直到你从 Discord 应用中移除它们。Slack 命令在 Slack 应用中管理，不会自动移除。

在 Discord 上，原生命令规范可以包含 descriptionLocalizations，OpenClaw 会将其作为 Discord description_localizations 发布，并纳入调和比较。

在受支持时以原生方式注册 skill 命令。Auto：对 Discord/Telegram 启用；对 Slack 关闭（Slack 要求为每个 skill 创建一个斜杠命令）。设置 channels.discord.commands.nativeSkills、channels.telegram.commands.nativeSkills 或 channels.slack.commands.nativeSkills 可按提供商覆盖（布尔值或 "auto"）。


启用 ! <cmd> 来运行主机 shell 命令（/bash <cmd> 是别名；需要 tools.elevated 允许列表）。


控制 bash 在切换到后台模式前等待多长时间（0 会立即转入后台）。


启用 /config（读取/写入 openclaw.json）。


启用 /mcp（读取/写入 mcp.servers 下由 OpenClaw 管理的 MCP 配置）。


启用 /plugins（插件发现/状态以及安装 + 启用/禁用控制）。


启用 /debug（仅运行时覆盖）。


启用 /restart 以及 Gateway 网关重启工具动作。


设置仅限所有者命令/工具表面的显式所有者允许列表。这是可以批准危险操作并运行 /diagnostics、/export-trajectory 和 /config 等命令的人类操作员账户。它独立于 commands.allowFrom，也独立于私信配对访问。


按渠道设置：使仅限所有者的命令需要所有者身份才能在该表面运行。当为 true 时，发送者必须匹配已解析的所有者候选项（例如 commands.ownerAllowFrom 中的条目或提供商原生所有者元数据），或者在内部消息渠道上拥有内部 operator.admin scope。渠道 allowFrom 中的通配符条目，或空的/未解析的所有者候选列表，不足以满足要求：仅限所有者命令会在该渠道上失败关闭。如果你希望仅限所有者命令只由 ownerAllowFrom 和标准命令允许列表限制，请保持关闭。


控制所有者 id 在系统提示中的显示方式。


可选设置当 commands.ownerDisplay="hash" 时使用的 HMAC 密钥。


用于命令授权的按提供商允许列表。配置后，它就是命令和指令的唯一授权来源（渠道允许列表/配对和 commands.useAccessGroups 会被忽略）。使用 "*" 作为全局默认值；提供商特定键会覆盖它。


当未设置 commands.allowFrom 时，对命令强制执行允许列表/策略。

命令列表

当前事实来源：

• 核心内置项来自 src/auto-reply/commands-registry.shared.ts
• 生成的 dock 命令来自 src/auto-reply/commands-registry.data.ts
• 插件命令来自插件 registerCommand() 调用
• 你的 Gateway 网关上的实际可用性仍取决于配置标志、渠道表面，以及已安装/已启用的插件

核心内置命令

- /new [model] 启动新会话；/reset 是重置别名。
- Control UI 会拦截输入的 /new，创建并切换到新的仪表盘会话，除非配置了 session.dmScope: "main" 且当前父级是智能体的主会话；在这种情况下，/new 会就地重置主会话。输入的 /reset 仍会运行 Gateway 网关的就地重置。
- /reset soft [message] 保留当前转录，丢弃复用的 CLI 后端会话 id，并就地重新运行启动/系统提示加载。
- /compact [instructions] 压缩会话上下文。参见 压缩。
- /stop 中止当前运行。
- /session idle <duration|off> 和 /session max-age <duration|off> 管理线程绑定过期时间。
- /export-session [path] 将当前会话导出为 HTML。别名：/export。
- /export-trajectory [path] 请求 exec 批准，然后为当前会话导出 JSONL 轨迹包。当你需要一个 OpenClaw 会话的提示、工具和转录时间线时使用它。在群聊中，批准提示和导出结果会私下发送给所有者。别名：/trajectory。

- /think <level|default> 设置思考级别或清除会话覆盖。选项来自活跃模型的提供商配置文件；常见级别包括 off、minimal、low、medium 和 high，而 xhigh、adaptive、max 等自定义级别，或二元 on 仅在受支持时可用。别名：/thinking、/t。
- /verbose on|off|full 切换详细输出。别名：/v。
- /trace on|off 切换当前会话的插件 trace 输出。
- /fast [status|on|off|default] 显示、设置或清除快速模式。
- /reasoning [on|off|stream] 切换推理可见性。别名：/reason。
- /elevated [on|off|ask|full] 切换提升模式。别名：/elev。
- /exec host=<auto|sandbox|gateway|node> security=<deny|allowlist|full> ask=<off|on-miss|always> node=<id> 显示或设置 exec 默认值。
- /model [name|#|status] 显示或设置模型。
- /models [provider] [page] [limit=<n>|size=<n>|all] 列出已配置/认证可用的提供商，或列出某个提供商的模型；添加 all 可浏览该提供商的完整目录。agents.defaults.models 中的 provider/* 条目会让 /model 和 /models 仅显示这些提供商的已发现模型。
- /queue <mode> 管理队列行为（steer、旧版 queue、followup、collect、steer-backlog、interrupt）以及 debounce:0.5s cap:25 drop:summarize 等选项；/queue default 或 /queue reset 会清除会话覆盖。参见 命令队列 和 Steering queue。
- /steer <message> 将引导注入当前会话的活跃运行中，独立于 /queue 模式。当会话空闲时，它不会启动新运行。别名：/tell。参见 Steer。

- /help 显示简短帮助摘要。
- /commands 显示生成的命令目录。
- /tools [compact|verbose] 显示当前智能体此刻可以使用的内容。
- /status 显示执行/运行时状态、Gateway 网关和系统运行时间，以及可用时的提供商用量/配额。
- /diagnostics [note] 是用于 Gateway 网关错误和 Codex harness 运行的仅限所有者支持报告流程。它每次运行 openclaw gateway diagnostics export --json 前都会请求显式 exec 批准；不要用全允许规则批准诊断。批准后，它会发送一份可粘贴的报告，其中包含本地包路径、清单摘要、隐私说明和相关会话 id。在群聊中，批准提示和报告会私下发送给所有者。当活跃会话使用 OpenAI Codex harness 时，同一次批准也会向 OpenAI 服务器发送相关 Codex 反馈，并且完成后的回复会列出 OpenClaw 会话 id、Codex 线程 id 和 codex resume <thread-id> 命令。参见 诊断导出。
- /crestodian <request> 从所有者私信运行 Crestodian 设置和修复助手。
- /tasks 列出当前会话的活跃/最近后台任务。
- /context [list|detail|map|json] 说明上下文如何组装。map 会发送当前会话上下文的矩形树图图像。
- /whoami 显示你的发送者 id。别名：/id。
- /usage off|tokens|full|cost 控制每条回复的用量页脚，或打印本地成本摘要。

- /skill <name> [input] 按名称运行一个 Skills。
- /allowlist [list|add|remove] ... 管理 allowlist 条目。仅文本。
- /approve <id> <decision> 处理 exec 审批提示。
- /btw <question> 提出一个旁支问题，且不会改变后续会话上下文。别名：/side。参见 BTW。

- /subagents list|kill|log|info|send|steer|spawn 管理当前会话的子 Agent 运行。
- /acp spawn|cancel|steer|close|sessions|status|set-mode|set|cwd|permissions|timeout|model|reset-options|doctor|install|help 管理 ACP 会话和运行时选项。
- /focus <target> 将当前 Discord 线程或 Telegram 主题/对话绑定到一个会话目标。
- /unfocus 移除当前绑定。
- /agents 列出当前会话中绑定到线程的 Agent。
- /kill <id|#|all> 中止一个或所有正在运行的子 Agent。
- /subagents steer <id|#> <message> 向正在运行的子 Agent 发送 Steer。参见 Steer。

- /config show|get|set|unset 读取或写入 openclaw.json。仅所有者。需要 commands.config: true。
- /mcp show|get|set|unset 读取或写入 mcp.servers 下由 OpenClaw 管理的 MCP 服务器配置。仅所有者。需要 commands.mcp: true。
- /plugins list|inspect|show|get|install|enable|disable 检查或变更插件状态。/plugin 是别名。写入仅限所有者。需要 commands.plugins: true。
- /debug show|set|unset|reset 管理仅运行时的配置覆盖。仅所有者。需要 commands.debug: true。
- /restart 在启用时重启 OpenClaw。默认：启用；设置 commands.restart: false 可将其禁用。
- /send on|off|inherit 设置发送策略。仅所有者。

- /tts on|off|status|chat|latest|provider|limit|summary|audio|help 控制 TTS。参见 TTS。
- /activation mention|always 设置群组激活模式。
- /bash <command> 运行主机 shell 命令。仅文本。别名：! <command>。需要 commands.bash: true 加上 tools.elevated allowlist。
- !poll [sessionId] 检查后台 bash 任务。
- !stop [sessionId] 停止后台 bash 任务。

生成的停靠命令

停靠命令会将当前会话的回复路由切换到另一个已关联的
渠道。设置、示例和故障排除请参见 频道停靠。

停靠命令由支持原生命令的渠道插件生成。当前内置集合：

• /dock-discord（别名：/dock_discord）
• /dock-mattermost（别名：/dock_mattermost）
• /dock-slack（别名：/dock_slack）
• /dock-telegram（别名：/dock_telegram）

在直接聊天中使用停靠命令，可将当前会话的回复路由切换到另一个已关联的渠道。智能体会保留相同的会话上下文，但该会话后续回复会发送到选定的渠道对端。

停靠命令需要 session.identityLinks。源发送者和目标对端必须位于同一个身份组中，例如 ["telegram:123", "discord:456"]。如果 id 为 123 的 Telegram 用户发送 /dock_discord，OpenClaw 会在活动会话上存储 lastChannel: "discord" 和 lastTo: "456"。如果发送者未关联到 Discord 对端，该命令会回复一条设置提示，而不是落入普通聊天。

停靠只会更改活动会话路由。它不会创建渠道账号、授予访问权限、绕过渠道 allowlist，也不会将转录历史移动到另一个会话。使用 /dock-telegram、/dock-slack、/dock-mattermost 或另一个生成的停靠命令可再次切换路由。

内置插件命令

内置插件可以添加更多斜杠命令。此仓库中当前的内置命令：

• /dreaming [on|off|status|help] 切换记忆 Dreaming。参见 Dreaming。
• /pair [qr|status|pending|approve|cleanup|notify] 管理设备配对/设置流程。参见 配对。
• /phone status|arm <camera|screen|writes|all> [duration]|disarm 临时启用高风险手机节点命令。
• /voice status|list [limit]|set <voiceId|name> 管理 Talk 语音配置。在 Discord 上，原生命令名称是 /talkvoice。
• /card ... 发送 LINE 富卡片预设。参见 LINE。
• /codex status|models|threads|resume|compact|review|diagnostics|account|mcp|skills 检查并控制内置 Codex 应用服务器 harness。参见 Codex harness。
• QQBot 专用命令：
• /bot-ping
• /bot-version
• /bot-help
• /bot-upgrade
• /bot-logs

动态 Skills 命令

用户可调用的 Skills 也会作为斜杠命令公开：

• /skill <name> [input] 始终可作为通用入口点使用。
• 当 Skills/插件注册它们时，Skills 也可能显示为 /prose 这样的直接命令。
• 原生 Skills 命令注册由 commands.nativeSkills 和 channels.<provider>.commands.nativeSkills 控制。
• 命令规范可以为支持本地化描述的原生表面提供 descriptionLocalizations，包括 Discord。

- 命令接受命令和参数之间可选的 :（例如 /think: high、/send: on、/help:）。
- /new <model> 接受模型别名、provider/model 或提供商名称（模糊匹配）；如果没有匹配，文本会被视为消息正文。
- 要查看完整提供商用量明细，请使用 openclaw status --usage。
- /allowlist add|remove 需要 commands.config=true，并遵循渠道 configWrites。
- 在多账号渠道中，面向配置目标的 /allowlist --account <id> 和 /config set channels.<provider>.accounts.<id>... 也会遵循目标账号的 configWrites。
- /usage 控制每次响应的用量页脚；/usage cost 会从 OpenClaw 会话日志打印本地成本摘要。
- /restart 默认启用；设置 commands.restart: false 可将其禁用。
- /plugins install <spec> 接受与 openclaw plugins install 相同的插件规范：本地路径/归档、npm 包、git:<repo> 或 clawhub:<pkg>，随后会请求 Gateway 网关重启，因为插件源模块已更改。
- /plugins enable|disable 更新插件配置，并为新的智能体轮次触发 Gateway 网关插件重载。

- 仅 Discord 原生命令：/vc join|leave|status 控制语音频道（不能作为文本使用）。join 需要一个服务器和选定的语音/舞台频道。需要 channels.discord.voice 和原生命令。
- Discord 线程绑定命令（/focus、/unfocus、/agents、/session idle、/session max-age）需要启用有效线程绑定（session.threadBindings.enabled 和/或 channels.discord.threadBindings.enabled）。
- ACP 命令参考和运行时行为：ACP Agents。

- /verbose 用于调试和提供额外可见性；正常使用时保持关闭。
- /trace 比 /verbose 更窄：它只显示插件拥有的 trace/debug 行，并保持普通 verbose 工具杂讯关闭。
- /fast on|off 会持久化会话覆盖。使用会话 UI 的 inherit 选项清除它，并回退到配置默认值。
- /fast 与提供商相关：OpenAI/OpenAI Codex 会将其映射到原生 Responses 端点上的 service_tier=priority，而直接的公开 Anthropic 请求，包括发送到 api.anthropic.com 的 OAuth 认证流量，会将其映射到 service_tier=auto 或 standard_only。参见 OpenAI 和 Anthropic。
- 相关时仍会显示工具失败摘要，但详细失败文本只会在 /verbose 为 on 或 full 时包含。
- /reasoning、/verbose 和 /trace 在群组环境中有风险：它们可能暴露你不打算公开的内部推理、工具输出或插件诊断。建议保持关闭，尤其是在群聊中。

- /model 会立即持久化新的会话模型。
- 如果智能体空闲，下一次运行会立刻使用它。
- 如果已有运行处于活动状态，OpenClaw 会将实时切换标记为待处理，并只会在干净的重试点重启进入新模型。
- 如果工具活动或回复输出已经开始，待处理切换可能会保持排队，直到后续重试机会或下一次用户轮次。
- 在本地 TUI 中，/crestodian [request] 会从普通智能体 TUI 返回 Crestodian。这与消息渠道救援模式不同，也不会授予远程配置权限。

- 快速路径：来自 allowlist 发送者的仅命令消息会被立即处理（绕过队列 + 模型）。
- 群组提及门控：来自 allowlist 发送者的仅命令消息会绕过提及要求。
- 内联快捷方式（仅限 allowlist 发送者）：某些命令嵌入普通消息时也可工作，并会在模型看到剩余文本之前被剥离。
- 示例：hey /status 会触发状态回复，剩余文本继续走普通流程。
- 当前：/help、/commands、/status、/whoami（/id）。
- 未授权的仅命令消息会被静默忽略，内联 /... 令牌会被视为纯文本。

- Skills 命令：user-invocable Skills 会作为斜杠命令公开。名称会被清理为 a-z0-9_（最多 32 个字符）；冲突会获得数字后缀（例如 _2）。
- /skill <name> [input] 按名称运行一个 Skills（当原生命令限制阻止每个 Skills 使用单独命令时很有用）。
- 默认情况下，Skills 命令会作为普通请求转发给模型。
- Skills 可以选择声明 command-dispatch: tool，将命令直接路由到工具（确定性，无模型）。
- 示例：/prose（OpenProse 插件）——参见 OpenProse。
- 原生命令参数：Discord 对动态选项使用自动补全（当你省略必需参数时使用按钮菜单）。Telegram 和 Slack 会在命令支持选项且你省略参数时显示按钮菜单。动态选项会针对目标会话模型解析，因此像 /think 级别这样的模型特定选项会遵循该会话的 /model 覆盖。

/tools

/tools 回答的是运行时问题，而不是配置问题：这个智能体现在在此对话中可以使用什么。

• 默认 /tools 紧凑，并针对快速浏览优化。
• /tools verbose 添加简短描述。
• 支持参数的原生命令表面会公开相同的模式开关，即 compact|verbose。
• 结果限定在会话范围内，因此更改智能体、渠道、线程、发送者授权或模型都可能改变输出。
• /tools 包含运行时实际可达的工具，包括核心工具、已连接的插件工具和渠道拥有的工具。

对于资料和覆盖编辑，请使用控制 UI 的工具面板或配置/目录表面，而不要将 /tools 当作静态目录。

用量表面（哪里显示什么）

• 提供商用量/配额（示例：“Claude 剩余 80%”）会在启用用量跟踪时，针对当前模型提供商显示在 /status 中。OpenClaw 会将提供商窗口规范化为“剩余百分比”；对于 MiniMax，仅表示剩余量的百分比字段会在显示前反转，model_remains 响应会优先使用聊天模型条目以及带模型标签的计划标签。
• 令牌/缓存行 在 /status 中可以在实时会话快照信息较少时，回退到最新的转录用量条目。现有的非零实时值仍然优先，转录回退也可以在已存储总量缺失或较小时，恢复活跃运行时模型标签以及更大的面向提示词的总量。
• 执行与运行时： /status 会报告 Execution 作为生效沙箱路径，并报告 Runtime 作为实际运行会话的主体：OpenClaw Pi Default、OpenAI Codex、某个 CLI 后端或某个 ACP 后端。
• 单次响应令牌/费用 由 /usage off|tokens|full 控制（追加到普通回复中）。
• /model status 关注的是 模型/认证/端点，而不是用量。

模型选择（/model）

/model 以指令形式实现。

示例：

/model
/model list
/model 3
/model openai/gpt-5.4
/model opus@anthropic:default
/model status

说明：

• /model 和 /model list 会显示一个紧凑的编号选择器（模型系列 + 可用提供商）。
• 在 Discord 上，/model 和 /models 会打开一个交互式选择器，其中包含提供商和模型下拉框以及提交步骤。该选择器遵循 agents.defaults.models，包括 provider/* 条目，因此按提供商限定的发现可以让选择器保持在 Discord 的 25 个选项组件限制以内。
• /model <#> 从该选择器中选择（并会尽可能优先使用当前提供商）。
• /model status 会显示详细视图，包括已配置的提供商端点（baseUrl）和 API 模式（api，如果可用）。

调试覆盖

/debug 允许你设置仅运行时配置覆盖（内存中，而不是磁盘上）。仅限所有者。默认禁用；使用 commands.debug: true 启用。

示例：

/debug show
/debug set messages.responsePrefix="[openclaw]"
/debug set channels.whatsapp.allowFrom=["+1555","+4477"]
/debug unset messages.responsePrefix
/debug reset

覆盖会立即应用于新的配置读取，但不会写入 openclaw.json。使用 /debug reset 清除所有覆盖并返回磁盘上的配置。

插件跟踪输出

/trace 允许你切换会话范围的插件跟踪/调试行，无需开启完整详细模式。

示例：

/trace
/trace on
/trace off

说明：

• 不带参数的 /trace 会显示当前会话跟踪状态。
• /trace on 会为当前会话启用插件跟踪行。
• /trace off 会再次禁用它们。
• 插件跟踪行可以出现在 /status 中，也可以在普通助手回复之后作为后续诊断消息出现。
• /trace 不会取代 /debug；/debug 仍然管理仅运行时配置覆盖。
• /trace 不会取代 /verbose；普通详细工具/状态输出仍然属于 /verbose。

配置更新

/config 会写入你的磁盘配置（openclaw.json）。仅限所有者。默认禁用；使用 commands.config: true 启用。

示例：

/config show
/config show messages.responsePrefix
/config get messages.responsePrefix
/config set messages.responsePrefix="[openclaw]"
/config unset messages.responsePrefix

配置会在写入前进行验证；无效更改会被拒绝。/config 更新会在重启后保留。

MCP 更新

/mcp 会在 mcp.servers 下写入由 OpenClaw 管理的 MCP 服务器定义。仅限所有者。默认禁用；使用 commands.mcp: true 启用。

示例：

/mcp show
/mcp show context7
/mcp set context7={"command":"uvx","args":["context7-mcp"]}
/mcp unset context7

/mcp 将配置存储在 OpenClaw 配置中，而不是 Pi 拥有的项目设置中。运行时适配器决定哪些传输协议实际可执行。

插件更新

/plugins 允许操作员检查已发现的插件，并在配置中切换启用状态。只读流程可以使用 /plugin 作为别名。默认禁用；使用 commands.plugins: true 启用。

示例：

/plugins
/plugins list
/plugin show context7
/plugins enable context7
/plugins disable context7

- /plugins list 和 /plugins show 会根据当前工作区以及磁盘上的配置进行真实插件发现。
- /plugins install 会从 ClawHub、npm、git、本地目录和归档安装。
- /plugins enable|disable 只更新插件配置；它不会安装或卸载插件。
- 启用和禁用更改会为新的 agent 轮次热重载 Gateway 网关插件运行时表面；安装会请求重启 Gateway 网关，因为插件源模块已更改。

表面说明

- 文本命令 在普通聊天会话中运行（DM 共享 main，群组有自己的会话）。
- 原生命令 使用隔离会话：
- Discord: agent:<agentId>:discord:slash:<userId>
- Slack: agent:<agentId>:slack:slash:<userId>（可通过 channels.slack.slashCommand.sessionPrefix 配置前缀）
- Telegram: telegram:slash:<userId>（通过 CommandTargetSessionKey 指向聊天会话）
- /stop 指向活跃聊天会话，因此它可以中止当前运行。

仍然支持 channels.slack.slashCommand，用于单个 /openclaw 风格命令。如果你启用 commands.native，则必须为每个内置命令创建一个 Slack 斜杠命令（名称与 /help 相同）。Slack 的命令参数菜单会作为临时 Block Kit 按钮发送。

Slack 原生例外：注册 `/agentstatus`（而不是 `/status`），因为 Slack 保留了 `/status`。文本 `/status` 仍然可以在 Slack 消息中使用。

BTW 旁路问题

/btw 是关于当前会话的快速旁路问题。/side 是别名。

与普通聊天不同：

• 它使用当前会话作为背景上下文，
• 在 Codex harness 会话中，它会作为临时 Codex 旁路线程运行，并带有当前 Codex 权限和原生工具表面，
• 在非 Codex 会话中，它保留较旧的直接一次性旁路调用行为，
• 它不会改变未来的会话上下文，
• 它不会写入转录历史，
• 它会作为实时旁路结果发送，而不是普通助手消息。

当你希望在主任务继续进行时获得临时澄清，/btw 会很有用。

示例：

/btw what are we doing right now?
/side what changed while the main run continued?

有关完整行为和客户端 UX 细节，请参阅 BTW 旁路问题。

相关

• 创建技能
• Skills
• Skills 配置

📄 Skills

原文：https://docs.openclaw.ai/zh-CN/tools/skills

OpenClaw 使用兼容 AgentSkills 的技能文件夹来教智能体如何使用工具。每个 Skills 都是一个目录，其中包含带有 YAML frontmatter 和说明的 SKILL.md。OpenClaw 会加载内置 Skills 以及可选的本地覆盖项，并在加载时根据环境、配置和二进制文件是否存在对它们进行过滤。

位置和优先级

OpenClaw 从这些来源加载 Skills，优先级从高到低：

如果 Skills 名称冲突，优先级最高的来源生效。

Codex CLI 的原生 $CODEX_HOME/skills 目录不是这些 OpenClaw Skills 根目录之一。在 Codex harness 模式下，本地应用服务器启动会使用隔离的每智能体 Codex 主目录，因此个人 Codex CLI Skills 不会被隐式加载。使用 openclaw migrate codex --dry-run 盘点它们，并使用 openclaw migrate codex 通过交互式复选框提示选择 Skills 目录，然后复制到当前 OpenClaw 智能体工作区。对于非交互式运行，请重复使用 --skill <name> 指定要复制的确切 Skills。

每智能体与共享 Skills

在多智能体设置中，每个智能体都有自己的工作区：

同名 Skills 出现在多个位置 → 优先级最高的来源生效。工作区优先于项目智能体，项目智能体优先于个人智能体，个人智能体优先于托管/本地，托管/本地优先于内置，内置优先于额外目录。

智能体 Skills allowlist

Skills 位置和 Skills 可见性是分开的控制项。位置/优先级决定同名 Skills 的哪个副本生效；智能体 allowlist 决定智能体实际可以使用哪些 Skills。

{
  agents: {
    defaults: {
      skills: ["github", "weather"],
    },
    list: [
      { id: "writer" }, // inherits github, weather
      { id: "docs", skills: ["docs-search"] }, // replaces defaults
      { id: "locked-down", skills: [] }, // no skills
    ],
  },
}

- 默认情况下，省略 agents.defaults.skills 表示不限制 Skills。
- 省略 agents.list[].skills 会继承 agents.defaults.skills。
- 设置 agents.list[].skills: [] 表示没有 Skills。
- 非空的 agents.list[].skills 列表是该智能体的最终集合，不会与默认值合并。
- 有效 allowlist 会应用于提示构建、Skills 斜杠命令发现、沙箱同步和 Skills 快照。

插件和 Skills

插件可以通过在 openclaw.plugin.json 中列出 skills 目录来附带自己的 Skills（路径相对于插件根目录）。插件启用时会加载插件 Skills。这适合放置特定工具的操作指南：这些指南对于工具描述来说太长，但只要插件已安装就应该可用。例如，浏览器插件会附带一个 browser-automation Skills，用于多步骤浏览器控制。

插件 Skills 目录会合并到与 skills.load.extraDirs 相同的低优先级路径中，因此同名的内置、托管、智能体或工作区 Skills 会覆盖它们。你可以通过插件配置条目上的 metadata.openclaw.requires.config 对它们设门槛。

请参阅 插件 了解发现/配置，并参阅 工具 了解这些 Skills 所教授的工具表面。

Skills 工作坊

可选的实验性 Skills 工作坊插件可以根据智能体工作期间观察到的可复用流程创建或更新工作区 Skills。它默认禁用，必须通过 plugins.entries.skill-workshop 显式启用。

Skills 工作坊只写入 <workspace>/skills，会扫描生成内容，支持待批准或自动安全写入，会隔离不安全提案，并在成功写入后刷新 Skills 快照，使新 Skills 无需重启 Gateway 网关即可可用。

将它用于类似 “下次验证 GIF 署名” 的修正，或类似媒体 QA 检查清单这类来之不易的工作流。先从待批准开始；仅在可信工作区中审核其提案后再使用自动写入。完整指南：Skills 工作坊插件。

ClawHub（安装和同步）

ClawHub 是 OpenClaw 的公共 Skills 注册表。使用原生 openclaw skills 命令进行发现/安装/更新，或使用单独的 clawhub CLI 执行发布/同步工作流。完整指南：ClawHub。

原生 openclaw skills install 会安装到活动工作区的 skills/ 目录。单独的 clawhub CLI 也会安装到你当前工作目录下的 ./skills（或回退到配置的 OpenClaw 工作区）。OpenClaw 会在下一个会话中将其识别为 <workspace>/skills。配置的 Skills 根目录也支持一级分组，例如 skills/<group>/<skill>/SKILL.md，因此相关的第三方 Skills 可以保存在共享文件夹下，而无需进行宽泛的递归扫描。

需要私有、非 ClawHub 交付的 Gateway 网关客户端可以使用 skills.upload.begin、skills.upload.chunk 和 skills.upload.commit 暂存一个 zip Skills 归档，然后使用 skills.install({ source: "upload", uploadId, slug, force?, sha256? }) 安装已提交的上传。这是面向可信客户端的显式管理员上传路径，不是普通的 openclaw skills install <slug> 或 ClawHub 安装流程。它默认关闭，只有在 openclaw.json 中设置 skills.install.allowUploadedArchives: true 时才可用。上传模式仍会安装到默认智能体工作区的 skills/<slug> 目录；归档内部的文件夹名称会被忽略，不作为最终安装目标。

ClawHub Skills 页面会在安装前显示最新安全扫描状态，并提供 VirusTotal、ClawScan 和静态分析的扫描器详情页。openclaw skills install <slug> 仍然只是安装路径；发布者可通过 ClawHub 控制台或 clawhub skill rescan <slug> 处理误报。

安全

将第三方 Skills 视为不可信代码。启用前请先阅读。对于不可信输入和高风险工具，优先使用沙箱隔离运行。请参阅沙箱隔离了解智能体侧控制项。

• 工作区和额外目录的 Skills 发现只接受解析后的真实路径仍位于配置根目录内的 Skills 根目录和 SKILL.md 文件。
• Gateway 网关私有归档安装默认关闭。显式启用后，它们需要一个已提交的 zip 上传，其中包含 SKILL.md，并复用与 ClawHub Skills 安装相同的归档解压、路径遍历、符号链接、强制覆盖和回滚保护。它们由 skills.install.allowUploadedArchives 控制；普通 ClawHub 安装不需要该设置。
• Gateway 网关支持的 Skills 依赖安装（skills.install、新手引导和 Skills 设置 UI）会在执行安装器元数据前运行内置危险代码扫描器。默认情况下，critical 发现会阻止执行，除非调用方显式设置危险覆盖；可疑发现仍然只会警告。
• openclaw skills install <slug> 不同：它会把 ClawHub Skills 文件夹下载到工作区，并且不使用上面的安装器元数据路径。
• skills.entries.*.env 和 skills.entries.*.apiKey 会将密钥注入该智能体轮次的宿主进程（不是沙箱）。不要把密钥放进提示和日志。

如需更广泛的威胁模型和检查清单，请参阅安全。

SKILL.md 格式

SKILL.md 至少必须包含：

---
name: image-lab
description: Generate or edit images via a provider-backed image workflow
---

OpenClaw 遵循 AgentSkills 规范的布局/意图。嵌入式智能体使用的解析器仅支持单行 frontmatter 键；metadata 应该是一个单行 JSON 对象。在说明中使用 {baseDir} 引用 Skills 文件夹路径。

可选 frontmatter 键

在 macOS Skills UI 中显示为“网站”的 URL。也支持通过 metadata.openclaw.homepage 设置。


当为 true 时，Skills 会作为用户斜杠命令暴露。


当为 true 时，OpenClaw 会将该 Skills 的说明排除在智能体的普通提示之外。该 Skills 仍会安装，并且当 user-invocable 也为 true 时，仍可作为斜杠命令显式运行。


设置为 tool 时，斜杠命令会绕过模型并直接分派到工具。


设置 command-dispatch: tool 时要调用的工具名称。


对于工具分派，将原始参数字符串转发给工具（不进行核心解析）。工具会以 { command: "<raw args>", commandName: "<slash command>", skillName: "<skill name>" } 调用。

门控（加载时过滤器）

OpenClaw 在加载时使用 metadata（单行 JSON）过滤 Skills：

---
name: image-lab
description: Generate or edit images via a provider-backed image workflow
metadata:
  {
    "openclaw":
      {
        "requires": { "bins": ["uv"], "env": ["GEMINI_API_KEY"], "config": ["browser.enabled"] },
        "primaryEnv": "GEMINI_API_KEY",
      },
  }
---

metadata.openclaw 下的字段：

当为 true 时，始终包含该技能（跳过其他门控）。


macOS Skills UI 使用的可选 emoji。


在 macOS Skills UI 中显示为“网站”的可选 URL。


可选平台列表。如果设置，该技能仅在这些 OS 上符合条件。


每一项都必须存在于 PATH 上。


至少一项必须存在于 PATH 上。


环境变量必须存在，或在配置中提供。


必须为真值的 openclaw.json 路径列表。


与 skills.entries.<name>.apiKey 关联的环境变量名称。


macOS Skills UI 使用的可选安装器规格（brew/node/go/uv/download）。

如果没有 metadata.openclaw，该技能始终符合条件（除非在配置中被
禁用，或对于内置技能被 skills.allowBundled 阻止）。

当缺少 metadata.openclaw 时，仍会接受旧版 metadata.clawdbot
块，因此较旧的已安装技能会保留它们的依赖门控和安装器提示。新的和更新后的技能应使用
metadata.openclaw。

沙箱隔离注意事项

• requires.bins 会在技能加载时在主机上检查。
• 如果智能体处于沙箱隔离中，该二进制文件也必须存在于容器内。通过 agents.defaults.sandbox.docker.setupCommand（或自定义镜像）安装它。setupCommand 会在容器创建后运行一次。包安装还需要网络出口、可写的根 FS，以及沙箱中的 root 用户。
• 示例：summarize 技能（skills/summarize/SKILL.md）需要沙箱容器中有 summarize CLI 才能在那里运行。

安装器规格

---
name: gemini
description: Use Gemini CLI for coding assistance and Google search lookups.
metadata:
  {
    "openclaw":
      {
        "emoji": "♊️",
        "requires": { "bins": ["gemini"] },
        "install":
          [
            {
              "id": "brew",
              "kind": "brew",
              "formula": "gemini-cli",
              "bins": ["gemini"],
              "label": "Install Gemini CLI (brew)",
            },
          ],
      },
  }
---

- 如果列出了多个安装器，Gateway 网关会选择一个首选选项（brew 可用时选择 brew，否则选择 node）。
- 如果所有安装器都是 download，OpenClaw 会列出每个条目，让你看到可用的构件。
- 安装器规格可以包含 os: ["darwin"|"linux"|"win32"]，用于按平台筛选选项。
- Node 安装会遵循 openclaw.json 中的 skills.install.nodeManager（默认：npm；选项：npm/pnpm/yarn/bun）。这只影响技能安装；Gateway 网关运行时仍应是 Node - 不建议将 Bun 用于 WhatsApp/Telegram。
- Gateway 网关支持的安装器选择由偏好驱动：当安装规格混合多种类型时，如果启用了 skills.install.preferBrew 且存在 brew，OpenClaw 会优先选择 Homebrew，然后是 uv，然后是已配置的 node 管理器，再然后是其他回退选项，如 go 或 download。
- 如果每个安装规格都是 download，OpenClaw 会展示所有下载选项，而不是折叠为一个首选安装器。

- Go 安装：如果缺少 go 且 brew 可用，Gateway 网关会先通过 Homebrew 安装 Go，并在可能时将 GOBIN 设置为 Homebrew 的 bin。
- 下载安装：url（必需）、archive（tar.gz | tar.bz2 | zip）、extract（默认：检测到归档时自动）、stripComponents、targetDir（默认：~/.openclaw/tools/<skillKey>）。

配置覆盖

内置和托管技能可以在 ~/.openclaw/openclaw.json 的 skills.entries
下切换，并提供环境值：

{
  skills: {
    entries: {
      "image-lab": {
        enabled: true,
        apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" }, // or plaintext string
        env: {
          GEMINI_API_KEY: "GEMINI_KEY_HERE",
        },
        config: {
          endpoint: "https://example.invalid",
          model: "nano-pro",
        },
      },
      peekaboo: { enabled: true },
      sag: { enabled: false },
    },
  },
}

false 会禁用该技能，即使它是内置或已安装的。
内置的 coding-agent 技能是选择加入的：在将其暴露给智能体之前，设置
skills.entries.coding-agent.enabled: true，
然后确保已安装 claude、codex、opencode 或 pi 之一，并已为其自己的 CLI
完成身份验证。


为声明 metadata.openclaw.primaryEnv 的技能提供的便捷配置。支持明文或 SecretRef。


仅在该变量尚未在进程中设置时注入。


用于自定义单技能字段的可选包。自定义键必须放在这里。


仅适用于内置技能的可选允许列表。如果设置，只有列表中的内置技能符合条件（托管/工作区技能不受影响）。

如果技能名称包含连字符，请为键加引号（JSON5 允许带引号的键）。默认情况下，配置键与技能名称匹配 - 如果技能
定义了 metadata.openclaw.skillKey，请在 skills.entries 下使用该键。

在 OpenClaw 内部进行原生图像生成/编辑时，请使用核心
image_generate 工具和 agents.defaults.imageGenerationModel，而不是
内置技能。这里的技能示例用于自定义或第三方
工作流。原生图像分析请使用 image 工具和
agents.defaults.imageModel。如果你选择 openai/*、google/*、
fal/* 或其他提供商特定的图像模型，也要添加该提供商的
auth/API key。

环境注入

当智能体运行开始时，OpenClaw 会：

1. 读取技能元数据。
2. 将 skills.entries.<key>.env 和 skills.entries.<key>.apiKey 应用于 process.env。
3. 使用符合条件的技能构建系统提示词。
4. 运行结束后恢复原始环境。

环境注入的作用域是智能体运行，不是全局 shell
环境。

对于内置的 claude-cli 后端，OpenClaw 还会将同一个
符合条件的快照实体化为临时 Claude Code 插件，并通过
--plugin-dir 传入。Claude Code 随后可以使用其原生技能解析器，同时
OpenClaw 仍负责优先级、按智能体允许列表、门控，以及
skills.entries.* env/API key 注入。其他 CLI 后端仅使用
提示词目录。

快照和刷新

OpenClaw 会在会话开始时快照符合条件的技能，并在同一会话的后续轮次中
复用该列表。对技能或配置的更改会在下一个新会话中生效。

技能可在会话中途在两种情况下刷新：

• 技能观察器已启用。
• 出现新的符合条件的远程节点。

可以把它理解为热重载：刷新的列表会在下一个
智能体轮次中被采用。如果该会话的有效智能体技能允许列表发生变化，
OpenClaw 会刷新快照，让可见技能与当前智能体保持一致。

Skills 观察器

默认情况下，OpenClaw 会观察技能文件夹，并在 SKILL.md 文件变化时更新技能快照。
在 skills.load 下配置：

{
  skills: {
    load: {
      extraDirs: ["~/Projects/agent-scripts/skills"],
      allowSymlinkTargets: ["~/Projects/manager/skills"],
      watch: true,
      watchDebounceMs: 250,
    },
  },
}

对于内置技能根包含符号链接的有意兄弟仓库布局，使用
allowSymlinkTargets，例如
~/.agents/skills/manager -> ~/Projects/manager/skills。目标列表会在 realpath 解析后
匹配，并应保持狭窄。

远程 macOS 节点（Linux Gateway 网关）

如果 Gateway 网关运行在 Linux 上，但连接了一个macOS 节点且
允许 system.run（Exec 审批安全未设置为 deny），
当所需二进制文件存在于该节点上时，OpenClaw 可以将仅限 macOS 的技能视为符合条件。
智能体应通过带 host=node 的 exec 工具执行这些技能。

这依赖于节点报告其命令支持，并通过 system.which 或 system.run
进行 bin 探测。离线节点不会让仅远程可用的技能可见。
如果已连接节点停止响应 bin 探测，OpenClaw 会清除其缓存的 bin 匹配，
这样智能体就不再看到当前无法在那里运行的技能。

Token 影响

当技能符合条件时，OpenClaw 会将可用技能的紧凑 XML 列表
注入到系统提示词中（通过 pi-coding-agent 中的 formatSkillsForPrompt）。
成本是确定性的：

• 基础开销（仅当 ≥1 个技能时）：195 个字符。
• 每个技能：97 个字符 + XML 转义后的 <name>、<description> 和 <location> 值长度。

公式（字符）：

total = 195 + Σ (97 + len(name_escaped) + len(description_escaped) + len(location_escaped))

XML 转义会将 & < > " ' 扩展为实体（&、< 等），
从而增加长度。Token 数会随模型 tokenizer 而变化。粗略的
OpenAI 风格估计是约 4 个字符/token，因此97 个字符 ≈ 24 个 token/每个
技能，再加上你的实际字段长度。

托管技能生命周期

OpenClaw 随安装（npm 包或 OpenClaw.app）附带一组基线技能作为内置技能。
~/.openclaw/skills 用于本地覆盖 - 例如，在不更改
内置副本的情况下固定或修补某个技能。工作区技能由用户拥有，并会在
名称冲突时覆盖前两者。

想找更多技能？

浏览 https://clawhub.ai。完整配置
schema：Skills 配置。

相关

• ClawHub - 公共技能注册表
• 创建技能 - 构建自定义技能
• 插件 - 插件系统概览
• Skill Workshop 插件 - 从智能体工作生成技能
• Skills 配置 - 技能配置参考
• 斜杠命令 - 所有可用斜杠命令

📄 Skills 配置

原文：https://docs.openclaw.ai/zh-CN/tools/skills-config

大多数 Skills 加载器/安装配置位于
~/.openclaw/openclaw.json 中的 skills 下。智能体特定的技能可见性位于
agents.defaults.skills 和 agents.list[].skills 下。

{
  skills: {
    allowBundled: ["gemini", "peekaboo"],
    load: {
      extraDirs: ["~/Projects/agent-scripts/skills", "~/Projects/oss/some-skill-pack/skills"],
      allowSymlinkTargets: ["~/Projects/manager/skills"],
      watch: true,
      watchDebounceMs: 250,
    },
    install: {
      preferBrew: true,
      nodeManager: "npm", // npm | pnpm | yarn | bun (Gateway runtime still Node; bun not recommended)
      allowUploadedArchives: false,
    },
    entries: {
      "image-lab": {
        enabled: true,
        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 },
    },
  },
}

对于内置图像生成/编辑，优先使用 agents.defaults.imageGenerationModel
加核心 image_generate 工具。skills.entries.* 仅用于自定义或
第三方技能工作流。

如果你选择特定图像提供商/模型，也要配置该提供商的
身份验证/API key。典型示例：google/* 使用 GEMINI_API_KEY 或
GOOGLE_API_KEY，openai/* 使用 OPENAI_API_KEY，fal/* 使用 FAL_KEY。

示例：

• 原生 Nano Banana Pro 风格设置：agents.defaults.imageGenerationModel.primary: "google/gemini-3-pro-image-preview"
• 原生 fal 设置：agents.defaults.imageGenerationModel.primary: "fal/fal-ai/flux/dev"

智能体技能允许列表

当你想使用同一台机器/工作区技能根目录，但希望每个智能体有
不同可见技能集时，请使用智能体配置。

{
  agents: {
    defaults: {
      skills: ["github", "weather"],
    },
    list: [
      { id: "writer" }, // inherits defaults -> github, weather
      { id: "docs", skills: ["docs-search"] }, // replaces defaults
      { id: "locked-down", skills: [] }, // no skills
    ],
  },
}

规则：

• agents.defaults.skills：共享基线允许列表，供省略
  agents.list[].skills 的智能体使用。
• 省略 agents.defaults.skills 会让技能默认不受限制。
• agents.list[].skills：该智能体的显式最终技能集；它不会
  与默认值合并。
• agents.list[].skills: []：不向该智能体暴露任何技能。

字段

• 内置技能根目录始终包括 ~/.openclaw/skills、~/.agents/skills、
  <workspace>/.agents/skills 和 <workspace>/skills。
• allowBundled：仅适用于内置技能的可选允许列表。设置后，只有
  列表中的内置技能符合条件（托管、智能体和工作区技能不受影响）。
• load.extraDirs：要扫描的附加技能目录（最低优先级）。
• load.allowSymlinkTargets：受信任的真实目标目录；符号链接的
  技能文件夹即使符号链接位于该目标根目录之外，也可以解析到其中。
  用于有意采用的同级仓库布局，例如
  ~/.agents/skills/manager -> ~/Projects/manager/skills。
• load.watch：监视技能文件夹并刷新 Skills 快照（默认：true）。
• load.watchDebounceMs：技能监视器事件的防抖时间，单位为毫秒（默认：250）。
• install.preferBrew：可用时优先使用 brew 安装器（默认：true）。
• install.nodeManager：node 安装器偏好（npm | pnpm | yarn | bun，默认：npm）。
  这只影响技能安装；Gateway 网关运行时仍应使用 Node
  （不建议对 WhatsApp/Telegram 使用 Bun）。
• openclaw setup --node-manager 范围更窄，目前接受 npm、
  pnpm 或 bun。如果你想使用 Yarn 支持的技能安装，请手动设置
  skills.install.nodeManager: "yarn"。
• install.allowUploadedArchives：允许受信任的 operator.admin Gateway 网关
  客户端安装通过 skills.upload.* 暂存的私有 zip 归档
  （默认：false）。这只启用上传归档路径；普通 ClawHub
  安装不需要它。
• entries.<skillKey>：每个技能的覆盖项。
• agents.defaults.skills：可选的默认技能允许列表，由省略
  agents.list[].skills 的智能体继承。
• agents.list[].skills：可选的每智能体最终技能允许列表；显式
  列表会替换继承的默认值，而不是合并。

符号链接的同级仓库

默认情况下，每个技能根目录都是一个包含边界。如果
~/.agents/skills 下的技能文件夹是解析到 ~/.agents/skills
之外的符号链接，OpenClaw 会跳过它，并记录 Skipping escaped skill path outside its configured
root。

保留符号链接布局，并只允许受信任的目标根目录：

{
  skills: {
    load: {
      extraDirs: ["~/Projects/manager/skills"],
      allowSymlinkTargets: ["~/Projects/manager/skills"],
    },
  },
}

使用此配置后，类似
~/.agents/skills/manager -> ~/Projects/manager/skills 的符号链接会在
realpath 解析后被接受。extraDirs 还会直接扫描同级仓库，而
allowSymlinkTargets 会为现有智能体技能
布局保留符号链接路径。保持目标条目范围狭窄；不要指向 ~ 或
~/Projects 等宽泛根目录，除非该根目录下的每棵技能树都受信任。

每技能字段：

• enabled：设置为 false 可禁用某个技能，即使它是内置/已安装技能。
• env：为智能体运行注入的环境变量（仅在尚未设置时）。
• apiKey：为声明主环境变量的技能提供的可选便捷项。
  支持明文字符串或 SecretRef 对象（{ source, provider, id }）。

注意事项

• entries 下的键默认映射到技能名称。如果某个技能定义了
  metadata.openclaw.skillKey，请改用该键。
• 加载优先级为 <workspace>/skills → <workspace>/.agents/skills →
  ~/.agents/skills → ~/.openclaw/skills → 内置技能 →
  skills.load.extraDirs。
• 启用监视器后，对技能的更改会在下一个智能体轮次被拾取。

沙箱隔离技能和环境变量

当会话被沙箱隔离时，技能进程会在配置的沙箱后端内运行。沙箱不会继承主机 process.env。

全局 env 和 skills.entries.<skill>.env/apiKey 仅适用于主机运行。在沙箱内它们不起作用，因此依赖 GEMINI_API_KEY 的技能会因 apiKey not configured 失败，除非单独向沙箱提供该变量。

使用以下之一：

• Docker 后端使用 agents.defaults.sandbox.docker.env（或每智能体的 agents.list[].sandbox.docker.env）。
• 将环境变量烘焙进你的自定义沙箱镜像或远程沙箱环境。

相关

Skills 是什么以及它们如何加载。


编写自定义技能包。


原生命令目录和聊天指令。


完整的 skills 和 agents.skills schema。

📄 插件

原文：https://docs.openclaw.ai/zh-CN/tools/plugin

插件为 OpenClaw 扩展新能力：渠道、模型提供商、Agent harnesses、工具、Skills、语音、实时转写、实时
语音、媒体理解、图像生成、视频生成、Web 抓取、Web
搜索等。有些插件是核心插件（随 OpenClaw 发布），其他则是外部插件。大多数外部插件通过
ClawHub 发布和发现。Npm 仍支持直接安装，并在迁移完成前支持一组临时的 OpenClaw 所有插件包。

快速开始

如需可复制粘贴的安装、列出、卸载、更新和发布示例，请参阅
管理插件。

bash
openclaw plugins list

```bash
# Search ClawHub plugins
openclaw plugins search "calendar"

# From ClawHub
openclaw plugins install clawhub:openclaw-codex-app-server

# From npm
openclaw plugins install npm:@acme/openclaw-plugin
openclaw plugins install npm-pack:./openclaw-plugin-1.2.3.tgz

# From git
openclaw plugins install git:github.com/acme/openclaw-plugin@v1.0.0

# From a local directory or archive
openclaw plugins install ./my-plugin
openclaw plugins install ./my-plugin.tgz
```

bash
openclaw gateway restart

然后在你的配置文件中的 `plugins.entries.\<id\>.config` 下配置。

在运行中的 Gateway 网关里，仅所有者可用的 /plugins enable 和 /plugins disable
会触发 Gateway 网关配置重载器。Gateway 网关会在进程内重新加载插件运行时
表面，新 Agent 轮次会从刷新后的注册表重建其工具列表。/plugins install 会更改插件源代码，因此
Gateway 网关会请求重启，而不是假装当前进程可以
安全地重新加载已经导入的模块。

```bash
openclaw plugins inspect --runtime --json

# If the plugin registered a CLI root, run one command from that root.
openclaw <plugin-command> --help
```

当你需要证明已注册的工具、服务、Gateway 网关
方法、钩子或插件拥有的 CLI 命令时，请使用 `--runtime`。普通的 `inspect` 是一次冷
清单/注册表检查，并且有意避免导入插件运行时。

如果你更偏好聊天原生控制，请启用 commands.plugins: true 并使用：

/plugin install clawhub:<package>
/plugin show <plugin-id>
/plugin enable <plugin-id>

安装路径使用与 CLI 相同的解析器：本地路径/归档、显式
clawhub:<pkg>、显式 npm:<pkg>、显式 npm-pack:<path.tgz>、
显式 git:<repo>，或通过 npm 解析的裸包规范。

如果配置无效，安装通常会失败关闭，并提示你使用
openclaw doctor --fix。唯一的恢复例外是一条很窄的内置插件
重装路径，适用于选择加入
openclaw.install.allowInvalidConfigRecovery 的插件。
在 Gateway 网关启动期间，无效的插件配置会像任何其他无效
配置一样失败关闭。运行 openclaw doctor --fix 可通过
禁用该插件条目并移除其无效配置载荷来隔离错误的插件配置；正常的
配置备份会保留之前的值。
当渠道配置引用了不再可发现的插件，但同一个过期插件 ID 仍留在插件配置或安装记录中时，Gateway 网关启动
会记录警告并跳过该渠道，而不是阻塞所有其他渠道。
运行 openclaw doctor --fix 可移除过期的渠道/插件条目；没有过期插件证据的未知
渠道键仍会验证失败，因此拼写错误仍然可见。
如果设置了 plugins.enabled: false，过期插件引用会被视为惰性：
Gateway 网关启动会跳过插件发现/加载工作，且 openclaw doctor 会保留
已禁用的插件配置，而不是自动移除它。如果你希望移除过期插件 ID，请先重新启用插件，再运行
doctor 清理。

插件依赖安装只会发生在显式安装/更新或
doctor 修复流程中。Gateway 网关启动、配置重载和运行时检查
不会运行包管理器，也不会修复依赖树。本地插件必须已经
安装好其依赖，而 npm、git 和 ClawHub 插件会
安装到 OpenClaw 的托管插件根目录下。npm 依赖可以在
OpenClaw 的托管 npm 根目录内提升；安装/更新会先扫描该托管根目录再
信任，卸载会通过 npm 移除 npm 托管的包。外部插件
和自定义加载路径仍必须通过 openclaw plugins install 安装。
使用 openclaw plugins list --json 可查看每个
可见插件的静态 dependencyStatus，无需导入运行时代码或修复依赖。
有关安装时生命周期，请参阅插件依赖解析。

被阻止的插件路径所有权

如果插件诊断显示
blocked plugin candidate: suspicious ownership (... uid=1000, expected uid=0 or root)
并且配置验证随后显示 plugin present but blocked，则表示 OpenClaw 发现
插件文件归属于与加载它们的进程不同的 Unix 用户。
保留插件配置；修复文件系统所有权，或以拥有该状态目录的同一用户身份运行
OpenClaw。

对于 Docker 安装，官方镜像以 node（uid 1000）运行，因此
主机绑定挂载的 OpenClaw 配置和工作区目录通常应
归 uid 1000 所有：

sudo chown -R 1000:1000 /path/to/openclaw-config /path/to/openclaw-workspace

如果你有意以 root 运行 OpenClaw，请改为将托管插件根目录修复为
root 所有权：

sudo chown -R root:root /path/to/openclaw-config/npm

修复所有权后，重新运行 openclaw doctor --fix 或
openclaw plugins registry --refresh，使持久化的插件注册表匹配
已修复的文件。

对于 npm 安装，latest 或 dist-tag 等可变选择器会在
安装前解析，然后固定为 OpenClaw
托管 npm 根目录中精确验证过的版本。npm 完成后，OpenClaw 会验证已安装的
package-lock.json 条目仍匹配已解析版本和完整性。如果
npm 写入了不同的包元数据，安装会失败，托管包会
回滚，而不是接受不同的插件构件。
托管 npm 根目录还会继承 OpenClaw 包级别的 npm overrides，因此
保护打包宿主的安全固定同样适用于提升后的外部
插件依赖。

源码检出是 pnpm 工作区。如果你克隆 OpenClaw 来修改内置
插件，请运行 pnpm install；随后 OpenClaw 会从
extensions/<id> 加载内置插件，因此编辑内容和包本地依赖会被直接使用。
普通 npm 根目录安装用于打包版 OpenClaw，而不是源码检出
开发。

插件类型

OpenClaw 识别两种插件格式：

两者都会出现在 openclaw plugins list 下。有关 bundle 详情，请参阅 Plugin Bundles。

如果你正在编写原生插件，请从构建插件
和插件 SDK 概览开始。

包入口点

原生插件 npm 包必须在 package.json 中声明 openclaw.extensions。
每个条目必须保持在包目录内，并解析到一个可读的
运行时文件，或解析到一个带有推断构建后 JavaScript
对等文件的 TypeScript 源文件，例如从 src/index.ts 到 dist/index.js。
打包安装必须包含该 JavaScript 运行时输出。TypeScript
源回退用于源码检出和本地开发路径，不用于
安装到 OpenClaw 托管插件根目录中的 npm 包。

放入全局扩展根目录的未跟踪目录会被视为
本地源码检出，并且可以直接加载 TypeScript 条目。仍然
由安装记录命名的目录，包括 installPath 或 sourcePath，会保持
托管状态，并保留编译输出要求，即使全局扫描看见了
它们。如果你有意将托管安装转换为未跟踪的本地
检出，请先通过卸载或 doctor 清理移除过期安装记录。

如果托管包警告说它 requires compiled runtime output for
TypeScript entry ...，说明该包发布时缺少 OpenClaw
运行时所需的 JavaScript 文件。这是插件打包问题，不是本地配置
问题。发布者重新发布已编译的
JavaScript 后，更新或重新安装该插件；或者在修复包可用前禁用/卸载该插件。

当已发布的运行时文件与源条目不在
相同路径时，请使用 openclaw.runtimeExtensions。存在时，runtimeExtensions 必须包含
与每个 extensions 条目一一对应的条目。列表不匹配会导致安装和
插件发现失败，而不是静默回退到源路径。如果你还
发布 openclaw.setupEntry，请为其构建后的
JavaScript 对等文件使用 openclaw.runtimeSetupEntry；声明后该文件是必需的。

{
  "name": "@acme/openclaw-plugin",
  "openclaw": {
    "extensions": ["./src/index.ts"],
    "runtimeExtensions": ["./dist/index.js"]
  }
}

官方插件

迁移期间 OpenClaw 所有的 npm 包

ClawHub 是大多数插件的主要分发路径。当前打包的
OpenClaw 版本已经内置许多官方插件，因此在常规设置中无需
单独 npm 安装。在每个 OpenClaw 所有插件都
迁移到 ClawHub 之前，OpenClaw 仍会在 npm 上发布一些 @openclaw/* 插件包，
用于旧版/自定义安装和直接 npm 工作流。

如果 npm 报告某个 @openclaw/* 插件包已弃用，该包
版本来自较旧的外部包列车。请使用
当前 OpenClaw 的内置插件或本地检出，直到发布更新的 npm 包。

核心（随 OpenClaw 发布）

anthropic, byteplus, cloudflare-ai-gateway, github-copilot, google,
huggingface, kilocode, kimi-coding, minimax, mistral, qwen,
moonshot, nvidia, openai, opencode, opencode-go, openrouter,
qianfan, synthetic, together, venice,
vercel-ai-gateway, volcengine, xiaomi, zai

- memory-core - 内置记忆搜索（默认通过 plugins.slots.memory）
- memory-lancedb - 基于 LanceDB 的长期记忆，支持自动召回/捕获（设置 plugins.slots.memory = "memory-lancedb"）

请参阅 [Memory LanceDB](/zh-CN/plugins/memory-lancedb)，了解 OpenAI 兼容的
嵌入设置、Ollama 示例、召回限制和故障排除。

elevenlabs, microsoft

- browser - 用于浏览器工具、openclaw browser CLI、browser.request Gateway 网关方法、浏览器运行时以及默认浏览器控制服务的内置浏览器插件（默认启用；替换它之前请禁用）
- copilot-proxy - VS Code Copilot Proxy 桥接器（默认禁用）

正在寻找第三方插件？请参阅 ClawHub。

配置

{
  plugins: {
    enabled: true,
    allow: ["voice-call"],
    deny: ["untrusted-plugin"],
    load: { paths: ["~/Projects/oss/voice-call-plugin"] },
    entries: {
      "voice-call": { enabled: true, config: { provider: "twilio" } },
    },
  },
}

plugins.allow 是独占的。当它非空时，只有列出的插件可以加载或暴露工具，即使 tools.allow 包含 "*" 或某个插件拥有的特定工具名称。如果工具允许列表引用插件工具，请将所属插件 id 添加到 plugins.allow，或移除 plugins.allow；openclaw doctor 会对此形态发出警告。

对于新配置，plugins.bundledDiscovery 默认为 "allowlist"，因此限制性的 plugins.allow 清单也会阻止被省略的内置提供商插件，包括运行时 Web 搜索提供商发现。Doctor 会在迁移期间为较旧的限制性允许列表配置标记 "compat"，这样升级会保留旧版内置提供商行为，直到操作者选择更严格的模式。空的 plugins.allow 仍会被视为未设置/开放。

通过 /plugins enable 或 /plugins disable 做出的配置更改会触发进程内 Gateway 网关插件重新加载。新的 Agent 轮次会从刷新的插件注册表重建其工具列表。安装、更新和卸载等会更改源的操作仍会重启 Gateway 网关进程，因为已导入的插件模块无法安全地就地替换。

openclaw plugins list 是本地插件注册表/配置快照。其中的 enabled 插件表示持久化注册表和当前配置允许该插件参与。它不能证明已在运行的远程 Gateway 网关已经重新加载或重启到相同的插件代码。在带有包装进程的 VPS/容器设置中，请将重启或触发重新加载的写入发送给实际的 openclaw gateway run 进程，或在重新加载报告失败时，对正在运行的 Gateway 网关使用 openclaw gateway restart。

- 已禁用：插件存在，但启用规则将其关闭。配置会保留。
- 缺失：配置引用了发现未找到的插件 id。
- 无效：插件存在，但其配置与声明的 schema 不匹配。Gateway 网关启动时只会跳过该插件；openclaw doctor --fix 可以通过禁用无效条目并移除其配置负载来隔离该条目。

发现与优先级

OpenClaw 按以下顺序扫描插件（第一个匹配项获胜）：

plugins.load.paths - 显式文件或目录路径。指回
OpenClaw 自身打包内置插件目录的路径会被忽略；
运行 openclaw doctor --fix 可移除这些过时别名。

\<workspace\>/.openclaw/<plugin-root>/*.ts 和 \<workspace\>/.openclaw/<plugin-root>/*/index.ts。

~/.openclaw/<plugin-root>/*.ts 和 ~/.openclaw/<plugin-root>/*/index.ts。

随 OpenClaw 一起发布。许多默认启用（模型提供商、语音）。
其他插件需要显式启用。

打包安装和 Docker 镜像通常会从已编译的 dist/extensions 树解析内置插件。如果一个内置插件源目录被绑定挂载到匹配的打包源路径之上，例如 /app/extensions/synology-chat，OpenClaw 会将该挂载的源目录视为内置源覆盖，并在打包的 /app/dist/extensions/synology-chat bundle 之前发现它。这样可以让维护者容器循环继续工作，而无需将每个内置插件都切回 TypeScript 源。设置 OPENCLAW_DISABLE_BUNDLED_SOURCE_OVERLAYS=1 可强制使用打包的 dist bundle，即使存在源覆盖挂载也是如此。

启用规则

• plugins.enabled: false 会禁用所有插件，并跳过插件发现/加载工作
• plugins.deny 始终优先于允许
• plugins.entries.\<id\>.enabled: false 会禁用该插件
• 工作区来源的插件默认禁用（必须显式启用）
• 除非被覆盖，否则内置插件遵循内建的默认启用集合
• 独占槽位可以强制启用为该槽位选定的插件
• 当配置命名插件拥有的界面时，一些内置的选择加入插件会自动启用，例如提供商模型引用、渠道配置或 harness 运行时
• 当 plugins.enabled: false 处于活动状态时，过时的插件配置会保留；如果你想移除过时 id，请在运行 Doctor 清理前重新启用插件
• OpenAI 系列 Codex 路由保持独立的插件边界：
  openai-codex/* 属于 OpenAI 插件，而内置 Codex
  app-server 插件由规范的 openai/* agent 引用、显式的
  provider/model agentRuntime.id: "codex"，或旧版 codex/* model 引用选择

排查运行时钩子

如果某个插件出现在 plugins list 中，但 register(api) 副作用或钩子没有在实时聊天流量中运行，请先检查这些项：

• 运行 openclaw gateway status --deep --require-rpc，并确认活动的
  Gateway 网关 URL、配置文件、配置路径和进程就是你正在编辑的对象。
• 在插件安装/配置/代码更改后重启实时 Gateway 网关。在包装容器中，PID 1 可能只是 supervisor；请重启或向子级 openclaw gateway run 进程发送信号。
• 使用 openclaw plugins inspect <id> --runtime --json 确认钩子注册和诊断。非内置会话钩子，例如 before_model_resolve、before_agent_reply、before_agent_run、llm_input、llm_output、before_agent_finalize 和 agent_end，需要 plugins.entries.<id>.hooks.allowConversationAccess=true。
• 对于模型切换，优先使用 before_model_resolve。它会在 Agent 轮次的模型解析前运行；llm_output 只会在一次模型尝试产出 assistant 输出后运行。
• 要证明有效的会话模型，请使用 openclaw sessions 或 Gateway 网关 session/status 界面；调试提供商负载时，请用 --raw-stream --raw-stream-path <path> 启动 Gateway 网关。

插件工具设置缓慢

如果 Agent 轮次在准备工具时似乎停滞，请启用 trace 日志并检查插件工具工厂耗时行：

openclaw config set logging.level trace
openclaw logs --follow

查找：

[trace:plugin-tools] factory timings ...

摘要会列出总工厂耗时和最慢的插件工具工厂，包括插件 id、声明的工具名称、结果形态，以及该工具是否可选。当单个工厂至少耗时 1 秒，或总插件工具工厂准备至少耗时 5 秒时，慢速行会提升为警告。

OpenClaw 会为具有相同有效请求上下文的重复解析缓存成功的插件工具工厂结果。缓存键包括有效运行时配置、工作区、agent/session id、沙箱策略、浏览器设置、交付上下文、请求者身份和所有权状态，因此依赖这些可信字段的工厂会在上下文变化时重新运行。

如果某个插件主导耗时，请检查其运行时注册：

openclaw plugins inspect <plugin-id> --runtime --json

然后更新、重新安装或禁用该插件。插件作者应将昂贵的依赖加载移动到工具执行路径之后，而不是在工具工厂内部执行。

重复的渠道或工具所有权

症状：

• channel already registered: <channel-id> (<plugin-id>)
• channel setup already registered: <channel-id> (<plugin-id>)
• plugin tool name conflict (<plugin-id>): <tool-name>

这些表示有多个已启用插件试图拥有相同的渠道、设置流程或工具名称。最常见的原因是外部渠道插件安装在一个现在已提供相同渠道 id 的内置插件旁边。

调试步骤：

• 运行 openclaw plugins list --enabled --verbose 查看每个已启用插件及其来源。
• 对每个疑似插件运行 openclaw plugins inspect <id> --runtime --json，并比较 channels、channelConfigs、tools 和诊断。
• 安装或移除插件包后，运行 openclaw plugins registry --refresh，使持久化元数据反映当前安装。
• 在安装、注册表或配置更改后重启 Gateway 网关。

修复选项：

• 如果一个插件有意替换另一个同渠道 id 的插件，首选插件应声明 channelConfigs.<channel-id>.preferOver，并填入较低优先级的插件 id。请参阅 /plugins/manifest#replacing-another-channel-plugin。
• 如果重复是意外的，请使用 plugins.entries.<plugin-id>.enabled: false 禁用一侧，或移除过时的插件安装。
• 如果你显式启用了两个插件，OpenClaw 会保留该请求并报告冲突。请为该渠道选择一个所有者，或重命名插件拥有的工具，使运行时界面明确无歧义。

插件槽位（独占类别）

某些类别是独占的（一次只能有一个处于活动状态）：

{
  plugins: {
    slots: {
      memory: "memory-core", // or "none" to disable
      contextEngine: "legacy", // or a plugin id
    },
  },
}

CLI 参考

openclaw plugins list                       # compact inventory
openclaw plugins list --enabled            # only enabled plugins
openclaw plugins list --verbose            # per-plugin detail lines
openclaw plugins list --json               # machine-readable inventory
openclaw plugins search <query>            # search ClawHub plugin catalog
openclaw plugins inspect <id>              # static detail
openclaw plugins inspect <id> --runtime    # registered hooks/tools/CLI/gateway methods
openclaw plugins inspect <id> --json       # machine-readable
openclaw plugins inspect --all             # fleet-wide table
openclaw plugins info <id>                 # inspect alias
openclaw plugins doctor                    # diagnostics
openclaw plugins registry                  # inspect persisted registry state
openclaw plugins registry --refresh        # rebuild persisted registry
openclaw doctor --fix                      # repair plugin registry state

openclaw plugins install <package>         # install from npm by default
openclaw plugins install clawhub:<pkg>     # install from ClawHub only
openclaw plugins install npm:<pkg>         # install from npm only
openclaw plugins install git:<repo>        # install from git
openclaw plugins install git:<repo>@<ref>  # install from git ref
openclaw plugins install <spec> --force    # overwrite existing install
openclaw plugins install <path>            # install from local path
openclaw plugins install -l <path>         # link (no copy) for dev
openclaw plugins install <plugin> --marketplace <source>
openclaw plugins install <plugin> --marketplace https://github.com/<owner>/<repo>
openclaw plugins install <spec> --pin      # record exact resolved npm spec
openclaw plugins install <spec> --dangerously-force-unsafe-install
openclaw plugins update <id-or-npm-spec> # update one plugin
openclaw plugins update <id-or-npm-spec> --dangerously-force-unsafe-install
openclaw plugins update --all            # update all
openclaw plugins uninstall <id>          # remove config and plugin index records
openclaw plugins uninstall <id> --keep-files
openclaw plugins marketplace list <source>
openclaw plugins marketplace list <source> --json

# Verify runtime registrations after install.
openclaw plugins inspect <id> --runtime --json

# Run plugin-owned CLI commands directly from the OpenClaw root CLI.
openclaw <plugin-command> --help

openclaw plugins enable <id>
openclaw plugins disable <id>

内置插件随 OpenClaw 一起发布。许多插件默认启用（例如内置模型提供商、内置语音提供商和内置浏览器插件）。其他内置插件仍需要 openclaw plugins enable <id>。

--force 会原地覆盖已安装的插件或钩子包。对已跟踪的 npm 插件进行常规升级时，请使用 openclaw plugins update <id-or-npm-spec>。它不支持与 --link 一起使用；--link 会复用源路径，而不是复制到托管安装目标。

当 plugins.allow 已设置时，openclaw plugins install 会先把已安装插件的 id 添加到该允许列表，然后启用它。如果同一个插件 id 存在于 plugins.deny 中，安装会移除这条过期的拒绝项，这样显式安装的插件在重启后即可立即加载。

OpenClaw 会保留一个持久化的本地插件注册表，作为插件清单、贡献所有权和启动规划的冷读模型。安装、更新、卸载、启用和禁用流程在更改插件状态后都会刷新该注册表。同一个 plugins/installs.json 文件会在顶层 installRecords 中保存持久安装元数据，并在 plugins 中保存可重建的清单元数据。如果注册表缺失、过期或无效，openclaw plugins registry --refresh 会基于安装记录、配置策略以及清单/包元数据重建其清单视图，而不会加载插件运行时模块。

在 Nix 模式（OPENCLAW_NIX_MODE=1）下，插件生命周期变更命令会被禁用。请改为通过该安装的 Nix 源来管理插件包选择和配置；对于 nix-openclaw，请从 Agent 优先的快速开始开始。openclaw plugins update <id-or-npm-spec> 适用于已跟踪的安装。传入带 dist-tag 或精确版本的 npm 包规格时，会把包名解析回已跟踪的插件记录，并记录新的规格以供未来更新。传入不带版本的包名会把精确固定的安装移回注册表的默认发布线。如果已安装的 npm 插件已匹配解析后的版本和记录的构件身份，OpenClaw 会跳过更新，不会下载、重新安装或重写配置。
当 openclaw update 在 beta 频道运行时，默认线的 npm 和 ClawHub 插件记录会先尝试 @beta，如果不存在插件 beta 版本，则回退到默认/latest。精确版本和显式标签会保持固定。

--pin 仅适用于 npm。它不支持与 --marketplace 一起使用，因为市场安装会持久化市场源元数据，而不是 npm 规格。

--dangerously-force-unsafe-install 是针对内置危险代码扫描器误报的应急覆盖开关。它允许插件安装和插件更新在内置 critical 发现项之后继续执行，但仍不会绕过插件 before_install 策略阻断或扫描失败阻断。安装扫描会忽略常见测试文件和目录，例如 tests/、__tests__/、*.test.* 和 *.spec.*，以避免阻断打包的测试 mock；声明的插件运行时入口点即使使用这些名称之一，仍会被扫描。

此 CLI 标志仅适用于插件安装/更新流程。由 Gateway 网关支持的技能依赖安装会改用对应的 dangerouslyForceUnsafeInstall 请求覆盖，而 openclaw skills install 仍然是独立的 ClawHub 技能下载/安装流程。

如果你在 ClawHub 发布的插件被扫描隐藏或阻断，请打开 ClawHub 仪表板，或运行 clawhub package rescan <name> 请求 ClawHub 重新检查。--dangerously-force-unsafe-install 只影响你自己机器上的安装；它不会请求 ClawHub 重新扫描插件，也不会让被阻断的发布变为公开。

兼容包会参与同一个插件列表/检查/启用/禁用流程。当前运行时支持包括包内 Skills、Claude 命令技能、Claude settings.json 默认值、Claude .lsp.json 和清单声明的 lspServers 默认值、Cursor 命令技能，以及兼容的 Codex 钩子目录。

openclaw plugins inspect <id> 还会报告检测到的包能力，以及由包支持的插件中受支持或不受支持的 MCP 和 LSP 服务器条目。

市场源可以是 ~/.claude/plugins/known_marketplaces.json 中的 Claude 已知市场名称、本地市场根目录或 marketplace.json 路径、形如 owner/repo 的 GitHub 简写、GitHub 仓库 URL，或 git URL。对于远程市场，插件条目必须保留在克隆的市场仓库内，并且只能使用相对路径源。

参见 openclaw plugins CLI 参考了解详情。

插件 API 概览

Native plugins 会导出一个入口对象，该对象暴露 register(api)。旧插件可能仍将 activate(api) 用作遗留别名，但新插件应使用 register。

export default definePluginEntry({
  id: "my-plugin",
  name: "My Plugin",
  register(api) {
    api.registerProvider({
      /* ... */
    });
    api.registerTool({
      /* ... */
    });
    api.registerChannel({
      /* ... */
    });
  },
});

OpenClaw 会加载入口对象，并在插件激活期间调用 register(api)。加载器仍会为旧插件回退到 activate(api)，但内置插件和新的外部插件应将 register 视为公共契约。

api.registrationMode 会告诉插件其入口为何被加载：

会打开套接字、数据库、后台工作线程或长生命周期客户端的插件入口，应使用 api.registrationMode === "full" 保护这些副作用。发现加载与激活加载分开缓存，并且不会替换正在运行的 Gateway 网关注册表。发现是非激活的，但不是免导入的：OpenClaw 可能会求值可信插件入口或频道插件模块来构建快照。保持模块顶层轻量且无副作用，并将网络客户端、子进程、监听器、凭证读取和服务启动移到完整运行时路径之后。

常见注册方法：

类型化生命周期钩子的钩子保护行为：

• before_tool_call：{ block: true } 是终止性的；较低优先级的处理器会被跳过。
• before_tool_call：{ block: false } 是空操作，不会清除更早的阻断。
• before_install：{ block: true } 是终止性的；较低优先级的处理器会被跳过。
• before_install：{ block: false } 是空操作，不会清除更早的阻断。
• message_sending：{ cancel: true } 是终止性的；较低优先级的处理器会被跳过。
• message_sending：{ cancel: false } 是空操作，不会清除更早的取消。

Codex 原生 app-server 会将桥接后的 Codex 原生工具事件运行回此钩子表面。插件可以通过 before_tool_call 阻止原生 Codex 工具，通过 after_tool_call 观察结果，并参与 Codex PermissionRequest 审批。该桥接目前还不会重写 Codex 原生工具参数。确切的 Codex 运行时支持边界见 Codex harness v1 支持契约。

有关完整的类型化钩子行为，请参阅 SDK 概览。

相关

• 构建插件 - 创建你自己的插件
• 插件包 - Codex/Claude/Cursor 包兼容性
• 插件清单 - 清单 schema
• 注册工具 - 在插件中添加智能体工具
• 插件内部机制 - 能力模型和加载流水线
• ClawHub - 第三方插件发现