server-manager/CODEX_SKILL_SETUP.md

Развёртывание Codex Skill Для ServerManager

Этот документ описывает текущее состояние интеграции ServerManager -> Codex, автоматическое и ручное развёртывание, проверку и все известные edge cases.

Поддерживаемый deployment target для этой интеграции:

• Linux
• macOS
• Windows

Что именно разворачивается

Интеграция для Codex состоит из трёх слоёв:

1. Общий локальный backend:
   • ~/.server-connections/ssh.py
   • ~/.server-connections/encryption.py
   • ~/.server-connections/servers.json
2. Codex skill package:
   • ~/.codex/skills/server-manager/
3. Безопасный wrapper для вызова backend из Codex:
   • ~/.server-connections/codex-ssh на Linux/macOS
   • ~/.server-connections/codex-ssh.cmd на Windows

В репозитории исходники skill лежат здесь:

• SKILL.md
• command-matrix.md
• project.md
• server-manager-doctor.sh
• server-manager-doctor.cmd
• codex-ssh-wrapper.sh
• codex-ssh-wrapper.cmd

Как это работает

Модель безопасности та же, что и у Claude integration:

Codex skill -> ~/.server-connections/codex-ssh -> ~/.server-connections/ssh.py -> encrypted servers.json

Ключевая идея:

• Codex видит только алиасы и безопасные результаты команд.
• ssh.py сам читает credentials из локального зашифрованного хранилища.
• Codex не должен читать servers.json, settings.json или encryption.py напрямую.

Что уже автоматизировано

Теперь Codex integration встроена в продуктовый setup flow:

• core/claude_setup.py ставит ssh.py, encryption.py, ~/.claude/commands/ssh.md, ~/.codex/skills/server-manager/, wrapper ~/.server-connections/codex-ssh и блок в ~/.claude/CLAUDE.md
• вкладка Setup в GUI показывает отдельные статусы для Claude skill, Codex skill и Codex wrapper
• build.py после сборки автоматически синхронизирует Claude- и Codex-артефакты в локальный runtime

Платформенный split такой:

• Linux/macOS: используются codex-ssh-wrapper.sh и server-manager-doctor.sh
• Windows: используются codex-ssh-wrapper.cmd и server-manager-doctor.cmd

Ручная установка всё ещё полезна как fallback path, если нужен точечный repair или offline debugging.

Предварительные условия

Перед установкой Codex skill должны уже существовать или быть установлены через Setup:

1. ~/.server-connections/ssh.py
2. ~/.server-connections/encryption.py
3. ~/.server-connections/servers.json
4. codex CLI

Проверка:

ls -la ~/.server-connections
codex --help

Если ~/.server-connections/ssh.py отсутствует:

1. Открыть ServerManager GUI
2. Перейти в Setup
3. Нажать Install Everything

Это поставит backend, Claude skill и Codex skill целиком.

Рекомендуемый путь: установка через GUI

1. Открыть ServerManager
2. Перейти в Setup
3. Нажать Install Everything
4. Проверить, что зелёные статусы появились у:
   • ssh.py
   • Encryption module
   • Claude /ssh skill
   • Codex skill
   • Codex wrapper
   • SSH key

Для точечного ремонта можно использовать отдельные кнопки Claude skill и Codex skill в той же вкладке.

Ручная установка Codex Skill

1. Скопировать skill package в глобальный Codex home

mkdir -p ~/.codex/skills
cp -R .codex/skills/server-manager ~/.codex/skills/server-manager

2. Установить wrapper в shared runtime directory

Linux/macOS:

install -m 755 .codex/skills/server-manager/scripts/codex-ssh-wrapper.sh ~/.server-connections/codex-ssh

Windows:

copy .codex\skills\server-manager\scripts\codex-ssh-wrapper.cmd %USERPROFILE%\.server-connections\codex-ssh.cmd

3. Проверить doctor script

Linux/macOS:

~/.codex/skills/server-manager/scripts/server-manager-doctor.sh

Windows:

%USERPROFILE%\.codex\skills\server-manager\scripts\server-manager-doctor.cmd

Ожидается:

• ssh.py найден
• encryption.py найден
• codex-ssh executable

4. Проверить wrapper без раскрытия credentials

Linux/macOS:

~/.server-connections/codex-ssh --list

Windows:

%USERPROFILE%\.server-connections\codex-ssh.cmd --list

Это безопасная базовая проверка. Она должна вывести список алиасов и типов серверов.

5. Перезапустить Codex

Если у вас уже была открыта интерактивная Codex session, её нужно перезапустить. Новый skill обычно подхватывается новым процессом Codex, а не уже живой сессией.

Как проверить, что Codex реально видит skill

Самый надёжный способ:

codex exec --skip-git-repo-check -s read-only -C /tmp \
  "A user asks: Using the locally installed ServerManager integration, what is the safest first command to enumerate configured servers? Reply with only the command."

Если skill подхватился корректно, Codex должен сам прочитать ~/.codex/skills/server-manager/SKILL.md и ответить:

$HOME/.server-connections/codex-ssh --list

Что Codex должен делать через skill

Правильный workflow для любой server operation:

1. Сначала --list
2. Прочитать колонку Type
3. Выбрать команду строго по типу сервера
4. Выполнить ровно одно подключение/одно действие
5. Вернуть результат без IP/логинов/паролей/портов

Безопасные discovery-команды:

$HOME/.server-connections/codex-ssh --list
$HOME/.server-connections/codex-ssh --info ALIAS
$HOME/.server-connections/codex-ssh --status

Источники истины по интеграции

Если меняется поведение интеграции, проверять нужно в таком порядке:

1. tools/ssh.py
2. tools/skill-ssh.md
3. core/claude_setup.py
4. build.py
5. SKILL.md
6. command-matrix.md

Если меняется семантика ssh.py, нужно обновлять и Claude skill, и Codex skill.

Edge Cases

1. python alias отсутствует

В этой среде python отсутствует, но ssh.py имеет shebang #!/usr/bin/env python3 и executable bit.

Поэтому wrapper вызывает ssh.py напрямую:

~/.server-connections/codex-ssh --list

Это намеренно лучше, чем завязка на python ~/.server-connections/ssh.py.

2. ssh.py --help не поддерживается

ssh.py не имеет полноценного --help. Попытка вызвать --help возвращает список доступных alias'ов, а не usage.

Поэтому для безопасной проверки используются:

• --list
• --info ALIAS
• --status

3. Skill установлен в repo, но не установлен глобально

Наличие .codex/skills/server-manager/ внутри репозитория полезно как source of truth, но новый Codex процесс по умолчанию ищет глобальные skills в ~/.codex/skills.

Если skill есть только в repo:

• документация в проекте будет на месте
• глобальный Codex может его не увидеть

Для надёжности нужен именно глобальный install в ~/.codex/skills/server-manager.

4. Wrapper отсутствует, а skill уже установлен

В этом случае Codex прочитает skill, но не сможет выполнить рекомендуемую команду $HOME/.server-connections/codex-ssh ....

Проверка:

~/.codex/skills/server-manager/scripts/server-manager-doctor.sh

Исправление:

install -m 755 .codex/skills/server-manager/scripts/codex-ssh-wrapper.sh ~/.server-connections/codex-ssh

5. Backend отсутствует

Если нет ~/.server-connections/ssh.py или encryption.py, skill бесполезен: он знает workflow, но не имеет локального transport layer.

Исправление:

1. Запустить ServerManager
2. Setup -> Install Everything

6. Интерактивный Codex уже был запущен до установки skill

Новая интерактивная сессия обычно увидит skill, старая может не увидеть.

Исправление:

• закрыть старую Codex session
• запустить новый процесс codex

7. codex exec не может проверить skill из-за sandbox/network policy

Во время non-interactive проверки Codex может упереться не в skill, а в сетевую политику среды:

• websocket backend заблокирован
• sandbox запрещает соединение

Симптом:

failed to connect to websocket ... Operation not permitted

Это не означает, что skill неверный. Это означает, что проверка упёрлась в runtime policy Codex backend.

8. Повторная установка поверх существующего skill

GUI installer и install_codex_skill() синхронизируют дерево skill поверх существующей директории без полного удаления. Это безопасно для обычных обновлений.

Но при ручном cp -R возможен stale state, если какие-то файлы были удалены из repo, а старая глобальная копия осталась.

Полная ручная пересинхронизация нужна только если вы осознанно хотите очистить старые файлы:

1. удалить старую копию осознанно
2. снова скопировать skill целиком

Пример:

rm -rf ~/.codex/skills/server-manager
cp -R .codex/skills/server-manager ~/.codex/skills/server-manager

Делать это только если вы уверены, что хотите полностью пересобрать глобальную копию.

9. Изменился tools/ssh.py, но глобальная установка осталась старой

Это самый вероятный operational drift.

Что может устареть:

• ~/.server-connections/ssh.py
• ~/.codex/skills/server-manager/*
• ~/.server-connections/codex-ssh

После изменения tools/ssh.py или skill docs нужно заново синхронизировать:

cp tools/ssh.py ~/.server-connections/ssh.py
cp core/encryption.py ~/.server-connections/encryption.py
rm -rf ~/.codex/skills/server-manager
cp -R .codex/skills/server-manager ~/.codex/skills/server-manager
install -m 755 .codex/skills/server-manager/scripts/codex-ssh-wrapper.sh ~/.server-connections/codex-ssh

10. Windows / macOS / Linux split

Сейчас runtime path intentionally разделён по платформам:

• Linux/macOS: shell wrapper codex-ssh-wrapper.sh
• Windows: native wrapper codex-ssh-wrapper.cmd

Installer на Windows кладёт wrapper как:

• ~/.server-connections/codex-ssh.cmd

Installer на Linux/macOS кладёт wrapper как:

• ~/.server-connections/codex-ssh

Что это закрывает:

• Linux/macOS path без platform-specific разветвления в skill
• запуск через cmd.exe
• запуск из PowerShell
• отсутствие bash-зависимости для стандартного Windows deployment path

Ограничение остаётся одно: в текущей среде я прогнал end-to-end smoke только на Linux. macOS и Windows path подготовлены в installer/docs, но не smoke-tested здесь из-за отсутствия соответствующих runner'ов.

11. ssh.py intentionally не должен читать secrets в контекст AI

Это не баг. Даже если кажется проще открыть servers.json, делать этого нельзя.

Skill намеренно запрещает:

• cat ~/.server-connections/servers.json
• cat ~/.server-connections/settings.json
• python -c "...read servers.json..."
• --list-full

12. fail2ban / anti-bruteforce edge case

Повторные неудачные подключения опасны. Поэтому skill зафиксирован как:

• максимум 1 попытка на действие
• при timeout/ошибке остановиться и сообщить пользователю

Это обязательное правило, а не рекомендация.

Рекомендуемый Update Workflow

После любых изменений, затрагивающих Codex integration:

1. Обновить исходники в repo:
   • tools/ssh.py
   • .codex/skills/server-manager/*
   • этот документ
2. Синхронизировать глобальную установку
3. Прогнать doctor
4. Прогнать ~/.server-connections/codex-ssh --list
5. Прогнать свежий codex exec smoke test

Минимальный Smoke Test

~/.codex/skills/server-manager/scripts/server-manager-doctor.sh
~/.server-connections/codex-ssh --list
codex exec --skip-git-repo-check -s read-only -C /tmp \
  "A user asks: Using the locally installed ServerManager integration, what is the safest first command to enumerate configured servers? Reply with only the command."

Что ещё желательно автоматизировать позже

Чтобы интеграция стала production-complete, в проект ещё полезно добавить:

1. отдельный smoke test script внутри репозитория для проверки именно Codex integration
2. e2e smoke test на Windows runner
3. e2e smoke test на macOS runner
4. optional PowerShell-native wrapper, если понадобится richer Windows logging