v-claw-provider

OpenClaw provider plugin for V-Claw token gateway (token.v-claw.org).

Runtime status: end-to-end verified with real OpenClaw calls against the live V-Claw AIAPI surface.

Baseline

• OpenClaw baseline target: 2026.4.1
• Provider id: v-claw
• User-facing title: V-Claw/SubProvider

Install into OpenClaw (real usage)

1. Build plugin package:

npm install
npm run build

2. Ensure plugin manifest and dist output exist:

• openclaw.plugin.json
• dist/**

3. Add this plugin package to OpenClaw plugin loading flow according to your OpenClaw 2026.4.1 setup (local path or packed tarball).

4. Configure runtime auth/config in OpenClaw environment:

VCLAW_API_KEY=...
VCLAW_BASE_URL=https://token.v-claw.org

Optional envs:

VCLAW_DEFAULT_MODEL=gpt-5.4
VCLAW_CATALOG_MODE=catalog-endpoint
VCLAW_BOOTSTRAP_CONTEXT='{"base_url":"https://...","default_model":"...","models":["..."]}'
VCLAW_CATALOG_ENDPOINT_URL=https://.../provider-catalog

5. Verify plugin package locally:

npm run test

Plugin config schema summary

• baseUrl?: string
• defaultModel?: string
• catalogMode?: "static" | "bootstrap-context" | "catalog-endpoint"
• catalogEndpointUrl?: string
• bootstrapContext?: object
• staticModels?: Array<{ id: string; ... }>

Catalog source-of-truth

Nguồn metadata runtime/provider chính là GET /v1/provider-catalog.

GET /v1/models chỉ được dùng như:

• fallback signal
• live availability check

Nếu cả hai path live đều không usable, plugin vẫn fallback về static catalog để giữ safety net.

Current aiapi.linkto.com.vn endpoint surface (runtime probe)

Probe runtime gần nhất cho thấy surface đang hiện hữu như sau:

• GET /v1/provider-catalog → live endpoint, nhưng hiện có thể trả 403 INSUFFICIENT_BALANCE với API key không đủ balance
• GET /v1/models → live endpoint, cùng gating balance như trên
• POST /v1/responses → live endpoint cho OpenAI-compatible responses flow
• POST /v1/chat/completions → live endpoint cho OpenAI-compatible chat flow
• POST /v1/messages → có route nhưng chỉ usable theo group/platform phù hợp; với key OpenAI hiện probe public có thể không usable như Claude lane
• GET /v1beta/models → live Gemini-compatible listing surface
• GET /antigravity/models → live Antigravity listing surface
• GET /api/v1/groups/available → cho thấy group surface user đang được cấp
• GET /api/v1/keys → trả API key + bound group runtime

Runtime state observed from admin/user surface

• Hiện có 2 group chính: OpenAI và Antigravity.
• Key openai đang bound vào group OpenAI (group_id=10).
• Group OpenAI hiện default_mapped_model = gpt-5.4.
• Surface admin cho thấy runtime account mappings hiện expose rộng family google-claude-*, google-gemini-*, gpt-oss-120b-medium, và tab_flash_lite_preview.
• Một số live gateway endpoints hiện bị gate bởi balance/eligibility, nên plugin không được giả định rằng probe không-auth hoặc low-balance sẽ always trả catalog JSON.

Catalog modes (xwp.2 + provider-catalog primary)

Plugin hiện hỗ trợ 3 mode catalog, với default là catalog-endpoint:

• catalog-endpoint (mặc định): gọi endpoint catalog (mặc định ${baseUrl}/provider-catalog, hoặc override bởi catalogEndpointUrl / VCLAW_CATALOG_ENDPOINT_URL) để hydrate metadata chính.
• bootstrap-context: hydrate từ bootstrapContext (plugin config hoặc VCLAW_BOOTSTRAP_CONTEXT).
• static: dùng staticModels trong config/plugin.

Hydration mapping

Các field được map ở mức bounded:

• base_url -> baseUrl
• default_model -> defaultModel
• models -> staticModels (nhận cả string model id hoặc object model)

Nếu endpoint trả non-200 hoặc payload không hợp lệ, plugin tự động fallback về static/default để tránh fail cứng.

Khi provider-catalog không usable, plugin sẽ probe /v1/models như availability signal (không dùng payload này làm metadata source-of-truth).

Current packaging strategy (xwp.1)

• Runtime/package compatibility is declared via peerDependencies.openclaw (>=2026.4.1 <2027).
• Local development currently uses a repo-reference dev dependency:
  • openclaw: file:../../reference/openclaw
• TypeScript compile currently uses a local declaration shim for openclaw/plugin-sdk/provider-entry because the local file:../../reference/openclaw dependency is used as source reference in this phase.

This strategy is dev-only and keeps the repo self-contained for now. It should be replaced by pure package-based SDK type resolution once the OpenClaw package surface used by this plugin is available as stable consumable types for external plugins.

Current limitations

• openclaw: file:../../reference/openclaw vẫn đang là dev dependency local để compile/test trong giai đoạn baseline này.
• Shim type types/openclaw-provider-entry.d.ts vẫn được giữ để tránh kéo compile graph xuyên repo.
• Chưa implement transport chuyên biệt cho Anthropic/Gemini; scope hiện tại là canonical v-claw dưới user-facing title V-Claw/SubProvider.

Verify

npm run build
npm run test

Runtime smoke in isolated OpenClaw profile (headless bootstrap)

Use the repo-local helper below to run runtime verification without manual JSON editing.

Single-command headless flow

VCLAW_API_KEY=... npm run runtime:smoke:headless

What it does:

1. installs this plugin into profile v-claw-provider-smoke
2. seeds provider auth with models auth paste-token (non-interactive)
3. runs plugins list, plugins inspect v-claw-provider, models list --all --provider v-claw, plugins doctor

Notes

• Script path: scripts/runtime-smoke-headless.sh
• Defaults:
  • OPENCLAW_PROFILE=v-claw-provider-smoke
  • OPENCLAW_PROVIDER=v-claw
  • OPENCLAW_AUTH_PROFILE_ID=v-claw:default
• Optional overrides:
  • OPENCLAW_BIN=/opt/homebrew/bin/openclaw (force a specific OpenClaw binary)
  • OPENCLAW_SKIP_INSTALL=1 (skip reinstall if plugin is already installed in profile)
• If VCLAW_API_KEY is missing, the script skips seeding and uses whatever auth is already in OpenClaw store.

Phase2 closeout status (reporting clarity)

• Repo verification status: PASS (build/test pass).
• Execution telemetry note: callback/session-resolution telemetry for run v-claw-provider-phase2-20260403t0214 was not fully clean.
• This repository does not claim that observability for that run was fully clean.