配置指南

OpenClaw 使用位于 ~/.openclaw/openclaw.json 的 JSON5 配置文件，如果文件缺失则使用安全默认值。

配置文件位置

默认位置：~/.openclaw/openclaw.json

使用环境变量覆盖：

export OPENCLAW_CONFIG=/path/to/config.json

配置方法

1. 交互式设置

# 首次设置向导
openclaw onboard

# 重新配置现有设置
openclaw configure

2. CLI 命令

# 获取值
openclaw config get agents.defaults.model.primary

# 设置值
openclaw config set agents.defaults.model.primary "anthropic/claude-opus-4-6"

# 取消设置值
openclaw config unset agents.defaults.temperature

3. 控制 UI

网关运行时访问 Web 界面：http://127.0.0.1:18789

4. 直接编辑文件

直接编辑 ~/.openclaw/openclaw.json。更改会自动热重载。

基本配置结构

最小示例

{
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace"
    }
  },
  channels: {
    whatsapp: {
      allowFrom: ["+15555550123"]
    }
  }
}

完整示例

{
  // 代理配置
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
      model: {
        primary: "anthropic/claude-sonnet-4-6",
        fallbacks: ["anthropic/claude-haiku-4-5"]
      },
      temperature: 0.7,
      maxTokens: 4096,
      systemPrompt: "你是一个乐于助人的 AI 助手。",
      thinking: {
        level: "medium"
      }
    }
  },

  // 渠道配置
  channels: {
    whatsapp: {
      enabled: true,
      dmPolicy: "pairing",
      allowFrom: ["+15555550123"]
    },
    telegram: {
      enabled: true,
      dmPolicy: "allowlist",
      allowFrom: ["@username"]
    },
    slack: {
      enabled: true,
      dmPolicy: "open",
      allowFrom: ["*"]
    }
  },

  // 会话配置
  sessions: {
    scope: "per-channel-peer",
    reset: {
      daily: true,
      idleMinutes: 1440
    }
  },

  // 技能配置
  skills: {
    load: {
      watch: true,
      extraDirs: []
    },
    entries: {
      "nano-banana-pro": {
        enabled: true,
        env: {
          GEMINI_API_KEY: "${GEMINI_API_KEY}"
        }
      }
    }
  },

  // 网关配置
  gateway: {
    port: 18789,
    host: "127.0.0.1"
  },

  // 日志配置
  logging: {
    level: "info",
    format: "pretty"
  }
}

代理配置

模型选择

{
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-sonnet-4-6",
        fallbacks: [
          "anthropic/claude-haiku-4-5",
          "openai/gpt-4o"
        ]
      }
    }
  }
}

支持的模型提供商：

anthropic/ - Claude 模型（Opus、Sonnet、Haiku）
openai/ - GPT 模型
google/ - Gemini 模型

温度和令牌

{
  agents: {
    defaults: {
      temperature: 0.7,  // 0.0-1.0，越高越有创造性
      maxTokens: 4096    // 最大响应长度
    }
  }
}

系统提示

{
  agents: {
    defaults: {
      systemPrompt: "你是一个乐于助人的 AI 助手。请简洁准确。"
    }
  }
}

思考级别

{
  agents: {
    defaults: {
      thinking: {
        level: "medium"  // off|minimal|low|medium|high|xhigh
      }
    }
  }
}

工作区

{
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace"
    }
  }
}

渠道配置

DM 策略

四种 DM 策略模式：

pairing（默认）- 一次性批准码
allowlist - 仅批准的发送者
open - 所有入站（需要 allowFrom: ["*"]）
disabled - 忽略所有 DM

{
  channels: {
    whatsapp: {
      enabled: true,
      dmPolicy: "pairing",
      allowFrom: ["+15555550123", "+15555550124"]
    }
  }
}

{
  channels: {
    telegram: {
      enabled: true,
      dmPolicy: "allowlist",
      allowFrom: ["@username", "@another_user"],
      botToken: "${TELEGRAM_BOT_TOKEN}"
    }
  }
}

Slack

{
  channels: {
    slack: {
      enabled: true,
      dmPolicy: "open",
      allowFrom: ["*"],
      botToken: "${SLACK_BOT_TOKEN}",
      signingSecret: "${SLACK_SIGNING_SECRET}"
    }
  }
}

Discord

{
  channels: {
    discord: {
      enabled: true,
      dmPolicy: "pairing",
      botToken: "${DISCORD_BOT_TOKEN}"
    }
  }
}

会话配置

会话范围

{
  sessions: {
    scope: "per-channel-peer"  // 或 "per-channel"、"global"
  }
}

范围选项：

per-channel-peer - 每个渠道和用户单独的会话
per-channel - 每个渠道单独的会话
global - 单个共享会话

会话重置

{
  sessions: {
    reset: {
      daily: true,           // 在午夜重置
      idleMinutes: 1440,     // 空闲 24 小时后重置
      onRestart: false       // 网关重启时不重置
    }
  }
}

技能配置

技能加载

{
  skills: {
    load: {
      watch: true,           // 更改时热重载
      debounce: 500,         // 防抖延迟（毫秒）
      extraDirs: [           // 额外的技能目录
        "/opt/company-skills",
        "~/shared-skills"
      ]
    }
  }
}

技能覆盖

{
  skills: {
    entries: {
      "nano-banana-pro": {
        enabled: true,
        apiKey: {
          source: "env",
          provider: "default",
          id: "GEMINI_API_KEY"
        },
        env: {
          GEMINI_API_KEY: "${GEMINI_API_KEY}",
          CUSTOM_SETTING: "value"
        },
        config: {
          endpoint: "https://api.example.com",
          timeout: 30000
        }
      },
      "peekaboo": {
        enabled: false  // 禁用此技能
      }
    }
  }
}

沙箱

在隔离的 Docker 容器中运行代理：

{
  agents: {
    defaults: {
      sandbox: {
        mode: "all",        // off|non-main|all
        runtime: "docker",
        image: "openclaw/sandbox:latest"
      }
    }
  }
}

沙箱模式：

off - 无沙箱
non-main - 仅沙箱非主代理
all - 沙箱所有代理

自动化

心跳检查

{
  automation: {
    heartbeat: {
      enabled: true,
      interval: 3600,  // 每小时
      message: "系统状态检查"
    }
  }
}

Cron 任务

{
  automation: {
    cron: {
      jobs: [
        {
          schedule: "0 9 * * *",  // 每天上午 9 点
          command: "openclaw agent --message '每日摘要'"
        },
        {
          schedule: "0 */6 * * *",  // 每 6 小时
          command: "openclaw sessions cleanup"
        }
      ]
    }
  }
}

Webhooks

{
  automation: {
    webhooks: [
      {
        url: "https://example.com/webhook",
        events: ["message", "session", "error"],
        secret: "${WEBHOOK_SECRET}"
      }
    ]
  }
}

网关配置

服务器设置

{
  gateway: {
    port: 18789,
    host: "127.0.0.1",
    cors: {
      enabled: true,
      origins: ["http://localhost:3000"]
    }
  }
}

热重载

{
  gateway: {
    hotReload: {
      mode: "hybrid"  // hybrid|hot|restart|off
    }
  }
}

热重载模式：

hybrid（默认）- 自动应用安全更改，关键更改需重启
hot - 仅安全更改
restart - 任何更改都重启
off - 需要手动重启

日志配置

{
  logging: {
    level: "info",        // debug|info|warn|error
    format: "pretty",     // pretty|json
    file: "~/.openclaw/logs/openclaw.log",
    maxSize: "100MB",
    maxFiles: 10,
    compress: true
  }
}

环境变量

变量替换

在配置中使用 ${VAR_NAME} 语法：

{
  channels: {
    telegram: {
      botToken: "${TELEGRAM_BOT_TOKEN}"
    }
  }
}

.env 文件支持

在配置目录中创建 .env 文件：

TELEGRAM_BOT_TOKEN=your-token-here
SLACK_BOT_TOKEN=your-slack-token
GEMINI_API_KEY=your-gemini-key

SecretRef 对象

用于高级密钥管理：

{
  channels: {
    telegram: {
      botToken: {
        source: "env",
        id: "TELEGRAM_BOT_TOKEN"
      }
    }
  }
}

SecretRef 来源：

env - 环境变量
file - 从文件读取
exec - 执行命令

多代理路由

将不同渠道路由到不同的代理配置：

{
  routing: {
    "whatsapp:+15555550123": {
      workspace: "~/.openclaw/workspaces/personal",
      model: {
        primary: "anthropic/claude-sonnet-4-6"
      },
      systemPrompt: "你是我的个人助手。"
    },
    "slack:#engineering": {
      workspace: "~/.openclaw/workspaces/work",
      model: {
        primary: "anthropic/claude-opus-4-6"
      },
      systemPrompt: "你是一个专业的工程助手。",
      thinking: {
        level: "high"
      }
    }
  }
}

验证

验证配置

openclaw config validate

诊断问题

openclaw doctor

模式验证

OpenClaw 在启动时根据模式验证配置。未知键会导致失败。

配置配置文件

使用多个配置文件：

# 开发环境
openclaw gateway --profile dev

# 生产环境
openclaw gateway --profile prod

# 自定义配置文件
openclaw gateway --config /path/to/config.json

配置文件：~/.openclaw/openclaw.<profile>.json

热重载行为

大多数设置无需重启即可热应用：

✅ 渠道设置
✅ 代理配置
✅ 技能
✅ 路由规则
✅ 日志级别
❌ 网关服务器设置（端口、主机）- 需要重启

最佳实践

使用环境变量存储密钥
启用热重载以加快迭代
验证配置后再部署
使用配置文件用于不同环境
版本控制配置（不包含密钥）
用注释记录自定义设置
定期备份配置
先在开发环境测试更改

故障排除

配置未加载

# 检查配置文件位置
openclaw config show --verbose

# 验证语法
openclaw config validate

# 检查错误
openclaw doctor

热重载不工作

# 检查热重载模式
openclaw config get gateway.hotReload.mode

# 手动重启网关
openclaw gateway restart

环境变量未展开

# 验证变量已设置
echo $TELEGRAM_BOT_TOKEN

# 检查配置值
openclaw config get channels.telegram.botToken

配置指南

配置指南

配置文件位置

配置方法

1. 交互式设置

2. CLI 命令

3. 控制 UI

4. 直接编辑文件

基本配置结构

最小示例

完整示例

代理配置

模型选择

温度和令牌

系统提示

思考级别

工作区

渠道配置

DM 策略

WhatsApp

Telegram

Slack

Discord

会话配置

会话范围

会话重置

技能配置

技能加载

技能覆盖

沙箱

自动化

心跳检查

Cron 任务

Webhooks

网关配置

服务器设置

热重载

日志配置

环境变量

变量替换

.env 文件支持

SecretRef 对象

多代理路由

验证

验证配置

诊断问题

模式验证

配置配置文件

热重载行为

最佳实践

故障排除

配置未加载

热重载不工作

环境变量未展开

下一步