openclaw claws¶

A Claw 是针对一个新 OpenClaw agent 的版本化设置。它可以描述该 agent 的可移植身份、工作区文件、技能、插件、MCP 服务器和 cron 任务。特定 harness 的 agent 设置可以通过约定包配置文件承载。Claw 不会替换或修改现有 agent。

Claw 是实验性的。它们的 schema、命令输出和生命周期可能会发生变化。请显式启用命令面：

export OPENCLAW_EXPERIMENTAL_CLAWS=1

对于人类可读的 claws add，OpenClaw 会在更改状态前打印实验性警告。JSON 模式保持 stdout 为机器可读，并通过 "stability": "experimental" 标识契约。

当前 CLI 会读取本地包目录、CLAW.md 或分组的 JSON manifest。通过 ClawHub 发布、搜索和安装整个 Claw 属于独立的 registry 轨道，目前还不是这个命令面的一部分。

内置角色 Claw¶

内置的 coordinator、researcher、writer 和 reviewer 角色是位于源码检出目录 docs/reference/templates/roles/<role> 下的 Claw 源，不要求提供 package.json。可通过 预览与同意流程 使用 agents add --role 或 openclaw claws add docs/reference/templates/roles/<role>。agents team create 负责委托连接配置；一旦独立的 Claw profile 支持落地，角色 Claw 将携带这些设置。

创建 Claw 包¶

一个包包含 package.json、一个 CLAW.md manifest，以及该 manifest 使用的任何约定配置文件、bootstrap 指令或可移植资产：

{
  "name": "@acme/incident-triage-claw",
  "version": "1.0.0",
  "type": "module",
  "openclaw": { "claw": "CLAW.md" }
}

CLAW.md 以 YAML frontmatter 开头。非空的 Markdown 正文即为可移植 agent prompt。OpenClaw 会将其作为新 agent 的由 Claw 管理的 SOUL.md 应用：

---
schemaVersion: 1
agent:
  id: incident-triage
  name: Incident triage
workspace:
  bootstrapFiles: {}
packages: []
mcpServers: {}
cronJobs: []
---

# Incident triage

You review incoming incidents, identify severity and ownership, and leave a
concise handoff with evidence.

OpenClaw 会自动发现可选的 profiles/openclaw.yml 文件，无需 manifest 指针。其他 harness 可以在不改变可移植 manifest 的情况下，发现各自约定的配置文件，例如 profiles/codex.yml。

较旧的 metadata.openclaw.config 指针已弃用，但仍会被读取，因此基于它发布的包可以继续工作。读取该指针时会报告 deprecated_openclaw_profile_pointer 警告；请将该文件移至 profiles/openclaw.yml，并移除 metadata 条目。如果指针不是包内相对的 .yml/.yaml 路径，则会被拒绝；如果指针引用了其他文件，但同时存在 profiles/openclaw.yml，则会被视为冲突而拒绝。

schemaVersion: 1
agent:
  model:
    primary: acme/primary
    fallbacks: [acme/fallback]
  subagents:
    allowAgents: [researcher, writer]
    delegationMode: prefer
  tools:
    allow: [read, write, cron]
    deny: [exec]
    fs:
      workspaceOnly: true
  memory:
    search:
      enabled: true
      rememberAcrossConversations: true
      sources: [memory, sessions]

该配置文件只存在于 Claw 包内部。OpenClaw 在检查、添加、更新和导出该 Claw 时会验证并使用它；它不会被复制到用户的常规 OpenClaw 配置路径。其他 harness 会使用可移植 manifest，并且只解释各自约定的配置文件。

agent.model 选择一个必填的 primary 引用，以及可选的有序 fallbacks。每个引用都必须使用非空的 provider/model 形式；上面的 acme 引用只是示例，应替换为你已经配置的模型。agent.subagents.allowAgents 列出委托目标 agent ID，使用与 Claw agent 相同的小写 ID 规则。空列表明确表示不授予任何委托目标。可选的 delegationMode 接受 suggest 或 prefer。这两个对象都是可选的，并会拒绝未知键。

添加和更新计划会披露模型与委托配置。本地目录中缺少的模型，以及本地 agent 名册中缺少的目标，会产生通知，而不会造成阻塞。精确的计划同意会按声明应用这些值，因此团队可以一次安装一个 Claw。使用之前，请先配置不可用的模型并安装缺失的目标。claws dev 会离线检查本地目录。Status 会通过 agent 配置漂移检测任一字段的变化；export 会保留显式的 agent 设置，而不会复制继承的默认值。

同样严格的版本 1 schema 继续接受分组的 JSON manifests。分组的 JSON 会发现相同的约定配置文件，而不是嵌入 OpenClaw 设置的第二份副本。本页其余 schema 片段使用 JSON，等效键也可在 CLAW.md frontmatter 中使用。

OpenClaw 包配置文件可以使用显式的 tools.allow 列表，或选择运行中的 OpenClaw 版本注册的任何内置工具配置文件。coding 和 messaging 配置包含动态的 bundle-mcp 选择器，因此选择任一配置文件的 Claw 还必须提供一个受限的 tools.allow 交集。请将任何 MCP 授权命名为具体的生成工具名称，例如 github__list_issues；包本身不能冻结 bundle-mcp。

其他情况下，可以使用 alsoAllow、deny 以及 tools.fs.workspaceOnly: true 对配置文件进行细化。tools.allow 不能与 alsoAllow 组合使用；当包需要所选配置文件之外的工具时，请像上面那样使用独立的允许列表。Claw 不能将 workspaceOnly 设置为 false 来削弱主机文件系统限制。Claw 还可以设置 memory.search.enabled，选择可移植的 memory 和 sessions 数据源，并通过 rememberAcrossConversations 选择加入跨对话记忆。声明 sessions 数据源需要该选择加入。主机策略仍然会约束这些设置，Claw 也不会携带自定义配置文件定义、提供者、凭据、绑定或本地记忆路径。约定配置文件限制为 256 KiB，必须是 JSON 兼容的 YAML，不得使用别名、锚点、标签或合并键，并且必须是包内的常规文件，不能是符号链接或硬链接。

An OpenClaw profile may also declare harness-specific extension requirements:

schemaVersion: 1
agent: {}
extensions:
  - id: incident-tools
    kind: plugin
    format: claude
    source: clawhub
    ref: "@acme/incident-tools"
    version: 2.0.0

format 断言 OpenClaw 必须检测的工件格式（openclaw、claude、codex 或 cursor）。标准插件预检会解析精确工件，并报告当前 OpenClaw 适配器映射了哪些组件，以及哪些仍不可用。缺失的身份、完整性、格式检测或适配器身份会阻止应用。扩展支持的插件使用现有的插件安装器和所有权模型；它们是共享主机要求，而不是 Claw 拥有的成员或第二个包系统。

OpenClaw 在应用期间忽略外部 harness 配置文件。包完整性仍然覆盖已发布包的每个字节，而开发快照会绑定可移植清单、引导和工作区源，以及所选的 OpenClaw 配置文件。状态和 doctor 会报告适配器映射漂移或不可用的检查。导出会将扩展支持的插件写入 profiles/openclaw.yml，并且不会在可移植的 packages 列表中重复它们。

包和工作区路径必须保持在包根目录内。清单限制为 1 MiB，包元数据限制为 256 KiB，工作区源则强制执行单独的每文件限制和聚合限制。工作区源还会拒绝符号链接父目录。

CLAW.md 正文是 SOUL.md 的首选可移植源；当正文非空时，不要同时声明 SOUL.md sidecar 文件。其他引导文件使用命名条目，而附加文件使用相对于包的源和相对于工作区的目标：

{
  "workspace": {
    "bootstrapFiles": {
      "AGENTS.md": { "source": "workspace/AGENTS.md" }
    },
    "files": [
      {
        "source": "workspace/reference/policy.md",
        "path": "reference/policy.md"
      }
    ]
  }
}

附加文件是可移植资产机制。作者可以将包源组织在诸如 assets/、schemas/、templates/ 和 examples/ 等目录下，然后使用 workspace.files 将它们映射到新的 agent 工作区。Apply 会将这些目标记录为受管文件；update 会协调未更改的受管资产，remove 会保留已修改或用户拥有的文件。

可选的包根目录 BOOTSTRAP.md 提供对话式首次运行说明。OpenClaw 会将其注入新的 agent 工作区，并通过原生工作区引导状态记录进度。一旦 agent 消费或移除它，Claw update 就不会重新创建它。因此，根目录 BOOTSTRAP.md 不能同时通过 workspace.files 声明。Claw 移除操作会在验证其记录的摘要后，删除未更改且仍待处理的包引导文件；它会保留已编辑的引导内容以及入职期间创建的文件。

Skills 和插件使用精确的 ClawHub 版本：

{
  "packages": [
    {
      "kind": "skill",
      "source": "clawhub",
      "ref": "incident-triage",
      "version": "1.0.0"
    },
    {
      "kind": "plugin",
      "source": "clawhub",
      "ref": "@acme/audit-plugin",
      "version": "2.0.0"
    }
  ]
}

试运行使用现有的 skill 和插件预检路径，在同意之前解析精确工件、完整性以及任何 ClawHub 信任警告。该警告在完整性绑定的计划中保持可见。每个需求都会显示为已满足、缺失可安装、冲突或需要设置。精确计划同意会批准缺失的安装；OpenClaw 会在创建 agent 或工作区之前完成这些标准插件操作。Apply 会重用匹配的工件，并记录 Claw 是引入还是引用了每个资源。插件仍然是进程范围的 OpenClaw 能力，而不是按 agent 安装。

Cron 任务为新的 agent 声明计划工作：

{
  "cronJobs": [
    {
      "id": "daily-summary",
      "name": "Daily incident summary",
      "schedule": { "cron": "0 9 * * *", "timezone": "UTC" },
      "session": "isolated",
      "message": "Summarize active incidents."
    }
  ]
}

Claws 使用现有的 Gateway 调度器，并将创建的任务绑定到新的 agent。在 add 或 update 期间创建任务之前，Claws 会等待目标 agent 出现在 Gateway 的已应用配置中。Preview、provenance、status 和 removal 会覆盖这些任务，而不会改变普通 cron 命令的行为。Removal 会通过 Gateway 重新读取实时任务，并在其拥有的定义在计划之后发生变化时保留该任务。

MCP 声明使用现有的 mcp.servers 配置模型：

{
  "mcpServers": {
    "statuspage": {
      "command": "npx",
      "args": ["--yes", "@acme/statuspage-mcp@1.0.0"],
      "env": { "STATUSPAGE_TOKEN": "${STATUSPAGE_TOKEN}" }
    }
  }
}

环境变量引用仍然是引用；Claws 不会嵌入已解析的密钥值。无冲突的声明会成为受管声明，而完全匹配现有或共享的声明则会被引用。Preview、provenance、status、export 和 removal 遵循与其他 Claw 资源相同的所有权策略。

本地创建¶

创建一个最小项目，验证其可发布输入，离线预览其完整的 OpenClaw add 计划，并构建一个不可变的包工件：

openclaw claws create ./incident-triage
openclaw claws validate ./incident-triage
openclaw claws dev ./incident-triage
openclaw claws build ./incident-triage --out ./incident-triage-1.0.0.tgz

create 只写入 package.json 和 CLAW.md，并拒绝合并到非空目录。项目验证要求 openclaw.claw 指向根目录 CLAW.md，拒绝包脚本和生命周期钩子，发现唯一且无歧义的项目根目录，并报告从包中排除的文件。

dev 会验证并构建将要发布的同一工件，然后让该工件通过标准 add 计划器。它不会安装包、联系 ClawHub、启动 agent 回合、启用计划、传递消息或修改 OpenClaw 状态。需要在线预检的依赖项会显示为阻止项，而不是削弱该边界。使用 --agent-id 或 --workspace 预览无冲突的本地目标。

build 会写入一个确定性的、兼容 npm 的 .tgz，其根目录为 package/。 仅包含包元数据、CLAW.md、可选的 BOOTSTRAP.md、OpenClaw 配置文件，以及由清单选定的源文件。测试、缓存、环境凭据或未选定的凭据、未选定的文件、先前产物以及源控制状态均保留在包外。被选定的源字节属于包内容，因此作者不得选定包含秘密的文件。构建拒绝覆盖已有产物，报告其 SHA-256 完整性，并在成功前通过标准 Claw 读取器重新打开它。

检查与预览¶

在不规划本地更改的情况下验证源。对于 OpenClaw 配置文件扩展，inspect 还会执行标准的只读产物探测，并报告已映射和不可用的组件：

openclaw claws inspect ./incident-triage.claw.json

预览所有建议的生命周期操作：

openclaw claws add ./incident-triage.claw.json --dry-run --json

计划报告派生的代理和工作区、每个建议操作、前置条件、阻塞项、不同的能力升级，以及一个 planIntegrity 摘要。能力记录显示确切的包、MCP、计划任务、沙箱、工具或心跳影响。在创建代理之前审阅计划：

openclaw claws add ./incident-triage.claw.json \
  --yes \
  --plan-integrity <SHA256_FROM_DRY_RUN>

仅使用 --yes 是不够的。当源、目标或实时配置在预览后发生变化时，OpenClaw 会重建计划并拒绝授权。当包默认值与本地状态冲突时，在预览和应用期间使用 --agent-id 或 --workspace。对于临时配置文件和并行验证，请显式传递 --workspace；OPENCLAW_STATE_DIR 会迁移运行时状态，但不会更改默认工作区位置。

添加 Claw 会先实现已同意的共享插件要求，然后创建新的代理和工作区配置，预置可选的首次运行指令，写入声明的工作区资产，实现工作区技能，并记录包、MCP 和 cron 来源。现有文件不会被覆盖；当受管内容发生漂移时，重试会失败关闭。

在本地 Gateway 运行时，Claw add 和 update 会先应用其插件要求，然后继续代理、工作区、MCP 和 cron 阶段。一次有界交接会在包租约释放后重新加载受影响的包；它不会重启 Gateway 或重新加载无关插件。一个实时要求批次最多支持 64 个插件包。常规的包、能力和信任确认仍然适用。

如果安装已保存但运行时激活未得到确认，命令会报告这一区别并在后续阶段之前停止。检查报告的错误并再次预览后再重试。精确重试会重用已保存的包并重试激活。如果后续 Claw 阶段失败，已成功实现的共享要求仍保持已安装。已禁用或仅元数据条目保持未评估状态；其源尚未通过运行时执行验证。在没有本地 Gateway 时，安装保留现有的重启要求。

检查已安装状态¶

openclaw claws status
openclaw claws status incident-triage --json
openclaw doctor

status 将已安装的代理及其记录的工作区、包、MCP 和 cron 来源与当前状态进行比较。它还报告原生首次运行 bootstrap 是否仍处于待处理状态。它报告不完整的安装、缺失资源和漂移，而不更改本地状态。openclaw doctor 为不完整的属主记录、不安全的受管文件以及无法与实时 Gateway 清单相互印证的 cron 任务添加 Claw 特定诊断。

Claw 来源区分两种关系：

• 受管： 该 Claw 引入并当前管理此资源。当资源未更改且没有冲突属主时，它是清理候选项。
• 引用： 该资源独立存在或为共享。删除会释放此 Claw 的引用，并默认保留该资源。

这不是引用计数。常规插件、技能和代理命令保持其现有行为；Claws 在其上添加来源和受保护的生命周期操作。

更新已安装的 Claw¶

默认情况下，update 使用添加 Claw 时记录的源。当该源已移动或正在测试另一个包目录时，使用 --from：

openclaw claws update incident-triage --dry-run --json
openclaw claws update incident-triage \
  --from ./incident-triage-next \
  --dry-run --json

计划将当前来源和实时状态与目标清单进行比较。它报告代理、工作区、包、MCP、cron 和属主更改，包括能力升级和阻塞项。能力升级具有单独的机器可读记录，以及在人类输出中带有精确脱敏效果的 ! 行。已解析的包完整性、安装身份、信任警告和剩余的本地设置前置条件均包含在内。移除包声明会释放此 Claw 的依赖边，而不会在更新期间卸载产物。最终的精确 planIntegrity 确认会绑定该已披露集合以及常规内容更改。宿主可以使用相同记录进行单独对话框或聚合多代理审查。使用显式授权应用经过审阅的精确计划：

openclaw claws update incident-triage \
  --yes \
  --plan-integrity <SHA256_FROM_DRY_RUN>

OpenClaw 会重建计划，并在每次变更前对受管状态执行比较并交换。移除的包声明会释放依赖边，而不会卸载产物。Cron 更改会重新读取实时调度器定义，并在操作员漂移时停止。包安装器、源配置写入器和 Gateway 调度器不是一个事务。如果在外部变更后无法证明补偿，OpenClaw 会报告错误代码 update_partial，并带有结构化 status: partial，保留不确定的来源，然后停止。检查 claws status、受影响资源和 openclaw doctor；然后在重试或移除任何内容之前再次预览。

移除已安装的 Claw¶

在选择清理之前，先预览移除操作：

openclaw claws remove incident-triage --dry-run --json
openclaw claws remove incident-triage \
  --yes \
  --plan-integrity <SHA256_FROM_DRY_RUN>

默认情况下，移除符合条件的受管状态并释放被引用的状态。 符合条件的由 Claw 拥有的计划会作为移除操作出现一次。正在服务的 Gateway 还会将该代理的配置拥有的心跳以及 Skill Workshop 监视器（包括已禁用的监视器）识别为移除操作。普通计划、 导入的心跳任务、未得到佐证的监视器，以及位于其他调度器存储中的任务 仍会构成阻塞。 已修改的文件以及具有其他当前所有者的资源会被保留或 阻塞。如果工作区包含未跟踪的文件，或其内容 无法完整检查（包括清理过程中子目录消失的情况），则工作区会被保留。 清理选择是计划摘要的一部分；--yes 永远不会扩大 这些选择。默认情况下，全局安装的插件会被保留，同时释放此 Claw 的引用。 移除操作会报告哪些保留的需求是由 Claw add 引入的；如果你打算卸载进程范围的插件， 请单独使用常规插件生命周期。

包含其他代理已注册数据库的目录会被保留，即使 该数据库已关闭。如果移除操作报告某个代理数据库 仍处于打开状态，请在重试前停止该命令或重启持有它的 Gateway。 预览可离线工作。已持久化的监视器行在正在服务的 Gateway 能够验证其所有权之前仍会构成阻塞。实际移除需要一个正在运行的 Gateway， 并且该 Gateway 需要对相同的配置、状态数据库和调度器 存储具有管理员访问权限，即使没有剩余的计划行也是如此。Gateway 会请求取消已同意的计划工作，并在本地清理前等待 其正在运行的代码完成。删除任务行或 收到其取消结果并不能证明其代码已停止。 配置移除后，清理还会等待 Gateway 应用该更改 并移除监视器。数据库租约拒绝会使代理配置、 执行批准和创建历史保持不变。

如果取消、排空或配置收敛无法完成，移除操作会报告 partial 并附带 monitor_cleanup_failed，同时保留其删除围栏和清理 记录。本地文件保持完整。解决报告的故障，再次预览， 然后重试移除。在清理完成之前，围栏会阻止新的运行和代理重建；重启 Gateway 不会丢弃未完成的移除。

如果代理从配置中移除后，会话清理或转录归档导出失败，移除操作会报告 partial 并附带 session_cleanup_failed，同时保留 其清理记录。更正报告的错误，再次预览移除，并重试 以在重新创建代理之前完成清理。

要移除未更改且没有其他当前所有者的由 Claw 引入的引用，请在预览和应用中都包含 --remove-unused。全局插件被排除在此通用清理模式之外。若要改为选择确切的被引用资源，请重复使用 --remove-referenced：

openclaw claws remove incident-triage \
  --dry-run \
  --remove-referenced 'plugin:@acme/audit-plugin@2.0.0'

仅在审查显示的依赖项、独立所有者和预先存在的来源后，才使用 --force-referenced。 它允许在存在这些冲突的情况下执行所选清理；它不会跳过计划完整性同意。

对于所选插件，正在服务的 Gateway 会撤回其运行时能力， 并在删除其已安装文件之前尝试清理。该命令会等待 运行时应用，并报告由此产生的 Gateway 代际，而不会 重启 Gateway。预览之后发生的所有权和工件更改需要新的计划。清理是尽力而为的：警告会出现在结果的 warnings 列表中以及人类可读输出中，而不会将已完成的移除变成失败结果。

如果包清理失败，移除操作会报告 partial 并附带 package_cleanup_failed， 同时保留其清理记录。之前的移除步骤不会回滚。 Gateway 运行时替换失败会停止剩余的包阶段， 并将未尝试的包报告为已保留，同时附带之前的结果和警告。 普通包错误会继续对其他选择进行尽力而为的清理。 解决报告的故障，再次预览并重试；连接丢失永远不会 导致自动本地卸载。

导出已安装的代理¶

导出会创建一个新的包目录，如果目标已存在或 受管状态已漂移，则失败：

openclaw claws export incident-triage --out ./incident-triage-export --json

使用 --bootstrap <path> 将一个明确审查过的 Markdown 文件作为包根目录中的 BOOTSTRAP.md 附加。导出会自动重新输出未更改且仍处于待处理状态的包引导。如果包引导在工作区中发生漂移 （被编辑、不安全或不可读），导出会以 bootstrap_drifted 失败，方式与受管工作区文件以 workspace_files_drifted 失败相同；传入 带有已审查替代文件的 --bootstrap <path> 仍可导出。代理已经消费的引导属于已完成的生命周期状态，因此导出会省略 BOOTSTRAP.md，而不是失败。导出器会验证已完成的包， 如果验证失败，则删除新的输出目录。引导是 包编写的提示内容：请勿包含凭据、令牌、私有 答案或特定于机器的路径。导出不会推断问题、渲染 个人数据模板、持久化答案或添加单独的设置生命周期。

结果包含 package.json、规范的 CLAW.md 以及受管工作区 伴随文件。当受管的 SOUL.md 内容是非空 UTF-8，且合并后的文档符合清单限制时，它会作为 CLAW.md 正文输出。否则， 导出会将其保留为显式伴随文件，以便包仍可导入。它 是一个可移植的 Claw 包，而不是整个实例的备份：无关的代理、 凭据、会话和无所有者的本地状态都会被排除。

命令参考¶

使用 --json 获取实验性的机器可读输出。

成功的命令退出码为 0。验证错误、被阻止的计划、缺失的目标，以及 failed 和 partial 两种变更结果都会以退出码 1 结束。检查 JSON 的 status 和 error.code 字段，以区分未发生任何变更的失败，与需要运行 claws status、openclaw doctor 并生成新的预览后才能重试的部分结果。

另请参阅¶

• 代理
• 技能
• 插件
• Cron 任务
• MCP 配置