配置参考手册

OpenClaw平台使用 config.yaml 作为核心配置文件，支持对全局设置、Agent行为、模型管理、工具集成、存储后端和日志系统进行全面控制。本手册将逐一详解每个配置段的所有可用选项。

全局配置（global）

全局配置段定义了平台级别的基础参数，这些参数影响整个OpenClaw实例的运行行为：

global:
  # 平台名称，用于标识和日志显示
  name: "my-openclaw-instance"

  # 运行模式：development / staging / production
  mode: production

  # 默认语言（影响系统提示词和日志）
  language: zh-CN

  # 时区设置
  timezone: Asia/Shanghai

  # API服务监听地址和端口
  api:
    host: 0.0.0.0
    port: 8080
    workers: 4
    timeout: 120

  # 安全配置
  security:
    api_key_required: true
    rate_limit: 1000/min
    cors_origins:
      - "https://your-domain.com"
    tls:
      enabled: true
      cert_file: /etc/ssl/certs/openclaw.crt
      key_file: /etc/ssl/private/openclaw.key

  # 功能开关
  features:
    web_dashboard: true
    plugin_system: true
    metrics_export: true

Agent配置（agents）

Agent配置段定义了智能体的默认行为和运行时参数：

agents:
  # Agent默认配置
  defaults:
    max_steps: 50
    timeout: 300
    retry_policy:
      max_retries: 3
      backoff_factor: 2.0
      retryable_errors:
        - timeout
        - rate_limit

    # 上下文窗口管理
    context:
      max_tokens: 8192
      summary_strategy: sliding_window
      reserved_tokens: 2048

    # 记忆配置
    memory:
      type: hybrid
      short_term:
        max_entries: 100
        ttl: 3600
      long_term:
        backend: vector_store
        embedding_model: text-embedding-3-small
        similarity_threshold: 0.75

  # 特定Agent覆盖配置
  overrides:
    research_agent:
      max_steps: 100
      tools:
        - web_search
        - document_reader
        - code_executor
    coding_agent:
      max_steps: 200
      tools:
        - file_editor
        - terminal
        - linter

模型配置（models）

模型配置段管理所有AI模型的连接和参数设置：

models:
  # LLM模型配置
  llm:
    default: gpt-4o
    providers:
      openai:
        api_key: ${OPENAI_API_KEY}
        base_url: https://api.openai.com/v1
        models:
          - id: gpt-4o
            max_tokens: 128000
            temperature: 0.7
          - id: gpt-4o-mini
            max_tokens: 128000
            temperature: 0.5
      anthropic:
        api_key: ${ANTHROPIC_API_KEY}
        models:
          - id: claude-3-5-sonnet
            max_tokens: 200000
      local:
        type: ollama
        base_url: http://localhost:11434
        models:
          - id: llama3.1
            max_tokens: 8192

  # 嵌入模型配置
  embeddings:
    default: text-embedding-3-small
    providers:
      openai:
        api_key: ${OPENAI_API_KEY}
        model: text-embedding-3-small
        dimensions: 1536

工具配置（tools）

工具配置段定义了Agent可以调用的外部工具和内置工具：

tools:
  # 内置工具配置
  builtin:
    web_search:
      enabled: true
      provider: serper
      api_key: ${SERPER_API_KEY}
      max_results: 10
    code_executor:
      enabled: true
      runtime: python
      timeout: 60
      sandbox: true
    file_system:
      enabled: true
      allowed_paths:
        - /data/workspace
        - /tmp/openclaw

  # 自定义工具注册
  custom:
    - name: database_query
      type: sql
      connection: ${DATABASE_URL}
      read_only: true
    - name: send_notification
      type: webhook
      url: https://hooks.slack.com/services/xxx
      method: POST

存储配置（storage）

存储配置段管理数据持久化和向量存储后端：

storage:
  # 关系型数据库（元数据和配置存储）
  database:
    type: postgresql
    host: localhost
    port: 5432
    name: openclaw
    user: openclaw
    password: ${DB_PASSWORD}
    pool_size: 20
    ssl: true

  # 向量存储（Agent记忆和知识检索）
  vector_store:
    type: qdrant
    host: localhost
    port: 6333
    collection: openclaw_memory
    distance: cosine

  # 对象存储（文件和大文档）
  object_store:
    type: s3
    bucket: openclaw-data
    region: cn-north-1
    endpoint: ${S3_ENDPOINT}
    access_key: ${S3_ACCESS_KEY}
    secret_key: ${S3_SECRET_KEY}

日志配置（logging）

日志配置段控制日志输出格式、级别和目标：

logging:
  # 全局日志级别
  level: INFO

  # 日志格式
  format: json
  timestamp_format: ISO8601

  # 输出目标
  outputs:
    - type: console
      level: DEBUG
      colorize: true
    - type: file
      path: /var/log/openclaw/openclaw.log
      level: INFO
      rotation:
        max_size: 100MB
        max_files: 10
    - type: elasticsearch
      hosts:
        - http://es-node1:9200
      index: openclaw-logs
      level: WARNING

  # 模块级别日志控制
  module_levels:
    openclaw.agent: DEBUG
    openclaw.model: INFO
    openclaw.tool: WARNING
    openclaw.security: DEBUG

环境变量

OpenClaw支持通过环境变量覆盖配置文件中的任何值。环境变量的命名规则是将配置路径中的点号替换为下划线，并添加 OPENCLAW_ 前缀：

# 覆盖 global.api.port
export OPENCLAW_GLOBAL_API_PORT=9090

# 覆盖 models.llm.default
export OPENCLAW_MODELS_LLM_DEFAULT=gpt-4o

# 覆盖 storage.database.host
export OPENCLAW_STORAGE_DATABASE_HOST=db.example.com

# 直接使用环境变量引用（在config.yaml中）
# 使用 ${VAR_NAME} 语法引用环境变量
# 使用 ${VAR_NAME:-default_value} 提供默认值

配置验证

OpenClaw内置了配置验证工具，可以在启动前检查配置文件的完整性和正确性：

# 验证配置文件
openclaw config validate --file /etc/openclaw/config.yaml

# 生成配置模板
openclaw config generate --mode production > config.yaml

# 查看当前生效配置（合并所有来源）
openclaw config show

# 对比两个配置文件的差异
openclaw config diff base.yaml override.yaml

配置验证器会检查以下内容：必填字段是否缺失、数据类型是否正确、枚举值是否合法、引用路径是否可达、安全配置是否满足最低要求。在生产模式下，任何验证错误都会阻止服务启动，确保系统始终在已知正确的配置下运行。