# Warp ACP Ops

## Current Phase

Phase 1 standardizes Warp-backed ACP usage for `opencode` only.

## Current Secret Source

Primary secret file:

- `~/.openclaw/.env`

Cluster rule:

- `mac-5`, `mac-6`, and `mac-7` must each keep a local `~/.openclaw/.env` if they may locally run Warp-backed ACP harnesses.
- Do not rely on `mac-5` secrets propagating to `mac-6` / `mac-7` at runtime.
- Wrapper scripts should always read the local machine's own `~/.openclaw/.env`.

Current placeholder variables:

- `WARP_INFINI_API_KEY`
- `WARP_INFINI_BASE_URL`
- `WARP_CKIMI_API_KEY`
- `WARP_CKIMI_BASE_URL`

This file should contain real values locally, but memory documents must never store actual secrets.

## Why `~/.openclaw/.env` instead of `~/.zshrc`

Observed behavior on `mac-5`: current OpenClaw / exec / ACP-related process paths do not reliably inherit environment variables from `~/.zshrc`. Therefore Warp provider secrets must be loaded explicitly by wrapper scripts or service environment, not assumed from interactive shell startup.

## Planned `opencode` ACP Agent Ids

Use provider-qualified names, not model-only names.

- `opencode-warp-infini-kimi`
- `opencode-warp-infini-minimax`
- `opencode-warp-infini-glm`

Future provider examples:

- `opencode-warp-ckimi-kimi`

## Wrapper Policy

Each Warp-backed `opencode` ACP agent should launch through a dedicated wrapper script.

Suggested wrapper locations:

- `~/.local/bin/opencode-warp-infini-kimi-acp`
- `~/.local/bin/opencode-warp-infini-minimax-acp`
- `~/.local/bin/opencode-warp-infini-glm-acp`

Each wrapper should:

1. load `~/.openclaw/.env`
2. verify required env vars exist
3. fix provider + model mapping
4. run `opencode-ai acp`

## Active Default Routing Baseline (2026-03-18)

Current `opencode` default-model routing baseline:

- `mac-5`
  - default model: `opencode/minimax-m2.5-free`
  - rationale: the minimax free cloud route already passed direct + ACP minimal validation and avoids the timeout-prone local `oMLX` ACP path
- `mac-6`
  - provider label: `vllm`
  - base URL: `http://100.64.0.5:8000/v1`
  - model id: `Qwen3.5-27B`
  - default model string: `vllm/Qwen3.5-27B`
- `mac-7`
  - provider label: `vllm`
  - base URL: `http://100.64.0.5:8000/v1`
  - model id: `Qwen3.5-27B`
  - default model string: `vllm/Qwen3.5-27B`

Superseded assumption:

- Do not continue to describe the cluster rule as "each machine defaults to its own local model" for `opencode` ACP.
- That older description was true for the earlier `oMLX`-first phase but is no longer the active default-policy baseline.

Validation snapshot:

- `mac-6` ACP test result: `MAC6_VLLM_ACP_OK`
- `mac-7` ACP test result: `MAC7_VLLM_ACP_OK`

## Key Files

### OpenClaw
- `~/.openclaw/openclaw.json`
  - purpose: allow ACP agent ids and overall runtime policy

### acpx
- `~/.acpx/config.json`
  - purpose: map ACP `agentId` values to wrapper commands

### opencode
- `~/.config/opencode/opencode.json`
  - purpose: harness provider/model behavior where needed

### secrets
- `~/.openclaw/.env`
  - purpose: provider secret and base URL storage

## Fallback Operating Rule

If a Warp-backed provider fails due to quota exhaustion, weekly limit exhaustion, rate limiting, or model unavailability during an ACP task, do not treat that as a dead end. Route to the documented fallback.

Fallback order:

1. same model, other provider
2. same provider, adjacent model
3. other provider, adjacent model

## Example Fallback Skeleton

For `opencode-warp-infini-kimi`:

- primary: `infini / kimi-k2.5`
- fallback candidate: `ckimi / kimi-k2.5`
- fallback candidate: `infini / glm-5`
- fallback candidate: `infini / minimax-m2.5`

For `opencode-warp-infini-glm`:

- primary: `infini / glm-5`
- fallback candidate: another provider with `glm-5`
- fallback candidate: `infini / kimi-k2.5`
- fallback candidate: `infini / minimax-m2.5`

## Continuation Rule for Limited / Failed ACP Runs

If an ACP `opencode` run is interrupted by provider-side request limits or similar provider failures, the replacement run should continue with context rather than restart from zero.

Required operator behavior:

1. classify the failure as provider-side (rate limit / quota / upstream unavailable) vs task-side
2. summarize the interrupted task before switching agents
3. start a new ACP run with the next fallback Warp agent
4. provide the summary so the new run can continue remaining work

Minimum summary fields:

- original task objective
- work completed so far
- files touched
- relevant error / provider limit signal
- remaining work

## Testing Checklist (for later execution)

1. Confirm `~/.openclaw/.env` exists on each machine
2. Confirm wrapper can load env successfully
3. Confirm `opencode` direct provider call works
4. Confirm ACP agent alias works through `acpx`
5. Confirm OpenClaw can invoke the ACP agent id
6. Record success/failure in daily notes

## Documentation Rule

Whenever a new Warp provider is added:

1. add new `WARP_<PROVIDER>_*` variable names to the ops doc
2. add/update fallback chains in the long-term project doc
3. add the corresponding `opencode-warp-<provider>-<model>` naming entry
4. document the change in daily notes