企业官网建设流程全解析

OpenClaw Claws 完整指南：用版本化代理包创建、检查、更新与移除 Agent

【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 🦞项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw

导读

openclaw claws是 OpenClaw 中一个实验性的命令面，用于把"一个全新 Agent"封装成可移植、可审计、带版本号的Claw 代理包：包内可描述 Agent 的便携身份、工作区文件、技能（skills）、插件（plugins）、MCP 服务器与定时任务（cron jobs），并通过本地目录、CLAW.md清单或分组 JSON 清单来驱动create / validate / dev / build / inspect / add / status / update / remove / export十个子命令的完整生命周期。读完本文你将掌握：如何从零编写并校验一个 Claw 包、如何用离线 dry-run 计划安全地新增 Agent、如何审计已安装状态与漂移（drift）、如何精准地更新与移除一个 Claw，以及如何把已安装 Agent 反向导出为可移植包。

实验性声明：Claws 属于实验特性，其 schema、命令输出与生命周期可能随版本变化。启用命令面需要显式设置环境变量：

export OPENCLAW_EXPERIMENTAL_CLAWS=1

该门控在源码中由 src/claws/experimental.ts 实现：OPENCLAW_EXPERIMENTAL_CLAWS取值为1或true时才会注册claws命令，否则会抛出 "Claws are experimental and disabled" 的错误。从源码结构看，CLI 注册逻辑位于 src/cli/claws-cli.ts，十个子命令均通过动态导入按需加载实现模块。

对于人类可读的claws add，OpenClaw 会在改动状态前打印实验性警告；JSON 模式保持 stdout 机器可读，并通过"stability": "experimental"字段标识契约（见 src/claws/types.ts 中的CLAW_OUTPUT_STABILITY）。当前 CLI 只读取本地包目录、CLAW.md或分组 JSON 清单；通过 ClawHub 发布、搜索与整包安装属于独立的注册表轨道，不在本命令面内。

创建 Claw 包：包结构、清单与便携 Profile

一个 Claw 包至少包含package.json、CLAW.md清单，以及清单引用的常规 profile、引导说明（bootstrap）或便携资源。package.json通过openclaw.claw字段指向根目录的CLAW.md：

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

CLAW.md以 YAML frontmatter 开头，非空的 Markdown 正文即便携 Agent 提示词，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.

schemaVersion必须为1（对应源码中的CLAW_SCHEMA_VERSION = 1）。清单结构在 src/claws/schema.ts 中由严格的 Zod schema 校验，例如agent.id必须以小写字母开头、只允许小写字母/数字/下划线/连字符且长度不超过 64；cron表达式必须是五字段标准格式并通过computeNextRunAtMs验证时区。

常规 profile：profiles/openclaw.yml

OpenClaw 会自动发现可选的profiles/openclaw.yml文件，无需在清单中声明指针。其他 harness（如profiles/codex.yml）可以各自发现自己的常规 profile，而不改变便携清单。OpenClaw 只在自己的 inspect/add/update/export 流程中校验和使用这个 profile，它不会被复制到用户正常的 OpenClaw 配置路径。

较早的metadata.openclaw.config指针已废弃但仍会被读取，保证按旧契约发布的包继续可用；读取时会产生deprecated_openclaw_profile_pointer警告。迁移方式是把文件移动到profiles/openclaw.yml并删除 metadata 条目。源码 src/claws/openclaw-profile.ts 明确了两种拒绝情形：指针不是包内相对.yml/.yaml路径时返回invalid_openclaw_profile_path；指针指向其他文件而profiles/openclaw.yml同时存在时返回conflicting_openclaw_profile_pointer。

一个典型的 OpenClaw 包 profile 示例：

schemaVersion: 1 agent: tools: allow: [read, write, cron] deny: [exec] fs: workspaceOnly: true memory: search: enabled: true rememberAcrossConversations: true sources: [memory, sessions]

profile 的完整可配置面（来自 src/claws/types.ts 的ClawOpenClawProfile）包括：

• agent.tools.profile：选择运行中 OpenClaw 注册的内置工具 profile（如coding、messaging等）；agent.tools.allow / alsoAllow / deny进一步细化授权。
• agent.tools.fs.workspaceOnly: true：仅允许工作区内的文件系统访问。
• agent.memory.search：开启便携的memory/sessions记忆检索源与跨会话记忆。
• agent.sandbox：mode（off/non-main/all）、scope（session/agent/shared）、workspaceAccess（none/ro/rw）。
• agent.heartbeat：every（时长字符串）、activeHours（start/end/timezone）、lightContext、isolatedSession、timeoutSeconds。
• agent.humanDelay：mode（off/natural/custom）与minMs/maxMs。
• extensions：harness 专属的扩展插件声明。

关键安全约束（源码级）

• 工具授权：显式tools.allow列表中的每一项都必须是"有界的"授权。源码isBoundedClawToolGrant会拒绝通配符、group:plugins与bundle-mcp这类动态选择器；coding/messagingprofile 含动态bundle-mcp选择器，因此选择这些 profile 的 Claw 必须额外提供有界的tools.allow交集，MCP 授权必须写成具体生成的工具名（如github__list_issues），不能冻结bundle-mcp本身。
• allow 与 alsoAllow 互斥：tools.allow不能与alsoAllow组合；需要 profile 之外工具时应使用独立 allowlist（即上面的写法）。
• 不得削弱主机关机：Claw 不能把workspaceOnly设为false。
• sessions 源要求显式 opt-in：声明sessions检索源必须同时设置rememberAcrossConversations: true，否则 schema 校验直接报错（见 src/claws/schema.ts 中memory.search的superRefine）。
• 体积与文件形态：常规 profile 限制 256 KiB，必须是 JSON 兼容 YAML，不得使用别名/锚点/标签/合并键，且必须是包内的常规文件（拒绝符号链接与硬链接——读取时通过fsSafeRoot以symlinks: "reject"、hardlinks: "reject"加载）。
• 主机策略仍然生效：Claw 不携带自定义 profile 定义、provider、凭据、绑定或本地记忆路径，主机策略会继续约束这些设置。

扩展声明：harness 专属插件需求

profile 还可以声明 harness 专属的扩展插件需求：

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）。规范插件预检（canonical plugin preflight）会解析出确切工件，并报告当前 OpenClaw 适配器映射了哪些组件、哪些仍不可用；缺失身份、完整性、格式检测或适配器身份时会阻塞。扩展型插件复用现有插件安装器与所有权模型，属于共享主机需求，而不是 Claw 自有成员或第二套包系统。OpenClaw 在 apply 时忽略外来 harness 的 profile；status 与 doctor 会报告适配器映射漂移或不可用的检查结果；export 会把扩展型插件写回profiles/openclaw.yml，而不会在便携packages列表中重复。

包与工作区路径安全

包与工作区路径必须始终位于包根目录之内，路径检查逻辑见 src/claws/path-containment.ts。清单限制为 1 MiB，包元数据限制为 256 KiB，工作区源另有逐文件与总量限制，且工作区源拒绝符号链接父目录。清单目标也不能重复声明：工作区目标重复、BOOTSTRAP.md与workspace.files冲突、cron job id 重复、包引用重复等都会在 schema 阶段被拒绝（src/claws/schema.ts 的manifestSchema.superRefine）。

工作区引导文件与可移植资产

CLAW.md正文是SOUL.md的首选便携来源；当正文非空时不要再声明SOUL.md侧车文件。其他引导文件使用具名条目（源码中CLAW_BOOTSTRAP_FILE_NAMES支持AGENTS.md、SOUL.md、IDENTITY.md、TOOLS.md、HEARTBEAT.md），额外文件使用包相对 source 与工作区相对 target：

{ "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 工作区，并通过原生工作区 bootstrap 状态记录进度。一旦 Agent 消费或删除了它，Claw update 不会重新创建；因此包根BOOTSTRAP.md也不能再通过workspace.files声明。Claw 移除时，仅当未变更且仍处于 pending 状态、且校验了记录的摘要（digest）后才删除包 bootstrap；被编辑过的 bootstrap 内容与引导期间创建的文件会被保留。

技能与插件：精确版本 + 完整性预检

技能与插件使用确切的 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" } ] }

dry-run 会走现有的技能与插件预检路径，在征得同意前解析确切工件、完整性与任何 ClawHub 信任警告；警告会保留在完整性绑定的计划中。每个需求显示为 satisfied（已满足）、missing-installable（缺失可安装）、conflicting（冲突）或 setup-required（需要设置）之一。精确计划同意会批准缺失安装，OpenClaw 在创建 Agent 或工作区前先完成这些规范插件动作。apply 复用匹配的工件并记录该 Claw 是"引入"还是"引用"了每个资源；插件始终是进程级 OpenClaw 能力，而非按 Agent 安装。

定时任务：绑定到新 Agent 的 Gateway 调度

Cron 任务为新 Agent 声明定时工作：

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

Claw 复用现有 Gateway 调度器，并把创建的 job 绑定到新 Agent；add/update 期间，Claw 会等待目标 Agent 出现在 Gateway 的应用配置中之后才创建 job。预览、溯源、状态与移除都会覆盖这些 job，但不改变普通 cron 命令的行为。移除时会通过 Gateway 重新读取实时 job，如果其自有定义在计划之后被改动则保留。

MCP 服务器：复用mcp.servers配置模型

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

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

环境引用保持为引用（${STATUSPAGE_TOKEN}形式），Claw 不会内嵌解析后的密钥值——schema 中的environmentReference正则强制 MCP 环境值必须是未解析的${ENV_VAR}引用，且拒绝isDangerousHostEnvVarName命中的危险环境变量键。无冲突的新声明成为托管资源，完全一致或共享的现有声明则被引用。schema 还支持 stdio（command/args/env）与远端（url+transport: sse|streamable-http，远程 URL 必须 HTTPS，仅精确 loopback 主机例外）两种形态，并允许toolFilter的 include/exclude 精确名与*通配过滤。预览、溯源、状态、导出与移除遵循与其他 Claw 资源相同的所有权策略。

本地编写：create / validate / dev / build 四步流程

创建一个最小项目、校验可发布输入、离线预览完整的 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

各子命令行为（实现见 src/cli/claws-cli.project.ts）：

• create：只写入package.json与CLAW.md，拒绝向非空目录合并；可用--name、--agent-id定制。
• validate：要求openclaw.claw指向根CLAW.md，拒绝 package 脚本与生命周期钩子，发现唯一无歧义的项目根，并报告被排除在包外的文件。
• dev：校验并构建与发布完全一致的工件，再让该工件通过规范 add 规划器运行。它不安装包、不联系 ClawHub、不启动 Agent 回合、不启用调度、不投递消息、不修改 OpenClaw 状态——需要在线预检的依赖会以 blocker 形式出现，而不是削弱这一边界。可用--agent-id或--workspace预览无冲突的本地目标。
• build：写出确定性的 npm 兼容.tgz，带package/根目录。只包含包元数据、CLAW.md、可选BOOTSTRAP.md、OpenClaw profile 与清单选中的源文件；测试、缓存、环境或未选中的凭据、未选中的文件、历史工件与源码控制状态都不进包。选中的源字节就是包内容，因此作者不得选中含密钥的文件。build 拒绝覆盖已有工件、报告 SHA-256 完整性，并在成功前通过规范 Claw reader 重新打开验证。

检查与预览：inspect / add --dry-run / planIntegrity

校验源而不规划任何本地改动；对 OpenClaw profile 扩展，inspect 还会执行规范的只读工件探测，并报告映射与不可用组件：

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

预览所有提议的生命周期动作：

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

计划报告：派生的 Agent 与工作区、每一个提议动作、前置条件、blocker、不同的能力升级（capability escalations）与planIntegrity摘要。能力记录显示确切的包、MCP、定时工作、沙箱、工具或心跳效果。创建 Agent 前请先审阅计划，然后用--plan-integrity绑定同意：

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

--yes单独使用是不够的：OpenClaw 会重建计划，当源、目标或实时配置在预览之后发生变化时拒绝同意。包默认值与本地状态冲突时，在预览与 apply 阶段都要用--agent-id或--workspace指定无冲突目标。对于一次性 profile 与并行校验，请显式传--workspace；OPENCLAW_STATE_DIR只迁移运行时状态，不改变默认工作区位置。

添加一个 Claw 的执行顺序（见 src/claws/add.ts）：先落实已同意的共享插件需求，然后创建新 Agent 与工作区配置、播种可选首次运行说明、写入声明的工作区资产、落实工作区技能，最后记录包、MCP 与 cron 溯源。已有文件不会被覆盖，自有内容发生漂移时重试会 fail-closed。

检查已安装状态：status / doctor 与所有权模型

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

status对比已安装 Agent 与其记录的 workspace/package/MCP/cron 溯源和当前状态，并报告原生首次运行 bootstrap 是否仍为 pending；它只报告不完整安装、缺失资源与漂移，不改变本地状态。openclaw doctor增加 Claw 专属诊断：不完整的所有权记录、不安全的托管文件，以及无法与实时 Gateway 库存对证的 cron job。

Claw 溯源区分两种关系：

• Managed（托管）：该 Claw 引入并当前管理该资源；未变更且无冲突所有者时是清理候选。
• Referenced（引用）：资源独立存在或为共享；移除只释放本 Claw 的引用，默认保留资源。

这不是引用计数。普通 plugin、skill 与 agent 命令保持既有行为，Claw 只是在上面叠加溯源与受保护的生命周期操作。

更新已安装 Claw：from 源、能力升级与部分失败

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

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

计划对比当前溯源与实时状态和目标清单，报告 agent、workspace、package、MCP、cron 与所有权变更，包括能力升级与 blocker。能力升级有独立的机器可读记录，人类输出中带!行并给出精确脱敏效果；同时包含已解析的包完整性、安装身份、信任警告与剩余本地设置前置条件。删除某个包声明只会释放该 Claw 的边，不会在 update 期间卸载工件。最终的精确planIntegrity确认既绑定披露集，也绑定普通内容变更；主机可以用同一套记录做单独对话框或聚合式多 Agent 审阅。

应用经过精确审阅的计划需要显式同意：

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

OpenClaw 会重建计划，并在每次变更前对自有状态做 compare-and-swap。删除的包声明释放依赖边而不卸载工件；cron 变更会重读实时调度器定义，遇到操作者漂移即停止。包安装器、源配置写入器与 Gateway 调度器不是一个事务：如果外部变更后无法证明补偿（compensation）已完成，OpenClaw 报告错误码update_partial，附带结构化status: partial，保留不确定的溯源并停止。此时应检查claws status、受影响的资源与openclaw doctor，在重试或移除任何东西之前重新预览。

移除已安装 Claw：清理语义、fence 与部分失败

先预览移除再选择清理范围：

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

默认行为是移除符合条件的托管状态并释放引用状态。符合条件、Claw 自有的调度以一次性移除动作出现；服务中的 Gateway 还会把该 Agent 的 config-owned heartbeat 与 Skill Workshop 监控器（包括被禁用的监控器）识别为移除动作。普通调度、导入的 heartbeat 任务、无法对证的监控器与位于其他调度器存储中的 job 仍是 blocker。

被修改的文件与存在其他当前所有者的资源会被保留或阻塞。清理选择是计划摘要的一部分，--yes永远不会扩大它们。全局安装的插件会保留，同时释放本 Claw 的引用；移除报告 Claw add 引入了哪些被保留的需求，若要卸载进程级插件请另行使用普通插件生命周期。

数据库、监控器与删除 fence

包含另一 Agent 已注册数据库的目录会被保留，即使该数据库已关闭。如果移除报告 Agent 数据库仍处于打开状态，请先停止命令或重启持有它的 Gateway 再重试。预览可离线进行；持久化的监控器行在服务 Gateway 能验证所有权之前始终是 blocker。实际移除需要运行中的 Gateway，且对同一 config、状态数据库与调度器存储具有管理员权限，即使已无调度行。Gateway 会请求取消已同意的定时工作，并等待其运行中的代码结束后再执行本地清理——删除 job 行或收到取消结果并不能证明其代码已停止。配置移除后，清理还会等待 Gateway 应用该变更并移除监控器。数据库租约被拒绝时，Agent 配置、执行审批与创建历史保持不变。

如果取消、排空（drainage）或配置收敛无法完成，移除报告partial与monitor_cleanup_failed，并保留删除 fence 与清理记录，本地文件保持完整。解决报告的问题、再次预览并重试移除；fence 会阻止新运行与 Agent 重建，直到清理完成，重启 Gateway 也不会丢弃未完成的移除。

如果 Agent 从配置移除后会话清理或转录归档导出失败，移除报告partial与session_cleanup_failed并保留清理记录。修正错误、再次预览移除并重试完成清理，然后才能重建 Agent。

引用资源的精确选择

要移除没有其他当前所有者的未变更 Claw 引入引用，预览与 apply 都加--remove-unused；要精确选择引用资源，重复使用--remove-referenced：

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

--force-referenced只在审阅过显示的依赖者、独立所有者与既有来源之后使用；它允许在存在这些冲突时进行选择性清理，但不会跳过 plan-integrity 同意。

导出已安装 Agent：生成可移植 Claw 包

导出会创建新包目录，目标已存在或托管状态漂移时失败：

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

--bootstrap <path>可附加一份经人工审阅的 Markdown 文件作为包根BOOTSTRAP.md。导出会自动重新发出未变更且仍 pending 的包 bootstrap；工作区内漂移（被编辑、不安全或不可读）的包 bootstrap 会以bootstrap_drifted使导出失败，与托管工作区文件的workspace_files_drifted同理——此时可传--bootstrap <path>提供经审阅的替换文件继续导出。已被 Agent 消费的 bootstrap 属于已完成生命周期状态，导出会省略BOOTSTRAP.md而不是失败。导出器会校验完成的包，校验失败时删除新输出目录。Bootstrap 是包作者创作的提示内容：不得包含凭据、令牌、私密回答或机器专属路径；导出不会推断问题、渲染个人数据模板、持久化回答或增加单独设置生命周期。

结果包含package.json、规范CLAW.md与托管工作区侧车文件。托管SOUL.md内容在非空 UTF-8 且合并文档符合清单上限时作为CLAW.md正文输出；否则保留为显式侧车，保证包仍可导入。它是可移植 Claw 包而非整实例备份：无关 Agent、凭据、会话与无主的本地状态都不包含。

命令参考与退出码

使用--json获取实验性机器可读输出。成功命令退出0；校验错误、被阻塞的计划、缺失目标以及failed/partial变更结果退出1。检查 JSON 的status与error.code字段，以区分未做任何变更的失败与需要claws status、openclaw doctor并在重试前重新预览的部分结果。

更多资源

• Agents
• Skills
• Plugins
• Cron jobs
• MCP 配置

进一步阅读源码：清单与 profile 的 schema 校验位于 src/claws/schema.ts，常规 profile 的发现与安全加载位于 src/claws/openclaw-profile.ts，共享类型与稳定性常量位于 src/claws/types.ts，CLI 命令注册位于 src/cli/claws-cli.ts，fixtures 示例位于 src/claws/fixtures/（含incident-response.claw.json、minimal-agent.claw.json及其对应profiles/*.openclaw.yml），完整测试覆盖见 src/claws/lifecycle.e2e.test.ts、src/claws/add.test.ts、src/claws/update-plan.test.ts 等。

【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 🦞项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw