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)

bash

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

Follow the prompts to enter your API key.

Manual config (openclaw.json)

Add to your openclaw.json:

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:

json

{
  "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 IDNameInputContextMax OutputNotesdoubao-1-5-pro-32k-250115Doubao 1.5 Pro 32Ktext131,07212,288Balanced flagship, function callingdoubao-1-5-lite-32k-250115Doubao 1.5 Lite 32Ktext32,76812,288Lightweight, lower costdoubao-seed-character-251128Doubao Seed Charactertext131,07232,768Role-play optimizedglm-4-7-251222GLM 4.7text204,800131,072Zhipu AI, strong Chinesedeepseek-v3-2-251201DeepSeek V3.2text131,07232,768Cost-effectiveglm-4-5-air-20250728GLM 4.5 Airtext——Third-party, lightweightqwen3-32b-20250429Qwen 3 32Btext——Alibaba, deployed via volcengine

VLM Models (Multimodal: Text + Image + Video)#

Model IDNameInputContextMax OutputNotesdoubao-seed-2-0-pro-260215Doubao Seed 2.0 Protext, image, video262,144131,072Latest flagship, recommendeddoubao-seed-2-0-lite-260215Doubao Seed 2.0 Litetext, image, video262,144131,072Fast, balanceddoubao-seed-2-0-mini-260215Doubao Seed 2.0 Minitext, image, video262,144131,072Cost-efficientdoubao-seed-2-0-code-preview-260215Doubao Seed 2.0 Codetext, image, video262,144131,072Code-optimizeddoubao-seed-1-8-251228Doubao Seed 1.8text, image, video262,144131,072Previous flagshipdoubao-seed-1-6-*Doubao Seed 1.6 seriestext, image, video262,144131,072Flash/Vision variantsdoubao-1-5-vision-pro-32k-250115Doubao 1.5 Vision Protext, image131,07212,288Older vision model

Video & Image Generation#

Model IDNameTypeInputdoubao-seedance-2-0-260128Seedance 2.0Videotext, image, video, audiodoubao-seedance-2-0-fast-260128Seedance 2.0 FastVideotext, image, video, audiodoubao-seedance-1-5-pro-251215Seedance 1.5 ProVideotext, imagedoubao-seedream-5-0-260128Seedream 5.0Imagetextdoubao-seedream-4-5-251128Seedream 4.5Imagetext

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

Usage Examples#

Using via CLI#

bash

# 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#

bash

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

bash

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

RegionEndpointRecommendationBeijing (default)ark.cn-beijing.volces.com/api/v3Stable defaultShanghaiark.cn-shanghai.volces.com/api/v3Same 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:

bash

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

# Or manually in config

json

{
  "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#

bash

# 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