collective-memory-repo/shared/long-term/projects/warp-acp-integration.md

Warp ACP Integration

Purpose

This document defines the long-term design for routing ACP harnesses through Warp-managed cloud providers. Phase 1 standardizes opencode; future phases may extend the same pattern to gemini cli and claude code.

Scope

• Control plane: OpenClaw on mac-5
• Execution nodes: mac-6, mac-7
• Current phase: opencode
• Future candidates: gemini cli, claude code

Core Design Principles

1. Provider identity and model identity are different things.
   • Model names can repeat across providers.
   • Environment variables and agent ids must therefore encode the provider, not just the model.
2. Do not rely on ~/.zshrc for ACP runtime secrets.
   • ACP / acpx / harness execution may not inherit interactive shell startup files.
   • Secrets should be loaded explicitly.
3. Secrets and routing rules should be separated.
   • Secrets live in ~/.openclaw/.env.
   • Routing / alias / model selection live in ACP config, wrapper scripts, and documented policy.
4. Wrapper scripts are the stable injection point.
   • Wrapper scripts should explicitly load ~/.openclaw/.env, validate required variables, and then exec the target harness.
5. Fallback must be designed up front.
   • Cloud provider quota exhaustion and rate limiting are expected operating conditions, not edge cases.

Secret Storage Standard

Primary local secret file:

• ~/.openclaw/.env

Recommended format:

WARP_INFINI_API_KEY=
WARP_INFINI_BASE_URL=https://cloud.infini-ai.com/maas/coding/v1
WARP_CKIMI_API_KEY=
WARP_CKIMI_BASE_URL=

Notes:

• Use plain KEY=value lines.
• Do not store secrets in ~/.openclaw/openclaw.json, ~/.acpx/config.json, or long-term memory files.
• Restrict file permissions: chmod 600 ~/.openclaw/.env.

Environment Variable Naming Rule

Use the pattern:

• WARP_<PROVIDER>_API_KEY
• WARP_<PROVIDER>_BASE_URL

Examples:

• WARP_INFINI_API_KEY
• WARP_INFINI_BASE_URL
• WARP_CKIMI_API_KEY
• WARP_CKIMI_BASE_URL

Do not name variables by model alone, because identical model names may exist on multiple providers.

Agent Naming Standard

For Warp-backed ACP harnesses, use:

• <harness>-warp-<provider>-<model-family>

Phase 1 examples for opencode:

• opencode-warp-infini-kimi
• opencode-warp-infini-minimax
• opencode-warp-infini-glm

Future examples:

• gemini-warp-infini-kimi
• claude-warp-ckimi-kimi

Configuration Layer Responsibilities

OpenClaw

Responsible for:

• Allowing ACP agent ids to be called
• High-level routing policy

Key file:

• ~/.openclaw/openclaw.json

acpx

Responsible for:

• Mapping ACP agentId to a concrete command

Key file:

• ~/.acpx/config.json

Wrapper scripts

Responsible for:

• Loading ~/.openclaw/.env
• Validating provider secrets / URLs
• Fixing provider and model selection
• Launching the harness ACP command

Suggested location:

• ~/.local/bin/

Harness config (opencode in phase 1)

Responsible for:

• Harness-specific provider usage and model invocation details

Key file:

• ~/.config/opencode/opencode.json

Wrapper Contract

Every Warp-backed ACP wrapper should:

1. Load ~/.openclaw/.env
2. Validate that required variables exist
3. Select the target provider
4. Pin the intended model
5. Launch the harness ACP entrypoint
6. Fail fast with a readable error if env/config is missing

Pseudo-flow:

set -a
source ~/.openclaw/.env
set +a

# validate WARP_<PROVIDER>_API_KEY and WARP_<PROVIDER>_BASE_URL
# select model
exec opencode-ai acp

Fallback Policy

Why fallback exists

Warp-backed cloud providers may fail due to:

• 5-hour quota exhaustion
• weekly quota exhaustion
• rate limiting / throttling
• transient upstream 5xx
• model retirement or temporary unavailability
• provider auth / billing issues

These are normal operational conditions and must be documented as first-class routing rules.

Fallback priority

When a primary provider/model is unavailable, use this order:

1. Same model, different provider
2. Same provider, adjacent model
3. Different provider, adjacent model

This preserves behavior consistency as much as possible before changing model family.

Example fallback chain

For opencode-warp-infini-kimi:

1. primary: infini / kimi-k2.5
2. fallback-1: another provider offering kimi-k2.5 (for example ckimi / kimi-k2.5)
3. fallback-2: infini / glm-5
4. fallback-3: infini / minimax-m2.5

Exact fallback order should be documented per agent as providers are added.

Operational Reminder

If runtime errors show quota exhaustion or provider-specific capacity limits during an ACP task, the operator should treat that as a routing event, not just a task failure. The next step is to move to the documented fallback provider/model path.

Extension Path

After opencode stabilizes, the same naming / secret-loading / fallback framework should be reused for:

• gemini cli
• claude code

The framework should stay provider-centric and wrapper-based even as the harnesses differ.