From 183729613c0031b35ce1cb61fe02920a288decec Mon Sep 17 00:00:00 2001 From: FenjuFu <92919259+FenjuFu@users.noreply.github.com> Date: Mon, 24 Aug 2026 13:39:49 +0800 Subject: [PATCH] docs(faq): add CLI namespace-not-found and PostgreSQL permission entries (#743) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add two entries collected from community support, to both the zh docs and the en i18n mirror: - FAQ: installing a skill via CLI reporting `namespace not found` — set the registry / log in with an API token, and use the correct namespace slug (`@team/skill` -> `team--skill`); the web UI Install button provides a ready-made command. - Troubleshooting: PostgreSQL container failing to start with `operation not permitted` on bind mounts — fix data volume ownership (`chown 999:999`), check SELinux, or use the `runtime.sh` script. Signed-off-by: FenjuFu <92919259+FenjuFu@users.noreply.github.com> --- document/docs/05-reference/faq.md | 11 +++++++++++ document/docs/05-reference/troubleshooting.md | 8 ++++++++ .../current/05-reference/faq.md | 10 ++++++++++ .../current/05-reference/troubleshooting.md | 8 ++++++++ 4 files changed, 37 insertions(+) diff --git a/document/docs/05-reference/faq.md b/document/docs/05-reference/faq.md index eb2d352c..94c5ea4c 100644 --- a/document/docs/05-reference/faq.md +++ b/document/docs/05-reference/faq.md @@ -34,6 +34,17 @@ description: 常见问题解答 3. 是否包含必需的 SKILL.md 4. SKILL.md frontmatter 格式是否正确 +### 使用 CLI 安装技能时报 `namespace not found`？ + +多数情况是 CLI 没有指向你自己的 SkillHub 实例，或命名空间格式不对： + +1. **配置 registry 并登录**：用环境变量或 `--registry` 指向你的实例，例如 + `clawhub --registry https://skillhub.your-company.com install `；登录需要先在 Web 控制台生成 API Token。 +2. **命名空间 slug 格式**：全局命名空间的技能直接用名字（如 `my-skill`）；团队命名空间要用 `team--skill` 的形式（`@team/skill` → `team--skill`）。 +3. 最稳妥的方式是直接在 SkillHub Web 界面点技能的「安装」按钮，复制其中已经带好正确 registry 与命名空间的命令。 + +> SkillHub 同时提供 `clawhub` 和 `skillhub` 两种 CLI，用法见各自 README；通过 OpenClaw 对话安装技能时，底层同样调用 CLI。 + ## 开发相关 ### 如何扩展 OAuth Provider？ diff --git a/document/docs/05-reference/troubleshooting.md b/document/docs/05-reference/troubleshooting.md index 492d910f..05d8a41f 100644 --- a/document/docs/05-reference/troubleshooting.md +++ b/document/docs/05-reference/troubleshooting.md @@ -22,6 +22,14 @@ description: 常见问题诊断和解决方案 - Redis 连接失败 - 环境变量缺失 +### PostgreSQL 容器启动报 `operation not permitted`（写 `postmaster.pid` / `pg_wal` 失败） + +内网/自建环境使用绑定挂载时常见，根因是**数据卷目录权限**与容器内 `postgres` 用户（UID 999）不匹配： + +1. 将数据卷目录属主改为 postgres 用户：`chown -R 999:999 <数据目录>`。 +2. 在 RHEL/CentOS 上检查 SELinux 是否拦截了容器写入宿主目录。 +3. 推荐直接使用官方 `runtime.sh` 部署脚本，它会处理相关初始化步骤，避免手工编写 compose 时漏配权限。 + ## 上传失败 ### 技能包上传失败 diff --git a/document/i18n/en/docusaurus-plugin-content-docs/current/05-reference/faq.md b/document/i18n/en/docusaurus-plugin-content-docs/current/05-reference/faq.md index 137a90e7..04ec69b8 100644 --- a/document/i18n/en/docusaurus-plugin-content-docs/current/05-reference/faq.md +++ b/document/i18n/en/docusaurus-plugin-content-docs/current/05-reference/faq.md @@ -34,6 +34,16 @@ Check: 3. Whether required SKILL.md is included 4. Whether SKILL.md frontmatter format is correct +### CLI install reports `namespace not found`? + +Usually the CLI is not pointing at your own SkillHub instance, or the namespace format is wrong: + +1. **Set the registry and log in**: point at your instance via an environment variable or `--registry`, e.g. `clawhub --registry https://skillhub.your-company.com install `. Logging in requires an API Token generated in the web console first. +2. **Namespace slug format**: skills in the global namespace use the bare name (e.g. `my-skill`); team namespaces use the `team--skill` form (`@team/skill` → `team--skill`). +3. The most reliable way is to click the **Install** button on the skill's page in the SkillHub web UI and copy the command, which already includes the correct registry and namespace. + +> SkillHub ships both a `clawhub` and a `skillhub` CLI (see their respective READMEs); installing a skill through an OpenClaw conversation calls the CLI under the hood as well. + ## Development Related ### How to extend OAuth Provider? diff --git a/document/i18n/en/docusaurus-plugin-content-docs/current/05-reference/troubleshooting.md b/document/i18n/en/docusaurus-plugin-content-docs/current/05-reference/troubleshooting.md index 95716b51..e1eec4b9 100644 --- a/document/i18n/en/docusaurus-plugin-content-docs/current/05-reference/troubleshooting.md +++ b/document/i18n/en/docusaurus-plugin-content-docs/current/05-reference/troubleshooting.md @@ -22,6 +22,14 @@ description: Common problem diagnosis and solutions - Redis connection failed - Environment variables missing +### PostgreSQL container fails to start with `operation not permitted` (cannot write `postmaster.pid` / `pg_wal`) + +Common in intranet / self-hosted environments using bind mounts. The root cause is a mismatch between the **data volume directory permissions** and the container's `postgres` user (UID 999): + +1. Change the data volume directory owner to the postgres user: `chown -R 999:999 `. +2. On RHEL/CentOS, check whether SELinux is blocking the container from writing to the host directory. +3. Prefer the official `runtime.sh` deployment script, which handles the relevant initialization steps and avoids permission gaps from hand-written compose files. + ## Upload Failed ### Skill Package Upload Failed