> ## Documentation Index
> Fetch the complete documentation index at: https://docs.velesagent.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Инструменты, веб-поиск и MCP

> Как настраивать встроенные инструменты Велеса, веб-поиск, загрузку страниц, exec, MCP, разбор документов, векторную память и ограничения рабочей области.

# Инструменты, веб-поиск и MCP

Инструменты дают модели возможность действовать: читать файлы, искать в интернете, запускать команды, работать с памятью, создавать cron-задачи и подключаться к внешним MCP-серверам.

## Общие ограничения

Для постоянной установки начните с ограничения рабочей области:

```json theme={null}
{
  "tools": {
    "blockPrivateNetworks": true,
    "restrictToWorkspace": true
  }
}
```

Это ограничивает файловые действия и команды оболочки пределами рабочей области и снижает риск случайного доступа к чужим данным.

## exec

`exec` запускает команды оболочки. Это мощный и рискованный инструмент.

```json theme={null}
{
  "tools": {
    "exec": {
      "enable": true,
      "timeout": 60,
      "pathAppend": ""
    }
  }
}
```

| Поле         | Назначение                            |
| ------------ | ------------------------------------- |
| `enable`     | Регистрировать ли инструмент оболочки |
| `timeout`    | Таймаут команды в секундах            |
| `pathAppend` | Дополнительные директории для `PATH`  |

`exec` по-прежнему применяет базовую защиту от явно разрушительных команд. Сетевая проверка управляется общим полем `tools.blockPrivateNetworks`. По умолчанию оно равно `true`, поэтому Велес блокирует внутренние домены и частные адреса для `exec` и `web_fetch`. Если поставить `false`, команды оболочки и загрузка страниц смогут обращаться к таким адресам, если среда Велеса видит эту сеть.

Если команды оболочки не нужны, выключите их:

```json theme={null}
{
  "tools": {
    "exec": {
      "enable": false
    }
  }
}
```

## Веб-поиск

Веб-поиск настраивается в `tools.web.search`.

```json theme={null}
{
  "tools": {
    "web": {
      "search": {
        "provider": "brave",
        "apiKey": "BSA...",
        "maxResults": 5
      }
    }
  }
}
```

Поддерживаемые варианты:

| Провайдер    | Что нужно                        |
| ------------ | -------------------------------- |
| `brave`      | `apiKey` или `BRAVE_API_KEY`     |
| `tavily`     | `apiKey` или `TAVILY_API_KEY`    |
| `jina`       | `apiKey` или `JINA_API_KEY`      |
| `searxng`    | `baseUrl` или `SEARXNG_BASE_URL` |
| `duckduckgo` | ничего                           |

Если учётные данные отсутствуют, Велес может перейти на DuckDuckGo.

## Загрузка страниц

`web_fetch` читает уже известный URL и возвращает очищенный текст страницы, JSON, обычный текст или изображение.

Для длинных страниц Велес не отдаёт только начало текста. Он показывает начало и конец страницы, сохраняет полный очищенный текст в рабочей области в `.veles/web-fetch/` и добавляет в ответ путь для `read_file`. Так можно дочитать пропущенную середину без повторной загрузки страницы.

Параметр `maxChars` задаёт объём текста, который попадает прямо в ответ инструмента. Он не ограничивает сохранённый полный текст страницы.

Прокси для веб-поиска и загрузки страниц:

```json theme={null}
{
  "tools": {
    "web": {
      "proxy": "http://127.0.0.1:7890"
    }
  }
}
```

## MCP

MCP подключает внешние серверы инструментов.

```json theme={null}
{
  "tools": {
    "mcpServers": {
      "filesystem": {
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]
      },
      "remote": {
        "url": "https://example.com/mcp/",
        "headers": {
          "Authorization": "Bearer ..."
        }
      }
    }
  }
}
```

Поддерживаются `stdio` и транспорт HTTP/SSE. Если `type` не указан, Велес определяет его по конфигурации.

Каждое подключение MCP живёт в собственной фоновой задаче. При остановке Велес просит эту задачу закрыться, поэтому транспорт и клиентская сессия освобождаются в той же задаче, где были открыты.

## Фильтрация инструментов MCP

Оставить только часть инструментов:

```json theme={null}
{
  "tools": {
    "mcpServers": {
      "filesystem": {
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"],
        "enabledTools": ["read_file", "mcp_filesystem_write_file"]
      }
    }
  }
}
```

Правила:

* `["*"]` или отсутствие поля — зарегистрировать все инструменты;
* `[]` — не регистрировать ни одного инструмента;
* список имён — зарегистрировать только указанные;
* принимаются исходные имена MCP и обёрнутые имена вида `mcp_<server>_<tool>`.

Для медленных MCP-вызовов:

```json theme={null}
{
  "tools": {
    "mcpServers": {
      "slow": {
        "url": "https://example.com/mcp/",
        "toolTimeout": 120
      }
    }
  }
}
```

## Разбор документов

`documentParse` использует Mistral OCR для извлечения текста из документов.

```json theme={null}
{
  "tools": {
    "documentParse": {
      "mistralApiKey": "..."
    }
  }
}
```

Используйте зашифрованные секреты для ключа, если инструмент разбора документов нужен в постоянной установке.

## Векторная память

Векторная память индексирует документы и помогает искать по смыслу.

```json theme={null}
{
  "tools": {
    "vectorMemory": {
      "enabled": true,
      "embeddingModel": "openrouter/openai/text-embedding-3-small",
      "chunkTokens": 512,
      "chunkOverlap": 64,
      "syncIntervalSeconds": 60,
      "vectorWeight": 0.7,
      "textWeight": 0.3
    }
  }
}
```

Эта функция полезна для больших папок `docs/`, проектных материалов и длительных рабочих областей.

Индекс хранит модель эмбеддингов и признак успешного построения векторов для каждого файла. Если провайдер эмбеддингов временно недоступен, Велес сохраняет текстовый поиск по файлу и повторяет векторизацию при следующей синхронизации. При смене модели эмбеддингов неизменившиеся файлы также переиндексируются.

## Глубокое исследование

Глубокое исследование настраивается в `tools.deepResearch`: отдельные модели для исследования, сжатия, планирования и итогового отчёта, лимиты токенов, число параллельных исследователей и бюджет поиска.

Если не хотите тонко настраивать процесс, начните с отдельной страницы навыка: [Глубокое исследование](/skills/deep_research_ru).

## Минимальный безопасный профиль

```json theme={null}
{
  "tools": {
    "restrictToWorkspace": true,
    "exec": {
      "enable": false
    },
    "web": {
      "search": {
        "provider": "duckduckgo",
        "maxResults": 5
      }
    },
    "mcpServers": {}
  }
}
```

Этот профиль подходит для первых запусков, демонстраций и публичных каналов.