技术方案：OpenClaw Volcengine/BytePlus Fast Mode 改造方案

📅 日期：2026-03-14
📎 分支：feature/volcengine-byteplus-fast-mode
📎 基于版本：OpenClaw v2026.3.12

一、背景

OpenClaw v2026.3.12 引入了 Fast Mode，但仅支持 OpenAI 和 Anthropic 两个 Provider。本方案为 Volcengine（火山引擎） 和 BytePlus 添加 Fast Mode 支持。

当前 Fast Mode 支持矩阵

Provider	API 类型	Fast Mode	说明
OpenAI	`openai-responses`	✅ 已支持	注入 reasoning + text + service_tier
Anthropic	`anthropic-messages`	✅ 已支持	注入 service_tier
Volcengine	`openai-completions`	❌ → ✅	本次新增
BytePlus	`openai-completions`	❌ → ✅	本次新增

现有 Wrapper 不命中的原因

OpenAI Fast Mode Wrapper → Guard 要求 model.api === "openai-responses"，火山引擎用的是 "openai-completions" ❌
Anthropic Fast Mode Wrapper → Guard 要求 model.provider === "anthropic" ❌

二、改动范围

2.1 文件变更

文件	类型	变更
`src/agents/pi-embedded-runner/volcengine-stream-wrappers.ts`	新增	Wrapper 实现
`src/agents/pi-embedded-runner/volcengine-stream-wrappers.test.ts`	新增	19 个单元测试
`src/agents/pi-embedded-runner/extra-params.ts`	修改	管线注册（+14 行）

2.2 不需要改动的部分（自动继承）

功能	说明
`/fast on/off` 命令	共享 `sessionEntry.fastMode`
`@fast on` 内联指令	共享 `extractFastDirective`
Config `params.fastMode`	共享 `resolveFastModeState()`
TUI `/fast`	共享 `sessions.patch` API
Control UI 下拉	共享 session 面板
ACP Bridge	共享 ACP config
`/status` 显示	共享状态卡片

三、实现细节

3.1 新增文件：`volcengine-stream-wrappers.ts`

支持的 Provider

const VOLCENGINE_PROVIDERS = new Set([
  "volcengine",        // 火山引擎标准
  "volcengine-plan",   // 火山引擎 Coding Plan
  "byteplus",          // BytePlus 标准
  "byteplus-plan",     // BytePlus Coding Plan
]);

Guard 条件（全部满足才注入）

条件	值	说明
`model.api`	`"openai-completions"`	ARK API 类型
`model.provider`	volcengine/byteplus 系列	不影响其他 Provider
`model.baseUrl`	`.volces.com` 或 `.bytepluses.com`	仅直连 ARK API

注入参数

参数	值	注入条件	作用
`stream_options.chunk_result`	`true`	payload 未指定	降低首 token 延迟 (TTFT)
`max_tokens`	`4096`	payload 未指定	减少生成长度开销
`temperature`	`0.3`	payload 未指定	更确定性的输出，加速推理

所有参数遵循 === undefined 守卫原则：用户显式设置的参数绝不被覆盖。

核心代码

export function createVolcengineFastModeWrapper(
  baseStreamFn: StreamFn | undefined,
  enabled: boolean,
): StreamFn {
  const underlying = baseStreamFn ?? streamSimple;

  // disabled 时直接透传
  if (!enabled) return underlying;

  return (model, context, options) => {
    // Guard 条件
    if (
      model.api !== "openai-completions" ||
      !VOLCENGINE_PROVIDERS.has(model.provider) ||
      !isVolcenginePublicApiBaseUrl(model.baseUrl)
    ) {
      return underlying(model, context, options);
    }

    // 注入 payload 修改
    const originalOnPayload = options?.onPayload;
    return underlying(model, context, {
      ...options,
      onPayload: (payload) => {
        if (payload && typeof payload === "object") {
          applyVolcengineFastModePayloadOverrides(payload);
        }
        return originalOnPayload?.(payload, model);
      },
    });
  };
}

3.2 修改文件：`extra-params.ts`

在 Wrapper 组装管线中，OpenAI Fast Mode 之后 注册：

// 现有：OpenAI Fast Mode
if (resolveOpenAIFastMode(merged)) {
  agent.streamFn = createOpenAIFastModeWrapper(agent.streamFn);
}

// 新增：Volcengine / BytePlus Fast Mode
const volcFastMode = resolveVolcengineFastMode(merged);
if (volcFastMode !== undefined && isVolcengineProvider(provider)) {
  log.debug(
    `applying Volcengine/BytePlus fast mode=${volcFastMode} for ${provider}/${modelId}`,
  );
  agent.streamFn = createVolcengineFastModeWrapper(agent.streamFn, volcFastMode);
}

完整管线位置

基础 streamFn
  ├── ...
  ├── 9.  Anthropic Fast Mode Wrapper
  ├── 10. OpenAI Fast Mode Wrapper
  ├── 11. 🆕 Volcengine/BytePlus Fast Mode Wrapper  ← 新增
  ├── 12. OpenAI Service Tier Wrapper
  └── ...

3.3 测试文件：`volcengine-stream-wrappers.test.ts`

测试组	测试数	覆盖内容
`isVolcengineProvider`	2	正确识别 4 个 Provider + 排除其他
`resolveVolcengineFastMode`	4	true/false/on/undefined 解析
Guard 条件	7	各 Provider ✅、非 volcengine ❌、错误 API ❌、未知 URL ❌、disabled ❌
Payload 覆盖	6	参数注入 ✅、不覆盖已有值 ✅、回调链 ✅
总计	19	全部通过 ✅

四、验证方法

4.1 安装测试版本

# 从 fork 分支安装（不影响其他机器）
npm install -g github:wujiaming88/openclaw#feature/volcengine-byteplus-fast-mode

# 重启 Gateway
openclaw gateway restart

# 确认版本（应显示 fork 的 commit hash）
openclaw --version

4.2 配置 Fast Mode

方式 A：Config 默认启用

在 ~/.openclaw/openclaw.json 中添加：

{
  "agents": {
    "defaults": {
      "models": {
        "volcengine/doubao-seed-1-8-251228": {
          "params": { "fastMode": true }
        },
        "byteplus/seed-1-8-251228": {
          "params": { "fastMode": true }
        }
      }
    }
  }
}

方式 B：会话中手动开启

/fast on

方式 C：消息内联指令

帮我写一个函数 /fast on

4.3 验证生效

检查日志

# 查看是否有 Volcengine fast mode 日志
grep -i "volcengine.*fast" /tmp/openclaw/openclaw-*.log

预期输出：

applying Volcengine/BytePlus fast mode=true for volcengine/doubao-seed-1-8-251228

检查状态

在对话中发送：

/fast

预期回复：

⚙️ Current fast mode: on

对比测试

/fast off → 发一条消息，记录响应时间
/fast on → 发同样消息，对比响应时间
Fast Mode 开启后应有明显的延迟降低

4.4 回滚

# 恢复到官方版本
npm install -g openclaw@2026.3.12
openclaw gateway restart

# 确认版本
openclaw --version
# 应显示：OpenClaw 2026.3.12 (6472949)

五、风险评估

风险	等级	说明
影响现有 Provider	🟢 无	Guard 条件严格隔离，仅匹配 volcengine/byteplus
影响现有 Fast Mode	🟢 无	OpenAI/Anthropic wrapper 代码未修改
参数兼容性	🟡 低	ARK API 兼容 OpenAI Chat Completions，注入参数均为标准字段
`stream_options` 支持	🟡 待确认	需验证 ARK API 是否支持 `chunk_result`
未来 ARK API 升级	🟢 无	如 ARK 新增 `service_tier` 等参数，可后续迭代

六、后续迭代建议

优先级	建议
P1	验证 ARK API 是否支持 `reasoning_effort` 参数（Seed 系列模型）
P2	如果火山引擎推出优先调度通道，添加 `service_tier` 支持
P3	根据实测数据调优 `max_tokens` 和 `temperature` 默认值
P3	考虑为不同模型（Seed vs Kimi vs GLM）定制不同的 fast mode 参数

文档由小帅整理于 2026-03-14