Sync Docker Hub images to CNB.tool registry via GitHub Actions, solving domestic Docker pull failures for OpenClaw. Use when: - User needs to pull Docker ima...
--- name: docker-image-sync label: Docker官网镜像拉取能力 description: | Sync Docker Hub images to CNB.tool registry via GitHub Actions, solving domestic Docker pull failures for OpenClaw. Use when: - User needs to pull Docker images but direct access to hub.docker.com is blocked - OpenClaw fails to pull Docker images automatically - Setting up a Docker mirror using CNB + GitHub Actions proxy ─────────────────────────────── 使用 Github Action 同步 Docker 镜像至 cnb.tool 制品库,解决国内拉取镜像失败问题,从而解决 openclaw 自动拉取镜像失败的问题。 适用场景: - 无法直连 hub.docker.com,需要通过 CNB 代理拉取镜像 - OpenClaw 自动拉取 Docker 镜像失败 - 通过 GitHub Actions + CNB 构建 Docker 镜像中转服务 --- # Docker官网镜像拉取能力 **使用 Github Action 同步Docker 镜像至cnb.tool 制品库,解决国内拉取镜像失败问题,从而解决 openclaw 自动拉取镜像失败的问题。** **技能介绍:https://github.com/lufei4/docker-image-sync** ## 前置条件(必选) - **GitHub CLI(`gh`)**:登录检测、Fork 仓库、设置 Secrets、监控 Actions 状态 - 安装:`brew install gh`(macOS)或 [github.com/cli](https://cli.github.com) - 需登录:`gh auth login` - **Docker CLI(`docker`)**:登录 CNB 制品库、推送和拉取镜像 - 安装:`brew install docker` 或从 [docker.com](https://docs.docker.com/desktop/install/linux-install/) ## 工作原理 当无法直连 `hub.docker.com` 时,通过 GitHub Actions 代理中转: 1. 修改 GitHub 仓库 `images.txt`,**清空已有记录,只写入目标镜像** 2. 推送触发 GitHub Actions 同步到 CNB 3. 等待 Actions 完成 4. 从 CNB 拉取镜像到本地 ## 🚀 安装流程 技能安装后,请按以下步骤操作: ### 第一步:GitHub 登录检测 & 创建私有仓库 运行以下命令检测 GitHub 登录状态: ```bash bash ~/.openclaw/workspace/skills/cnb-image-sync/cnb-pull.sh --check ``` - **已登录** → 自动创建私有仓库 `cnb-docker-sync`(**默认私有,不会暴露镜像名**) - **未登录** → 运行 `gh auth login` 在终端登录,或提供 GitHub Personal Access Token 给 openclaw > Token 获取路径:GitHub → Settings → Developer settings → Personal access tokens → Generate new token > > **推荐方式(不过用户手):** > 运行 `gh auth login`,走设备码流程登录,token 自动由 `gh` 管理,无需用户复制粘贴 > > **如果必须提供 Token(细粒度最小权限):** > 创建 Fine-grained Personal Access Token,限制到**仅 `cnb-docker-sync` 仓库**,权限: > - `Contents: read and write`(读写仓库,触发 workflow) > - `Secrets: read and write`(设置 Repository Secrets) > - `Workflows: read and write`(触发 Actions) > **不要**给 `repo` 全部范围,只给这一个仓库 ### 第二步:注册 CNB 账号并创建制品仓库 #### 2.1 注册 CNB 账号 访问 [cnb.cool](https://cnb.cool/),使用微信账号登录(支持扫码登录)。  #### 2.2 创建仓库 登录后,按以下路径操作: 1. 点击页面**右上角头像** 2. 选择**我的仓库** 3. 点击**创建仓库**按钮,填写仓库名称(可使用中文),类型选择 **Docker**  创建完成后,进入仓库列表:  #### 2.3 获取 CNB 参数(关键步骤) 仓库创建完成后,进入仓库管理页,选择刚创建的仓库 → **制品** → **使用指引**(或**操作指引**)。 点击**使用指引**,找到**了解更多**,这里包含本技能所需的 CNB 参数:  同时在仓库页面点击**操作指引**,可以看到推送和拉取命令,其中有两个关键信息需要记录:  | 参数 | 对应信息 | 说明 | |------|----------|------| | `CNB_REGISTRY` | 仓库地址 | 固定值,如 `docker.cnb.cool` | | `CNB_REPO_SLUG` | 命名空间 | 格式 `用户名/仓库名`,需转为小写,如 `lufei123/lufei-docker` | #### 2.4 获取 CNB_TOKEN 在制品库页面,找到**访问令牌**或 **Access Token** 配置,创建一个访问令牌(用于拉取凭证)。 ### 第三步:提供参数给 openclaw 准备好以下 4 个参数后,**直接回复我这些值**: | 参数 | 说明 | 示例 | |------|------|------| | `CNB_TOKEN` | CNB 访问令牌 | `8B76Bopie1d966fVDMgJnhFRepZ` | | `CNB_REGISTRY` | CNB 仓库地址(固定值) | `docker.cnb.cool` | | `CNB_REPO_SLUG` | CNB 命名空间(小写) | `lufei123/lufei-docker` | | `CNB_GITHUB_REPO` | 私有仓库地址(格式:`你的GitHub用户名/cnb-docker-sync`) | `你的GitHub用户名/cnb-docker-sync` | **openclaw 收到后会帮你完成以下操作:** 1. 写入 `~/.openclaw/.env`(注意:请保持该文件可信,`chmod 600 ~/.openclaw/.env`) 2. 自动创建私有仓库 `你的用户名/cnb-docker-sync`(如不存在) 3. 将 **内嵌的 GitHub Actions workflow** 推送到你的私有仓库(workflow 代码来自技能制品,透明可查) 4. 将 `CNB_REGISTRY`、`CNB_REPO_SLUG_LOWERCASE`、`CNB_TOKEN` 设置到私有仓库的 Repository Secrets > ⚠️ 私有仓库默认不会暴露镜像名,这是相比 Fork 方案的关键改进 ### 第四步:测试验证 参数配置完成后,openclaw 自动拉取 `postgres:latest` 进行测试,通过后汇报结果。 ## 安全特性 - ✅ **`.env` 安全加载**:使用 IFS 逐行解析,仅提取需要的变量,无 shell source,避免注入 - ✅ **workflow 内嵌**:GitHub Actions workflow 代码来自技能制品(非外部仓库),透明可查 - ✅ **默认私有仓库**:GitHub 仓库默认为私有,镜像名不会暴露在公开历史记录中 - ✅ **最小权限 Token**:推荐使用 `gh auth login` 登录(不过用户手),或创建细粒度最小权限 Token - ✅ **环境变量文件保护**:建议 `chmod 600 ~/.openclaw/.env` ## 使用方式 ```bash bash ~/.openclaw/workspace/skills/cnb-image-sync/cnb-pull.sh <镜像名>[:标签] ``` **示例:** ```bash bash ~/.openclaw/workspace/skills/cnb-image-sync/cnb-pull.sh mongo:latest bash ~/.openclaw/workspace/skills/cnb-image-sync/cnb-pull.sh nginx:1.25 bash ~/.openclaw/workspace/skills/cnb-image-sync/cnb-pull.sh redis:7-alpine ``` ## 关键特性 - **images.txt 始终只有一个镜像**:每次拉取时清空已有记录,只写入目标镜像 - **自动重试**:优先尝试直接从 CNB 拉取(镜像已存在时),失败则走代理中转 - **等待 Actions**:代理模式下等待 GitHub Actions 完成(约 1-3 分钟) - **不污染 Git 历史**:拉取完成后清空 images.txt,不推送清理 - **彩色输出**:绿色 info、黄色 warn、红色 error ## 环境变量 | 变量 | 说明 | 默认值 | |------|------|--------| | `CNB_TOKEN` | CNB 访问令牌(必填) | — | | `CNB_REGISTRY` | CNB 镜像仓库地址 | `docker.cnb.cool` | | `CNB_REPO_SLUG` | CNB 目标仓库(必填,需小写) | — | | `CNB_GITHUB_REPO` | GitHub 代理仓库(必填) | — | ## 疑难排除 | 问题 | 解决方案 | |------|----------| | `gh: command not found` | 安装 GitHub CLI:`brew install gh` | | GitHub Actions 失败 | 检查 Repository Secrets 是否正确配置 | | 拉取超时 | 稍后重试,CNB 制品同步有延迟 | | 仓库不存在 | 确认 CNB_REPO_SLUG 与制品库命名空间完全一致 | --- # Docker Image Sync via CNB **Sync Docker Hub images to CNB.tool registry via GitHub Actions, solving domestic Docker pull failures and enabling OpenClaw to auto-pull images without issues.** ## Prerequisites (Required) - **GitHub CLI (`gh`)**: Login detection, Fork repo, set Secrets, monitor Actions - Install: `brew install gh` (macOS) or [github.com/cli](https://cli.github.com) - Login: `gh auth login` - **Docker CLI (`docker`)**: Login to CNB registry, push and pull images - Install: `brew install docker` or from [docker.com](https://docs.docker.com/desktop/install/linux-install/) ## How It Works When `hub.docker.com` is unreachable, this skill proxies through GitHub Actions: 1. Modify `images.txt` in the GitHub repo — **clear all entries, write only the target image** 2. Push to trigger GitHub Actions sync to CNB 3. Wait for Actions completion 4. Pull the image from CNB to local ## 🚀 Installation ### Step 1 — GitHub Login Check & Create Private Repo ```bash bash ~/.openclaw/workspace/skills/cnb-image-sync/cnb-pull.sh --check ``` - **Logged in** → Automatically creates private repo `cnb-docker-sync` (**private by default, image names not exposed**) - **Not logged in** → Run `gh auth login` in terminal, or provide a GitHub Personal Access Token to openclaw > Token path: GitHub → Settings → Developer settings → Personal access tokens → Generate new token > > **Recommended (token never touches user input):** > Run `gh auth login` — device flow, token managed by `gh`, no copy-paste needed > > **If you must provide a Token (fine-grained, minimal scope):** > Create a Fine-grained Personal Access Token limited to the **`cnb-docker-sync` repo only**, permissions: > - `Contents: read and write` (commit/push to trigger workflow) > - `Secrets: read and write` (set Repository Secrets) > - `Workflows: read and write` (trigger Actions) > **Do NOT** grant full `repo` scope — limit to this single repository only ### Step 2 — Register CNB Account & Create Registry #### 2.1 Register CNB Account Visit [cnb.cool](https://cnb.cool/), sign in with your Alibaba Cloud account (supports QR code login).  #### 2.2 Create a Registry 1. Click your **avatar** (top-right) 2. Select **我的仓库** (My Repositories) 3. Click **创建仓库** (Create Repository), fill in a name, choose type **Docker**   #### 2.3 Get CNB Parameters (Key Step) After creating the registry, go to: your repository → **制品** (Artifacts) → **使用指引** (Usage Guide) or **操作指引** (Operations Guide). Click **了解更多** (Learn More) — this contains the CNB parameters needed by this skill:  Also in the repository page, click **操作指引** (Operations Guide) to see push/pull commands. Record these two values:  | Parameter | Maps to | Notes | |-----------|---------|-------| | `CNB_REGISTRY` | Registry address | Fixed value, e.g. `docker.cnb.cool` | | `CNB_REPO_SLUG` | Namespace | Format `username/repo-name`, lowercase, e.g. `lufei123/lufei-docker` | #### 2.4 Get CNB_TOKEN In the CNB registry page, find **访问令牌** (Access Token) configuration, create an access token for pull authentication. ### Step 3 — Provide Parameters to openclaw Reply with these 4 values: | Parameter | Description | Example | |-----------|-------------|---------| | `CNB_TOKEN` | CNB access token | `8B76Bopie1d966fVDMgJnhFRepZ` | | `CNB_REGISTRY` | CNB registry address (fixed value) | `docker.cnb.cool` | | `CNB_REPO_SLUG` | CNB namespace (lowercase) | `lufei123/lufei-docker` | | `CNB_GITHUB_REPO` | Private repo address (format: `your-github-username/cnb-docker-sync`) | `your-github-username/cnb-docker-sync` | **openclaw will automatically:** 1. Write to `~/.openclaw/.env` (please keep this file trusted — run `chmod 600 ~/.openclaw/.env`) 2. Auto-create private repo `your-username/cnb-docker-sync` (if not exists) 3. Push the **bundled GitHub Actions workflow** to your private repo (workflow code comes from skill artifacts, transparent and inspectable) 4. Set `CNB_REGISTRY`, `CNB_REPO_SLUG_LOWERCASE`, `CNB_TOKEN` as Repository Secrets in the private repo > ⚠️ Private repos do not expose image names in public history — this is the key improvement over the fork approach ### Step 4 — Test Verification openclaw automatically pulls `postgres:latest` to verify the setup, then reports the result. ## Security Features - ✅ **Secure `.env` loading**: Uses IFS line-by-line parsing, extracts only needed variables, no shell source, injection-safe - ✅ **Bundled workflow**: GitHub Actions workflow code comes from skill artifacts (not external repo), transparent and inspectable - ✅ **Private repo by default**: GitHub repo is private by default, image names are not exposed in public history - ✅ **Minimal-scope token**: Recommends `gh auth login` (token never exposed in chat), or create fine-grained minimal-scope Token - ✅ **Environment file protection**: Recommend `chmod 600 ~/.openclaw/.env` ## Usage ```bash bash ~/.openclaw/workspace/skills/cnb-image-sync/cnb-pull.sh <image>[:tag] ``` **Examples:** ```bash bash ~/.openclaw/workspace/skills/cnb-image-sync/cnb-pull.sh mongo:latest bash ~/.openclaw/workspace/skills/cnb-image-sync/cnb-pull.sh nginx:1.25 bash ~/.openclaw/workspace/skills/cnb-image-sync/cnb-pull.sh redis:7-alpine ``` ## Key Features - **images.txt always contains only one image**: Clears existing entries before each pull - **Auto retry**: Tries direct CNB pull first (works when image already exists), falls back to proxy - **Waits for Actions**: Waits for GitHub Actions completion (~1-3 min) in proxy mode - **No Git history pollution**: Clears `images.txt` locally after pull without pushing - **Colorized output**: Green info, yellow warn, red error ## Environment Variables | Variable | Description | Default | |----------|-------------|---------| | `CNB_TOKEN` | CNB access token (required) | — | | `CNB_REGISTRY` | CNB registry address | `docker.cnb.cool` | | `CNB_REPO_SLUG` | CNB target repo (required, lowercase) | — | | `CNB_GITHUB_REPO` | GitHub proxy repo (required) | — | ## Troubleshooting | Issue | Solution | |-------|----------| | `gh: command not found` | Install GitHub CLI: `brew install gh` | | GitHub Actions failed | Check Repository Secrets configuration | | Pull timeout | Retry later — CNB sync may have delay | | Repository not found | Verify `CNB_REPO_SLUG` matches the registry namespace exactly |
don't have the plugin yet? install it then click "run inline in claude" again.