volcano-engine（火山发动机）

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*