Volcengine (Volcano Engine)

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

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