🎁 Get the FREE AI Skills Starter Guide — Subscribe →
BytesAgainBytesAgain
BytesAgain › Skills › Volcengine (Volcano Engine)
🦀 ClawHub

Volcengine (Volcano Engine)

by @andapeng

Configure and use Volcano Engine models like Doubao, GLM, Kimi, and DeepSeek via OpenClaw for general, coding, and troubleshooting tasks.

Versionv1.1.2
Downloads389
#crypto-defi#security#legal#gaming#productivity
TERMINAL
clawhub install volcano-engine

📖 About This Skill

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)

| Model ID | Name | Input | Context | Max Output | Notes | |----------|------|-------|---------|------------|-------| | doubao-1-5-pro-32k-250115 | Doubao 1.5 Pro 32K | text | 131,072 | 12,288 | Balanced flagship, function calling | | doubao-1-5-lite-32k-250115 | Doubao 1.5 Lite 32K | text | 32,768 | 12,288 | Lightweight, lower cost | | doubao-seed-character-251128 | Doubao Seed Character | text | 131,072 | 32,768 | Role-play optimized | | glm-4-7-251222 | GLM 4.7 | text | 204,800 | 131,072 | Zhipu AI, strong Chinese | | deepseek-v3-2-251201 | DeepSeek V3.2 | text | 131,072 | 32,768 | Cost-effective | | glm-4-5-air-20250728 | GLM 4.5 Air | text | — | — | Third-party, lightweight | | qwen3-32b-20250429 | Qwen 3 32B | text | — | — | Alibaba, deployed via volcengine |

VLM Models (Multimodal: Text + Image + Video)

| Model ID | Name | Input | Context | Max Output | Notes | |----------|------|-------|---------|------------|-------| | doubao-seed-2-0-pro-260215 | Doubao Seed 2.0 Pro | text, image, video | 262,144 | 131,072 | Latest flagship, recommended | | doubao-seed-2-0-lite-260215 | Doubao Seed 2.0 Lite | text, image, video | 262,144 | 131,072 | Fast, balanced | | doubao-seed-2-0-mini-260215 | Doubao Seed 2.0 Mini | text, image, video | 262,144 | 131,072 | Cost-efficient | | doubao-seed-2-0-code-preview-260215 | Doubao Seed 2.0 Code | text, image, video | 262,144 | 131,072 | Code-optimized | | doubao-seed-1-8-251228 | Doubao Seed 1.8 | text, image, video | 262,144 | 131,072 | Previous flagship | | doubao-seed-1-6-* | Doubao Seed 1.6 series | text, image, video | 262,144 | 131,072 | Flash/Vision variants | | doubao-1-5-vision-pro-32k-250115 | Doubao 1.5 Vision Pro | text, image | 131,072 | 12,288 | Older vision model |

Video & Image Generation

| Model ID | Name | Type | Input | |----------|------|------|-------| | doubao-seedance-2-0-260128 | Seedance 2.0 | Video | text, image, video, audio | | doubao-seedance-2-0-fast-260128 | Seedance 2.0 Fast | Video | text, image, video, audio | | doubao-seedance-1-5-pro-251215 | Seedance 1.5 Pro | Video | text, image | | doubao-seedream-5-0-260128 | Seedream 5.0 | Image | text | | doubao-seedream-4-5-251128 | Seedream 4.5 | Image | text |

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):

| Region | Endpoint | Recommendation | |--------|----------|----------------| | Beijing (default) | ark.cn-beijing.volces.com/api/v3 | Stable default | | Shanghai | ark.cn-shanghai.volces.com/api/v3 | Same models as Beijing |

> 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 \
  -H "Authorization: Bearer $VOLCANO_ENGINE_API_KEY" \
  -H "Content-Type: application/json" \
  -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*

    💡 Examples

    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"
        }
      }
    }
  }
}

    📋 Tips & 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