# 確認(rèn) OpenClaw 版本（2026 年 6 月最新是 0.9.x）
openclaw --version
# 確認(rèn) Python 版本（至少 3.11）
python --version
# 確認(rèn) Node 版本（如果用 JS Skills）
node --version

openclaw.exceptions.SkillInitError: Failed to initialize skill 'my_skill': 
 config.yaml not found in skill root directory

# config.yaml — 放在 skill 根目錄
name: my_skill
version: "0.1.0"
runtime: python
entry: main.py
model:
 provider: openai-compatible
 name: claude-sonnet-4-20250514
timeout: 30

# main.py — 必須有這個(gè)函數(shù)簽名
async def run(context, params):
 """OpenClaw 標(biāo)準(zhǔn)入口函數(shù)"""
 user_input = params.get("input", "")
 # 你的邏輯
 return {"result": f"處理完成: {user_input}"}

openclaw.exceptions.AuthTokenExpired: API token expired at 2026-06-15T00:00:00Z. 
 Please refresh your token.

# 手動(dòng)刷新
openclaw auth refresh
# 或者在配置里開啟自動(dòng)刷新
openclaw config set auth.auto_refresh true

openclaw.exceptions.ModelNotFound: Model 'gpt-4' not found. 
 Available models: gpt-5, claude-sonnet-4-20250514, ...

# config.yaml 里用最新的模型名
model:
 provider: openai-compatible
 name: gpt-5 # 不是 gpt-4
 # 或者
 name: claude-sonnet-4-20250514 # 不是 claude-3.5-sonnet

model:
 provider: openai-compatible
 name: deepseek-chat
 base_url: "https://api.ofox.ai/v1"
 api_key: "your-key"

openclaw.exceptions.SkillTimeoutError: Skill 'data_analyzer' exceeded 
 timeout of 30s

# config.yaml
timeout: 120 # 改成 120 秒

# 或者在代碼里動(dòng)態(tài)設(shè)置
async def run(context, params):
 context.set_timeout(120)
 # 長(zhǎng)任務(wù)邏輯...

async def run(context, params):
 from openai import OpenAI
 client = OpenAI(
 api_key=context.get_secret("api_key"),
 base_url="https://api.ofox.ai/v1"
 )
 chunks = []
 stream = client.chat.completions.create(
 model="claude-sonnet-4-20250514",
 messages=[{"role": "user", "content": params["input"]}],
 stream=True
 )
 for chunk in stream:
 if chunk.choices[0].delta.content:
 chunks.append(chunk.choices[0].delta.content)
 # 持續(xù)輸出，不會(huì)超時(shí)
 await context.emit_progress(len(chunks))
 return {"result": "".join(chunks)}

openclaw.exceptions.DependencyConflict: Skill 'web_scraper' requires 
 httpx>=0.27 but openclaw-core pins httpx==0.25.2

# config.yaml — 使用隔離運(yùn)行時(shí)
runtime: python
isolation: venv # 關(guān)鍵！用虛擬環(huán)境隔離
dependencies:
 - httpx>=0.27
 - beautifulsoup4

runtime: python
isolation: container
dockerfile: ./Dockerfile # 自定義 Dockerfile

openclaw.exceptions.RateLimitExceeded: Rate limit exceeded for skill 
 'batch_processor': 60 calls/min (limit: 30)

import asyncio
async def run(context, params):
 items = params.get("items", [])
 results = []
 for i, item in enumerate(items):
 result = await process_item(context, item)
 results.append(result)
 # 每處理 5 個(gè)暫停 1 秒，避免觸發(fā)限流
 if (i + 1) % 5 == 0:
 await asyncio.sleep(1)
 return {"results": results}

rate_limit:
 calls_per_minute: 120
 burst: 20

openclaw.exceptions.SkillChainBreak: Chain broken at step 2 
 ('summarizer'): expected output key 'summary' not found in result

graph LR
 A[Skill: fetcher] -->|output: text| B[Skill: summarizer]
 B -->|? expected: summary
got: result| C[Skill: formatter]
 style B fill:#ff6b6b,color:#fff

# summarizer 的 config.yaml
name: summarizer
input_schema:
 type: object
 properties:
 text:
 type: string
 required: [text]
output_schema:
 type: object
 properties:
 summary: # 確保 key 名一致！
 type: string
 required: [summary]

# summarizer 的 main.py
async def run(context, params):
 text = params["text"]
 # 處理邏輯...
 return {"summary": processed_text} # 注意：是 summary 不是 result

openclaw.exceptions.MemoryOverflow: Skill 'image_processor' exceeded 
 memory limit of 512MB

# config.yaml
resources:
 memory: 2048 # 單位 MB
 cpu: 2 # CPU 核數(shù)

entry: src/main.py # 不要用反斜杠

# 錯(cuò)誤 — 引號(hào)會(huì)被當(dāng)成值的一部分
export OPENCLAW_API_KEY="sk-xxxx"
# 正確
export OPENCLAW_API_KEY=sk-xxxx

openclaw cache clear
openclaw dev --no-cache

graph TD
 A[OpenClaw 報(bào)錯(cuò)] --> B{報(bào)錯(cuò)信息里有哪個(gè)關(guān)鍵詞?}
 B -->|Init/Config| C[檢查 config.yaml 格式和路徑]
 B -->|Auth/Token| D[openclaw auth refresh]
 B -->|Model/NotFound| E[檢查模型名是否用了最新版本號(hào)]
 B -->|Timeout| F[增加 timeout 或改 streaming]
 B -->|Dependency| G[開啟 isolation: venv]
 B -->|RateLimit| H[加 sleep 或升級(jí)配額]
 B -->|Chain/Schema| I[檢查上下游 schema 定義]
 B -->|Memory| J[增加 resources.memory]
 B -->|其他| K[openclaw logs --tail 50 看完整日志]
 C --> L[重新運(yùn)行 openclaw dev]
 D --> L
 E --> L
 F --> L
 G --> L
 H --> L
 I --> L
 J --> L
 K --> L