跳到主要内容

OpenClaw 配置指南

· 阅读需 3 分钟

本文档是 OpenClaw openclaw.json 配置文件的完整参考，根据官方文档进行了修订和补充。

目录​

基础结构​

OpenClaw 使用 JSON5 格式，支持注释和尾随逗号。

{
  // 身份信息
  "identity": {},

  // 代理配置 (核心)
  "agents": {
    "defaults": {},
    "list": []
  },

  // 通信通道
  "channels": {},

  // 工具权限
  "tools": {},

  // 会话管理
  "session": {},

  // 模型提供商和自定义模型
  "models": {},

  // 认证配置
  "auth": {},

  // 安全沙箱
  "sandbox": {},

  // 日志配置
  "logging": {},

  // 网关设置
  "gateway": {},

  // 定时任务
  "cron": {},

  // Webhook 钩子
  "hooks": {},

  // 环境变量
  "env": {}
}

核心模块配置​

1. 身份配置 (identity)​

"identity": {
  "name": "AssistantName",           // 显示名称，用于 @mentions
  "theme": "professional assistant", // 性格描述，影响系统提示
  "emoji": "🤖",                     // 默认反应表情符号
  "avatar": "images/avatar.png"      // 头像图片路径或URL
}

2. 代理配置 (agents)​

默认与多代理设置​

"agents": {
  "defaults": {
    "workspace": "~/.openclaw/workspace",
    "model": {
      "primary": "anthropic/claude-sonnet-4-5",
      "fallbacks": ["openai/gpt-5-mini"]
    },
    "maxConcurrent": 4,
    "contextPruning": {
      "enabled": true,
      "maxLength": 8000
    },
    "heartbeat": {
        "every": "30m",
        "target": "last"
    }
  },
  "list": [
    {
      "id": "monitor",
      "model": {
        "primary": "openai/gpt-5-nano"
      },
      "systemPromptFile": "workspace/agents/monitor.md",
      "maxConcurrent": 2
    },
    {
      "id": "researcher",
      "model": {
        "primary": "anthropic/claude-opus"
      },
      "tools": {
        "web": { "search": { "enabled": true } }
      }
    }
  ]
}

3. 通信通道 (channels)​

Telegram 配置​

"channels": {
  "telegram": {
    "enabled": true,
    "botToken": "YOUR_TELEGRAM_BOT_TOKEN",
    "dmPolicy": "pairing",              // pairing | allowlist | open | disabled
    "allowFrom": ["tg:123456789"],
    "groupPolicy": "allowlist",
    "allowedGroups": ["-1001234567890"]
  },
  "modelByChannel": {
      "telegram": {
          "-1001234567890": "anthropic/claude-opus"
      }
  }
}

4. 工具配置 (tools)​

"tools": {
  "web": {
    "search": {
      "enabled": true,
      "provider": "brave",
      "apiKey": "YOUR_BRAVE_API_KEY"
    },
    "browse": {
      "enabled": true,
      "headless": true
    }
  },
  "filesystem": {
    "read": true,
    "write": false,
    "execute": false
  }
}

5. 会话管理 (session)​

"session": {
  "dmScope": "per-channel-peer",      // main | per-peer | per-channel-peer | per-account-channel-peer
  "reset": {
      "mode": "daily",
      "atHour": 4
  },
  "threadBindings": {
      "enabled": true,
      "idleHours": 24
  },
  "maxHistoryLength": 50
}

6. 模型配置 (models)​

"models": {
  "providers": {
    "local-ollama": {
      "baseUrl": "http://localhost:11434/api/generate",
      "api": "ollama",
      "models": [
        {
          "id": "llama3.1:8b",
          "contextWindow": 8192
        }
      ]
    }
  }
}

7. 认证配置 (auth)​

"auth": {
  "profiles": {
    "openrouter": {
      "provider": "openrouter",
      "apiKey": "YOUR_OPENROUTER_KEY"
    },
    "anthropic": {
      "provider": "anthropic",
      "apiKey": "YOUR_ANTHROPIC_KEY"
    }
  }
}

安全配置​

沙箱设置 (sandbox)​

"sandbox": {
  "mode": "agent",                 // off | agent | all
  "scope": "session",               // session | agent | shared
  "docker": {
    "enabled": true,
    "image": "openclaw/sandbox:latest",
    "network": "none",
    "memoryLimit": "512m"
  }
}

网关安全 (gateway)​

"gateway": {
  "port": 18789,
  "bind": "loopback",                 // localhost | loopback | 0.0.0.0
  "tls": {
    "enabled": false
  },
  "auth": {
    "mode": "token",
    "token": "GENERATE_SECURE_TOKEN"
  },
  "cors": {
    "enabled": false
  }
}

高级设置​

定时任务 (cron)​

"cron": {
    "enabled": true,
    "jobs": [
        {
            "id": "daily-report",
            "schedule": "0 9 * * *",
            "prompt": "Summarize yesterday's activities and send a report to the #general channel.",
            "agentId": "reporter"
        }
    ]
}

Webhook (hooks)​

"hooks": {
    "enabled": true,
    "token": "your-shared-secret",
    "mappings": [
        {
            "match": { "path": "/github-pr" },
            "action": "agent",
            "agentId": "developer",
            "prompt": "A new pull request has been opened. Please review it."
        }
    ]
}

WhatsApp Web (web)​

"web": {
    "enabled": true,
    "heartbeatSeconds": 60,
    "reconnect": {
        "initialMs": 2000,
        "maxMs": 120000
    }
}

日志配置 (logging)​

"logging": {
  "level": "info",
  "format": "json",
  "outputs": [
    {
      "type": "file",
      "path": "~/logs/openclaw.log"
    }
  ]
}

最佳实践​

成本控制​

{
  "budget": {
    "monthlyLimit": 50, // USD
    "alerts": {
      "email": "admin@example.com"
    }
  }
}

常见问题​

配置过程中若遇到问题，可参考 OpenClaw 安装文档 或官方文档。本文档将随版本更新持续修订。

最后更新: 2026年3月

相关内容推荐