Volcengine: 高性能 AI 模型集成 - Openclaw Skills

什么是 Volcengine？

Volcengine 技能在火山引擎强大的模型生态系统与您的 AI 智能体工作流之间架起了一座坚实的桥梁。通过在 Openclaw Skills 中利用此集成，开发人员可以通过 OpenAI 兼容的端点访问包括豆包系列、GLM、DeepSeek 和通义千问在内的多种模型。此技能专为需要文本、图像和视频处理能力的高性能应用而设计。

此集成支持最新的 Seed 2.0 模型，提供庞大的上下文窗口和多模态输入。无论您是使用 GLM 4.7 构建本地化解决方案，还是使用 DeepSeek 构建成本优化的智能体，此技能都能简化身份验证和配置过程，确保您的 Openclaw Skills 设置达到企业级标准。

下载入口:https://github.com/openclaw/skills/tree/main/skills/andapeng/volcano-engine

安装与下载

1. ClawHub CLI

从源直接安装技能的最快方式。

npx clawhub@latest install volcano-engine

2. 手动安装

将技能文件夹复制到以下位置之一

全局模式 ~/.openclaw/skills/ 工作区 <project>/skills/

优先级：工作区 > 本地 > 内置

3. 提示词安装

将此提示词复制到 OpenClaw 即可自动安装。

请帮我使用 Clawhub 安装 volcano-engine。如果尚未安装 Clawhub，请先安装（npm i -g clawhub）。

Volcengine 应用场景

• 部署豆包 Seed 2.0 系列，处理涉及文本、图像和视频分析的复杂多模态任务。
• 使用 GLM 4.7 配置高性能中文智能体，以获得卓越的语言准确性。
• 使用 DeepSeek V3.2 集成实现高性价比的 AI 推理工作流。
• 扩展智能体能力，支持高达 262,144 token 的大上下文窗口，用于长文本处理。

Volcengine 工作原理

1. 用户从火山引擎控制台生成安全的 API key 并提供给 OpenClaw 环境。
2. 该技能配置数据面 API 端点，通常针对北京或上海地区以获得最佳延迟。
3. OpenClaw 通过标准化的 API 架构，利用 Volcengine 提供商路由模型推理请求。
4. 模型处理指定的输入类型（文本、视觉或视频）并将响应流式传输回智能体。
5. 使用情况和计费通过火山引擎控制台进行跟踪，从而实现对 Openclaw Skills 的细粒度成本管理。

Volcengine 配置指南

要开始使用，请先从火山引擎方舟控制台获取您的 API key。然后，使用 Openclaw Skills 提供的交互式设置命令：

openclaw onboard --auth-choice volcengine-api-key

如需手动配置，请使用以下提供商结构更新您的 openclaw.json：

{
  "models": {
    "providers": {
      "volcengine": {
        "baseUrl": "https://ark.cn-beijing.volces.com/api/v3",
        "api": "openai-completions",
        "apiKey": "YOUR_VOLCANO_ENGINE_API_KEY"
      }
    }
  }
}

Volcengine 数据架构与分类体系

Volcengine 技能组织模型配置和元数据以确保智能体无缝执行。关键数据结构包括：

组件	详情
API Endpoint	ark.cn-beijing.volces.com/api/v3 (默认)
身份验证	Bearer Token / HMAC-SHA256 Access Key
模型元数据	上下文窗口 (高达 262K), 输入类型, 最大输出 token
区域配置	支持北京和上海集群

所有模型交互都会被记录以进行故障排除，并完全支持官方错误代码映射。

name: volcengine
description: Configure and use Volcano Engine (Volcengine) models including Doubao (Seed 2.0), GLM, DeepSeek, and Qwen. Use when: (1) Setting up Volcengine API access in OpenClaw, (2) Choosing between LLM and VLM (multimodal) models, (3) Configuring model aliases for easy access, (4) Troubleshooting authentication or connection issues with Volcengine providers.

Volcengine Skill

Configure and use Volcano Engine (Volcengine) models with OpenClaw. This skill covers both general-purpose models and specialized coding models through Volcengine's OpenAI-compatible API endpoints.

Quick Start

1. Get API Key

1. Sign up at Volcano Engine Console
2. Navigate to Access Key Management
3. Create a new API key with appropriate permissions
4. Copy the API key (format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx，无需添加sk-前缀)

2. Configure OpenClaw

Interactive setup (recommended)

openclaw onboard --auth-choice volcengine-api-key

Follow the prompts to enter your API key.

Manual config (openclaw.json)

Add to your openclaw.json:

{
  "models": {
    "mode": "merge",
    "providers": {
      "volcengine": {
        "baseUrl": "https://ark.cn-beijing.volces.com/api/v3",
        "api": "openai-completions",
        "apiKey": "your-api-key-here",
        "models": [
          {
            "id": "doubao-seed-2-0-pro-260215",
            "name": "Doubao Seed 2.0 Pro",
            "reasoning": false,
            "input": ["text", "image", "video"],
            "cost": { "input": 0, "output": 0 },
            "contextWindow": 262144,
            "maxTokens": 131072
          },
          {
            "id": "doubao-seed-2-0-lite-260215",
            "name": "Doubao Seed 2.0 Lite",
            "reasoning": false,
            "input": ["text", "image", "video"],
            "cost": { "input": 0, "output": 0 },
            "contextWindow": 262144,
            "maxTokens": 131072
          },
          {
            "id": "glm-4-7-251222",
            "name": "GLM 4.7",
            "reasoning": false,
            "input": ["text", "image"],
            "cost": { "input": 0, "output": 0 },
            "contextWindow": 204800,
            "maxTokens": 131072
          },
          {
            "id": "doubao-seed-2-0-mini-260215",
            "name": "Doubao Seed 2.0 Mini",
            "reasoning": false,
            "input": ["text", "image", "video"],
            "cost": { "input": 0, "output": 0 },
            "contextWindow": 262144,
            "maxTokens": 131072
          },
          {
            "id": "deepseek-v3-2-251201",
            "name": "DeepSeek V3.2",
            "reasoning": false,
            "input": ["text"],
            "cost": { "input": 0, "output": 0 },
            "contextWindow": 131072,
            "maxTokens": 32768
          }
        ]
      }
    }
  }
}

3. Set Model Aliases (Optional)

For easier access, add aliases to agents.defaults.models:

{
  "agents": {
    "defaults": {
      "models": {
        "volcengine/doubao-seed-2-0-pro-260215": {
          "alias": "DoubaoPro"
        },
        "volcengine/doubao-seed-2-0-lite-260215": {
          "alias": "Doubao"
        },
        "volcengine/doubao-seed-2-0-mini-260215": {
          "alias": "DoubaoMini"
        },
        "volcengine/glm-4-7-251222": {
          "alias": "GLM4"
        }
      }
    }
  }
}

Available Models

LLM Models (Text Generation)

VLM Models (Multimodal: Text + Image + Video)

Video & Image Generation

See models.md for the complete list including deprecated models, 3D generation, embedding, and third-party models.

Usage Examples

Using via CLI

# Use Doubao 2.0 Lite (daily use)
openclaw --model Doubao "Hello, summarize this text"

# Use Doubao 2.0 Pro for complex tasks
openclaw --model DoubaoPro "Explain quantum computing with examples"

# Use full model reference
openclaw --model volcengine/doubao-seed-2-0-pro-260215 "Write a Python function"

# Use GLM 4.7 for Chinese content
openclaw --model GLM4 "写一篇关于人工智能的文章"

Setting Default Model

# Set Doubao as default
openclaw configure --set agents.defaults.model.primary volcengine/doubao-seed-2-0-pro-260215

# Set Doubao 2.0 Lite as default
openclaw configure --set agents.defaults.model.primary volcengine/doubao-seed-2-0-lite-260215

Advanced Configuration

Environment Variable

For better security, use environment variables:

# Set in your shell profile
export VOLCANO_ENGINE_API_KEY=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx  # 火山引擎密钥无需添加sk-前缀

# Reference in config
"apiKey": "VOLCANO_ENGINE_API_KEY"

Region Configuration

Volcano Engine API supports two regions (verified 2026-04-25):

Both regions expose the same 115 models. Pick whichever is geographically closer. Note: cn-guangzhou, cn-shenzhen, ap-southeast-1 and other regions were tested but do not resolve.

To switch regions:

# Using helper script
pwsh ./scripts/regional-config.ps1 -Region Shanghai

# Or manually in config

{
  "volcengine": {
    "baseUrl": "https://ark.cn-shanghai.volces.com/api/v3",
    // ... rest of config
  }
}

Troubleshooting

Common Issues

1. Authentication failed

   • Verify API key is correct
   • Check if key has necessary permissions
   • Ensure key is not expired

2. Connection timeout

   • Verify network connectivity to ark.cn-beijing.volces.com
   • Check firewall settings
   • Try switching to Shanghai region (regional-config.ps1 -Region Shanghai)

3. Model not found

   • Verify model ID spelling
   • Both regions share the same models (no region-specific model differences detected)
   • Ensure you're using the correct model ID

4. Rate limiting

   • Check API usage quotas
   • Implement retry logic with exponential backoff
   • Consider upgrading plan for higher limits

Testing Connection

# Test with curl
curl -X POST https://ark.cn-beijing.volces.com/api/v3/chat/completions r
  -H "Authorization: Bearer $VOLCANO_ENGINE_API_KEY" r
  -H "Content-Type: application/json" r
  -d '{
    "model": "doubao-seed-2-0-pro-260215",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

Cost Management

Volcano Engine uses token-based pricing. Check the official pricing page for current rates.

To monitor usage:

1. Visit Volcano Engine Console
2. Navigate to Billing Center
3. Check Usage Details

Best Practices

1. Model Selection

   • Use doubao-seed-2-0-code-preview-260215 for coding tasks
   • Use doubao-seed-2-0-pro-260215 for complex general tasks
   • Use doubao-seed-2-0-lite-260215 or doubao-seed-2-0-mini-260215 for daily/high-volume use
   • Consider context window size for long documents (Seed 2.0 series supports 262K)

2. API Key Security

   • Never commit API keys to version control
   • Use environment variables
   • Rotate keys periodically
   • Quota Limit: Each account supports up to 50 API Keys
   • Permission Control: Restrict keys to specific Model IDs or IP addresses
   • Project Isolation: Keys only work within their project space

3. Error Handling

   • Implement retry logic for transient failures (429, 500, 502, 503, 504)
   • Log errors for debugging
   • Set up alerts for quota limits
   • Handle sensitive content detection errors (400 series)
   • See Error Codes for complete list

4. Performance

   • Use streaming for long responses
   • Adjust temperature for creativity vs consistency
   • Set appropriate max_tokens to control response length

5. Authentication Methods

   • API Key (Recommended for most users): Simple bearer token authentication
   • Access Key (Enterprise): HMAC-SHA256 signature-based auth for fine-grained permissions
   • See Configuration Guide for details

6. Subscription & Access

   • Standard models: All models listed above work with a standard API key through the volcengine provider
   • Code Plan: For dedicated coding endpoint (volcengine-plan), a separate Code Plan subscription may be needed. Visit Console → Products & Services → Code Plan
   • Model availability: Check the Volcano Engine Console to see which models are deployed for your account

Documentation Validation

This skill has been validated against official Volcano Engine API Reference PDF (2026-04-15). Key validation findings:

? Verified Configuration

• API Key Format: Correct bearer token authentication
• Base URL: Verified Beijing region endpoint (ark.cn-beijing.volces.com)
• Error Codes: Complete mapping of official error codes
• Security Practices: Quota limits (50 API keys), permission controls, project isolation

?? PDF-Verified Information

Based on high-priority page extraction from official PDFs:

1. API Key Management:

   • Maximum 50 API keys per account
   • Keys can be restricted to specific Model IDs and IP addresses
   • Project space isolation (no cross-project access)

2. Error Handling:

   • Complete error code mapping for 400, 429, 401/403 errors
   • Sensitive content detection categories
   • Rate limiting error details

3. API Architecture:

   • Dual-track API (Data Plane vs Control Plane)
   • API version 2024-01-01
   • Regional endpoint configurations

?? Validation Methodology

1. PDF Analysis: Extracted 6 high-priority pages from volcengine-api-reference.pdf
2. Cross-Reference: Compared existing documentation against official specifications
3. Gap Analysis: Identified missing information and prioritized updates
4. Continuous Updates: Documentation updated based on official sources

Validation Status: ? High Confidence - Configuration aligns with official documentation

?? Model Data Source Update (2026-04-25)

Model information was refreshed via the Volcano Engine List Models API on 2026-04-25:

• Total active models: 39 (including text, vision, video, image, 3D, embedding, router)
• Active LLM: 7 models
• Active VLM: 12 models
• All Seed 2.0 models now support video input in addition to text and image
• Kimi models (K2, K2.5, K2-thinking) are no longer available on the platform (Shutdown/Retiring)
• DeepSeek V3.2 (not V4) is the latest available DeepSeek model
• See models.md for the complete detailed reference

API Architecture

Volcano Engine uses a dual-track API architecture:

Data Plane API (数据面API)

• Purpose: Direct business data transmission and real-time interaction
• Base URL: https://ark.cn-beijing.volces.com/api/v3
• Use Cases: Chat API, Responses API, model inference
• Authentication: API Key (Bearer token) or Access Key (HMAC-SHA256)

Control Plane API (管控面API)

• Purpose: System resource management and configuration
• Base URL: https://ark.cn-beijing.volcengineapi.com/
• Use Cases: API Key management, endpoint configuration, model customization
• Authentication: Access Key signature required

API Version

Current API version: 2024-01-01

Resources

• Volcano Engine Official Documentation
• API Reference
• Console
• Community Support

---

Model list last updated via API: 2026-04-25 | Core config validated against official PDF: 2026-04-15