Capgo Live Updates for Capacitor

安装指南

1. ClawHub CLI 从源直接安装技能的最快方式。
   npx clawhub@latest install capgo-live-updates
2. 手动安装 将技能文件夹复制到以下位置之一
   全局模式
   ~/.openclaw/skills/
   工作区
   /skills/
   优先级：工作区 > 本地 > 内置
3. 提示词安装 将此提示词复制到 OpenClaw 即可自动安装。
   请帮我使用 Clawhub 安装 capgo-live-updates。如果尚未安装 Clawhub，请先安装（npm i -g clawhub）。
   更倾向于下载？
   获取包含原生技能文件的ZIP压缩包。
   下载技能 (.zip)

什么是

本 Openclaw Skills 指南帮助开发者为 Capacitor 应用添加 Capgo 实时更新，涵盖账户设置、插件配置、部署、分阶段发布和监控。借助本指南，您可以快速发布网页层修复和功能，管理 beta 与 production channels，并通过 CI/CD 自动化发布。
如果应用在 10 秒内未报告已就绪，Capgo 可以自动回滚更新。OTA 更新适用于应用的 JavaScript、HTML 和 CSS 层；Swift、Kotlin 或 Java 原生代码的更改仍需提交应用商店审核。

应用场景

发布网页层热修复或功能更新，无需等待应用商店审核。
为新的或现有的 Capacitor 项目添加 Capgo 实时更新。
通过 GitHub Actions 或 GitLab CI 自动构建和上传 bundle。
先使用 beta 或 staging channels 测试发布，再将其推广到 production。
逐步推出更新，并监控成功率、错误和回滚率。
让用户控制何时下载并应用可用更新。
配置加密或签名 bundle，或将更新器指向自托管的 Capgo 服务器。

工作原理

创建 Capgo 账户，安装 CLI 并进行身份验证。
在 Capacitor 项目中运行 capgo init，创建 Capgo 应用、配置更新器插件并设置初始 channel。
在 capacitor.config.ts 中配置更新器，并选择自动或手动更新行为。
构建网页应用，并使用 Capgo CLI 或 CI/CD pipeline 上传其 bundle，也可以指定 channel。
应用检查更新并下载可用 bundle。使用手动更新时，应用代码可以明确执行检查、下载、提示、安装和重新加载。
应用成功启动后调用 notifyAppReady()。如果 10 秒内未报告已就绪，Capgo 会将更新视为失败并回滚。
监控发布指标、扩大分阶段发布范围，或在需要时恢复到以前的 bundle。

配置指南

在 capgo.app 创建账户，并选择适合使用需求的方案。
安装 CLI 并进行身份验证：
npm install -g @capgo/cli
capgo login
或者使用 API key 进行身份验证：
capgo login --apikey YOUR_API_KEY
初始化 Capacitor 应用：
cd your-capacitor-app
capgo init
如果初始化时未安装更新器插件，请安装它并同步原生项目：
npm install @capgo/capacitor-updater
npx cap sync
在 capacitor.config.ts 中配置 CapacitorUpdater。对于自动更新，请启用 autoUpdate，并在应用代码中报告成功启动：
import type { CapacitorConfig } from '@capacitor/cli';
const config: CapacitorConfig = {
appId: 'com.yourapp.id',
appName: 'Your App',
webDir: 'dist',
plugins: {
CapacitorUpdater: {
autoUpdate: true,
},
},
};
export default config;
import { CapacitorUpdater } from '@capgo/capacitor-updater';
CapacitorUpdater.notifyAppReady();
应用成功初始化后，请及时调用 notifyAppReady()；本指南规定的就绪时间窗口为 10 秒。
构建并上传 bundle：
npm run build
capgo upload
若要指定 channel 或 bundle 版本：
capgo upload --channel beta
capgo upload --bundle 1.2.3
对于 CI/CD，请将 Capgo token 保存为受保护的 secret，并将其作为 CAPGO_TOKEN 提供给上传步骤。原生代码更改仍须遵守应用商店发布要求。
Capgo Live Updates for Capacitor 数据架构与分类体系
本指南未定义单独的数据库 schema 或生成的项目文件布局。Capgo 围绕应用配置、已上传的更新 bundle、channels 和 bundle 版本组织实时发布。
数据或元数据 用途
appId 和 appName 在配置和 Capgo 设置中标识 Capacitor 应用。
webDir 标识 Capacitor 项目使用的已构建网页资源目录。
Bundle 版本 标记已上传的发布，并支持版本选择和回滚。
Channel 区分 beta、staging 和 production 等发布轨道。
更新和 stats URLs 配置更新分发和分析端点；自托管时可以使用自定义 URL。
更新器设置 控制自动更新、检查时间、重置行为以及可选的私有更新配置。
Dashboard 指标 包括活跃设备、更新成功率和回滚率、版本分布及错误日志。
构建输出会作为更新 bundle 上传。本技能不规定特定的 bundle 目录或自定义元数据文件格式。

高级特性

自动和手动更新流程：
选择后台更新，或通过更新器 API 明确检查、下载、安装和重新加载 bundle。
更新生命周期事件：
updateAvailable
、
downloadProgress
、
updateFailed
appReady
事件。
Channels 和分阶段发布：
创建 beta 和 staging channels，将设备分配到 channels，并在验证发布时逐步提高 production 发布百分比。
回滚和 bundle 管理：
使用 CLI 将 channel 恢复到指定版本，或在应用中列出、重置和删除已下载的 bundle。
CI/CD 部署：
使用受保护的
CAPGO_TOKEN
secret，从 GitHub Actions 或 GitLab CI 上传 bundle。
安全选项：
为加密更新生成密钥，并使用 bundle 签名和验证命令。
自托管：
运行 Capgo 服务器，并为企业或隐私需求配置自定义更新和 stats 端点。
运营监控：
查看设备活动、更新结果、版本分布和错误日志，以指导发布决策。

name: capgo-live-updates description: Complete guide to implementing live updates in Capacitor apps using Capgo. Covers account creation, plugin installation, configuration, update strategies, and CI/CD integration. Use this skill when users want to deploy updates without app store review.

Capgo Live Updates for Capacitor

Deploy updates to your Capacitor app instantly without waiting for app store review.

When to Use This Skill

User wants live/OTA updates

User asks about Capgo

User wants to skip app store review

User needs to push hotfixes quickly

User wants A/B testing or staged rollouts

What is Capgo?

Capgo is a live update service for Capacitor apps that lets you:

Push JavaScript/HTML/CSS updates instantly

Skip app store review for web layer changes

Roll back bad updates automatically

A/B test features with channels

Monitor update analytics

Note: Native code changes (Swift/Kotlin/Java) still require app store submission.

Getting Started

Step 1: Create a Capgo Account
Go to https://capgo.app
Click "Sign Up" or "Get Started"
Sign up with GitHub, Google, or email
Choose a plan:
Free: 1 app, 500 updates/month
Solo: $14/mo, unlimited updates
Team: $49/mo, team features
Enterprise: Custom pricing
Step 2: Install the CLI

npm install -g @capgo/cli

Step 3: Login to Capgo
capgo login

# Opens browser to authenticate

Or use API key:

capgo login --apikey YOUR_API_KEY

Step 4: Initialize Your App
cd your-capacitor-app
capgo init

This will:

Create app in Capgo dashboard

Add @capgo/capacitor-updater to your project
Configure capacitor.config.ts

Set up your first channel

Step 5: Install the Plugin

If not installed automatically:

npm install @capgo/capacitor-updater
npx cap sync

Configuration

Basic Configuration

// capacitor.config.ts
import type { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
appId: 'com.yourapp.id',
appName: 'Your App',
webDir: 'dist',
plugins: {
CapacitorUpdater: {
autoUpdate: true, // Enable automatic updates
},
},
};

export default config;

Advanced Configuration

// capacitor.config.ts
plugins: {
CapacitorUpdater: {
autoUpdate: true,
// Update behavior
resetWhenUpdate: true, // Reset to built-in on native update
updateUrl: 'https://api.capgo.app/updates', // Default
statsUrl: 'https://api.capgo.app/stats', // Analytics

// Channels
defaultChannel: 'production',

// Update timing
periodCheckDelay: 600, // Check every 10 minutes (seconds)
delayConditionsFail: false, // Don't delay on condition fail

// Private updates (enterprise)
privateKey: 'YOUR_PRIVATE_KEY', // For encrypted updates
},
},

Implementing Updates

Automatic Updates (Recommended)

With autoUpdate: true, updates are automatic:

// app.ts - Just notify when ready
import { CapacitorUpdater } from '@capgo/capacitor-updater';

// Tell Capgo the app loaded successfully
// This MUST be called within 10 seconds of app start
CapacitorUpdater.notifyAppReady();

Important: Always call notifyAppReady(). If not called within 10 seconds, Capgo assumes the update failed and rolls back.

Manual Updates

For more control:

// capacitor.config.ts
plugins: {
CapacitorUpdater: {
autoUpdate: false, // Disable auto updates
},
},

// update-service.ts
import { CapacitorUpdater } from '@capgo/capacitor-updater';

class UpdateService {
async checkForUpdate() {
// Check for available update
const update = await CapacitorUpdater.getLatest();

if (!update.url) {

console.log('No update available');
return null;
}

console.log('Update available:', update.version);
return update;
}

async downloadUpdate(update: any) {
// Download the update bundle
const bundle = await CapacitorUpdater.download({
url: update.url,
version: update.version,
});

console.log('Downloaded:', bundle.id);
return bundle;
}

async installUpdate(bundle: any) {
// Set as next version (applies on next app start)
await CapacitorUpdater.set(bundle);
console.log('Update will apply on next restart');
}

async installAndReload(bundle: any) {
// Set and reload immediately
await CapacitorUpdater.set(bundle);
await CapacitorUpdater.reload();
}
}

Update with User Prompt

import { CapacitorUpdater } from '@capgo/capacitor-updater';
import { Dialog } from '@capacitor/dialog';

async function checkUpdate() {
const update = await CapacitorUpdater.getLatest();

if (!update.url) return;

const { value } = await Dialog.confirm({
title: 'Update Available',
message: Version ${update.version} is available. Update now?,
});

if (value) {

// Show loading indicator
showLoading('Downloading update...');

const bundle = await CapacitorUpdater.download({
url: update.url,
version: update.version,
});

hideLoading();

// Apply and reload
await CapacitorUpdater.set(bundle);
await CapacitorUpdater.reload();
}
}

Listen for Update Events

import { CapacitorUpdater } from '@capgo/capacitor-updater';

// Update downloaded
CapacitorUpdater.addListener('updateAvailable', (info) => {
console.log('Update available:', info.bundle.version);
});

// Download progress
CapacitorUpdater.addListener('downloadProgress', (progress) => {
console.log('Download:', progress.percent, '%');
});

// Update failed
CapacitorUpdater.addListener('updateFailed', (info) => {
console.error('Update failed:', info.bundle.version);
});

// App ready
CapacitorUpdater.addListener('appReady', () => {
console.log('App is ready');
});

Deploying Updates

Deploy via CLI

# Build your web app
npm run build

# Upload to Capgo

capgo upload

# Upload to specific channel

capgo upload --channel beta

# Upload with version

capgo upload --bundle 1.2.3

Deploy via CI/CD

GitHub Actions

name: Deploy to Capgo

# .github/workflows/deploy.yml

on:
push:
branches: [main]

jobs:
deploy:
runs-on: ubuntu-latest
steps:

• uses: actions/checkout@v4

• uses: actions/setup-node@v4

• name: Install dependencies run: npm install

• name: Build run: npm run build

• name: Deploy to Capgo run: npx @capgo/cli bundle upload
  env:
  CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}

GitLab CI

# .gitlab-ci.yml

deploy:
stage: deploy
image: node:20
script:

• npm install
• npm run build
• npx @capgo/cli bundle upload only:
• main variables:
  CAPGO_TOKEN: $CAPGO_TOKEN

Channels and Staged Rollouts

Create Channels

# Create beta channel

capgo channel create beta

# Create staging channel

capgo channel create staging

Deploy to Channels

# Deploy to beta (internal testing)

capgo upload --channel beta

# Promote to production

capgo upload --channel production

Staged Rollout

In Capgo dashboard:

Go to Channels > production
Set rollout percentage (e.g., 10%)

Monitor analytics

Increase to 50%, then 100%

Device-Specific Channels

// Assign device to channel
import { CapacitorUpdater } from '@capgo/capacitor-updater';

// For beta testers
await CapacitorUpdater.setChannel({ channel: 'beta' });

// For production users
await CapacitorUpdater.setChannel({ channel: 'production' });

Rollback and Version Management

Automatic Rollback

If notifyAppReady() isn't called within 10 seconds, Capgo automatically rolls back to the previous working version.

Manual Rollback

# List available versions

capgo bundle list

# Rollback to specific version

capgo bundle revert --bundle 1.2.2 --channel production

In-App Rollback

// Get list of downloaded bundles
const bundles = await CapacitorUpdater.list();

// Rollback to built-in version
await CapacitorUpdater.reset();

// Delete a specific bundle
await CapacitorUpdater.delete({ id: 'bundle-id' });

Self-Hosted Option

For enterprise or privacy requirements:

# Install self-hosted Capgo

docker run -d
-p 8080:8080
-e DATABASE_URL=postgres://...
capgo/capgo-server

Configure app to use self-hosted:

// capacitor.config.ts
plugins: {
CapacitorUpdater: {
autoUpdate: true,
updateUrl: 'https://your-server.com/updates',
statsUrl: 'https://your-server.com/stats',
},
},

Security

Encrypted Updates

For sensitive apps, enable encryption:

# Generate key pair

capgo key create

# Upload with encryption

capgo upload --key-v2

Configure in app:

// capacitor.config.ts
plugins: {
CapacitorUpdater: {
autoUpdate: true,
privateKey: 'YOUR_PRIVATE_KEY',
},
},

Code Signing

Verify updates are from trusted source:

# Sign bundle

capgo upload --sign

# Verify signature in app

capgo key verify

Monitoring and Analytics

Dashboard Metrics

In Capgo dashboard, view:

Active devices

Update success rate

Rollback rate

Version distribution

Error logs

Custom Analytics

// Track custom events
import { CapacitorUpdater } from '@capgo/capacitor-updater';

// Get current bundle info
const current = await CapacitorUpdater.current();
console.log('Current version:', current.bundle.version);

// Get download stats
const stats = await CapacitorUpdater.getBuiltinVersion();

Troubleshooting

Issue: Updates Not Applying
Check notifyAppReady() is called

Verify app ID matches Capgo dashboard

Check channel assignment

Review Capgo dashboard logs

Issue: Rollback Loop
App crashes before notifyAppReady()
Fix: Ensure notifyAppReady() is called early

Temporarily disable updates to debug

Issue: Slow Downloads
Enable delta updates (automatic)

Optimize bundle size

Use CDN (enterprise)

Best Practices

Always call notifyAppReady() - First thing after app initializes
Test updates on beta channel first - Never push untested to production

Use semantic versioning - Makes rollback easier

Monitor rollback rate - High rate indicates quality issues

Implement error boundary - Catch crashes before rollback

Keep native code stable - Native changes need app store

Resources

Capgo Documentation: https://capgo.app/docs
Capgo Dashboard: https://web.capgo.app
Plugin GitHub: https://github.com/Cap-go/capacitor-updater
Discord Community: https://discord.gg/capgo
Capgo CLI 使用指南
沙盒操作（启用与停用）