Add Warp ACP provider design and ops docs

agents/openclaw-main/warp-acp-ops.md

@@ -0,0 +1,115 @@
+# Warp ACP Ops
+
+## Current Phase
+
+Phase 1 standardizes Warp-backed ACP usage for `opencode` only.
+
+## Current Secret Source
+
+Primary secret file:
+
+- `~/.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`
+
+## 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`
+
+## 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