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_CLAWS1该门控在源码中由 src/claws/experimental.ts 实现OPENCLAW_EXPERIMENTAL_CLAWS取值为1或true时才会注册claws命令否则会抛出 Claws are experimental and disabled 的错误。从源码结构看CLI 注册逻辑位于 src/cli/claws-cli.ts十个子命令均通过动态导入按需加载实现模块。对于人类可读的claws addOpenClaw 会在改动状态前打印实验性警告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必须以小写字母开头、只允许小写字母/数字/下划线/连字符且长度不超过 64cron表达式必须是五字段标准格式并通过computeNextRunAtMs验证时区。常规 profileprofiles/openclaw.ymlOpenClaw 会自动发现可选的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.sandboxmodeoff/non-main/all、scopesession/agent/shared、workspaceAccessnone/ro/rw。agent.heartbeatevery时长字符串、activeHoursstart/end/timezone、lightContext、isolatedSession、timeoutSeconds。agent.humanDelaymodeoff/natural/custom与minMs/maxMs。extensionsharness 专属的扩展插件声明。关键安全约束源码级工具授权显式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.0format断言 OpenClaw 必须识别的工件格式openclaw、claude、codex或cursor。规范插件预检canonical plugin preflight会解析出确切工件并报告当前 OpenClaw 适配器映射了哪些组件、哪些仍不可用缺失身份、完整性、格式检测或适配器身份时会阻塞。扩展型插件复用现有插件安装器与所有权模型属于共享主机需求而不是 Claw 自有成员或第二套包系统。OpenClaw 在 apply 时忽略外来 harness 的 profilestatus 与 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 绑定到新 Agentadd/update 期间Claw 会等待目标 Agent 出现在 Gateway 的应用配置中之后才创建 job。预览、溯源、状态与移除都会覆盖这些 job但不改变普通 cron 命令的行为。移除时会通过 Gateway 重新读取实时 job如果其自有定义在计划之后被改动则保留。MCP 服务器复用mcp.servers配置模型MCP 声明复用现有mcp.servers配置模型{ mcpServers: { statuspage: { command: npx, args: [--yes, acme/statuspage-mcp1.0.0], env: { STATUSPAGE_TOKEN: ${STATUSPAGE_TOKEN} } } } }环境引用保持为引用${STATUSPAGE_TOKEN}形式Claw 不会内嵌解析后的密钥值——schema 中的environmentReference正则强制 MCP 环境值必须是未解析的${ENV_VAR}引用且拒绝isDangerousHostEnvVarName命中的危险环境变量键。无冲突的新声明成为托管资源完全一致或共享的现有声明则被引用。schema 还支持 stdiocommand/args/env与远端urltransport: 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.tscreate只写入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 与并行校验请显式传--workspaceOPENCLAW_STATE_DIR只迁移运行时状态不改变默认工作区位置。添加一个 Claw 的执行顺序见 src/claws/add.ts先落实已同意的共享插件需求然后创建新 Agent 与工作区配置、播种可选首次运行说明、写入声明的工作区资产、落实工作区技能最后记录包、MCP 与 cron 溯源。已有文件不会被覆盖自有内容发生漂移时重试会 fail-closed。检查已安装状态status / doctor 与所有权模型openclaw claws status openclaw claws status incident-triage --json openclaw doctorstatus对比已安装 Agent 与其记录的 workspace/package/MCP/cron 溯源和当前状态并报告原生首次运行 bootstrap 是否仍为 pending它只报告不完整安装、缺失资源与漂移不改变本地状态。openclaw doctor增加 Claw 专属诊断不完整的所有权记录、不安全的托管文件以及无法与实时 Gateway 库存对证的 cron job。Claw 溯源区分两种关系Managed托管该 Claw 引入并当前管理该资源未变更且无冲突所有者时是清理候选。Referenced引用资源独立存在或为共享移除只释放本 Claw 的引用默认保留资源。这不是引用计数。普通 plugin、skill 与 agent 命令保持既有行为Claw 只是在上面叠加溯源与受保护的生命周期操作。更新已安装 Clawfrom 源、能力升级与部分失败默认情况下update 使用添加 Claw 时记录的源。当源已迁移或想测试另一个包目录时用--fromopenclaw 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_RUNOpenClaw 会重建计划并在每次变更前对自有状态做 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-referencedopenclaw claws remove incident-triage \ --dry-run \ --remove-referenced plugin:acme/audit-plugin2.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、凭据、会话与无主的本地状态都不包含。命令参考与退出码CommandPurposeclaws create [path]创建最小本地 Claw 项目。claws validate [path]校验项目输入与包内容。claws dev [path]本地构建并预览不做任何变更。claws build [path] --out tgz构建确定性包工件。claws inspect source校验包目录或分组清单。claws add source预览或创建一个新 Agent 与工作区。claws status [claw-or-agent]报告已安装状态、所有权与漂移。claws update claw-or-agent从所选源预览或应用变更。claws remove claw-or-agent预览或移除 Agent 与符合条件的资源。claws export agent --out path从已安装 Agent 创建可移植包。使用--json获取实验性机器可读输出。成功命令退出0校验错误、被阻塞的计划、缺失目标以及failed/partial变更结果退出1。检查 JSON 的status与error.code字段以区分未做任何变更的失败与需要claws status、openclaw doctor并在重试前重新预览的部分结果。更多资源AgentsSkillsPluginsCron jobsMCP 配置进一步阅读源码清单与 profile 的 schema 校验位于 src/claws/schema.ts常规 profile 的发现与安全加载位于 src/claws/openclaw-profile.ts共享类型与稳定性常量位于 src/claws/types.tsCLI 命令注册位于 src/cli/claws-cli.tsfixtures 示例位于 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考