skill-template/docs/RUNTIME.md

运行时契约（环境变量与目录）

本文档定义技能进程建议依赖的外部条件，便于不同 Claw 宿主统一接入。业务技能应读取环境变量，而不是在代码里写死路径或用户名。

必需程度说明

• 强烈建议：生产环境由宿主注入；技能应对缺失给出明确错误提示，避免静默写到意外目录。
• 可选：没有时技能仍可部分运行（例如只读 health）。

变量一览

CLAW_DATA_ROOT（强烈建议）

用户数据根。多个技能、多个用户的数据都在此根之下分区。

• 典型场景：组织策略指定的盘符路径或 ~/.your-org-data。
• 未设置时：技能不应猜测网络盘；开发机 fallback 仅限 optional/paths_snippet.py 中说明的情形。

CLAW_USER_ID（强烈建议）

当前会话所代表的用户或工作空间 ID（字符串）。与数据隔离强相关。

• 用于拼接：{CLAW_DATA_ROOT}/{CLAW_USER_ID}/{skill_slug}/
• 未设置时：可用匿名占位（如 _anon）仅用于开发，生产应显式注入。

CLAW_SKILLS_ROOT（可选）

多个技能以并列目录安装时的根路径，例如：

{CLAW_SKILLS_ROOT}/skill-a/scripts/...
{CLAW_SKILLS_ROOT}/skill-b/scripts/...

编排型技能若需要通过子进程调用兄弟技能，应基于该变量定位脚本，避免写死绝对路径。

JIANGCHANG_SKILLS_ROOT（可选）

与 CLAW_SKILLS_ROOT 同义；匠厂桌面宿主可只注入此名。未设置时，技能可从「本技能 scripts/ 的上一级目录的上一级」推断并列根（OpenClaw 开发仓与 skills/<slug>/ 解压布局均适用）。

JIANGCHANG_APP_ROOT（可选）

匠厂应用安装根。未设置且未设置上述技能根时，Windows 下会尝试用默认 D:\AI\jiangchang：若存在子目录 skills 且其下像并列技能安装，则技能根为 {APP}/skills；否则若 {APP} 下直接可见各技能 slug 子目录，则 {APP} 即技能根。其他平台默认回退为 ~/.openclaw/skills。

加密发布包布局

CI 产物 ZIP 解压后与仓库技能目录结构一致：含 SKILL.md 与 scripts/（PyArmor 输出在 scripts/ 内）。宿主启动入口应为 python scripts/main.py（工作目录为技能根）。

本技能推荐的数据目录

{CLAW_DATA_ROOT}/{CLAW_USER_ID}/{skill_slug}/

• skill_slug：与 SKILL.md 内 metadata.skill.slug 一致。
• 在此目录下可放置 SQLite 文件、缓存、上传临时文件等；不要向版本库提交该目录内容。

标准输出约定（建议）

为便于宿主与自动化解析，建议：

• 致命错误：单行前缀 ERROR:，例如 ERROR:MISSING_ENV_CLAW_DATA_ROOT
• 成功：人类可读一行或多行；若有机读需求，可用 JSON 单行输出并在 SKILL.md 中说明格式。

与具体宿主的关系

若某宿主文档规定了另一套变量名，应在宿主启动技能子进程时注入为本文档中的 CLAW_* 名称，或在技能内使用一层极薄的 getenv 封装（见 optional/paths_snippet.py 注释示例）。不要在业务模块中散落多套变量名判断。