openclaw Configuration 配置管理

配置基础

OpenClaw 配置使用点号/方括号路径（例如：agents.list[0]）。值解析为 JSON5 格式。运行 openclaw config validate 来检查模式。

配置文件结构

配置文件位置

~/.openclaw/config.yaml     # 用户级配置
./config.yaml               # 项目级配置
/etc/openclaw/config.yaml   # 系统级配置

配置优先级

命令行参数 > 环境变量 > 项目配置 > 用户配置 > 系统配置

配置语法

基本语法

# 点号路径
server.port: 3000
server.host: "localhost"

# 方括号路径（数组访问）
agents.list[0].name: "primary"
agents.list[1].name: "backup"

# 嵌套对象
database:
  type: "postgresql"
  host: "localhost"
  port: 5432

JSON5 支持

# 支持注释
// 这是注释
server:
  /* 多行
     注释 */
  port: 3000

# 支持尾随逗号
agents: [
  "agent1",
  "agent2",  // 尾随逗号
]

# 支持单引号
message: 'Hello World'

核心配置项

服务器配置

server:
  host: "0.0.0.0"           # 监听地址
  port: 3000                # HTTP 端口
  websocket_port: 3001      # WebSocket 端口
  ssl:
    enabled: false          # SSL 启用
    cert_file: ""           # 证书文件
    key_file: ""            # 私钥文件

代理配置

agents:
  default: "primary"
  list:
    - name: "primary"
      model: "gpt-4"
      temperature: 0.7
      max_tokens: 2000
      
    - name: "backup"
      model: "claude-3"
      temperature: 0.5
      max_tokens: 1500

频道配置

channels:
  slack:
    enabled: true
    token: "xoxb-your-token"
    signing_secret: "your-secret"
    
  discord:
    enabled: false
    token: "your-discord-token"

日志配置

logging:
  level: "info"             # debug, warn, error
  format: "json"            # json, text
  outputs:
    - type: "file"
      path: "./logs/app.log"
      max_size: "100MB"
      max_files: 5
    - type: "console"
      level: "error"

环境变量映射

自动映射规则

配置路径          环境变量名
server.port   →  SERVER_PORT
agents.list[0].name → AGENTS_LIST_0_NAME
database.host → DATABASE_HOST

使用示例

# 设置环境变量
export SERVER_PORT=8080
export DATABASE_HOST=localhost

# 启动应用（自动读取环境变量）
openclaw start

配置命令

基本操作

# 查看当前配置
openclaw config view

# 设置配置值
openclaw config set server.port 8080

# 获取配置值
openclaw config get server.port

# 删除配置项
openclaw config unset server.debug

高级操作

# 验证配置有效性
openclaw config validate

# 导出配置
openclaw config export --format yaml > config.backup.yaml

# 导入配置
openclaw config import config.new.yaml

# 重置为默认配置
openclaw config reset

配置模板

开发环境模板

# config.dev.yaml
server:
  host: "localhost"
  port: 3000
  debug: true

logging:
  level: "debug"
  outputs:
    - type: "console"
      level: "debug"

database:
  type: "sqlite"
  file: "./data/dev.db"

生产环境模板

# config.prod.yaml
server:
  host: "0.0.0.0"
  port: 80
  ssl:
    enabled: true
    cert_file: "/etc/ssl/certs/openclaw.crt"
    key_file: "/etc/ssl/private/openclaw.key"

logging:
  level: "info"
  outputs:
    - type: "file"
      path: "/var/log/openclaw/app.log"
      rotation: "daily"

database:
  type: "postgresql"
  host: "db.internal"
  port: 5432
  username: "openclaw"
  password: "${DB_PASSWORD}"

最佳实践

1. 配置组织

# 按功能模块组织
core:
  # 核心配置
network:
  # 网络相关
security:
  # 安全配置
integrations:
  # 第三方集成

2. 敏感信息处理

# 使用环境变量引用
database:
  password: "${DB_PASSWORD}"
  api_key: "${API_KEY}"

# 或使用密钥管理服务
secrets:
  provider: "vault"
  address: "https://vault.company.com"

3. 版本控制

# .gitignore
config.local.yaml
config.secrets.yaml
*.backup.yaml

4. 配置验证

# 预提交钩子中添加配置验证
#!/bin/bash
openclaw config validate
if [ $? -ne 0 ]; then
    echo "配置验证失败！"
    exit 1
fi

故障排除

常见问题

配置值未生效

# 检查配置优先级
openclaw config view --sources

JSON5 解析错误

# 验证配置语法
openclaw config validate --verbose

环境变量未加载

# 检查环境变量
printenv | grep OPENCLAW

调试技巧

# 查看完整的配置合并结果
openclaw config view --merged

# 查看特定配置源
openclaw config view --source file

# 实时监控配置变化
openclaw config watch

更多详情请参考官方文档: https://docs.openclaw.ai/cli/config.md