cacheforge-setup

设置 CacheForge — 注册、配置上游，在 30 秒内获取您的 API 密钥。一行配置，零代码更改。

## When to use this skill

Use this skill when the user wants to:
- Set up CacheForge for the first time
- Register a new CacheForge account
- Connect their LLM API provider to CacheForge
- Get a CacheForge API key

## Setup Flow

1. **Detect existing API keys** — Check for `OPENAI_API_KEY`, `OPENROUTER_API_KEY`, `ANTHROPIC_API_KEY` in the environment
2. **Collect credentials** — Ask user for email and password if not provided
3. **Auto-detect provider** — Infer upstream kind from key prefix:
   - `sk-or-` → openrouter
   - `sk-ant-` → anthropic
   - `sk-` → custom (OpenAI-compatible; legacy `openai` alias still accepted)
   - Preset default base URLs:
     - openrouter → `https://openrouter.ai/api/v1`
     - anthropic → `https://api.anthropic.com`
     - custom → `https://api.fireworks.ai/inference/v1`
4. **Provision** — Run `python3 setup.py provision` to register/authenticate and get a CacheForge API key
   - If registration mode is invite-only, pass `--invite-code` (or set `CACHEFORGE_INVITE_CODE`).
   - If email verification is enabled, complete verification and rerun `provision` to mint the tenant API key.
5. **Validate** — Run `python3 setup.py validate` to make a test request through the proxy
6. **Configure OpenClaw (recommended)** — Print the exact OpenClaw snippet and (with approval) apply it to `~/.openclaw/openclaw.json`
   - Print: `python3 setup.py openclaw-snippet`
   - Apply: `python3 setup.py openclaw-apply --set-default`
   - If upstream is OpenRouter, the snippet registers multiple popular models so users can switch in `/model` immediately.
7. **Fund credits** — Before first proxy traffic, top up at least `$10` via Stripe or crypto:
   - `python3 skills/cacheforge-ops/ops.py topup --amount 10 --method stripe`
   - `python3 skills/cacheforge-ops/ops.py topup --amount 10 --method crypto`

Important (Vault Mode):
- Vault Mode virtualizes tool outputs only when the request advertises a fetch-capable tool definition (`web_fetch` or `browser`).
- Without a fetch tool definition, CacheForge fail-opens with reason `no_fetch_tool`.

## Commands

```bash
# Full setup (interactive)
python3 skills/cacheforge-setup/setup.py provision \
  --email user@example.com \
  --password "..." \
  --invite-code "..." \
  --upstream-kind custom \
  --upstream-base-url https://api.fireworks.ai/inference/v1 \
  --upstream-key fw_...

# Just validate an existing setup
python3 skills/cacheforge-setup/setup.py validate \
  --base-url https://app.anvil-ai.io \
  --api-key cf_...

# Print the OpenClaw snippet (same structure as the CacheForge console)
python3 skills/cacheforge-setup/setup.py openclaw-snippet \
  --base-url https://app.anvil-ai.io \
  --api-key cf_...

# Apply CacheForge provider config into OpenClaw (JSON5-safe; prompts for approval)
python3 skills/cacheforge-setup/setup.py openclaw-apply \
  --base-url https://app.anvil-ai.io \
  --api-key cf_... \
  --set-default
```

## Environment Variables

- `CACHEFORGE_BASE_URL` — CacheForge API base (default: https://app.anvil-ai.io)
- `CACHEFORGE_API_KEY` — Existing API key (skip provisioning if set)
- `CACHEFORGE_INVITE_CODE` — Invite code (required on invite-only deployments)
- `OPENAI_API_KEY`, `OPENROUTER_API_KEY`, `ANTHROPIC_API_KEY`, `FIREWORKS_API_KEY` — Auto-detected for upstream
- `UPSTREAM_BASE_URL` — Optional override for `provision` upstream base URL

## After Setup

Once provisioned, set:
```bash
export OPENAI_BASE_URL=https://app.anvil-ai.io/v1
export OPENAI_API_KEY=cf_...  # your CacheForge tenant API key
```

All OpenAI-compatible tools (OpenClaw, Claude Code, Cursor, any agent framework) will route through CacheForge automatically.

If you prefer the OpenClaw-native provider approach (recommended), keep secrets out of `openclaw.json` and set:

```bash
export CACHEFORGE_API_KEY=cf_...
```

## API Contract (current)

This skill uses:
- `POST /api/provision`
- `GET /v1/account/info`

---

## 中文说明

## 何时使用此技能

当用户希望执行以下操作时使用此技能：
- 首次设置 CacheForge
- 注册新的 CacheForge 账户
- 将其 LLM API 提供商连接到 CacheForge
- 获取 CacheForge API 密钥

## 设置流程

1. **检测现有 API 密钥** — 检查环境中的 `OPENAI_API_KEY`、`OPENROUTER_API_KEY`、`ANTHROPIC_API_KEY`
2. **收集凭据** — 若未提供，向用户询问邮箱和密码
3. **自动检测提供商** — 根据密钥前缀推断上游类型：
   - `sk-or-` → openrouter
   - `sk-ant-` → anthropic
   - `sk-` → custom（OpenAI 兼容；仍接受旧版 `openai` 别名）
   - 预设的默认基础 URL：
     - openrouter → `https://openrouter.ai/api/v1`
     - anthropic → `https://api.anthropic.com`
     - custom → `https://api.fireworks.ai/inference/v1`
4. **预配置** — 运行 `python3 setup.py provision` 注册/认证并获取 CacheForge API 密钥
   - 如果注册模式为仅限邀请，传入 `--invite-code`（或设置 `CACHEFORGE_INVITE_CODE`）。
   - 如果启用了邮箱验证，完成验证后重新运行 `provision` 以生成租户 API 密钥。
5. **验证** — 运行 `python3 setup.py validate` 通过代理发起一次测试请求
6. **配置 OpenClaw（推荐）** — 打印准确的 OpenClaw 片段，并（经批准后）将其应用到 `~/.openclaw/openclaw.json`
   - 打印：`python3 setup.py openclaw-snippet`
   - 应用：`python3 setup.py openclaw-apply --set-default`
   - 如果上游是 OpenRouter，该片段会注册多个热门模型，以便用户立即在 `/model` 中切换。
7. **充值额度** — 在首次代理流量之前，通过 Stripe 或加密货币至少充值 `$10`：
   - `python3 skills/cacheforge-ops/ops.py topup --amount 10 --method stripe`
   - `python3 skills/cacheforge-ops/ops.py topup --amount 10 --method crypto`

重要（Vault 模式）：
- 仅当请求声明了具备抓取能力的工具定义（`web_fetch` 或 `browser`）时，Vault 模式才会虚拟化工具输出。
- 若没有抓取工具定义，CacheForge 会以原因 `no_fetch_tool` 进行 fail-open（失败时放行）。

## 命令

```bash
# Full setup (interactive)
python3 skills/cacheforge-setup/setup.py provision \
  --email user@example.com \
  --password "..." \
  --invite-code "..." \
  --upstream-kind custom \
  --upstream-base-url https://api.fireworks.ai/inference/v1 \
  --upstream-key fw_...

# Just validate an existing setup
python3 skills/cacheforge-setup/setup.py validate \
  --base-url https://app.anvil-ai.io \
  --api-key cf_...

# Print the OpenClaw snippet (same structure as the CacheForge console)
python3 skills/cacheforge-setup/setup.py openclaw-snippet \
  --base-url https://app.anvil-ai.io \
  --api-key cf_...

# Apply CacheForge provider config into OpenClaw (JSON5-safe; prompts for approval)
python3 skills/cacheforge-setup/setup.py openclaw-apply \
  --base-url https://app.anvil-ai.io \
  --api-key cf_... \
  --set-default
```

## 环境变量

- `CACHEFORGE_BASE_URL` — CacheForge API 基础地址（默认：https://app.anvil-ai.io）
- `CACHEFORGE_API_KEY` — 现有 API 密钥（若已设置则跳过预配置）
- `CACHEFORGE_INVITE_CODE` — 邀请码（在仅限邀请的部署中必需）
- `OPENAI_API_KEY`、`OPENROUTER_API_KEY`、`ANTHROPIC_API_KEY`、`FIREWORKS_API_KEY` — 自动检测用于上游
- `UPSTREAM_BASE_URL` — `provision` 上游基础 URL 的可选覆盖项

## 设置完成后

预配置完成后，设置：
```bash
export OPENAI_BASE_URL=https://app.anvil-ai.io/v1
export OPENAI_API_KEY=cf_...  # your CacheForge tenant API key
```

所有 OpenAI 兼容工具（OpenClaw、Claude Code、Cursor、任何 agent 框架）都将自动通过 CacheForge 路由。

如果你更倾向于 OpenClaw 原生的提供商方式（推荐），请将密钥保留在 `openclaw.json` 之外并设置：

```bash
export CACHEFORGE_API_KEY=cf_...
```

## API 契约（当前）

此技能使用：
- `POST /api/provision`
- `GET /v1/account/info`