文档指南¶

此目录负责文档编写、已发布链接规则以及文档 i18n 策略。

源文件所有权¶

• 维护者在 openclaw/clawhub 中编写 /clawhub/** 页面。scripts/docs-sync-publish.mjs 会从该源替换整个发布 docs/clawhub/ 树。不要在此处保留已编写的副本。
• 因此，本仓库不保存任何 /clawhub/** 页面源，即使 docs/docs.json 在导航中列出了它们。两种链接审计模式都接受这些已声明路由，无需 ClawHub 检出；未声明路由仍会失败。
• 将 OpenClaw 特定的技能和插件指南保留在所属的 OpenClaw 文档中，例如 docs/cli/skills.md 和 docs/cli/plugins.md。这些指南涵盖安装、更新、验证、移除和发布信任。独立的 ClawHub CLI 和发布参考属于上游。
• 对于指向 /clawhub/** 的链接，普通的 pnpm docs:check-links 不会检查片段。要验证锚点，请运行 pnpm docs:check-links:anchors，并将 OPENCLAW_DOCS_SYNC_CLAWHUB_REPO 指向实际的 ClawHub 源检出。没有该源时，指向已声明镜像路由的片段会被报告为未验证。
• 已批准的发布文档可以拥有一个标记的 CHANGELOG/<version>.md 镜像。更改这些源时，请在同一 PR 中使用 pnpm changelog:from-docs 重新生成该完整扁平 Markdown 文件，保留标记的有序源列表和冻结的 CHANGELOG/records/<version>.md。pnpm changelog:check 验证标记镜像；它不会转换未触及的历史发布。openclaw-changelog-update 技能拥有命令和独立的发布后发布序列。
• 生成的 CHANGELOG/** 产物保留精确迁移或镜像的字节。与根 changelog 一样，它们被排除在通用格式化之外；请改用所属生成器和 pnpm changelog:check。

本地预览¶

• 运行 pnpm docs:dev -- --page <route> 以使用当前网站 UI 预览未提交的英文内容。重复 --page 可预览更多页面；预览限制为 30 个页面。
• 将 openclaw/docs 克隆为主检出旁边的 ../openclaw-docs，并先在那里运行 npm ci。对于另一个检出，请传递 --site-repo <path> 或设置 OPENCLAW_DOCS_SITE_REPO。
• 预览读取此检出，并且只写入被忽略的 .cache/docs-preview/ 输出。它不会同步、翻译或发布。编辑后请重新运行。对于没有服务器的产物，使用 --build-only；或更改回环服务器默认端口 4173 时使用 --port <port>。提供需要 Python 3。
• 网站样式和渲染器更改属于 openclaw/docs；内容、导航、重定向和共享发布解析器仍保留在此处。

已发布链接规则¶

• 发布流水线从 openclaw/docs 发布仓库将文档推送到 https://docs.openclaw.ai，该仓库拥有网站设计和 UI。
• docs/**/*.md 中的内部文档链接必须保持根相对路径，且不带 .md 或 .mdx 后缀（示例：[Config](gateway/configuration.md)）。
• 章节交叉引用应使用根相对路径上的锚点（示例：[Hooks](gateway/config-hooks.md#hooks)）。
• 锚点 ID 来自 scripts/lib/docs-markdown.mjs 中的共享发布解析器。使用 pnpm docs:check-links:anchors 验证它们。已发布的标题 ID 保持稳定。兼容性别名永远不会替换现有目标。
• 当标题措辞可能会变化时，请使用显式的 <a id="stable-section-name" /> 作为持久章节链接。重新组织内容时，保留现有命名锚点。
• README 和其他 GitHub 渲染的文档应保持绝对文档 URL，以便链接在文档站点之外也能工作。
• 文档内容必须保持通用：不要包含个人设备名称、主机名或本地路径。使用类似 user@gateway-host 和 ~/path/to/skills 的占位符。
• 对于令牌、API 密钥和凭据片段，请遵循 Secret 占位符约定。保持示例值明显为假，以便密钥扫描器保持安静。

文档内容规则¶

• 当 node-version.mjs、package.json 的 engines 字段、src/infra/runtime-guard.ts 中的 Bun 最低版本，或 src/infra/sqlite-runtime-version.ts 中的 SQLite 下限发生变化时，请更新 docs/install/node-compatibility.md 和 docs/install/bun-compatibility.md 中的支持版本和历史表格。
• 对于文档、UI 文案和选择器列表，请按字母顺序排列服务和提供商。唯一例外是明确描述运行时顺序或自动检测顺序的章节。
• 保持捆绑插件命名与根 AGENTS.md 中全仓库插件术语规则一致。
• CI 会验证看起来像完整 openclaw.json 文档的 JSON5 和 JSON 配置围栏是否符合 schema。pnpm docs:check-config-examples 运行该验证。故意部分或遗留片段通过在围栏信息字符串中使用 validate=false 选择退出。
• 生成的文档，切勿手动编辑：docs/plugins/reference/**、docs/plugins/reference.md 和 docs/plugins/plugin-inventory.md 来自 pnpm plugins:inventory:gen。docs/maturity/** 来自 pnpm maturity:render。
• 发布和打包从 pnpm docs:list --headings 生成公共和打包文档映射。仅在 docs/docs_map.md 保留小型源存根。切勿提交展开的标题镜像。

内部文档¶

• 长期存在的私有运维文档应放在此仓库之外的私有运维仓库中。
• 仓库本地的内部草稿/镜像文档可以放在被忽略的 docs/internal/ 下。
• 切勿将 docs/internal/** 页面添加到 docs/docs.json 导航中，或从公共文档链接它们。
• 如果页面后来被强制添加，scripts/docs-sync-publish.mjs 会从公共 openclaw/docs 发布仓库中排除并修剪 docs/internal/**。
• 根 docs/AGENTS.md 和 docs/CLAUDE.md 是仓库说明，不是公共页面。源同步会排除并修剪它们；翻译定稿会移除它们的语言副本。docs/reference/templates/** 下的公共工作区模板仍会发布。
• 内部文档可以提及仓库路径、私有应用名称、1Password 条目名称和 runbook，但绝不能包含密钥值。

成熟度记分卡编辑¶

• taxonomy.yaml 和 qa/maturity-scores.yaml 是源输入。
• docs/maturity/ 下生成的成熟度文档是投影。不要手动编辑其中的分数、LTS、分类体系、QA 配置或证据表。
• scripts/qa/render-maturity-docs.ts 负责生成。使用 pnpm maturity:render 刷新已提交的文档，并使用 pnpm maturity:check 验证它们。
• .github/workflows/maturity-scorecard.yml 渲染工件预览，并可打开生成文档的 PR。.github/workflows/openclaw-release-checks.yml 会为其发布 QA 触发它。
• 除非维护者明确要求提供经过清理的已提交投影，否则保持 GitHub Actions 工件中确定性的 qa-evidence.json.scorecard 数据。
• 人工覆盖必须在 PR 中更改源状态，并说明原因以及公开或已脱敏的证据。

文档 i18n¶

• 本仓库不维护外语文档。生成的发布输出位于单独的 openclaw/docs 仓库中（通常在本地克隆为 ../openclaw-docs）。
• 不要在此处添加或编辑 docs/<locale>/** 下的本地化文档。
• 将本仓库中 OpenClaw 拥有的英文文档以及术语表文件视为唯一事实来源。ClawHub 英文源遵循上述源所有权。
• 流水线：在此处更新英文文档，按需更新 docs/.i18n/glossary.<locale>.json，然后让发布仓库同步，并在 openclaw/docs 中运行 scripts/docs-i18n。
• 在重新运行 scripts/docs-i18n 之前，为新的技术术语、页面标题和简短导航标签添加术语表条目。对于每个必须保留英文或使用固定翻译的术语，添加一个条目。
• pnpm docs:check-i18n-glossary 是用于已更改的英文文档标题和简短内部文档标签的防护机制。
• 翻译记忆位于发布仓库中生成的 docs/.i18n/*.tm.jsonl 文件中。
• 参见 docs/.i18n/README.md。