201 lines
5.0 KiB
Markdown
201 lines
5.0 KiB
Markdown
# 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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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.
|