OpenCode 2.x uses a new plugin API; V1 plugins do not load at all. Both
example plugins are rewritten as `export default { id, setup }`.
Fixes, in order of severity:
- Default export with id/setup instead of a named `export const XPlugin`,
which the V2 loader rejects with "Plugin must export a default definition
with an id and an effect or setup function".
- Drop `client.app.log`: the V2 context has no client and no logging API.
Poll results go to ~/.local/state/ollama-plagin-swap/client.log and to the
console. A file log is required because the managed background service
sends stdout to /dev/null.
- Replace the `server.connected` trigger with an immediate poll in `setup`;
V2 never delivers that event to in-process plugins.
- Replace the `session.deleted` interval teardown with a cleanup function
returned from `setup`, and unref the timer so monitoring never keeps the
server alive.
- Use `ctx.location.directory` instead of `ctx.directory`.
- Read opencode.jsonc as well as opencode.json when inferring controls from
providers, stripping comments and trailing commas; provider inference
previously failed silently on JSONC configs.
- Switch from require() to ESM imports.
- TypeScript variant: import types from `@opencode/plugin`, not
`@opencode-ai/plugin`; register tools via `ctx.tool.transform` with JSON
Schema and return `{ content }` from executors.
- Give the tool variant the id `ollama-plagin-swap.tools`, since reusing
`ollama-plagin-swap` makes OpenCode fail it with "Duplicate plugin ID".
Verified on a live OpenCode 2.2.5 server: both variants report `active` via
/api/plugin and the poller writes swap status every interval.
9.9 KiB
ollama-plagin-swap
Удалённый контроль swap для серверов Ollama, используемых через API OpenCode.
Что устанавливается
src/ollama_swap_agent.pyиsrc/ollama_swap_common.py: Python-агент для macOS и Ubuntu.examples/opencode/ollama-swap.js: канонический клиентский плагин OpenCode без зависимостей.examples/opencode/ollama-swap.ts: необязательный TypeScript-плагин с пользовательскими инструментами (ollama_swap_status,ollama_swap_restart) и runtime-guard. Требует установки как каталог-плагин сpackage.json(см. ниже).- Агент предоставляет
GET /health,GET /statusиPOST /restart.
Оба плагина написаны под API плагинов OpenCode 2.x (проверено на 2.2.5): экспортируют
export default { id, setup } и возвращают cleanup-функцию. Плагины V1 API
(export const XPlugin = async (ctx) => ({...})) в OpenCode 2.x не загружаются.
Почему раньше дублировались плагины
OpenCode автоматически загружает все файлы плагинов из .opencode/plugins/ проекта и из
~/.config/opencode/plugins/. Если один и тот же файл лежит в обоих местах, он загружается
дважды. Поэтому исходники перенесены в examples/opencode/, а устанавливается только один
глобальный файл.
Установка клиента на текущий macOS
./scripts/install-client.sh
Устанавливаются файлы:
~/.config/opencode/plugins/ollama-swap.js
~/.config/ollama-plagin-swap/clients.json
Отредактируйте clients.json и укажите URL и токен удалённого агента Ollama.
Установка агента на сервере Ollama
Подключитесь по SSH к серверу 10.8.0.62 под пользователем с правами администратора/root. Пример:
ssh admin@10.8.0.62
Сервер Ollama на macOS
Выполните на сервере Ollama:
mkdir -p ~/src/ollama-plagin-swap
# Сначала скопируйте файлы репозитория на сервер, затем:
cd ~/src/ollama-plagin-swap
./scripts/install-agent.sh
Установщик создаёт файлы:
~/.local/share/ollama-plagin-swap/ollama_swap_agent.py
~/.local/share/ollama-plagin-swap/ollama_swap_common.py
~/.config/ollama-plagin-swap/config.json
~/Library/LaunchAgents/com.ollama.swap-agent.plist
Измените токен в ~/.config/ollama-plagin-swap/config.json, затем перезапустите агент:
launchctl unload ~/Library/LaunchAgents/com.ollama.swap-agent.plist 2>/dev/null || true
launchctl load -w ~/Library/LaunchAgents/com.ollama.swap-agent.plist
Сам сервис Ollama агент перезапускает командами:
launchctl unload ~/Library/LaunchAgents/com.ollama.serve.plist 2>/dev/null
launchctl load -w ~/Library/LaunchAgents/com.ollama.serve.plist
Сервер Ollama на Ubuntu
Выполните на сервере Ollama под root:
cd /opt/ollama-plagin-swap
sudo ./scripts/install-agent.sh
Установщик создаёт файлы:
/opt/ollama-plagin-swap/ollama_swap_agent.py
/opt/ollama-plagin-swap/ollama_swap_common.py
/etc/ollama-plagin-swap/config.json
/etc/systemd/system/ollama-swap-agent.service
Измените /etc/ollama-plagin-swap/config.json, затем выполните:
sudo systemctl daemon-reload
sudo systemctl enable --now ollama-swap-agent
При необходимости откройте доступ с клиентского IP:
sudo ufw allow from <ip-клиента-opencode> to any port 8731 proto tcp
Сам сервис Ollama агент перезапускает командой:
sudo systemctl restart ollama
Генерация токена
Токен не выдаётся внешним сервисом: придумайте одинаковый секрет и впишите его и в серверный config.json, и в клиентский clients.json. Например:
openssl rand -hex 32
Порог swap
По умолчанию агент сравнивает общий объём используемого swap с конкретным размером:
swap_threshold_mb = 3048. Процентный режим выключен (swap_threshold_percent = null).
Чтобы оставить прежнее процентное поведение, задайте, например:
{
"swap_threshold_percent": 25,
"swap_threshold_mb": null
}
Поведение агента
- Каждые
poll_interval_seconds(по умолчанию 60) снимает метрики swap и состояние/api/ps. - При превышении порога останавливает загруженные модели через
ollama stop(unload_models_before_restart) и перезапускает сервис; если нужно,restart_force_after_secondsпозволяет принудительный restart. last_restart,restart_timesи навязчиво оставшийсяrestart_in_progressтеперь корректно сохраняются и сбрасываются после нового запуска агента.- После перезапуска ждёт
/api/tagsне болееrestart_health_timeout_seconds. - Действует cooldown и лимит restart-ов в час для защиты от штормов.
- Логи и state хранятся в
~/.local/state/ollama-plagin-swap/.
Проверка агента на сервере
curl -sS -H "Authorization: Bearer <token>" http://10.8.0.62:8731/health
curl -sS -H "Authorization: Bearer <token>" http://10.8.0.62:8731/status
Ручной запрос на перезапуск:
curl -sS -X POST \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{"reason":"manual","force":false}' \
http://10.8.0.62:8731/restart
Перезагрузка сервера
После reboot Mac mini агент запустится автоматически при входе пользователя, потому что записан
в ~/Library/LaunchAgents с RunAtLoad=true. Если автоматического входа нет, agent не стартует
до логина. Проверьте после перезагрузки:
launchctl list | grep com.ollama.swap-agent
curl -sS -H "Authorization: Bearer <token>" http://127.0.0.1:8731/health
Проверка клиентского плагина OpenCode
OpenCode 2.x автоматически подключает глобальный плагин из
~/.config/opencode/plugins/ollama-swap.js и вызывает setup(ctx) сразу при загрузке —
именно на этом шаге выполняется первый опрос агента. server.connected плагинам в OpenCode 2.x
не доставляется, поэтому старый триггер больше не используется.
Проверить загрузку:
opencode plugin list
Результат опроса пишется в файл ~/.local/state/ollama-plagin-swap/client.log (фоновый сервис
OpenCode направляет stdout в /dev/null, поэтому собственный лог надёжнее) и дублируется в
консоль сервера. Строка вида:
2026-11-02T11:21:09.728Z [info] ollama-remote: swap 663.19/2048 MB (32.38%), recommendation=none
При превышении порога уровень меняется на [warn], при недоступном агенте пишется
agent unreachable: <name> (<error>).
Установка TS-варианта с инструментами
ollama-swap.ts регистрирует инструменты, поэтому его нужно ставить как каталог-плагин:
mkdir -p ~/.config/opencode/plugins/ollama-tools
cp examples/opencode/ollama-swap.ts ~/.config/opencode/plugins/ollama-tools/index.ts
printf '{ "name": "ollama-swap-tools", "type": "module", "exports": { ".": "./index.ts" } }\n' \
> ~/.config/opencode/plugins/ollama-tools/package.json
Его id — ollama-plagin-swap.tools, поэтому он не конфликтует с обычным файловым плагином: OpenCode
отклоняет второй плагин с тем же id с ошибкой Duplicate plugin ID. Держать оба одновременно
обычно не нужно — инструменты лишь дублируют фоновый опрос.
Неполадки LaunchAgent
Если лог показывает unrecognized arguments: --config ..., plist вызывает
serve --config .... Переведите аргументы в порядок --config <path> serve:
<string>--config</string>
<string>/Users/andrew/.config/ollama-plagin-swap/config.json</string>
<string>serve</string>
После правки выполните launchctl unload ... && launchctl load -w ....
Локальные проверки перед установкой
/usr/bin/python3 -m py_compile src/*.py tests/*.py
/opt/homebrew/bin/pytest -q
node --check examples/opencode/ollama-swap.js
Для .ts-варианта нужен @opencode/plugin версии 2.x в devDependencies и проверка через tsc.