Add Warp ACP provider design and ops docs
This commit is contained in:
hotwa
115
agents/openclaw-main/warp-acp-ops.md
Normal file
115
agents/openclaw-main/warp-acp-ops.md
Normal file
@@ -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
|
||||
@@ -2,6 +2,28 @@
|
||||
|
||||
## OpenClaw / oMLX / subagent 配置记录
|
||||
|
||||
## Warp / ACP / opencode 规范草案
|
||||
|
||||
- 已决定长期文档主名采用 `warp-acp-*`
|
||||
- 第一阶段仅先标准化 `opencode` 的 Warp ACP 接入；后续再扩展到 `gemini cli`、`claude code`
|
||||
- 已新增本地 secrets 文件占位：`~/.openclaw/.env`
|
||||
- 当前预置的 provider 环境变量名：
|
||||
- `WARP_INFINI_API_KEY`
|
||||
- `WARP_INFINI_BASE_URL`
|
||||
- `WARP_CKIMI_API_KEY`
|
||||
- `WARP_CKIMI_BASE_URL`
|
||||
- 已确定：provider 级别用环境变量命名，**不**用模型名命名，避免不同 provider 出现同名模型时冲突
|
||||
- 已确定 `opencode` 的 Warp ACP agent 命名规范采用 provider-qualified 形式：
|
||||
- `opencode-warp-infini-kimi`
|
||||
- `opencode-warp-infini-minimax`
|
||||
- `opencode-warp-infini-glm`
|
||||
- 已确定 wrapper 方案为后续 ACP 稳定注入点：wrapper 显式读取 `~/.openclaw/.env`，不依赖 `~/.zshrc`
|
||||
- 已将 fallback 纳入规范设计：当 provider 配额耗尽、限流或模型不可用时，优先同模型跨 provider fallback，其次同 provider 跨相邻模型 fallback
|
||||
- 新增长期设计文档：`shared/long-term/projects/warp-acp-integration.md`
|
||||
- 新增 OpenClaw 私域操作文档：`agents/openclaw-main/warp-acp-ops.md`
|
||||
|
||||
## OpenClaw / oMLX / subagent 配置记录
|
||||
|
||||
- mac-5 / mac-6 / mac-7 三台机器都已安装并运行 `oMLX`，模型权重统一放在 `~/MLXModels`
|
||||
- 三台机器都存在 `com.lingyuzeng.omlx` 的 launchd plist，用于开机自动启动 oMLX 服务
|
||||
- 三台机器的 oMLX OpenAI 兼容接口分别为：
|
||||
|
||||
200
shared/long-term/projects/warp-acp-integration.md
Normal file
200
shared/long-term/projects/warp-acp-integration.md
Normal file
@@ -0,0 +1,200 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user