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

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

1. 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

1. 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)

1. 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

1. 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

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

1. 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

1. 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)

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

1. 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