Volcengine

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

Security Scan

The skill largely matches its stated purpose (integrating Volcengine models) but contains documentation/config inconsistencies and extra reconnaissance/scraping scripts that broaden its footprint; verify API key handling, endpoints, and any scripts before use.

Purpose & Capability

Name/description match the repository contents: docs, model lists, and usage examples for Volcengine. However the registry metadata declares no required credentials while the SKILL.md and many reference files clearly expect an API key (VOLCANO_ENGINE_API_KEY / openclaw onboarding). The repo also contains a substantial 'recon' and extraction toolset (Playwright scripts, deep-extract.js, extraction plans) whose presence is plausible for maintainers building the documentation, but is a broader capability than a minimal runtime provider integration.

Instruction Scope

SKILL.md instructions themselves are scoped to configuring an API key, adding providers to openclaw.json, testing with curl, and setting an env var. The SKILL.md does not instruct the agent to read local secrets or arbitrary files. However: (1) there are many included scripts (playwright recon, extraction, scraping plans) that are not referenced in the SKILL.md but can perform automated web scraping and headless-browser actions — these expand the effective scope if a user runs them; (2) documentation is inconsistent about API key format (some files say 'no sk- prefix', others show keys starting with 'sk-'); (3) the provider baseUrl used throughout is 'ark.cn-beijing.volces.com' (note 'volces' not 'volcengine') — this looks like a non-standard/possibly mistyped host and should be validated before use.

Install Mechanism

There is no install spec (instruction-only skill per registry), so nothing is automatically downloaded or installed by the platform. The repo does include scripts (Node/PowerShell) that a maintainer or user could run manually; running them would write to disk and execute code locally, but that's an explicit user action rather than an automatic install.

Credentials

The skill's practical operation requires an API key for Volcengine (documented in SKILL.md and many references), but the registry metadata declares no required env vars or primary credential — this mismatch may mislead users. The required secret (an API key) is proportionate to the provider integration, but the docs disagree on whether keys include an 'sk-' prefix. Also verify the baseUrl/host before sending a key; the repo consistently references 'ark.cn-beijing.volces.com', which is atypical and should be confirmed with official Volcengine docs.

Persistence & Privilege

Skill flags are default (always: false, agent-invocable allowed). The skill does not request permanent platform-wide presence. There is no evidence the skill attempts to modify other skills or global agent settings. The inclusion of scripts does not itself change platform privileges; they would only run if a user executes them.

What to consider before installing

This skill appears to implement a Volcengine provider integration and includes helpful docs and examples — but review before use: - API key: The SKILL.md and many references expect a Volcengine API key (set VOLCANO_ENGINE_API_KEY or use openclaw onboard). The registry metadata omitted this; assume you must supply a key. Do NOT commit keys to version control. - Endpoint sanity check: The repo uses baseUrl values like https://ark.cn-beijing.volces.com/api/v3 (note 'volces' spelling). Confirm the correct official API hostname with Volcengine docs before sending credentials or running tests. A mistyped or unexpected host may indicate config errors or a non-official proxy. - Inconsistent docs: Some files say keys require an 'sk-' prefix and others say they do not. Validate the expected key format from the Volcengine console. - Scripts and scraping tools: The repository contains Playwright/Node scraping and extraction scripts (scripts/recon/, extract_*.py, deep-extract.js). These can perform automated browsing/scraping and network requests. Only run these tools if you understand what they do and trust the source; they may touch external sites and send data off your host. - Minimal risk vectors: There is no automatic installer from remote URLs and no declared additional credentials beyond the provider key — the immediate risk is from manually running included scripts or misconfiguring endpoints. Actionable steps before installing/using: 1. Confirm official Volcengine API endpoints and expected API key format on Volcengine's site. 2. Prefer using openclaw's interactive onboarding to enter the key rather than editing files with plaintext keys. 3. Inspect any scripts you plan to run (scripts/recon/, scripts/*.ps1, .js files) to understand their network activity and targets; run them in an isolated environment if needed. 4. Do not run recon/scraping scripts as root or on a production machine; use an isolated VM or container. 5. If you need a clean, minimal provider integration, consider extracting only SKILL.md and configuration references and avoid the recon tooling.

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-1-8-251228",
            "name": "Doubao Seed 1.8",
            "reasoning": false,
            "input": ["text", "image"],
            "cost": { "input": 0, "output": 0 },
            "contextWindow": 256000,
            "maxTokens": 8192
          },
          {
            "id": "glm-4-7-251222",
            "name": "GLM 4.7",
            "reasoning": false,
            "input": ["text", "image"],
            "cost": { "input": 0, "output": 0 },
            "contextWindow": 200000,
            "maxTokens": 8192
          }
        ]
      },
      "volcengine-plan": {
        "baseUrl": "https://ark.cn-beijing.volces.com/api/coding/v3",
        "api": "openai-completions",
        "apiKey": "your-api-key-here",
        "models": [
          {
            "id": "ark-code-latest",
            "name": "Ark Coding Plan",
            "reasoning": false,
            "input": ["text"],
            "cost": { "input": 0, "output": 0 },
            "contextWindow": 256000,
            "maxTokens": 8192
          }
        ]
      }
    }
  }
}

3. Set Model Aliases (Optional)

For easier access, add aliases to agents.defaults.models:

{
  "agents": {
    "defaults": {
      "models": {
        "volcengine/doubao-seed-1-8-251228": {
          "alias": "Doubao"
        },
        "volcengine-plan/ark-code-latest": {
          "alias": "ArkCode"
        },
        "volcengine/glm-4-7-251222": {
          "alias": "GLM4"
        }
      }
    }
  }
}

Available Models

General Models (volcengine provider)

Model ID	Name	Input	Context	Description
doubao-seed-1-8-251228	Doubao Seed 1.8	text, image	256,000	ByteDance's flagship model
doubao-seed-code-preview-251028	Doubao Seed Code Preview	text, image	256,000	Code-focused preview
kimi-k2-5-260127	Kimi K2.5	text, image	256,000	Moonshot AI's model
glm-4-7-251222	GLM 4.7	text, image	200,000	Zhipu AI's model
deepseek-v3-2-251201	DeepSeek V3.2	text, image	128,000	DeepSeek's model

Coding Models (volcengine-plan provider)

Model ID	Name	Input	Context	Description
ark-code-latest	Ark Coding Plan	text	256,000	Optimized for coding tasks
doubao-seed-code	Doubao Seed Code	text	256,000	ByteDance's coding model
glm-4.7	GLM 4.7 Coding	text	200,000	Zhipu's coding model
kimi-k2-thinking	Kimi K2 Thinking	text	256,000	Moonshot's reasoning model
kimi-k2.5	Kimi K2.5 Coding	text	256,000	Moonshot's coding model

Usage Examples

Using via CLI

# Use Doubao model
openclaw --model Doubao "Hello, summarize this text"

# Use Ark Code for programming
openclaw --model ArkCode "Write a Python function to sort a list"

# Use full model reference
openclaw --model volcengine/doubao-seed-1-8-251228 "Explain quantum computing"

Setting Default Model

# Set Doubao as default
openclaw configure --set agents.defaults.model.primary volcengine/doubao-seed-1-8-251228

# Set Ark Code as default for coding tasks  
openclaw configure --set agents.defaults.model.primary volcengine-plan/ark-code-latest

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"

Custom Base URL

If you need a different region:

{
  "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 different region endpoint

3. Model not found

   • Verify model ID spelling
   • Check if model is available in your region
   • Ensure you're using correct provider (volcengine vs volcengine-plan)

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-1-8-251228",
    "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 volcengine-plan/* for coding tasks
   • Use volcengine/* for general conversation
   • Consider context window size for long documents

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

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

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

---

Documentation validated against official Volcano Engine API Reference PDF (2026-04-15) - High confidence verification completed