Конфигурационные файлы OpenClaw

OpenClaw использует JSON5 формат для конфигурационных файлов, что позволяет использовать комментарии и trailing commas. В этом руководстве мы рассмотрим структуру и все доступные параметры.

📁 Структура конфигурации

Основные файлы

~/.openclaw/
├── openclaw.json          # Основной конфигурационный файл
├── models.json           # Настройки моделей и API ключи
├── credentials/          # Директория для секретов (опционально)
│   ├── telegram.token
│   └── openai.key
└── logs/                 # Логи работы

📝 Формат JSON5

JSON5 расширяет JSON с поддержкой:
- Комментарии (// и /* */)
- Trailing commas
- Однострочные строки
- Числа в разных форматах

Пример:

{
  // Это комментарий
  "gateway": {
    "bind": "127.0.0.1",  // Всегда используйте localhost
    "port": 18789,        // trailing comma разрешен
  },
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "YOUR_TOKEN",
    },
  },
}

🏗️ Полная структура конфигурации

Основные секции

{
  // 1. Настройки шлюза
  "gateway": { ... },

  // 2. Настройки каналов связи
  "channels": { ... },

  // 3. Настройки агентов
  "agents": { ... },

  // 4. Настройки команд
  "commands": { ... },

  // 5. Настройки сообщений
  "messages": { ... },

  // 6. Настройки инструментов
  "tools": { ... },

  // 7. Настройки плагинов
  "plugins": { ... },

  // 8. Настройки кэширования
  "cache": { ... },
}

🔧 Детальное описание секций

1. Gateway Settings

{
  "gateway": {
    "bind": "127.0.0.1",      // Адрес привязки (ВСЕГДА 127.0.0.1!)
    "port": 18789,            // Порт шлюза
    "hostname": "localhost",  // Имя хоста для сертификатов
    "tls": {
      "enabled": false,       // Включить TLS
      "key": "/path/to/key.pem",
      "cert": "/path/to/cert.pem"
    },
    "cors": {
      "origins": ["http://localhost:3000"]
    },
    "rateLimit": {
      "enabled": true,
      "windowMs": 60000,      // 1 минута
      "max": 100              // Максимум 100 запросов в минуту
    }
  }
}

2. Channels Configuration

Общие настройки для всех каналов

{
  "channels": {
    "defaults": {
      "dmPolicy": "pairing",      // Политика личных сообщений
      "groupPolicy": "allowlist", // Политика групп
      "contextVisibility": "all"  // Видимость контекста
    },

    // Конкретные каналы
    "telegram": { ... },
    "whatsapp": { ... },
    "discord": { ... },
    "slack": { ... },
    "signal": { ... },
    "imessage": { ... }
  }
}

Политики доступа

3. Agents Configuration

{
  "agents": {
    "defaults": {
      "workspace": "~/.openclaw/workspace",
      "model": {
        "primary": "openai/gpt-4",
        "fallbacks": ["anthropic/claude-3-opus"]
      },
      "imageModel": {
        "primary": "openai/gpt-4-vision",
        "fallbacks": ["google/gemini-pro-vision"]
      },
      "params": {
        "temperature": 0.7,
        "maxTokens": 4000,
        "cacheRetention": "long"
      },
      "heartbeat": {
        "every": "30m",
        "model": "openai/gpt-3.5-turbo"
      }
    },
    "list": [
      {
        "id": "main",
        "name": "Основной агент",
        "skills": ["github", "weather", "calendar"],
        "groupChat": {
          "mentionPatterns": ["@openclaw", "openclaw"]
        }
      },
      {
        "id": "assistant",
        "name": "Ассистент",
        "model": "anthropic/claude-3-sonnet",
        "skills": ["docs", "search"]
      }
    ]
  }
}

4. Commands Configuration

{
  "commands": {
    "native": "auto",          // Нативные команды (Discord/Telegram)
    "text": true,             // Парсить /commands в сообщениях
    "bash": false,            // Разрешить ! (bash команды) - ОПАСНО!
    "config": false,          // Разрешить /config - с осторожностью
    "debug": false,           // Разрешить /debug
    "restart": false,         // Разрешить /restart
    "allowFrom": {
      "*": ["tg:336940264"],  // Кто может использовать команды
      "discord": ["user:123456789"]
    },
    "useAccessGroups": true   // Использовать группы доступа
  }
}

5. Messages Configuration

{
  "messages": {
    "groupChat": {
      "historyLimit": 50,     // Лимит истории в группах
      "mentionPatterns": ["@openclaw"]  // Паттерны упоминаний
    },
    "compaction": {
      "mode": "safeguard",    // Режим компрессии истории
      "timeoutSeconds": 900,
      "reserveTokensFloor": 24000
    }
  }
}

6. Tools Configuration

{
  "tools": {
    "elevated": {
      "enabled": true,        // Разрешить elevated команды
      "allowFrom": {
        "telegram": ["tg:336940264"],
        "discord": ["user:123456789"]
      },
      "requireApproval": true // Требовать подтверждение
    },
    "browser": {
      "enabled": true,
      "profile": "openclaw"   // Профиль браузера
    },
    "exec": {
      "security": "allowlist", // Режим безопасности
      "ask": "on-miss"        // Когда спрашивать разрешение
    }
  }
}

🎯 Примеры конфигураций

Минимальная конфигурация

{
  "gateway": {
    "bind": "127.0.0.1",
    "port": 18789
  },
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "YOUR_TOKEN",
      "dmPolicy": "pairing"
    }
  }
}

Production конфигурация

{
  "gateway": {
    "bind": "127.0.0.1",
    "port": 18789,
    "rateLimit": {
      "enabled": true,
      "windowMs": 60000,
      "max": 100
    }
  },
  "channels": {
    "defaults": {
      "dmPolicy": "pairing",
      "groupPolicy": "allowlist"
    },
    "telegram": {
      "enabled": true,
      "botToken": "YOUR_TOKEN",
      "allowFrom": ["tg:336940264"],
      "groups": {
        "*": {
          "requireMention": true,
          "allowFrom": ["@admin"]
        }
      },
      "configWrites": false,
      "historyLimit": 50
    }
  },
  "commands": {
    "bash": false,
    "config": false,
    "allowFrom": {
      "*": ["tg:336940264"]
    }
  },
  "tools": {
    "elevated": {
      "enabled": true,
      "requireApproval": true,
      "allowFrom": {
        "telegram": ["tg:336940264"]
      }
    }
  }
}

Мульти-агентная конфигурация

{
  "agents": {
    "list": [
      {
        "id": "general",
        "name": "General Assistant",
        "model": "openai/gpt-4",
        "skills": ["weather", "search", "calculator"],
        "bindings": [
          {
            "match": {
              "channel": "telegram",
              "peer": {
                "id": "tg:336940264"  // Личные сообщения
              }
            }
          }
        ]
      },
      {
        "id": "technical",
        "name": "Technical Support",
        "model": "anthropic/claude-3-opus",
        "skills": ["github", "terminal", "docs"],
        "bindings": [
          {
            "match": {
              "channel": "telegram",
              "peer": {
                "id": "-1001234567890"  // Техническая группа
              }
            }
          }
        ]
      }
    ]
  }
}

🔄 Динамическое изменение конфигурации

Через команды (если разрешено)

# Показать текущую конфигурацию
openclaw config show

# Установить параметр
openclaw config set channels.telegram.allowFrom '["tg:336940264"]'

# Удалить параметр
openclaw config unset channels.telegram.groups

Через файл

# Редактировать конфигурацию
nano ~/.openclaw/openclaw.json

# Проверить синтаксис
openclaw config validate

# Применить изменения
openclaw gateway restart

🛠️ Утилиты для работы с конфигурацией

Валидация конфигурации

# Проверить синтаксис
openclaw config validate

# Проверить и исправить проблемы
openclaw doctor --fix

# Экспортировать конфигурацию
openclaw config export > config-backup.json5

Миграция между версиями

# Автоматическая миграция
openclaw config migrate

# Создать бэкап перед миграцией
cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.backup

📊 Переменные окружения

OpenClaw поддерживает переменные окружения для секретов:

# В .bashrc или .zshrc
export TELEGRAM_BOT_TOKEN="your_token"
export OPENAI_API_KEY="sk-..."
export ANTHROPIC_API_KEY="sk-ant-..."

# Или в .env файле
TELEGRAM_BOT_TOKEN=your_token
OPENAI_API_KEY=sk-...

Конфигурация с переменными окружения:

{
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "${TELEGRAM_BOT_TOKEN}"  // Будет заменено на значение
    }
  }
}

🚨 Частые ошибки

1. Синтаксические ошибки JSON5

// ОШИБКА: пропущена запятая
{
  "gateway": {
    "bind": "127.0.0.1"
    "port": 18789  // ← Нет запятой после предыдущей строки
  }
}

2. Неправильные типы данных

// ОШИБКА: строка вместо числа
{
  "gateway": {
    "port": "18789"  // ← Должно быть число, не строка
  }
}

3. Несуществующие параметры

// ОШИБКА: неизвестный параметр
{
  "gateway": {
    "host": "127.0.0.1"  // ← Должно быть "bind", не "host"
  }
}

🔍 Отладка конфигурации

Включить подробные логи

openclaw gateway start --verbose

# Или в конфигурации
{
  "logging": {
    "level": "debug",
    "file": "~/.openclaw/logs/debug.log"
  }
}

Проверить загруженную конфигурацию

# Показать эффективную конфигурацию
openclaw config show --effective

# Показать разницу с дефолтами
openclaw config show --diff

📚 Дополнительные ресурсы

• Официальная справка по конфигурации
• JSON5 спецификация
• Примеры конфигураций на GitHub

Совет: Всегда создавайте бэкап конфигурации перед внесением изменений:

cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.$(date +%Y%m%d)