OpenClaw 配置详解：从入门到精通

OpenClaw 的灵活性是其核心优势之一，而这种灵活性主要通过配置文件实现。本文将详细介绍 OpenClaw 的所有配置选项，帮助你根据需求定制你的 AI 助手。无论你是初学者还是高级用户，都能从中找到有用的信息。

配置文件概览

OpenClaw 使用 YAML 格式的配置文件，主要包括：

文件 作用 必需
config/app.yaml 主配置文件 ✅
config/.env 环境变量 ✅
config/skills.yaml 技能注册 可选
config/cron.yaml 定时任务 可选
config/plugins/ 插件配置 可选

主配置文件结构

基础配置

app:
  name: "My OpenClaw"          # 应用名称
  description: "我的 AI 助手"   # 应用描述
  port: 3000                  # 服务端口
  host: "0.0.0.0"             # 监听地址
  baseUrl: "https://example.com"  # 公共访问 URL
  timezone: "Asia/Shanghai"   # 时区设置
  locale: "zh-CN"             # 语言设置

LLM 配置

这是最重要的配置部分，定义了你使用的 AI 模型。

llm:
  # LLM 提供商：openai, anthropic, google, local, custom
  provider: "openai"

  # 模型选择
  model: "gpt-4"
  # 备用模型
  fallbackModel: "gpt-3.5-turbo"

  # API 配置
  apiKey: "${OPENAI_API_KEY}"  # 从环境变量读取
  # 自定义 API 端点（用于代理或本地部署）
  apiBaseUrl: "https://api.openai.com/v1"

  # 请求参数
  parameters:
    temperature: 0.7          # 创造性程度 (0-1)
    maxTokens: 2000            # 最大响应 tokens
    topP: 1.0                  # nucleus sampling
    frequencyPenalty: 0       # 频率惩罚
    presencePenalty: 0         # 存在惩罚

  # 流式响应
  stream: true

  # 重试配置
  retry:
    maxAttempts: 3
    retryDelay: 1000

LLM 提供商对比

提供商 模型 特点
OpenAI GPT-4, GPT-3.5 通用能力强
Anthropic Claude 3 更安全、长上下文
Google Gemini 多模态能力强
本地模型 Llama, Mistral 隐私、成本低

插件配置

plugins:
  - telegram
  - discord
  - cron
  - memory
  - search

# 插件目录
pluginDir: "./plugins"

日志配置

logging:
  # 日志级别：debug, info, warn, error
  level: "info"

  # 日志格式
  format: "json"  # json, text

  # 日志输出
  outputs:
    - type: "console"
      colorize: true

    - type: "file"
      path: "./logs/app.log"
      maxSize: "10m"
      maxFiles: 5

    - type: "syslog"  # 可选
      host: "localhost"
      port: 514

安全配置

security:
  # IP 白名单
  allowedIPs:
    - "127.0.0.1"
    - "10.0.0.0/8"
    - "192.168.1.0/24"

  # 认证配置
  authentication:
    enabled: true
    type: "basic"  # basic, jwt, oauth
    users:
      - username: "admin"
        password: "${ADMIN_PASSWORD}"

  # API 密钥
  apiKeys:
    - name: "my-api-key"
      key: "${API_KEY_1}"
      permissions:
        - "read"
        - "write"

  # 速率限制
  rateLimit:
    enabled: true
    windowMs: 60000    # 1 分钟
    max: 100           # 最多 100 次请求

  # CORS 配置
  cors:
    enabled: true
    origins:
      - "https://example.com"
    credentials: true

记忆系统配置

memory:
  # 启用记忆功能
  enabled: true

  # 存储类型
  type: "file"  # file, redis, postgres, mongo

  # 文件存储
  file:
    path: "./data/memory"
    maxSize: "100MB"

  # Redis 存储（生产环境推荐）
  redis:
    host: "localhost"
    port: 6379
    db: 0
    password: "${REDIS_PASSWORD}"

  # PostgreSQL 存储
  postgres:
    connectionString: "${DATABASE_URL}"

  # 记忆配置
  settings:
    # 用户记忆保留时间（天）
    retentionDays: 30
    # 最大记忆条数
    maxMemories: 1000
    # 摘要生成
    summarize: true
    summaryThreshold: 10

平台配置

Telegram 配置

telegram:
  enabled: true
  botToken: "${TELEGRAM_BOT_TOKEN}"

  settings:
    respondToGroup: false
    allowPrivateChat: true
    commandPrefix: "/"
    maxMessageLength: 4096

  permissions:
    allowedUsers: []
    allowedGroups: []

  features:
    skills: true
    cron: true
    memory: true
    voice: false

Discord 配置

discord:
  enabled: true
  botToken: "${DISCORD_BOT_TOKEN}"

  settings:
    commandPrefix: "!"
    respondToSelf: false
    respondToBots: false

  intents:
    - GUILDS
    - GUILD_MESSAGES
    - MESSAGE_CONTENT

  permissions:
    allowedGuilds: []
    allowedChannels: []

飞书配置

feishu:
  enabled: true
  appId: "${FEISHU_APP_ID}"
  appSecret: "${FEISHU_APP_SECRET}"

  # 验证配置
  verificationToken: "${FEISHU_VERIFICATION_TOKEN}"
  encryptKey: "${FEISHU_ENCRYPT_KEY}"

  settings:
    # 自动通过验证
    autoVerify: true

  permissions:
    allowedUsers: []
    allowedGroups: []

Gmail 配置

gmail:
  enabled: true
  clientId: "${GMAIL_CLIENT_ID}"
  clientSecret: "${GMAIL_CLIENT_SECRET}"
  refreshToken: "${GMAIL_REFRESH_TOKEN}"

  settings:
    # 自动转发
    autoForward: false
    # 附件处理
    downloadAttachments: true
    maxAttachmentSize: "10MB"

技能配置

技能注册

在 config/skills.yaml 中：

skills:
  # 本地技能
  - path: "./skills/weather"
    name: "weather"
    enabled: true
    config:
      apiKey: "${WEATHER_API_KEY}"

  # NPM 包技能
  - package: "openclaw-skill-search"
    version: "latest"
    enabled: true
    config:
      apiKey: "${SEARCH_API_KEY}"

  # 远程技能
  - url: "https://example.com/skills/custom"
    enabled: true

技能触发词

skillTriggers:
  # 自然语言触发
  nlu:
    enabled: true
    confidenceThreshold: 0.7

  # 关键词触发
  keyword:
    enabled: true
    caseSensitive: false

  # 命令触发
  command:
    enabled: true
    prefix: "!"

定时任务配置

在 config/cron.yaml 中：

tasks:
  - name: "每日早报"
    schedule: "0 8 * * *"      # Cron 表达式
    skill: "daily-report"
    enabled: true

    # 通知配置
    notify:
      telegram:
        enabled: true
        chatId: "${REPORT_CHAT_ID}"

    # 条件执行
    conditions:
      # 只在周末执行（可选）
      # daysOfWeek: [0, 6]

  - name: "每周总结"
    schedule: "0 18 * * 5"
    skill: "weekly-summary"
    enabled: true

Cron 表达式指南

表达式 含义
0 * * * * 每小时
0 0 * * * 每天午夜
0 8 * * * 每天早上 8 点
0 0 * * 0 每周日午夜
0 0 1 * * 每月第一天

环境变量最佳实践

.env 文件示例

# ===== LLM =====
OPENAI_API_KEY=sk-xxxxxxxxxxxxx
ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxxx

# ===== 平台 =====
TELEGRAM_BOT_TOKEN=123456:ABCDEFGHIJKLMNOP
DISCORD_BOT_TOKEN=MTIzNDU2Nzg5MDEyMzQ1Njc4.GaBcDe.xxx
FEISHU_APP_ID=cli_xxxxxxxxxxxxx
FEISHU_APP_SECRET=xxxxxxxxxxxxxxxxxxxxx

# ===== 数据库 =====
DATABASE_URL=postgresql://user:pass@localhost:5432/openclaw
REDIS_PASSWORD=your-redis-password

# ===== 安全 =====
ADMIN_PASSWORD=your-secure-password
API_KEY_1=your-api-key-xxxx

# ===== 第三方服务 =====
WEATHER_API_KEY=your-weather-key
SEARCH_API_KEY=your-search-key

环境变量类型

# 字符串
VAR_NAME: "value"

# 数字
VAR_NAME: 123

# 布尔值
VAR_NAME: true

# 数组
VAR_NAME:
  - item1
  - item2

# 从环境变量读取
VAR_NAME: "${ENV_VAR_NAME}"

多环境配置

开发环境

# config/dev.yaml
app:
  port: 3000
  debug: true

logging:
  level: "debug"

llm:
  model: "gpt-3.5-turbo"

生产环境

# config/prod.yaml
app:
  port: 3000
  debug: false

logging:
  level: "warn"

llm:
  model: "gpt-4"

环境切换

# 使用开发配置
NODE_ENV=development npm start

# 使用生产配置
NODE_ENV=production npm start

常见配置问题

问题 1：配置不生效

解决方案： - 检查 YAML 语法（缩进、空格） - 确认文件路径正确 - 重启服务

问题 2：环境变量读取失败

解决方案： - 确认 .env 文件位置 - 检查变量名拼写 - 使用 ${VAR} 语法

问题 3：权限错误

解决方案： - 检查配置文件权限 - 确认目录可写 - 查看错误日志

高级配置技巧

1. 配置继承

# 基础配置
_base: &base
  llm:
    provider: "openai"

# 开发配置继承基础
development:
  <<: *base
  llm:
    model: "gpt-3.5-turbo"

# 生产配置继承基础
production:
  <<: *base
  llm:
    model: "gpt-4"

2. 动态配置

# 基于环境动态配置
llm:
  model: "${NODE_ENV:production === 'development' ? 'gpt-3.5-turbo' : 'gpt-4'}"

3. 敏感信息加密

使用加密工具处理敏感配置：

# 使用 SOPS 加密
npm install -g sops
sops --encrypt --age=public_key config/app.yaml > config/app.encrypted.yaml

总结

通过本文，你应该对 OpenClaw 的配置系统有了全面的了解。配置是定制 OpenClaw 的核心，合理的配置能让你的 AI 助手发挥最大价值。

关键要点： - 使用环境变量管理敏感信息 - 根据环境选择合适的配置 - 合理设置日志级别 - 配置适当的记忆和缓存策略 - 注意安全配置

掌握这些配置技巧，你就能根据不同场景灵活定制 OpenClaw！

相关阅读： - OpenClaw 安装指南 - OpenClaw 技能开发 - OpenClaw 定时任务 - OpenClaw 最佳实践