> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# AGENTS

# 文档指南

此目录负责文档编写、Mintlify 链接规则和文档 i18n 策略。

## Mintlify 规则

* 文档托管在 Mintlify（`https://docs.openclaw.ai`）。
* `docs/**/*.md` 中的内部文档链接必须保持根相对路径，且不带 `.md` 或 `.mdx` 后缀（示例：`[Config](/gateway/configuration)`）。
* 章节交叉引用应在根相对路径上使用锚点（示例：`[Hooks](/gateway/configuration-reference#hooks)`）。
* 文档标题应避免使用长破折号和撇号，因为 Mintlify 的锚点生成在这些字符上很脆弱。
* README 和其他由 GitHub 渲染的文档应保留绝对文档 URL，这样链接在 Mintlify 之外也能工作。
* 文档内容必须保持通用：不要包含个人设备名称、主机名或本地路径；使用类似 `user@gateway-host` 的占位符。

## 文档内容规则

* 对于文档、UI 文案和选择器列表，除非该章节明确描述运行时顺序或自动检测顺序，否则服务/提供商应按字母顺序排列。
* 保持内置插件命名与根 `AGENTS.md` 中的全仓库插件术语规则一致。
* 生成的文档，不要手动编辑：`docs/plugins/reference/**`、`docs/plugins/reference.md` 和 `docs/plugins/plugin-inventory.md` 来自 `pnpm plugins:inventory:gen`；`docs/docs_map.md` 来自 `pnpm docs:map:gen`；`docs/maturity/**` 来自 `pnpm maturity:render`。

## 内部文档

* 长期保留的私有操作员文档应放在 `~/Projects/manager/docs/`。
* 仓库本地的内部草稿/镜像文档可以放在被忽略的 `docs/internal/` 下。
* 绝不要将 `docs/internal/**` 页面添加到 `docs/docs.json` 导航中，也不要从公开文档链接到它们。
* 如果某个页面后来被强制添加，`scripts/docs-sync-publish.mjs` 会从公开的 `openclaw/docs` 发布仓库中排除并清理 `docs/internal/**`。
* 内部文档可以提及仓库路径、私有应用名称、1Password 条目名称和运行手册，但绝不能包含密钥值。

## 成熟度评分卡编辑

`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 调度它。
除非维护者明确要求提交经过净化的投影，否则将确定性的 `qa-evidence.json.scorecard` 数据保留在 GitHub Actions 构件中。
人工覆盖必须在 PR 中更改源状态，并说明原因以及公开或已脱敏的证据。

## 文档 i18n

* 外语文档不在此仓库中维护。生成的发布输出位于单独的 `openclaw/docs` 仓库中（本地通常克隆为 `../openclaw-docs`）。
* 不要在这里的 `docs/<locale>/**` 下添加或编辑本地化文档。
* 将此仓库中的英文文档和词汇表文件视为事实来源。
* 流程：在这里更新英文文档，按需更新 `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`。