Tools
Openviking Openclaw
By OpenViking plugin for OpenClaw
Install
npm install &&Configuration Example
{
"plugins": {
"slots": { "contextEngine": "openviking" },
"entries": {
"openviking": {
"config": {
"baseUrl": "http://127.0.0.1:1933",
"peer_role": "none",
"peer_prefix": "",
"apiKey": "<ключ аккаунта openclaw-system>",
"agentKeysFile": "/home/openclaw/memory/secrets/openviking-keys/secrets.conf"
}
}
}
}
}README
# OpenViking для OpenClaw — по отдельному аккаунту на агента
Форк [`@openviking/openclaw-plugin`](https://github.com/volcengine/OpenViking/tree/main/examples/openclaw-plugin)
версии **2026.7.15**. Единственное отличие: плагин выбирает API-ключ OpenViking
по тому, какой агент OpenClaw делает запрос, вместо одного общего ключа на весь
гейтвей.
Апстрим разделяет агентов только «пирами» внутри одного аккаунта
(`peer_role: "assistant"`) — общая файловая система, общие ресурсы, разделение
только на уровне выборки. Здесь каждому агенту соответствует свой
аккаунт/пользователь на сервере OpenViking, поэтому изоляция проходит по границе
арендатора: чужое пространство недоступно ни на чтение, ни на поиск, ни через
ресурсы, и в веб-панели OpenViking аккаунты видны по отдельности.
Плагин при этом работает в режиме `peer_role: "none"` — он считает, что сервер
принадлежит ему одному, и не создаёт вложенных папок под пиров. Разделение
целиком на стороне сервера, по ключу.
## Что именно изменено относительно апстрима
| Файл | Изменение |
|---|---|
| `agent-keys.ts` | Новый. Чтение файла ключей, правила fail-closed |
| `plugin/openviking-client-runtime.ts` | Пул клиентов: по одному на аккаунт OpenViking вместо единственного |
| `plugin/openviking-session-routing-runtime.ts` | Нераспознанная сессия больше не выдаёт себя за агента `main` |
| `config.ts`, `openclaw.plugin.json` | Новая опция `agentKeysFile` |
| ~12 файлов рантайма | `getClient()` → `getClient(agentId)`; идентификатор агента доводится до места выбора ключа |
Остальной код апстримовый и не тронут.
## Установка
Предполагается, что OpenClaw уже стоит, а на сервере OpenViking заранее созданы
аккаунты и пользователи — по одному на агента плюс системный:
```
openclaw-system / agent-system ← резервный, для неатрибутированного трафика
openclaw-main / agent-main
openclaw-igor / agent-igor
...
```
Сборка и установка:
```bash
cd /home/openclaw/memory/openviking-openclaw-plugin && npm install && npm run verify
```
`verify` — это сборка плюс тесты. После неё:
```bash
openclaw plugins install --link /home/openclaw/memory/openviking-openclaw-plugin --force
```
`--link` регистрирует каталог как есть, без копирования: пересобрал — и новый
`dist/` подхватится после перезапуска. `--force` нужен потому, что источник не
ClawHub.
Идентификатор плагина остался `openviking`, поэтому конфиг, имена инструментов и
слот совпадают с апстримом. Ставить обе версии одновременно нельзя — они займут
один и тот же id.
## Конфигурация в `openclaw.json`
```jsonc
{
"plugins": {
"slots": { "contextEngine": "openviking" },
"entries": {
"openviking": {
"config": {
"baseUrl": "http://127.0.0.1:1933",
"peer_role": "none",
"peer_prefix": "",
"apiKey": "<ключ аккаунта openclaw-system>",
"agentKeysFile": "/home/openclaw/memory/secrets/openviking-keys/secrets.conf"
}
}
}
}
}
```
- `apiKey` — ключ **системного** аккаунта. Это резерв: в него попадает всё, что
не удалось привязать к конкретному агенту.
- `peer_prefix` обязан быть пустым: имена в файле ключей сравниваются с
идентификатором агента OpenClaw, а непустой префикс превратил бы `main` в
`<prefix>_main`.
- `agentKeysFile` можно не указывать — тогда берётся
`/home/openclaw/memory/secrets/openviking-keys/secrets.conf` или значение
переменной окружения `OPENVIKING_AGENT_KEYS_FILE`.
Если плагин ставится с нуля, OpenClaw может оставить его выключенным до
появления конфига — тогда после правки `openclaw.json`:
```bash
openclaw plugins enable openviking
```
## Файл ключей
```bash
install -d -m 700 /home/openclaw/memory/secrets/openviking-keys
install -m 600 /dev/null /home/openclaw/memory/secrets/openviking-keys/secrets.conf
```
Содержимое — по строке на агента, имя слева совпадает с id агента в
`agents.entries` OpenClaw:
```ini
# /home/openclaw/memory/secrets/openviking-keys/secrets.conf
main = <ключ аккаунта openclaw-main>
igor = <ключ аккаунта openclaw-igor>
willi = <ключ аккаунта openclaw-willi>
kate = <ключ аккаунта openclaw-kate>
tina = <ключ аккаунта openclaw-tina>
```
Комментарии — `#` или `;`, значение можно брать в кавычки, заголовок секции
`[agents]` допускается и игнорируется. Файл читается **один раз при старте**:
добавили агента — перезапустили гейтвей.
Плагин откажется стартовать (и уйдёт в setup-only режим с ошибкой в логе), если:
- файл указан, но не читается;
- строка не разбирается, имя агента содержит недопустимые символы или значение пустое;
- один агент объявлен дважды;
- **два агента используют один и тот же ключ** — это молча слило бы их память;
- ключ агента совпадает с системным;
- ключи агентов заданы, а системный `apiKey` пустой.
Права мягче `600` — предупреждение в лог, не отказ.
## Как определяется агент и что будет, если не определился
Агент берётся из контекста OpenClaw: из `agentId`, который сообщают хуки, либо из
ключа сессии вида `agent:<id>:...`. Оба варианта работают независимо от
`peer_role`.
Если привязать сессию к агенту не удалось, апстрим молча подставляет литерал
`main`. Здесь это отдельный случай: запрос уходит в системный аккаунт, а в лог
пишется предупреждение (один раз на сессию):
```
openviking: no agent could be resolved for session <id> — routing to the system
OpenViking account instead of guessing an agent
```
То же самое происходит с агентом, которого нет в файле ключей. Данные никогда не
попадают в аккаунт другого агента — только в свой или в системный.
Без агентского контекста работает ровно одна вещь — health-check при старте
гейтвея; он идёт под системным ключом.
## Проверка после запуска
```bash
grep -a "openviking: per-agent credentials loaded" /tmp/openclaw/openclaw-$(date +%F).log
```
Ожидаемая строка перечисляет агентов, для которых нашлись ключи (сами ключи не
логируются никогда). Дальше — написать каждому агенту по факту, сделать коммит
сессии и посмотреть в веб-панели OpenViking, что аккаунты заполняются по
отдельности.
Подробный лог маршрутизации включается `"logFindRequests": true` в конфиге
плагина либо `OPENVIKING_LOG_ROUTING=1`; в нём видно, какой аккаунт выбран для
запроса.
## Обновление
```bash
cd /home/openclaw/memory/openviking-openclaw-plugin && npm run verify
```
и перезапуск гейтвея. Пересобирать нужно после любой правки исходников — OpenClaw
загружает `dist/`, а не `.ts`.
## Замечания
- Смена ключа у агента означает смену аккаунта: старая память останется в
прежнем аккаунте и перестанет находиться. Ключи стоит считать постоянными.
- При `tools.profile: "minimal"` инструменты плагина нужно перечислять и в
`tools.alsoAllow`, и в `tools.sandbox.tools.allow` у каждого агента.
- Слот `contextEngine` эксклюзивный: `openviking` вытесняет `legacy` и
`memory-core`.
## Лицензия
MIT, как и у апстрима.
tools
Comments
Sign in to leave a comment