From 298a77bd0e2fab4022c0af2bf5a2c9e6eeecebce Mon Sep 17 00:00:00 2001 From: hotwa Date: Tue, 17 Mar 2026 19:53:58 +0800 Subject: [PATCH] Add Warp ACP provider design and ops docs --- agents/openclaw-main/warp-acp-ops.md | 115 ++++++++++ daily/2026-03-17.md | 22 ++ .../projects/warp-acp-integration.md | 200 ++++++++++++++++++ 3 files changed, 337 insertions(+) create mode 100644 agents/openclaw-main/warp-acp-ops.md create mode 100644 shared/long-term/projects/warp-acp-integration.md diff --git a/agents/openclaw-main/warp-acp-ops.md b/agents/openclaw-main/warp-acp-ops.md new file mode 100644 index 0000000..faccc7e --- /dev/null +++ b/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__*` variable names to the ops doc +2. add/update fallback chains in the long-term project doc +3. add the corresponding `opencode-warp--` naming entry +4. document the change in daily notes diff --git a/daily/2026-03-17.md b/daily/2026-03-17.md index 6cbca65..0c37332 100644 --- a/daily/2026-03-17.md +++ b/daily/2026-03-17.md @@ -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 兼容接口分别为： diff --git a/shared/long-term/projects/warp-acp-integration.md b/shared/long-term/projects/warp-acp-integration.md new file mode 100644 index 0000000..089273c --- /dev/null +++ b/shared/long-term/projects/warp-acp-integration.md @@ -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__API_KEY` +- `WARP__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: + +- `-warp--` + +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__API_KEY and WARP__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.