适用版本： OpenClaw v2026.3 源码位置： src/config/types.ts

完整配置模板

以下是 OpenClaw 的完整配置文件模板，包含所有可用配置项：

# ~/.openclaw/openclaw.yaml
# OpenClaw 配置文件 - 完整参考

# ============================================
# 服务器配置
# ============================================
server:
  # 监听地址
  # - 127.0.0.1: 仅本机访问（最安全）
  # - 0.0.0.0: 允许局域网访问
  # - 100.x.y.z: Tailscale IP，仅 Tailscale 网络访问
  host: "127.0.0.1"

  # 监听端口
  port: 18789

  # 最大连接数
  maxConnections: 1000

  # 连接超时（毫秒）
  connectionTimeout: 30000

  # 控制台 UI
  controlUi:
    enabled: true
    port: 18790

# ============================================
# 认证配置
# ============================================
auth:
  # 认证方式: token | password | tailscale
  method: token

  # Token 认证
  tokens:
    - name: "api-token"
      value: "your-secret-token-here"
      permissions: ["read", "write"]
    - name: "readonly-token"
      value: "another-token"
      permissions: ["read"]

  # Password 认证
  # password: "your-password"

  # Tailscale 认证
  # tailscale:
  #   requireEmail: true
  #   allowedEmails:
  #     - "[email protected]"

# ============================================
# Provider 配置
# ============================================
providers:
  # OpenAI
  openai:
    apiKey: "${OPENAI_API_KEY}"
    defaultModel: "gpt-4"
    # 可选：自定义端点
    # baseUrl: "https://api.openai.com/v1"

  # Anthropic
  anthropic:
    apiKey: "${ANTHROPIC_API_KEY}"
    defaultModel: "claude-sonnet-4-6"

  # Google
  google:
    apiKey: "${GOOGLE_API_KEY}"
    defaultModel: "gemini-2.0-flash"

# ============================================
# Agent 配置
# ============================================
agents:
  # 默认配置
  defaults:
    model: "gpt-4"
    provider: "openai"
    # 最大并行工具调用
    parallelToolCalls: true
    maxParallelTools: 5
    # Turn 超时
    turnTimeout: 60000

  # Agent 列表
  list:
    - id: main
      name: General Assistant
      default: true

    - id: coder
      name: Code Assistant
      model: "claude-sonnet-4-6"
      provider: "anthropic"
      systemPrompt: |
        You are a code assistant...

    - id: architect
      name: System Architect
      model: "claude-opus-4-6"
      provider: "anthropic"

# ============================================
# ACP 配置
# ============================================
acp:
  # 是否启用 ACP
  enabled: true

  # 允许的 Agent
  agents:
    allowed:
      - main
      - coder
      - architect

  # 沙箱策略
  sandbox:
    mode: optional  # inherit | require | optional

# ============================================
# Channel 配置
# ============================================
channels:
  # WhatsApp
  whatsapp:
    enabled: true
    dmPolicy: pairing  # open | pairing
    sessionScope: per-sender  # per-sender | global | per-group

  # Telegram
  telegram:
    enabled: true
    dmPolicy: open
    sessionScope: per-sender
    botToken: "${TELEGRAM_BOT_TOKEN}"

  # Slack
  slack:
    enabled: false
    botToken: "${SLACK_BOT_TOKEN}"
    appToken: "${SLACK_APP_TOKEN}"

# ============================================
# Session 配置
# ============================================
sessions:
  # 最大活跃会话数
  maxActive: 100

  # 清理间隔
  cleanupInterval: "1h"

  # 会话超时
  timeout: "24h"

  # Transcript 配置
  transcript:
    # 策略: sliding_window | summarize
    strategy: sliding_window
    # 最大 Token 数
    maxTokens: 4000

# ============================================
# 工具配置
# ============================================
tools:
  # 权限控制
  permissions:
    default: allow
    deny:
      - fs.write
    confirm:
      - sessions.delete

  # 沙箱规则
  sandbox:
    default: deny
    allow:
      - fs.read
      - web.fetch

  # 自定义工具导入
  # import: ~/.openclaw/tools/index.ts

# ============================================
# Hook 配置
# ============================================
hooks:
  internal:
    enabled: true
    path: ~/.openclaw/hooks

  builtins:
    - name: rate-limiter
      enabled: true
      config:
        maxRequests: 100
        windowMs: 60000

# ============================================
# Skill 配置
# ============================================
skills:
  enabled:
    - translator

  translator:
    defaultTargetLang: zh
    preserveFormatting: true

# ============================================
# 日志配置
# ============================================
logging:
  level: info  # debug | info | warn | error
  format: json  # json | text
  output: ~/.openclaw/logs/gateway.log

  fields:
    include:
      - timestamp
      - level
      - message
      - traceId
      - sessionId

# ============================================
# 监控配置
# ============================================
metrics:
  enabled: true
  port: 9090
  path: /metrics

# ============================================
# 备份配置
# ============================================
backup:
  enabled: true
  schedule: "0 3 * * *"

  retention:
    daily: 7
    weekly: 4
    monthly: 12

  destination:
    type: local
    path: ~/.openclaw/backups

# ============================================
# 插件配置
# ============================================
plugins:
  enabled:
    - signal

  # 插件目录
  path: ~/.openclaw/plugins

# ============================================
# Cron 配置
# ============================================
cron:
  enabled: true
  timezone: "Asia/Shanghai"

配置优先级

配置值按以下优先级加载（从高到低）：

1. 命令行参数 - --port 18790
2. 环境变量 - OPENCLAW_SERVER_PORT=18790
3. 配置文件 - ~/.openclaw/openclaw.yaml
4. 默认值 - 代码中定义的默认值

环境变量

OpenClaw 支持通过环境变量覆盖配置：

# 服务器
OPENCLAW_SERVER_HOST=127.0.0.1
OPENCLAW_SERVER_PORT=18789

# Provider API Keys
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
GOOGLE_API_KEY=...

# Channel Tokens
TELEGRAM_BOT_TOKEN=...
SLACK_BOT_TOKEN=...

# 日志
LOG_LEVEL=debug
LOG_INCLUDE="gateway,agent,tools"

配置验证

# 验证配置文件
openclaw config validate

# 查看当前配置
openclaw config dump

# 查看特定配置项
openclaw config get server.port

# 解析配置值（显示来源）
openclaw config resolve providers.openai.apiKey

配置热更新

部分配置支持热更新，无需重启：

# 热更新配置
openclaw config reload

# 查看支持热更新的配置
openclaw config reloadable

支持热更新的配置：

• logging.level
• metrics.enabled
• channels.*.enabled

需要重启的配置：

• server.host
• server.port
• auth.method
• providers.*

系列索引： OpenClaw 源码解析：目录索引