livoras/claudex-gateway-skill

Claudex Gateway

Visão Geral

Use esta skill para operar o gateway local Claude Code → Codex OAuth de forma segura e consistente. Trate a stack implantada em CLAUDEX_GATEWAY_HOME como fonte da verdade, a menos que o usuário peça explicitamente para redesenhar. Para esta skill, use estas convenções:

• SKILL_ROOT: o caminho instalado deste diretório de skill claudex-gateway
• CLAUDEX_GATEWAY_HOME: o diretório de execução da stack de proxy local. Se não definido, os scripts auxiliares procuram primeiro em ${XDG_DATA_HOME:-$HOME/.local/share}/claudex-gateway e depois no legado ${XDG_DATA_HOME:-$HOME/.local/share}/cliproxyapi-codex-test
• CLAUDEX_WRAPPER: o caminho do wrapper claudex. Se não definido, o padrão é ${HOME}/.local/bin/claudex

Início Rápido

• Inicializar uma máquina nova: python3 "$SKILL_ROOT/scripts/bootstrap_stack.py"
• Atualizar o arquivo de autenticação local de ~/.codex/auth.json: python3 "$SKILL_ROOT/scripts/sync_codex_auth.py"
• Verificar status atual do gateway: claudex status
• Reiniciar o proxy local: claudex restart
• Testar a stack: python3 "$SKILL_ROOT/scripts/probe_stack.py"
• Iniciar Claude Code através do wrapper: claudex --resume

Fluxo de Trabalho

0. Inicializar primeiro se a stack do gateway ainda não existir

• Se CLAUDEX_GATEWAY_HOME estiver ausente, não crie arquivos manualmente um a um.
• Execute python3 "$SKILL_ROOT/scripts/bootstrap_stack.py" para criar o diretório de execução, configuração, iniciador, arquivo de ambiente, um wrapper claudex com status/start/stop/restart e um binário cli-proxy-api compilado.
• O script de inicialização assume: codex e claude já instalados git e go disponíveis para clonar e construir CLIProxyAPI
• Após a inicialização, sincronize a autenticação e inicie o proxy antes de depurar qualquer outra coisa.

1. Confirmar qual caminho está em uso

• Assuma que o caminho de trabalho é: Claude Code → wrapper claudex → CLIProxyAPI → chatgpt.com/backend-api/codex
• Não comece com LiteLLM quando o usuário estiver perguntando sobre a configuração atual do claudex.
• Leia current-stack.md antes de alterar a arquitetura ou explicar tradeoffs.

2. Atualizar credenciais primeiro quando o comportamento parecer desatualizado

• Execute python3 "$SKILL_ROOT/scripts/sync_codex_auth.py"
• Isso copia os tokens atuais do Codex OAuth de ~/.codex/auth.json para o arquivo de autenticação do proxy: "$CLAUDEX_GATEWAY_HOME/auth/codex-current.json"
• Se o usuário estiver desconectado do Codex, pare e autentique novamente primeiro.

3. Verificar o proxy local antes de tocar no Claude Code

• Prefira comandos do wrapper em vez de chamadas diretas ao executor: claudex status claudex start claudex restart
• Teste integridade, /v1/messages, uso de ferramentas e contagem de tokens: python3 "$SKILL_ROOT/scripts/probe_stack.py"
• Use run.sh diretamente apenas ao depurar a geração do wrapper.

4. Alterar roteamento de modelo apenas no arquivo de ambiente, a menos que o usuário peça mudanças mais profundas

• O wrapper claudex carrega: "$CLAUDEX_GATEWAY_HOME/claude-code-gpt54.env"
• O mapeamento atual é mantido ali.
• Preserve o contrato do wrapper em CLAUDEX_WRAPPER: subcomandos de serviço primeiro caso contrário, carregue o env e exec "$CLAUDE_BIN" "$@"
• Sempre preserve a passagem direta de argumentos. claudex --resume deve se comportar exatamente como claude --resume com env injetado.

5. Recompilar apenas se o binário implantado estiver ausente ou quebrado

• O binário implantado é: "$CLAUDEX_GATEWAY_HOME/cli-proxy-api"
• Se precisar ser recompilado, use o repositório upstream: git clone --depth=1 https://github.com/router-for-me/CLIProxyAPI.git /tmp/CLIProxyAPI cd /tmp/CLIProxyAPI && go build -o "$CLAUDEX_GATEWAY_HOME/cli-proxy-api" ./cmd/server
• Mantenha a configuração de execução e o diretório de autenticação inalterados, a menos que o usuário peça o contrário.

Regras Importantes

• Não "consertar" a stack substituindo CLIProxyAPI por LiteLLM a menos que o usuário peça explicitamente um redesenho.
• Não alterar silenciosamente portas, locais de arquivos de autenticação ou semântica do wrapper.
• Não quebrar a passagem de argumentos do claudex.
• Prefira editar os arquivos implantados atuais em vez de criar variantes paralelas.
• Ao explicar a stack, seja explícito de que o caminho de trabalho usa chatgpt.com/backend-api/codex, não chamadas diretas api.openai.com Responses.

Recursos

scripts/

• bootstrap_stack.py: Criar um novo ambiente de execução de gateway local em uma máquina nova
• sync_codex_auth.py: Atualizar o arquivo de autenticação do proxy a partir de ~/.codex/auth.json
• probe_stack.py: Testar integridade, mensagens do Claude, uso de ferramentas e contagem de tokens
• show_status.sh: Exibir o layout de arquivos atual, mapeamento de ambiente e status das portas

references/

• current-stack.md: Histórico, layout de arquivos, comandos e notas de solução de problemas