IT架构师

奔赴山海，保持热爱

0%

OpenClaw 配置文件详解：从入门到生产环境最佳实践

发表于 更新于 分类于 ， ，
本文字数： 24k 阅读时长 ≈ 43 分钟

OpenClaw 配置文件详解：从入门到生产环境最佳实践

摘要：配置文件是 OpenClaw 的”大脑”，决定了 Agent 的行为、能力、连接方式。本文深入解析 openclaw.json 的完整结构：模型配置、渠道配置、Gateway 配置、安全配置、扩展配置。从本地开发到 K8s 生产环境，包含完整配置示例、常见错误排查、安全加固方案、性能优化建议，以及真实生产环境的配置实践。

关键词：OpenClaw、配置文件、openclaw.json、环境配置、模型配置、渠道配置

一、配置文件概览

1.1 配置文件位置

1
2
3
4
5
6
7
8
9
10
OpenClaw 配置文件层次：
┌─────────────────────────────────────────────────────────┐
│  系统级：/etc/openclaw/openclaw.json（不推荐修改）       │
├─────────────────────────────────────────────────────────┤
│  用户级：~/.openclaw/openclaw.json（推荐）              │
├─────────────────────────────────────────────────────────┤
│  项目级：./.openclaw/openclaw.json（项目特定）          │
├─────────────────────────────────────────────────────────┤
│  运行时：环境变量覆盖（最高优先级）                      │
└─────────────────────────────────────────────────────────┘

1.2 配置加载顺序

1
2
3
4
5
6
7
8
9
10
graph TB
    A[启动 OpenClaw] --> B[加载系统配置]
    B --> C[加载用户配置]
    C --> D[合并配置]
    D --> E[应用环境变量]
    E --> F[验证配置]
    F --> G{配置有效？}
    G -->|是 | H[启动成功]
    G -->|否 | I[启动失败]
    I --> J[错误提示]

优先级：环境变量 > 项目配置 > 用户配置 > 系统配置 > 默认值

1.3 配置结构总览

1
2
3
4
5
6
7
8
9
10
{
  "models": {},           // 模型配置
  "channels": {},         // 渠道配置
  "gateway": {},          // Gateway 配置
  "browser": {},          // 浏览器配置
  "workspace": {},        // 工作区配置
  "security": {},         // 安全配置
  "logging": {},          // 日志配置
  "extensions": {}        // 扩展配置
}

二、模型配置

2.1 基础配置

1
2
3
4
5
6
7
8
9
10
11
12
{
  "models": {
    "default": "bailian/qwen3.5-plus",
    "fallback": "bailian/qwen-plus",
    "providers": {
      "bailian": {
        "baseUrl": "https://coding.dashscope.aliyuncs.com/v1",
        "apiKey": "sk-xxxxxxxxxxxxxxxx"
      }
    }
  }
}

2.2 多模型配置

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
{
  "models": {
    "default": "bailian/qwen3.5-plus",
    
    "byTask": {
      "chat": "bailian/qwen3.5-plus",
      "code": "bailian/qwen-coder",
      "analysis": "bailian/qwen-max",
      "translation": "bailian/qwen-turbo"
    },
    
    "byChannel": {
      "feishu": "bailian/qwen3.5-plus",
      "discord": "bailian/qwen-plus",
      "web": "bailian/qwen3.5-plus"
    },
    
    "providers": {
      "bailian": {
        "baseUrl": "https://coding.dashscope.aliyuncs.com/v1",
        "apiKey": "sk-xxxxxxxxxxxxxxxx",
        "models": {
          "qwen3.5-plus": {
            "contextWindow": 32768,
            "maxTokens": 8192,
            "temperature": 0.7,
            "topP": 0.9
          },
          "qwen-coder": {
            "contextWindow": 32768,
            "maxTokens": 8192,
            "temperature": 0.3,
            "topP": 0.95
          },
          "qwen-max": {
            "contextWindow": 32768,
            "maxTokens": 8192,
            "temperature": 0.5,
            "topP": 0.9
          },
          "qwen-turbo": {
            "contextWindow": 8192,
            "maxTokens": 2048,
            "temperature": 0.7,
            "topP": 0.9
          }
        }
      },
      
      "openai": {
        "baseUrl": "https://api.openai.com/v1",
        "apiKey": "sk-xxxxxxxxxxxxxxxx",
        "models": {
          "gpt-4": {
            "contextWindow": 8192,
            "maxTokens": 4096,
            "temperature": 0.7
          },
          "gpt-3.5-turbo": {
            "contextWindow": 4096,
            "maxTokens": 4096,
            "temperature": 0.7
          }
        }
      },
      
      "local": {
        "baseUrl": "http://localhost:11434/v1",
        "models": {
          "llama2": {
            "contextWindow": 4096,
            "maxTokens": 2048,
            "temperature": 0.7
          }
        }
      }
    }
  }
}

2.3 模型选择策略

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
def select_model(task_type: str, channel: str, user_preference: str = None):
    """模型选择策略"""
    
    # 1. 用户显式指定
    if user_preference:
        return user_preference
    
    # 2. 按任务类型
    if task_type in config['models']['byTask']:
        return config['models']['byTask'][task_type]
    
    # 3. 按渠道
    if channel in config['models']['byChannel']:
        return config['models']['byChannel'][channel]
    
    # 4. 默认模型
    return config['models']['default']

2.4 模型性能对比

模型 上下文 速度 质量 成本 适用场景
qwen3.5-plus 32K ⭐⭐⭐⭐ ⭐⭐⭐⭐⭐ 中 通用对话、复杂任务
qwen-coder 32K ⭐⭐⭐⭐ ⭐⭐⭐⭐⭐ 中 代码生成、审查
qwen-max 32K ⭐⭐⭐ ⭐⭐⭐⭐⭐ 高 复杂分析、推理
qwen-turbo 8K ⭐⭐⭐⭐⭐ ⭐⭐⭐ 低 简单任务、翻译
gpt-4 8K ⭐⭐⭐ ⭐⭐⭐⭐⭐ 高 高质量输出
llama2 4K ⭐⭐⭐⭐ ⭐⭐⭐ 免费 本地测试

三、渠道配置

3.1 飞书配置

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
{
  "channels": {
    "feishu": {
      "enabled": true,
      "appId": "cli_a1b2c3d4e5f6g7h8",
      "appSecret": "xxxxxxxxxxxxxxxxxx",
      "verificationToken": "xxxxxxxxxxxxxxxxxx",
      "dmPolicy": "pairing",
      "groupPolicy": "mention",
      "webhookPath": "/openclaw/feishu/webhook",
      "capabilities": {
        "inlineButtons": "dm",
        "richCards": true,
        "fileUpload": true
      },
      "messageFormat": {
        "defaultType": "text",
        "enableMarkdown": true,
        "maxTextLength": 3000
      },
      "rateLimit": {
        "enabled": true,
        "maxPerMinute": 60,
        "maxPerHour": 1000
      }
    }
  }
}

3.2 微信配置

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
  "channels": {
    "wechat": {
      "enabled": false,
      "type": "enterprise",
      "corpId": "wwxxxxxxxxxxxx",
      "agentId": "1000001",
      "secret": "xxxxxxxxxxxxxxxxxx",
      "token": "xxxxxxxxxxxxxxxxxx",
      "encodingAesKey": "xxxxxxxxxxxxxxxxxx",
      "dmPolicy": "pairing",
      "groupPolicy": "mention"
    }
  }
}

3.3 Discord 配置

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
  "channels": {
    "discord": {
      "enabled": false,
      "botToken": "xxxxxxxxxxxxxxxxxx",
      "guildId": "xxxxxxxxxxxxxxxxxx",
      "channelId": "xxxxxxxxxxxxxxxxxx",
      "enableMentions": true,
      "enableEmbeds": true,
      "prefix": "!",
      "commands": {
        "help": "/help",
        "status": "/status",
        "reset": "/reset"
      }
    }
  }
}

3.4 多渠道配置

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
{
  "channels": {
    "feishu": {
      "enabled": true,
      "priority": 1,
      "appId": "cli_xxx",
      "appSecret": "xxx"
    },
    "wechat": {
      "enabled": true,
      "priority": 2,
      "corpId": "wwxxx",
      "secret": "xxx"
    },
    "discord": {
      "enabled": false,
      "priority": 3,
      "botToken": "xxx"
    },
    "telegram": {
      "enabled": false,
      "priority": 4,
      "botToken": "xxx"
    },
    "whatsapp": {
      "enabled": false,
      "priority": 5,
      "phoneNumberId": "xxx",
      "accessToken": "xxx"
    }
  }
}

四、Gateway 配置

4.1 基础配置

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
{
  "gateway": {
    "port": 18789,
    "host": "0.0.0.0",
    "cors": {
      "enabled": true,
      "origins": ["*"],
      "methods": ["GET", "POST", "PUT", "DELETE", "OPTIONS"],
      "headers": ["Content-Type", "Authorization", "X-Request-ID"]
    },
    "ssl": {
      "enabled": false,
      "certPath": "/path/to/cert.pem",
      "keyPath": "/path/to/key.pem"
    },
    "compression": {
      "enabled": true,
      "threshold": 1024,
      "level": 6
    }
  }
}

4.2 认证配置

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
{
  "gateway": {
    "port": 18789,
    "auth": {
      "enabled": true,
      "type": "jwt",
      "secret": "your-jwt-secret-key",
      "expiresIn": "24h",
      "refreshEnabled": true,
      "refreshExpiresIn": "7d"
    },
    "apiKey": {
      "enabled": true,
      "header": "X-API-Key",
      "keys": [
        {
          "name": "admin",
          "key": "ak_xxxxxxxxxxxxxxxxxx",
          "permissions": ["*"]
        },
        {
          "name": "user",
          "key": "ak_yyyyyyyyyyyyyyyyyy",
          "permissions": ["read", "write"]
        }
      ]
    }
  }
}

4.3 限流配置

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
{
  "gateway": {
    "port": 18789,
    "rateLimit": {
      "enabled": true,
      "windowMs": 60000,
      "maxRequests": 100,
      "message": "请求过于频繁，请稍后再试",
      "headers": {
        "sendLimit": true,
        "sendRemaining": true,
        "sendReset": true
      },
      "skip": [
        "/health",
        "/metrics",
        "/ready"
      ]
    }
  }
}

4.4 K8s 环境配置

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
{
  "gateway": {
    "port": 18789,
    "host": "0.0.0.0",
    "metrics": {
      "enabled": true,
      "port": 18790,
      "path": "/metrics"
    },
    "health": {
      "enabled": true,
      "path": "/health",
      "interval": 30
    },
    "ready": {
      "enabled": true,
      "path": "/ready"
    },
    "gracefulShutdown": {
      "enabled": true,
      "timeout": 30
    }
  }
}

五、浏览器配置

5.1 基础配置

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
  "browser": {
    "enabled": true,
    "port": 18791,
    "profile": "openclaw",
    "headless": true,
    "timeout": 30000,
    "proxy": {
      "enabled": false,
      "server": "http://proxy.example.com:8080",
      "username": "user",
      "password": "pass"
    }
  }
}

5.2 Chrome 扩展配置

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
  "browser": {
    "enabled": true,
    "port": 18791,
    "profile": "chrome",
    "extension": {
      "enabled": true,
      "id": "xxxxxxxxxxxxxxxxxx",
      "autoAttach": true
    },
    "tabs": {
      "maxOpen": 10,
      "autoClose": true,
      "closeAfter": 300
    }
  }
}

5.3 Playwright 配置

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
  "browser": {
    "enabled": true,
    "port": 18791,
    "engine": "playwright",
    "browser": "chromium",
    "options": {
      "headless": true,
      "args": [
        "--no-sandbox",
        "--disable-setuid-sandbox",
        "--disable-dev-shm-usage"
      ],
      "viewport": {
        "width": 1920,
        "height": 1080
      }
    }
  }
}

六、工作区配置

6.1 基础配置

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
  "workspace": {
    "path": "/home/johnzok/.openclaw/workspace",
    "autoCreate": true,
    "permissions": {
      "read": true,
      "write": true,
      "execute": true
    },
    "backup": {
      "enabled": true,
      "interval": "daily",
      "time": "02:00",
      "retention": 30,
      "destination": "minio"
    }
  }
}

6.2 记忆配置

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
  "workspace": {
    "path": "/home/johnzok/.openclaw/workspace",
    "memory": {
      "enabled": true,
      "path": "memory/",
      "dailyEnabled": true,
      "longTermEnabled": true,
      "semanticSearch": {
        "enabled": true,
        "model": "bge-m3",
        "threshold": 0.7
      },
      "retention": {
        "daily": 90,
        "longTerm": -1
      }
    }
  }
}

6.3 技能配置

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
  "workspace": {
    "path": "/home/johnzok/.openclaw/workspace",
    "skills": {
      "enabled": true,
      "path": "skills/",
      "autoLoad": true,
      "sandbox": {
        "enabled": true,
        "allowedCommands": ["ls", "cat", "grep", "find"],
        "blockedCommands": ["rm", "sudo", "curl", "wget"],
        "maxExecutionTime": 30
      }
    }
  }
}

七、安全配置

7.1 基础安全

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
{
  "security": {
    "encryption": {
      "enabled": true,
      "algorithm": "aes-256-gcm",
      "keyRotation": "monthly"
    },
    "audit": {
      "enabled": true,
      "logPath": "logs/audit.log",
      "events": [
        "login",
        "logout",
        "config_change",
        "file_access",
        "command_execution"
      ]
    },
    "session": {
      "timeout": 3600,
      "maxConcurrent": 5,
      "secureCookie": true,
      "sameSite": "strict"
    }
  }
}

7.2 命令执行安全

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
{
  "security": {
    "exec": {
      "enabled": true,
      "mode": "allowlist",
      "allowlist": [
        "ls",
        "cat",
        "grep",
        "find",
        "git",
        "npm",
        "mvn",
        "python3"
      ],
      "blocklist": [
        "rm -rf",
        "sudo",
        "curl",
        "wget",
        "nc",
        "netcat"
      ],
      "maxExecutionTime": 300,
      "requireConfirmation": [
        "git push",
        "npm publish",
        "mvn deploy"
      ]
    }
  }
}

7.3 文件访问安全

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
{
  "security": {
    "fileAccess": {
      "enabled": true,
      "allowedPaths": [
        "/home/johnzok/.openclaw/workspace"
      ],
      "blockedPaths": [
        "/etc",
        "/root",
        "/home/*/.*"
      ],
      "maxFileSize": 52428800,
      "allowedExtensions": [
        ".md",
        ".txt",
        ".json",
        ".yaml",
        ".yml",
        ".py",
        ".js",
        ".java"
      ],
      "blockedExtensions": [
        ".exe",
        ".sh",
        ".bat",
        ".cmd"
      ]
    }
  }
}

八、日志配置

8.1 基础日志

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{
  "logging": {
    "level": "info",
    "format": "json",
    "output": {
      "console": {
        "enabled": true,
        "colorize": true
      },
      "file": {
        "enabled": true,
        "path": "logs/gateway.log",
        "maxSize": "100MB",
        "maxFiles": 10,
        "rotate": "daily"
      }
    }
  }
}

8.2 详细日志

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
{
  "logging": {
    "level": "debug",
    "format": "json",
    "output": {
      "console": {
        "enabled": true,
        "colorize": true
      },
      "file": {
        "enabled": true,
        "path": "logs/gateway.log",
        "maxSize": "100MB",
        "maxFiles": 30,
        "rotate": "daily"
      },
      "elk": {
        "enabled": true,
        "host": "elk.example.com",
        "port": 9200,
        "index": "openclaw-logs"
      }
    },
    "sampling": {
      "enabled": true,
      "rate": 0.1
    }
  }
}

九、扩展配置

9.1 MCP 服务器

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
{
  "extensions": {
    "mcp": {
      "enabled": true,
      "servers": [
        {
          "name": "filesystem",
          "type": "stdio",
          "command": "npx",
          "args": ["-y", "@modelcontextprotocol/server-filesystem"],
          "env": {}
        },
        {
          "name": "git",
          "type": "stdio",
          "command": "npx",
          "args": ["-y", "@modelcontextprotocol/server-git"],
          "env": {}
        },
        {
          "name": "postgres",
          "type": "sse",
          "url": "http://localhost:8080/sse"
        }
      ]
    }
  }
}

9.2 自定义扩展

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
  "extensions": {
    "custom": {
      "enabled": true,
      "paths": [
        "extensions/custom/",
        "extensions/community/"
      ],
      "autoLoad": true,
      "sandbox": {
        "enabled": true,
        "timeout": 30
      }
    }
  }
}

十、环境特定配置

10.1 开发环境

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
{
  "models": {
    "default": "local/llama2",
    "providers": {
      "local": {
        "baseUrl": "http://localhost:11434/v1"
      }
    }
  },
  "gateway": {
    "port": 18789,
    "host": "localhost",
    "auth": {
      "enabled": false
    }
  },
  "logging": {
    "level": "debug",
    "output": {
      "console": {
        "enabled": true,
        "colorize": true
      }
    }
  },
  "security": {
    "exec": {
      "mode": "full"
    }
  }
}

10.2 测试环境

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
{
  "models": {
    "default": "bailian/qwen-turbo",
    "providers": {
      "bailian": {
        "baseUrl": "https://coding.dashscope.aliyuncs.com/v1"
      }
    }
  },
  "gateway": {
    "port": 18789,
    "host": "0.0.0.0",
    "auth": {
      "enabled": true,
      "type": "api-key"
    }
  },
  "logging": {
    "level": "info"
  },
  "security": {
    "exec": {
      "mode": "allowlist"
    }
  }
}

10.3 生产环境（K8s）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
{
  "models": {
    "default": "bailian/qwen3.5-plus",
    "fallback": "bailian/qwen-plus",
    "providers": {
      "bailian": {
        "baseUrl": "https://coding.dashscope.aliyuncs.com/v1"
      }
    }
  },
  "channels": {
    "feishu": {
      "enabled": true,
      "dmPolicy": "pairing",
      "groupPolicy": "mention"
    }
  },
  "gateway": {
    "port": 18789,
    "host": "0.0.0.0",
    "metrics": {
      "enabled": true,
      "port": 18790
    },
    "health": {
      "enabled": true
    },
    "auth": {
      "enabled": true,
      "type": "jwt"
    },
    "rateLimit": {
      "enabled": true,
      "maxRequests": 100
    },
    "gracefulShutdown": {
      "enabled": true,
      "timeout": 30
    }
  },
  "browser": {
    "enabled": true,
    "port": 18791,
    "headless": true
  },
  "workspace": {
    "path": "/root/.openclaw/workspace",
    "backup": {
      "enabled": true,
      "interval": "daily",
      "destination": "minio"
    }
  },
  "security": {
    "encryption": {
      "enabled": true
    },
    "audit": {
      "enabled": true
    },
    "exec": {
      "mode": "allowlist"
    },
    "fileAccess": {
      "enabled": true
    }
  },
  "logging": {
    "level": "info",
    "format": "json",
    "output": {
      "file": {
        "enabled": true,
        "maxSize": "100MB",
        "maxFiles": 30
      }
    }
  }
}

十一、配置管理最佳实践

11.1 敏感信息管理

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
# ❌ 错误：明文存储
{
  "models": {
    "providers": {
      "bailian": {
        "apiKey": "sk-xxxxxxxxxxxxxxxx"
      }
    }
  }
}

# ✅ 正确：环境变量
{
  "models": {
    "providers": {
      "bailian": {
        "apiKey": "${DASHSCOPE_API_KEY}"
      }
    }
  }
}

# 设置环境变量
export DASHSCOPE_API_KEY="sk-xxxxxxxxxxxxxxxx"

11.2 配置版本控制

1
2
3
4
5
6
7
8
9
10
11
12
13
# 1. 创建配置模板
cp openclaw.json openclaw.json.template

# 2. 从模板生成实际配置
envsubst < openclaw.json.template > openclaw.json

# 3. Git 管理模板（不管理实际配置）
git add openclaw.json.template
git add .gitignore

# .gitignore
openclaw.json
*.secret

11.3 配置验证

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
def validate_config(config: dict) -> ValidationResult:
    """验证配置"""
    
    errors = []
    warnings = []
    
    # 1. 必需字段检查
    required_fields = ['models', 'gateway']
    for field in required_fields:
        if field not in config:
            errors.append(f"缺少必需字段：{field}")
    
    # 2. 模型配置验证
    if 'models' in config:
        if 'default' not in config['models']:
            errors.append("未指定默认模型")
        
        if 'providers' not in config['models']:
            errors.append("未配置模型提供商")
    
    # 3. Gateway 配置验证
    if 'gateway' in config:
        port = config['gateway'].get('port', 18789)
        if port < 1024 or port > 65535:
            errors.append(f"无效端口：{port}")
    
    # 4. 安全配置检查
    if 'security' not in config:
        warnings.append("未配置安全选项，使用默认值")
    
    # 5. 日志配置检查
    if 'logging' not in config:
        warnings.append("未配置日志选项，使用默认值")
    
    return ValidationResult(
        valid=len(errors) == 0,
        errors=errors,
        warnings=warnings
    )

十二、故障排查

12.1 问题 #1：配置加载失败

现象

1
Error: Failed to load configuration: Invalid JSON

排查

1
2
3
4
5
6
7
8
# 1. 验证 JSON 格式
jq . ~/.openclaw/openclaw.json

# 2. 检查文件权限
ls -la ~/.openclaw/openclaw.json

# 3. 查看完整错误
openclaw gateway start --verbose

解决方案

1
2
3
# 修复 JSON 格式
python3 -m json.tool openclaw.json > openclaw.fixed.json
mv openclaw.fixed.json openclaw.json

12.2 问题 #2：模型调用失败

现象

1
Error: Model 'qwen-plus' not found

排查

1
2
3
4
5
6
7
8
9
# 1. 检查模型配置
jq '.models' ~/.openclaw/openclaw.json

# 2. 验证 API Key
curl -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  https://coding.dashscope.aliyuncs.com/v1/models

# 3. 测试模型调用
openclaw models test --model bailian/qwen3.5-plus

解决方案

1
2
3
4
5
6
7
8
9
10
11
{
  "models": {
    "default": "bailian/qwen3.5-plus",
    "providers": {
      "bailian": {
        "baseUrl": "https://coding.dashscope.aliyuncs.com/v1",
        "apiKey": "${DASHSCOPE_API_KEY}"
      }
    }
  }
}

12.3 问题 #3：渠道连接失败

现象

1
Error: Failed to connect to Feishu: 401 Unauthorized

排查

1
2
3
4
5
6
7
8
9
10
# 1. 检查渠道配置
jq '.channels.feishu' ~/.openclaw/openclaw.json

# 2. 验证 App ID/Secret
curl -X POST https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal \
  -H "Content-Type: application/json" \
  -d '{"app_id":"cli_xxx","app_secret":"xxx"}'

# 3. 检查网络连通性
telnet open.feishu.cn 443

解决方案

1
2
3
4
5
6
7
8
9
10
{
  "channels": {
    "feishu": {
      "enabled": true,
      "appId": "${FEISHU_APP_ID}",
      "appSecret": "${FEISHU_APP_SECRET}",
      "verificationToken": "${FEISHU_VERIFICATION_TOKEN}"
    }
  }
}

十三、参考资料

13.1 官方文档

13.2 配置模板

1
2
3
obsidian-sync/projects/P3_OpenClaw_Extension/02_Docs/K8s_Deployment/
├── openclaw.json.template
└── DEPLOYMENT_PRACTICE.md

13.3 相关工具

作者：John
职位：高级技术架构师
日期：2026-03-04
版本：v1.0

本文基于 OpenClaw 生产环境配置经验编写，所有配置均经过实际验证。配置是 OpenClaw 的”大脑”，值得深入理解和持续优化。