diff --git a/devlog/_plan/261022_spanish_split/010_plan.md b/devlog/_plan/261022_spanish_split/010_plan.md new file mode 100644 index 00000000000..ae91404a430 --- /dev/null +++ b/devlog/_plan/261022_spanish_split/010_plan.md @@ -0,0 +1,155 @@ +# Spanish localization: split after #7406 + +## Delivery order + +The owner closed #7406 on October 22 because its combined locale changes were +too broad for the review queue and conflicted with dev. The original published +branch stays intact. Recover the contribution in independent branches rooted at +current dev, starting with the documentation site as requested: + +1. `codex/spanish-docs`: docs-site Spanish, directly related canonical/translated + documentation corrections, and the existing documentation regression guards. +2. `codex/spanish-dashboard`: shared Desktop/browser dashboard locale, total + auxiliary maps, formatting, tests and the dashboard contract. +3. `codex/spanish-readme`: README translation/navigation/manifest and its guard. + +Submit the first PR first. Preserve the later branches without opening multiple +review requests at once. Each submission must refresh dev and revalidate its +own diff; a clean merge today does not guarantee compatibility with future dev. + +## Documentation base and scope + +Initial base: `782655d2317d4c14a99d6db72e9be3368a27886d`, 23 commits after the combined +PR's last integration base. Before submission dev advanced to +`5f7f7db5765c7e99ab2f52c04d9fe0e4ce7608cf`; it was merged and its published +macOS storage-refusal clarification was synchronized in Spanish. Recovered changes use that base's files and retain +its new CLI registration and fallback navigation. The docs branch changes no +dashboard catalog, backend source, dependency, release or workflow implementation. + +Spanish covers all 74 current canonical paths, including the new fallback guide. +The refresh includes Remote Link peer versions, Windows refusal/recovery, apply +digests, client restart, service/install JSON and Claude reasoning details. +The sidecar note distinguishes web-search xAI from routed vision in both English +and Spanish. Other latest findings fix product metadata, prose number separators, +the plugin `name` string, and Pi loopback examples in all translated guides. +The timezone-dependent GUI test belongs to the separate dashboard branch. + +## Validation receipts + +- Frozen root/docs installs: no dependency or lockfile changes. System Bun is + 1.4.4; tests use the required Bun 1.4.3 in ignored scratch space. Its official + archive SHA-256 was verified against the GitHub release asset digest. +- Root `bun run typecheck`: passed. +- Final Spanish docs after the Pi contract guard: 15 passed, 0 failed (2,126 assertions). +- Structure and privacy scan: passed on staged files. +- Actual-browser inspection: Spanish landing/fallback guide at 1366 px, Pi at + 390 px, localized code controls, no horizontal page overflow, and 17 Spanish + Pagefind results for fallback. Captures remain outside the source branch. +- Initial Spanish docs and both layout tests: 41 passed, 0 failed. +- All docs guards, structure/hygiene/size and CLI export: 445 passed, one size + scan timed out while the docs build was running. Isolated size-guard retry + with `--timeout 120000`: 9 passed, 0 failed; repository scan took 691 ms. +- `OPENCODEX_DOCS_OFFLINE=1 bun run build`: 667 pages and 97,587 checked internal + links; Pagefind and sitemap completed. Existing unsupported sshconfig + highlighting falls back to text. + +The full root suite is not claimed passing for this branch. The preceding +combined-PR run hit its 900-second limit, with Windows symlink EPERM and timing +failures. This documentation-only split uses the root policy's resource +exception with explicit source-reading guards and exporter regressions instead. +Exact-head upstream CI and independent human language/render acceptance remain +required. No native Desktop acceptance is claimed. + +## Review hold + +Keep the first submission Draft for owner/localization acceptance. Do not reuse +old CI receipts as validation of a new head. Do not repeatedly request bot +reviews or wait for their completion after publication; the contributor will +inspect the result. Screenshot evidence belongs outside the feature branches. + +## PR #7559 consolidated review correction + +Reviewed all 36 CodeRabbit threads against canonical English and, for operational +claims, the current service guards, stop path, sidecar settings and CI workflow. +The corrections cover authentication, service repair/restart, search disable and +journal recovery, preview exit codes, adapter contracts and Spanish terminology. +Two suggested premises needed qualification: explicit `ocx stop` stops a managed +service and then restores native Codex; a valid refused preview can exit 0 because +inspection succeeded without applying a change. Neither was changed into the +incorrect behavior suggested by the review wording. + +The adjacent semantic pass also restored default-off wording for subagent force, +native subagent defaults, native WebSocket controls and custom context inference. +It checked account/queue/adapter state distinctions and removed unavailable +benchmark-filter instructions from every locale. The current backend, dependency +and workflow implementations remain outside this contribution. + +Merged dev at `ec8b8cfac11e8f179c4351f01baa32d76a71dd1b`, preserving both the new +chat layout shard and this branch's docs shard, then at +`9164950d926c770875a267edfeb74183af5caebc` and the docs-only update +`880127dbd356c720779222a14a97c11adc8cf881`. Spanish now includes Desktop +picker-state uncertainty, Antigravity family-quota evidence and the five-slot +`spawn_agent` model-selection rules, including both account-selector cases. + +Current validation: frozen root/docs installs, root typecheck and structure check +passed. The explicit docs/layout/hygiene/export/preview/service-auth group ran 588 +tests: 587 passed and the repository file-size scan timed out under the parallel +runner. Its isolated retry passed all 9 cases, with the repository scan completing +in 602 ms; no size cap or guard was changed. The root-suite resource exception +above still applies. The final Spanish-doc regression run passed all 15 tests +(2,132 assertions). The final offline site build completed with 667 pages and +97,652 checked internal links, Pagefind and sitemap. Desktop authentication and +service-token sections, mobile sidecar controls, six rendered coding benchmark +boards and Spanish search results were inspected in the real browser. The token +search returned 49 results. Screenshot evidence is pinned outside the source +branch at `588c95e9e636700f2035311017328d5670451e4a` on `pr-assets`. +Privacy scan and diff whitespace checks passed. Keep the Draft and independent +human language/render-acceptance hold; an agent's inspection is not that approval. + +## PR #7559 owner-requested refresh, October 23 + +Addressed the owner's [October 24 UTC triage comment](https://github.com/lidge-jun/opencodex/pull/7559#issuecomment-6378349500). +Merged `dev` first at `2494848f56e8a4f283722b2ebd816977e828c7af`, then at +`ceef4889e4666dc0492a375d272eafa5b785361e` (2.93.0), preserving published history. +All eight upstream test-layout shards remain byte-for-byte identical to that +base; the Spanish documentation shard is appended without dropping any shard. +The provider documentation retains upstream's new Alibaba Token Plan section. + +Corrected the remaining nonblank condition in `es/reference/adapters.md`: a +string must contain a non-whitespace character to be converted, while empty and +whitespace-only strings remain unchanged. The existing runtime regression file +checks those cases and exact whitespace preservation. Updated Spanish to match +current JEV session pinning and saved strategies, Antigravity per-account model +availability, provider discovery and credits, Hermes affinity, native effort +normalization, Remote Link readiness/retry diagnostics, and the Bun 1.4.4 runtime. +The landing also translates the new code-signing-policy link while retaining the +required English signing attribution verbatim. + +Validation for this refresh: + +- Frozen root, GUI and docs-site installs passed; no contribution-owned lockfile + or dependency changes. Tests use isolated Bun 1.4.3 through `scripts/test.ts`. +- All docs guards plus layout, structure, hygiene, routed-agent conversion and + CLI-export regressions: 512 passed, 0 failed, 4,661 assertions across 20 files. +- Separate file-size guard: 9 passed, 0 failed, 85 assertions. No cap changed. +- After the final upstream merge, fixture teardown, Codex auth-context and + server-management-auth regressions: 143 passed, 0 failed, 693 assertions. +- After the final Spanish edits, the Spanish documentation guard was rechecked: + 15 passed, 0 failed, 2,138 assertions. These 15 are already included in the + 512-test group and are not an additional coverage count. +- Root typecheck and structure check passed again after the final upstream merge. +- The offline documentation build checks all 667 pages, internal links, Pagefind + and sitemap. Final build and staged privacy-scan receipts are recorded in the + PR's Verification section before publication. +- Actual-browser DOM checks confirmed the corrected adapter paragraph and JEV + section, Spanish language metadata, mobile navigation, and no page overflow at + 1366px and 390px. The browser screenshot service returned "Unable to capture + screenshot", including on a fresh tab, so this refresh has no new capture and + does not claim fresh visual acceptance. Existing captures stay on `pr-assets`. + +The documented full-root-suite resource exception still applies. Hosted CI for +the new exact head, including the owner's requested `lane=all`, requires +maintainer authorization. Human Spanish/render acceptance and fresh review are +still pending; keep Draft and do not describe a skipped bot review or an +`action_required` workflow as passing. Request one consolidated CodeRabbit +review after publication without waiting for its result. diff --git a/docs-site/astro.config.mjs b/docs-site/astro.config.mjs index 89ccd0728d6..7e7b6313ce6 100644 --- a/docs-site/astro.config.mjs +++ b/docs-site/astro.config.mjs @@ -2,6 +2,7 @@ import { defineConfig } from "astro/config"; import starlight from "@astrojs/starlight"; import internalLinks from "./src/integrations/internal-links.mjs"; +import { codeBlockLocale } from "./src/data/code-block-locale"; // Canonical GitHub Pages custom domain. The site is served at the domain root, // so Starlight must not emit the former /opencodex project-site prefix. @@ -59,10 +60,12 @@ export default defineConfig({ baseUrl: "https://github.com/lidge-jun/opencodex/edit/main/docs-site/", }, lastUpdated: true, - // English at the site root; French under /fr, Korean under /ko, Simplified Chinese under /zh-cn, Traditional Chinese under /zh-tw, Russian under /ru, Japanese under /ja, Turkish under /tr. + expressiveCode: { getBlockLocale: ({ file }) => codeBlockLocale(file) }, + // English at the site root; Spanish under /es, French under /fr, Korean under /ko, Simplified Chinese under /zh-cn, Traditional Chinese under /zh-tw, Russian under /ru, Japanese under /ja, Turkish under /tr. defaultLocale: "root", locales: { root: { label: "English", lang: "en" }, + es: { label: "Español", lang: "es" }, fr: { label: "Français", lang: "fr" }, ko: { label: "한국어", lang: "ko" }, "zh-cn": { label: "简体中文", lang: "zh-CN" }, @@ -74,113 +77,113 @@ export default defineConfig({ sidebar: [ { label: "Getting Started", - translations: { fr: "Démarrage", ko: "시작하기", "zh-CN": "开始使用", "zh-TW": "開始使用", ru: "Начало работы", ja: "はじめに", tr: "Başlangıç" }, + translations: { es: "Primeros pasos", fr: "Démarrage", ko: "시작하기", "zh-CN": "开始使用", "zh-TW": "開始使用", ru: "Начало работы", ja: "はじめに", tr: "Başlangıç" }, items: [ - { label: "Installation", translations: { fr: "Installation", ko: "설치", "zh-CN": "安装", "zh-TW": "安裝", ru: "Установка", ja: "インストール", tr: "Kurulum" }, slug: "getting-started/installation" }, - { label: "Quickstart", translations: { fr: "Démarrage rapide", ko: "빠른 시작", "zh-CN": "快速开始", "zh-TW": "快速入門", ru: "Быстрый старт", ja: "クイックスタート", tr: "Hızlı Başlangıç" }, slug: "getting-started/quickstart" }, - { label: "How It Works", translations: { fr: "Fonctionnement", ko: "동작 원리", "zh-CN": "工作原理", "zh-TW": "運作原理", ru: "Как это работает", ja: "仕組み", tr: "Nasıl Çalışır" }, slug: "getting-started/how-it-works" }, - { label: "Agent Quickstart", translations: { fr: "Démarrage rapide pour les agents", ko: "에이전트 퀵스타트", "zh-CN": "Agent 快速上手", "zh-TW": "Agent 快速上手", ru: "Быстрый старт для агентов", ja: "エージェント向けクイックスタート", tr: "Ajanlar İçin Hızlı Başlangıç" }, slug: "getting-started/for-agents" }, + { label: "Installation", translations: { es: "Instalación", fr: "Installation", ko: "설치", "zh-CN": "安装", "zh-TW": "安裝", ru: "Установка", ja: "インストール", tr: "Kurulum" }, slug: "getting-started/installation" }, + { label: "Quickstart", translations: { es: "Inicio rápido", fr: "Démarrage rapide", ko: "빠른 시작", "zh-CN": "快速开始", "zh-TW": "快速入門", ru: "Быстрый старт", ja: "クイックスタート", tr: "Hızlı Başlangıç" }, slug: "getting-started/quickstart" }, + { label: "How It Works", translations: { es: "Cómo funciona", fr: "Fonctionnement", ko: "동작 원리", "zh-CN": "工作原理", "zh-TW": "運作原理", ru: "Как это работает", ja: "仕組み", tr: "Nasıl Çalışır" }, slug: "getting-started/how-it-works" }, + { label: "Agent Quickstart", translations: { es: "Inicio rápido para agentes", fr: "Démarrage rapide pour les agents", ko: "에이전트 퀵스타트", "zh-CN": "Agent 快速上手", "zh-TW": "Agent 快速上手", ru: "Быстрый старт для агентов", ja: "エージェント向けクイックスタート", tr: "Ajanlar İçin Hızlı Başlangıç" }, slug: "getting-started/for-agents" }, ], }, { label: "Guides", - translations: { fr: "Guides", ko: "가이드", "zh-CN": "指南", "zh-TW": "指南", ru: "Руководства", ja: "ガイド", tr: "Kılavuzlar" }, + translations: { es: "Guías", fr: "Guides", ko: "가이드", "zh-CN": "指南", "zh-TW": "指南", ru: "Руководства", ja: "ガイド", tr: "Kılavuzlar" }, items: [ - { label: "Remote Hub Deployment", translations: { fr: "Déploiement Remote Hub", ko: "Remote Hub 배포", "zh-CN": "Remote Hub 部署", "zh-TW": "Remote Hub 部署", ru: "Развёртывание Remote Hub", ja: "Remote Hub のデプロイ", tr: "Remote Hub Dağıtımı" }, slug: "guides/remote-hub" }, - { label: "Remote Link", translations: { fr: "Liaison distante", ko: "Remote Link", "zh-CN": "远程链接", "zh-TW": "遠端連結", ru: "Удалённая связь", ja: "リモートリンク", tr: "Uzak Bağlantı" }, slug: "guides/remote-link" }, - { label: "Response Inspection", translations: { fr: "Inspection des réponses et réponses volumineuses", ko: "응답 검사와 대용량 응답", "zh-CN": "响应检查与大型响应", "zh-TW": "回應檢查與大型回應", ru: "Проверка ответов и большие ответы", ja: "レスポンスの検査と大きなレスポンス", tr: "Yanıt incelemesi ve büyük yanıtlar" }, slug: "guides/response-inspection" }, - { label: "Remote Workspace", translations: { fr: "Espace de travail distant", ko: "원격 워크스페이스", "zh-CN": "远程工作区", "zh-TW": "遠端工作區", ru: "Удалённая рабочая область", ja: "リモートワークスペース", tr: "Uzak Çalışma Alanı" }, slug: "guides/remote-workspace" }, - { label: "Providers", translations: { fr: "Fournisseurs", ko: "프로바이더", "zh-CN": "提供商", "zh-TW": "供應商", ru: "Провайдеры", ja: "プロバイダー", tr: "Sağlayıcılar" }, slug: "guides/providers" }, - { label: "Factory Droid Bridge", translations: { fr: "Pont Factory Droid", ko: "Factory Droid 브리지", "zh-CN": "Factory Droid 桥接", "zh-TW": "Factory Droid 橋接", ru: "Мост Factory Droid", ja: "Factory Droid ブリッジ", tr: "Factory Droid köprüsü" }, slug: "guides/factory-droid" }, - { label: "Cursor Private Inference", translations: { ko: "Cursor Private Inference", fr: "Cursor Private Inference", "zh-CN": "Cursor Private Inference", "zh-TW": "Cursor Private Inference", ru: "Cursor Private Inference", ja: "Cursor Private Inference", tr: "Cursor Private Inference" }, slug: "guides/cursor-private-inference" }, - { label: "Model Routing", translations: { fr: "Routage des modèles", ko: "모델 라우팅", "zh-CN": "模型路由", "zh-TW": "模型路由", ru: "Маршрутизация моделей", ja: "モデルルーティング", tr: "Model Yönlendirme" }, slug: "guides/model-routing" }, - { label: "Codex Integration", translations: { fr: "Intégration de Codex", ko: "Codex 통합", "zh-CN": "Codex 集成", "zh-TW": "Codex 整合", ru: "Интеграция с Codex", ja: "Codex 連携", tr: "Codex Entegrasyonu" }, slug: "guides/codex-integration" }, - { label: "Composer Usage-Gate Fallback", translations: { ko: "Codex 입력 제한 대체 경로" }, slug: "guides/composer-usage-gate-fallback" }, - { label: "Codex App Model Picker", translations: { fr: "Sélecteur de modèles de Codex App", ko: "Codex App 모델 선택기", "zh-CN": "Codex App 模型选择器", "zh-TW": "Codex App 模型選擇器", ru: "Выбор модели в Codex App", ja: "Codex App モデルピッカー", tr: "Codex App Model Seçici" }, slug: "guides/codex-app-models" }, - { label: "Codex Prompt Layers", translations: { fr: "Couches d'invite Codex", ko: "Codex 프롬프트 레이어", "zh-CN": "Codex 提示词层", "zh-TW": "Codex 提示詞層", ru: "Слои промпта Codex", ja: "Codex プロンプトレイヤー", tr: "Codex İstem Katmanları" }, slug: "guides/codex-prompt" }, - { label: "Native Context Compatibility", translations: { ko: "네이티브 컨텍스트 호환성", fr: "Compatibilité du contexte natif", "zh-CN": "原生上下文兼容性", "zh-TW": "原生脈絡相容性", ru: "Совместимость с нативным контекстом", ja: "ネイティブコンテキストの互換性", tr: "Yerel bağlam uyumluluğu" }, slug: "guides/codex-native-context" }, - { label: "macOS Menu Bar App", translations: { fr: "Application barre de menus macOS", ko: "macOS 메뉴바 앱", "zh-CN": "macOS 菜单栏应用", "zh-TW": "macOS 選單列 App", ru: "Приложение в строке меню macOS", ja: "macOS メニューバーアプリ", tr: "macOS Menü Çubuğu Uygulaması" }, slug: "guides/macos-menu-bar" }, - { label: "Desktop App", translations: { fr: "Application de bureau", ko: "데스크톱 앱", "zh-CN": "桌面应用", "zh-TW": "桌面 App", ru: "Настольное приложение", ja: "デスクトップアプリ", tr: "Masaüstü Uygulaması" }, slug: "guides/desktop-app" }, - { label: "Model Ordering", translations: { fr: "Ordre des modèles", ko: "모델 정렬에 관하여", "zh-CN": "模型排序", "zh-TW": "模型排序", ru: "Сортировка моделей", ja: "モデルの並び順", tr: "Model Sıralaması" }, slug: "guides/model-ordering" }, - { label: "Combos", translations: { fr: "Combinaisons", ko: "콤보", "zh-CN": "组合", "zh-TW": "組合", ru: "Комбо", ja: "コンボ", tr: "Kombolar" }, slug: "guides/combos" }, - { label: "Fallback off", translations: { fr: "Désactiver le repli", ko: "폴백 끄기", "zh-CN": "关闭回退", "zh-TW": "關閉備援", ru: "Отключение резерва", ja: "フォールバックをオフにする", tr: "Yedeği kapatma" }, slug: "guides/fallback-off" }, - { label: "Protocol Paths", translations: { fr: "Chemins de protocole", ko: "프로토콜 경로", "zh-CN": "协议路径", "zh-TW": "協定路徑", ru: "Пути протоколов", ja: "プロトコル経路", tr: "Protokol Yolları" }, slug: "guides/protocol-paths" }, - { label: "Claude Code", translations: { fr: "Claude Code", ko: "Claude Code", "zh-CN": "Claude Code", "zh-TW": "Claude Code", ru: "Claude Code", ja: "Claude Code", tr: "Claude Code" }, slug: "guides/claude-code" }, - { label: "Grok Build", translations: { fr: "Grok Build", ko: "Grok Build", "zh-CN": "Grok Build", "zh-TW": "Grok Build", ru: "Grok Build", ja: "Grok Build", tr: "Grok Build" }, slug: "guides/grok-build" }, - { label: "opencode", translations: { fr: "opencode", ko: "opencode", "zh-CN": "opencode", "zh-TW": "opencode", ru: "opencode", ja: "opencode", tr: "opencode" }, slug: "guides/opencode" }, - { label: "Pi", translations: { fr: "Pi", ko: "Pi", "zh-CN": "Pi", "zh-TW": "Pi", ru: "Pi", ja: "Pi", tr: "Pi" }, slug: "guides/pi" }, - { label: "ChatGPT Desktop (experimental)", slug: "guides/chatgpt-desktop" }, - { label: "Integrations", translations: { fr: "Intégrations", ko: "연동", "zh-CN": "集成", "zh-TW": "整合", ru: "Интеграции", ja: "連携", tr: "Entegrasyonlar" }, slug: "guides/integrations" }, - { label: "MiniMax clients", translations: { fr: "Clients MiniMax", ko: "MiniMax 클라이언트", "zh-CN": "MiniMax 客户端", "zh-TW": "MiniMax 客戶端", ru: "Клиенты MiniMax", ja: "MiniMax クライアント", tr: "MiniMax İstemcileri" }, slug: "guides/minimax" }, - { label: "Sidecars: Web Search & Vision", translations: { fr: "Services auxiliaires : recherche web et vision", ko: "사이드카: 웹 검색 & 비전", "zh-CN": "边车：网络搜索与视觉", "zh-TW": "邊車：網路搜尋與視覺", ru: "Сайдкары: веб-поиск и зрение", ja: "サイドカー: ウェブ検索 & ビジョン", tr: "Sidecar'lar: Web Arama ve Görme" }, slug: "guides/sidecars" }, - { label: "Local Plugins", translations: { fr: "Plugins locaux", ko: "로컬 플러그인", "zh-CN": "本地插件", "zh-TW": "本機外掛", ru: "Локальные плагины", ja: "ローカルプラグイン", tr: "Yerel Eklentiler" }, slug: "guides/local-plugins" }, - { label: "Image Bridge", translations: { fr: "Pont d’images", ko: "이미지 브릿지", "zh-CN": "图像桥接", "zh-TW": "圖像橋接", ru: "Image Bridge", ja: "画像ブリッジ", tr: "Image Bridge" }, slug: "guides/image-bridge" }, - { label: "Video Bridge", translations: { fr: "Pont vidéo", ko: "비디오 브릿지", "zh-CN": "视频桥接", "zh-TW": "影片橋接", ru: "Video Bridge", ja: "動画ブリッジ", tr: "Video Bridge" }, slug: "guides/video-bridge" }, - { label: "Web Dashboard", translations: { fr: "Tableau de bord web", ko: "웹 대시보드", "zh-CN": "网页控制台", "zh-TW": "網頁儀表板", ru: "Веб-дашборд", ja: "ウェブダッシュボード", tr: "Web Kontrol Paneli" }, slug: "guides/web-dashboard" }, - { label: "Sub-agent Surface", translations: { fr: "Interface des sous-agents", ko: "서브에이전트 서피스", "zh-CN": "子代理界面", "zh-TW": "子代理介面", ru: "Интерфейс подагентов", ja: "サブエージェントサーフェス", tr: "Alt Ajan Arayüzü" }, slug: "guides/sub-agent-surface" }, - { label: "Why v1 Is the Default", translations: { fr: "Pourquoi v1 est la valeur par défaut", ko: "v1이 기본값인 이유", "zh-CN": "为什么默认是 v1", "zh-TW": "為什麼預設是 v1", ru: "Почему v1 по умолчанию", ja: "v1 がデフォルトである理由", tr: "Neden varsayılan v1" }, slug: "guides/subagent-v1-default" }, + { label: "Remote Hub Deployment", translations: { es: "Despliegue de Remote Hub", fr: "Déploiement Remote Hub", ko: "Remote Hub 배포", "zh-CN": "Remote Hub 部署", "zh-TW": "Remote Hub 部署", ru: "Развёртывание Remote Hub", ja: "Remote Hub のデプロイ", tr: "Remote Hub Dağıtımı" }, slug: "guides/remote-hub" }, + { label: "Remote Link", translations: { es: "Enlace remoto", fr: "Liaison distante", ko: "Remote Link", "zh-CN": "远程链接", "zh-TW": "遠端連結", ru: "Удалённая связь", ja: "リモートリンク", tr: "Uzak Bağlantı" }, slug: "guides/remote-link" }, + { label: "Response Inspection", translations: { es: "Inspección de respuestas", fr: "Inspection des réponses et réponses volumineuses", ko: "응답 검사와 대용량 응답", "zh-CN": "响应检查与大型响应", "zh-TW": "回應檢查與大型回應", ru: "Проверка ответов и большие ответы", ja: "レスポンスの検査と大きなレスポンス", tr: "Yanıt incelemesi ve büyük yanıtlar" }, slug: "guides/response-inspection" }, + { label: "Remote Workspace", translations: { es: "Espacio de trabajo remoto", fr: "Espace de travail distant", ko: "원격 워크스페이스", "zh-CN": "远程工作区", "zh-TW": "遠端工作區", ru: "Удалённая рабочая область", ja: "リモートワークスペース", tr: "Uzak Çalışma Alanı" }, slug: "guides/remote-workspace" }, + { label: "Providers", translations: { es: "Proveedores", fr: "Fournisseurs", ko: "프로바이더", "zh-CN": "提供商", "zh-TW": "供應商", ru: "Провайдеры", ja: "プロバイダー", tr: "Sağlayıcılar" }, slug: "guides/providers" }, + { label: "Factory Droid Bridge", translations: { es: "Puente Factory Droid", fr: "Pont Factory Droid", ko: "Factory Droid 브리지", "zh-CN": "Factory Droid 桥接", "zh-TW": "Factory Droid 橋接", ru: "Мост Factory Droid", ja: "Factory Droid ブリッジ", tr: "Factory Droid köprüsü" }, slug: "guides/factory-droid" }, + { label: "Cursor Private Inference", translations: { es: "Inferencia privada de Cursor", ko: "Cursor Private Inference", fr: "Cursor Private Inference", "zh-CN": "Cursor Private Inference", "zh-TW": "Cursor Private Inference", ru: "Cursor Private Inference", ja: "Cursor Private Inference", tr: "Cursor Private Inference" }, slug: "guides/cursor-private-inference" }, + { label: "Model Routing", translations: { es: "Enrutamiento de modelos", fr: "Routage des modèles", ko: "모델 라우팅", "zh-CN": "模型路由", "zh-TW": "模型路由", ru: "Маршрутизация моделей", ja: "モデルルーティング", tr: "Model Yönlendirme" }, slug: "guides/model-routing" }, + { label: "Codex Integration", translations: { es: "Integración con Codex", fr: "Intégration de Codex", ko: "Codex 통합", "zh-CN": "Codex 集成", "zh-TW": "Codex 整合", ru: "Интеграция с Codex", ja: "Codex 連携", tr: "Codex Entegrasyonu" }, slug: "guides/codex-integration" }, + { label: "Composer Usage-Gate Fallback", translations: { es: "Alternativa ante límites de uso de Composer", ko: "Codex 입력 제한 대체 경로" }, slug: "guides/composer-usage-gate-fallback" }, + { label: "Codex App Model Picker", translations: { es: "Selector de modelos de Codex App", fr: "Sélecteur de modèles de Codex App", ko: "Codex App 모델 선택기", "zh-CN": "Codex App 模型选择器", "zh-TW": "Codex App 模型選擇器", ru: "Выбор модели в Codex App", ja: "Codex App モデルピッカー", tr: "Codex App Model Seçici" }, slug: "guides/codex-app-models" }, + { label: "Codex Prompt Layers", translations: { es: "Capas de instrucciones de Codex", fr: "Couches d'invite Codex", ko: "Codex 프롬프트 레이어", "zh-CN": "Codex 提示词层", "zh-TW": "Codex 提示詞層", ru: "Слои промпта Codex", ja: "Codex プロンプトレイヤー", tr: "Codex İstem Katmanları" }, slug: "guides/codex-prompt" }, + { label: "Native Context Compatibility", translations: { es: "Compatibilidad de contexto nativo", ko: "네이티브 컨텍스트 호환성", fr: "Compatibilité du contexte natif", "zh-CN": "原生上下文兼容性", "zh-TW": "原生脈絡相容性", ru: "Совместимость с нативным контекстом", ja: "ネイティブコンテキストの互換性", tr: "Yerel bağlam uyumluluğu" }, slug: "guides/codex-native-context" }, + { label: "macOS Menu Bar App", translations: { es: "Aplicación de barra de menús de macOS", fr: "Application barre de menus macOS", ko: "macOS 메뉴바 앱", "zh-CN": "macOS 菜单栏应用", "zh-TW": "macOS 選單列 App", ru: "Приложение в строке меню macOS", ja: "macOS メニューバーアプリ", tr: "macOS Menü Çubuğu Uygulaması" }, slug: "guides/macos-menu-bar" }, + { label: "Desktop App", translations: { es: "Aplicación de escritorio", fr: "Application de bureau", ko: "데스크톱 앱", "zh-CN": "桌面应用", "zh-TW": "桌面 App", ru: "Настольное приложение", ja: "デスクトップアプリ", tr: "Masaüstü Uygulaması" }, slug: "guides/desktop-app" }, + { label: "Model Ordering", translations: { es: "Orden de modelos", fr: "Ordre des modèles", ko: "모델 정렬에 관하여", "zh-CN": "模型排序", "zh-TW": "模型排序", ru: "Сортировка моделей", ja: "モデルの並び順", tr: "Model Sıralaması" }, slug: "guides/model-ordering" }, + { label: "Combos", translations: { es: "Combos", fr: "Combinaisons", ko: "콤보", "zh-CN": "组合", "zh-TW": "組合", ru: "Комбо", ja: "コンボ", tr: "Kombolar" }, slug: "guides/combos" }, + { label: "Fallback off", translations: { es: "Desactivar el fallback", fr: "Désactiver le repli", ko: "폴백 끄기", "zh-CN": "关闭回退", "zh-TW": "關閉備援", ru: "Отключение резерва", ja: "フォールバックをオフにする", tr: "Yedeği kapatma" }, slug: "guides/fallback-off" }, + { label: "Protocol Paths", translations: { es: "Rutas de protocolo", fr: "Chemins de protocole", ko: "프로토콜 경로", "zh-CN": "协议路径", "zh-TW": "協定路徑", ru: "Пути протоколов", ja: "プロトコル経路", tr: "Protokol Yolları" }, slug: "guides/protocol-paths" }, + { label: "Claude Code", translations: { es: "Claude Code", fr: "Claude Code", ko: "Claude Code", "zh-CN": "Claude Code", "zh-TW": "Claude Code", ru: "Claude Code", ja: "Claude Code", tr: "Claude Code" }, slug: "guides/claude-code" }, + { label: "Grok Build", translations: { es: "Grok Build", fr: "Grok Build", ko: "Grok Build", "zh-CN": "Grok Build", "zh-TW": "Grok Build", ru: "Grok Build", ja: "Grok Build", tr: "Grok Build" }, slug: "guides/grok-build" }, + { label: "opencode", translations: { es: "OpenCode", fr: "opencode", ko: "opencode", "zh-CN": "opencode", "zh-TW": "opencode", ru: "opencode", ja: "opencode", tr: "opencode" }, slug: "guides/opencode" }, + { label: "Pi", translations: { es: "Pi", fr: "Pi", ko: "Pi", "zh-CN": "Pi", "zh-TW": "Pi", ru: "Pi", ja: "Pi", tr: "Pi" }, slug: "guides/pi" }, + { label: "ChatGPT Desktop (experimental)", translations: { es: "ChatGPT Desktop (experimental)" }, slug: "guides/chatgpt-desktop" }, + { label: "Integrations", translations: { es: "Integraciones", fr: "Intégrations", ko: "연동", "zh-CN": "集成", "zh-TW": "整合", ru: "Интеграции", ja: "連携", tr: "Entegrasyonlar" }, slug: "guides/integrations" }, + { label: "MiniMax clients", translations: { es: "Clientes MiniMax", fr: "Clients MiniMax", ko: "MiniMax 클라이언트", "zh-CN": "MiniMax 客户端", "zh-TW": "MiniMax 客戶端", ru: "Клиенты MiniMax", ja: "MiniMax クライアント", tr: "MiniMax İstemcileri" }, slug: "guides/minimax" }, + { label: "Sidecars: Web Search & Vision", translations: { es: "Sidecars: búsqueda web y visión", fr: "Services auxiliaires : recherche web et vision", ko: "사이드카: 웹 검색 & 비전", "zh-CN": "边车：网络搜索与视觉", "zh-TW": "邊車：網路搜尋與視覺", ru: "Сайдкары: веб-поиск и зрение", ja: "サイドカー: ウェブ検索 & ビジョン", tr: "Sidecar'lar: Web Arama ve Görme" }, slug: "guides/sidecars" }, + { label: "Local Plugins", translations: { es: "Plugins locales", fr: "Plugins locaux", ko: "로컬 플러그인", "zh-CN": "本地插件", "zh-TW": "本機外掛", ru: "Локальные плагины", ja: "ローカルプラグイン", tr: "Yerel Eklentiler" }, slug: "guides/local-plugins" }, + { label: "Image Bridge", translations: { es: "Puente de imágenes", fr: "Pont d’images", ko: "이미지 브릿지", "zh-CN": "图像桥接", "zh-TW": "圖像橋接", ru: "Image Bridge", ja: "画像ブリッジ", tr: "Image Bridge" }, slug: "guides/image-bridge" }, + { label: "Video Bridge", translations: { es: "Puente de video", fr: "Pont vidéo", ko: "비디오 브릿지", "zh-CN": "视频桥接", "zh-TW": "影片橋接", ru: "Video Bridge", ja: "動画ブリッジ", tr: "Video Bridge" }, slug: "guides/video-bridge" }, + { label: "Web Dashboard", translations: { es: "Dashboard web", fr: "Tableau de bord web", ko: "웹 대시보드", "zh-CN": "网页控制台", "zh-TW": "網頁儀表板", ru: "Веб-дашборд", ja: "ウェブダッシュボード", tr: "Web Kontrol Paneli" }, slug: "guides/web-dashboard" }, + { label: "Sub-agent Surface", translations: { es: "Interfaz de subagentes", fr: "Interface des sous-agents", ko: "서브에이전트 서피스", "zh-CN": "子代理界面", "zh-TW": "子代理介面", ru: "Интерфейс подагентов", ja: "サブエージェントサーフェス", tr: "Alt Ajan Arayüzü" }, slug: "guides/sub-agent-surface" }, + { label: "Why v1 Is the Default", translations: { es: "Por qué v1 es la opción predeterminada", fr: "Pourquoi v1 est la valeur par défaut", ko: "v1이 기본값인 이유", "zh-CN": "为什么默认是 v1", "zh-TW": "為什麼預設是 v1", ru: "Почему v1 по умолчанию", ja: "v1 がデフォルトである理由", tr: "Neden varsayılan v1" }, slug: "guides/subagent-v1-default" }, ], }, { label: "Benchmarks", - translations: { fr: "Bancs d’essai", ko: "벤치마크", "zh-CN": "基准测试", "zh-TW": "基準測試", ru: "Бенчмарки", ja: "ベンチマーク", tr: "Kıyaslamalar" }, + translations: { es: "Pruebas comparativas", fr: "Bancs d’essai", ko: "벤치마크", "zh-CN": "基准测试", "zh-TW": "基準測試", ru: "Бенчмарки", ja: "ベンチマーク", tr: "Kıyaslamalar" }, collapsed: true, items: [ - { label: "Overview", translations: { fr: "Vue d’ensemble", ko: "개요", "zh-CN": "概览", "zh-TW": "概覽", ru: "Обзор", ja: "概要", tr: "Genel Bakış" }, slug: "benchmarks" }, - { label: "Coding", translations: { fr: "Programmation", ko: "코딩", "zh-CN": "编程", "zh-TW": "程式設計", ru: "Кодинг", ja: "コーディング", tr: "Kodlama" }, slug: "benchmarks/coding" }, - { label: "Frontend", translations: { fr: "Frontend", ko: "프론트엔드", "zh-CN": "前端", "zh-TW": "前端", ru: "Фронтенд", ja: "フロントエンド", tr: "Ön Yüz" }, slug: "benchmarks/frontend" }, - { label: "Terminal", translations: { fr: "Terminal", ko: "터미널", "zh-CN": "终端", "zh-TW": "終端", ru: "Терминал", ja: "ターミナル", tr: "Terminal" }, slug: "benchmarks/terminal" }, - { label: "Security", translations: { fr: "Sécurité", ko: "보안", "zh-CN": "安全", "zh-TW": "安全", ru: "Безопасность", ja: "セキュリティ", tr: "Güvenlik" }, slug: "benchmarks/security" }, - { label: "Intelligence", translations: { fr: "Intelligence", ko: "인텔리전스", "zh-CN": "智能", "zh-TW": "智慧", ru: "Интеллект", ja: "インテリジェンス", tr: "Zeka" }, slug: "benchmarks/intelligence" }, + { label: "Overview", translations: { es: "Descripción general", fr: "Vue d’ensemble", ko: "개요", "zh-CN": "概览", "zh-TW": "概覽", ru: "Обзор", ja: "概要", tr: "Genel Bakış" }, slug: "benchmarks" }, + { label: "Coding", translations: { es: "Codificación", fr: "Programmation", ko: "코딩", "zh-CN": "编程", "zh-TW": "程式設計", ru: "Кодинг", ja: "コーディング", tr: "Kodlama" }, slug: "benchmarks/coding" }, + { label: "Frontend", translations: { es: "Frontend", fr: "Frontend", ko: "프론트엔드", "zh-CN": "前端", "zh-TW": "前端", ru: "Фронтенд", ja: "フロントエンド", tr: "Ön Yüz" }, slug: "benchmarks/frontend" }, + { label: "Terminal", translations: { es: "Terminal", fr: "Terminal", ko: "터미널", "zh-CN": "终端", "zh-TW": "終端", ru: "Терминал", ja: "ターミナル", tr: "Terminal" }, slug: "benchmarks/terminal" }, + { label: "Security", translations: { es: "Seguridad", fr: "Sécurité", ko: "보안", "zh-CN": "安全", "zh-TW": "安全", ru: "Безопасность", ja: "セキュリティ", tr: "Güvenlik" }, slug: "benchmarks/security" }, + { label: "Intelligence", translations: { es: "Inteligencia", fr: "Intelligence", ko: "인텔리전스", "zh-CN": "智能", "zh-TW": "智慧", ru: "Интеллект", ja: "インテリジェンス", tr: "Zeka" }, slug: "benchmarks/intelligence" }, ], }, { label: "Reference", - translations: { fr: "Référence", ko: "레퍼런스", "zh-CN": "参考", "zh-TW": "參考", ru: "Справочник", ja: "リファレンス", tr: "Referans" }, + translations: { es: "Referencia", fr: "Référence", ko: "레퍼런스", "zh-CN": "参考", "zh-TW": "參考", ru: "Справочник", ja: "リファレンス", tr: "Referans" }, items: [ { label: "CLI", - translations: { fr: "CLI", ko: "CLI", "zh-CN": "命令行", "zh-TW": "命令列", ru: "CLI", ja: "CLI", tr: "CLI" }, + translations: { es: "CLI", fr: "CLI", ko: "CLI", "zh-CN": "命令行", "zh-TW": "命令列", ru: "CLI", ja: "CLI", tr: "CLI" }, items: [ - { label: "Overview", translations: { fr: "Vue d’ensemble", ko: "개요", "zh-CN": "概览", "zh-TW": "概覽", ru: "Обзор", ja: "概要", tr: "Genel Bakış" }, slug: "reference/cli" }, - { label: "Lifecycle & Service", translations: { fr: "Cycle de vie et service", ko: "라이프사이클 & 서비스", "zh-CN": "生命周期与服务", "zh-TW": "生命週期與服務", ru: "Жизненный цикл и служба", ja: "ライフサイクル & サービス", tr: "Yaşam Döngüsü ve Servis" }, slug: "reference/cli/lifecycle" }, - { label: "Providers, Accounts & Models", translations: { fr: "Fournisseurs, comptes et modèles", ko: "프로바이더, 계정 & 모델", "zh-CN": "提供商、账户与模型", "zh-TW": "供應商、帳號與模型", ru: "Провайдеры, аккаунты и модели", ja: "プロバイダー・アカウント・モデル", tr: "Sağlayıcılar, Hesaplar ve Modeller" }, slug: "reference/cli/providers-accounts" }, - { label: "Agents, Routing & Integrations", translations: { fr: "Agents, routage et intégrations", ko: "에이전트, 라우팅 & 통합", "zh-CN": "代理、路由与集成", "zh-TW": "代理、路由與整合", ru: "Агенты, маршрутизация и интеграции", ja: "エージェント・ルーティング・連携", tr: "Ajanlar, Yönlendirme ve Entegrasyonlar" }, slug: "reference/cli/agents" }, + { label: "Overview", translations: { es: "Descripción general", fr: "Vue d’ensemble", ko: "개요", "zh-CN": "概览", "zh-TW": "概覽", ru: "Обзор", ja: "概要", tr: "Genel Bakış" }, slug: "reference/cli" }, + { label: "Lifecycle & Service", translations: { es: "Ciclo de vida y servicio", fr: "Cycle de vie et service", ko: "라이프사이클 & 서비스", "zh-CN": "生命周期与服务", "zh-TW": "生命週期與服務", ru: "Жизненный цикл и служба", ja: "ライフサイクル & サービス", tr: "Yaşam Döngüsü ve Servis" }, slug: "reference/cli/lifecycle" }, + { label: "Providers, Accounts & Models", translations: { es: "Proveedores, cuentas y modelos", fr: "Fournisseurs, comptes et modèles", ko: "프로바이더, 계정 & 모델", "zh-CN": "提供商、账户与模型", "zh-TW": "供應商、帳號與模型", ru: "Провайдеры, аккаунты и модели", ja: "プロバイダー・アカウント・モデル", tr: "Sağlayıcılar, Hesaplar ve Modeller" }, slug: "reference/cli/providers-accounts" }, + { label: "Agents, Routing & Integrations", translations: { es: "Agentes, enrutamiento e integraciones", fr: "Agents, routage et intégrations", ko: "에이전트, 라우팅 & 통합", "zh-CN": "代理、路由与集成", "zh-TW": "代理、路由與整合", ru: "Агенты, маршрутизация и интеграции", ja: "エージェント・ルーティング・連携", tr: "Ajanlar, Yönlendirme ve Entegrasyonlar" }, slug: "reference/cli/agents" }, ], }, { label: "Configuration", - translations: { fr: "Configuration", ko: "설정", "zh-CN": "配置", "zh-TW": "設定", ru: "Конфигурация", ja: "設定", tr: "Yapılandırma" }, + translations: { es: "Configuración", fr: "Configuration", ko: "설정", "zh-CN": "配置", "zh-TW": "設定", ru: "Конфигурация", ja: "設定", tr: "Yapılandırma" }, items: [ - { label: "Overview", translations: { fr: "Vue d’ensemble", ko: "개요", "zh-CN": "概览", "zh-TW": "概覽", ru: "Обзор", ja: "概要", tr: "Genel Bakış" }, slug: "reference/configuration" }, - { label: "Providers", translations: { fr: "Fournisseurs", ko: "프로바이더", "zh-CN": "提供商", "zh-TW": "供應商", ru: "Провайдеры", ja: "プロバイダー", tr: "Sağlayıcılar" }, slug: "reference/configuration/providers" }, - { label: "Routing", translations: { fr: "Routage", ko: "라우팅", "zh-CN": "路由", "zh-TW": "路由", ru: "Маршрутизация", ja: "ルーティング", tr: "Yönlendirme" }, slug: "reference/configuration/routing" }, - { label: "Agents", translations: { fr: "Agents", ko: "에이전트", "zh-CN": "代理", "zh-TW": "代理", ru: "Агенты", ja: "エージェント", tr: "Ajanlar" }, slug: "reference/configuration/agents" }, - { label: "Advisor", translations: { fr: "Conseiller", ko: "어드바이저", "zh-CN": "顾问", "zh-TW": "顧問", ru: "Консультант", ja: "アドバイザー", tr: "Danışman" }, slug: "reference/configuration/advisor" }, - { label: "Server & Runtime", translations: { fr: "Serveur et environnement d’exécution", ko: "서버 & 런타임", "zh-CN": "服务器与运行时", "zh-TW": "伺服器與執行階段", ru: "Сервер и рантайм", ja: "サーバー & ランタイム", tr: "Sunucu ve Çalışma Zamanı" }, slug: "reference/configuration/server" }, + { label: "Overview", translations: { es: "Descripción general", fr: "Vue d’ensemble", ko: "개요", "zh-CN": "概览", "zh-TW": "概覽", ru: "Обзор", ja: "概要", tr: "Genel Bakış" }, slug: "reference/configuration" }, + { label: "Providers", translations: { es: "Proveedores", fr: "Fournisseurs", ko: "프로바이더", "zh-CN": "提供商", "zh-TW": "供應商", ru: "Провайдеры", ja: "プロバイダー", tr: "Sağlayıcılar" }, slug: "reference/configuration/providers" }, + { label: "Routing", translations: { es: "Enrutamiento", fr: "Routage", ko: "라우팅", "zh-CN": "路由", "zh-TW": "路由", ru: "Маршрутизация", ja: "ルーティング", tr: "Yönlendirme" }, slug: "reference/configuration/routing" }, + { label: "Agents", translations: { es: "Agentes", fr: "Agents", ko: "에이전트", "zh-CN": "代理", "zh-TW": "代理", ru: "Агенты", ja: "エージェント", tr: "Ajanlar" }, slug: "reference/configuration/agents" }, + { label: "Advisor", translations: { es: "Advisor", fr: "Conseiller", ko: "어드바이저", "zh-CN": "顾问", "zh-TW": "顧問", ru: "Консультант", ja: "アドバイザー", tr: "Danışman" }, slug: "reference/configuration/advisor" }, + { label: "Server & Runtime", translations: { es: "Servidor y entorno de ejecución", fr: "Serveur et environnement d’exécution", ko: "서버 & 런타임", "zh-CN": "服务器与运行时", "zh-TW": "伺服器與執行階段", ru: "Сервер и рантайм", ja: "サーバー & ランタイム", tr: "Sunucu ve Çalışma Zamanı" }, slug: "reference/configuration/server" }, ], }, - { label: "Adapters", translations: { fr: "Adaptateurs", ko: "어댑터", "zh-CN": "适配器", "zh-TW": "適配器", ru: "Адаптеры", ja: "アダプター", tr: "Adaptörler" }, slug: "reference/adapters" }, - { label: "Architecture", translations: { fr: "Architecture", ko: "아키텍처", "zh-CN": "架构", "zh-TW": "架構", ru: "Архитектура", ja: "アーキテクチャ", tr: "Mimari" }, slug: "reference/architecture" }, - { label: "Platform Support", translations: { fr: "Prise en charge des plateformes", ko: "플랫폼 지원", "zh-CN": "平台支持", "zh-TW": "平台支援", ru: "Поддержка платформ", ja: "プラットフォーム対応", tr: "Platform Desteği" }, link: `${SITE_URL}/reference/platform-support` }, - { label: "Windows Code Signing", translations: { fr: "Signature du code Windows", ko: "Windows 코드 서명", "zh-CN": "Windows 代码签名", "zh-TW": "Windows 程式碼簽署", ru: "Подпись кода Windows", ja: "Windows コード署名", tr: "Windows Kod İmzalama" }, slug: "reference/code-signing" }, - { label: "Proxy API Formats", translations: { fr: "Formats de l’API proxy", ko: "프록시 API 형식", "zh-CN": "代理 API 格式", "zh-TW": "代理 API 格式", ru: "Форматы API прокси", ja: "プロキシAPI形式", tr: "Proxy API Formatları" }, slug: "reference/proxy-formats" }, - { label: "Management API", translations: { fr: "API de gestion", ko: "관리 API", "zh-CN": "管理 API", "zh-TW": "管理 API", ru: "API управления", ja: "管理API", tr: "Yönetim API'si" }, slug: "reference/management-api" }, + { label: "Adapters", translations: { es: "Adaptadores", fr: "Adaptateurs", ko: "어댑터", "zh-CN": "适配器", "zh-TW": "適配器", ru: "Адаптеры", ja: "アダプター", tr: "Adaptörler" }, slug: "reference/adapters" }, + { label: "Architecture", translations: { es: "Arquitectura", fr: "Architecture", ko: "아키텍처", "zh-CN": "架构", "zh-TW": "架構", ru: "Архитектура", ja: "アーキテクチャ", tr: "Mimari" }, slug: "reference/architecture" }, + { label: "Platform Support", translations: { es: "Soporte de plataforma", fr: "Prise en charge des plateformes", ko: "플랫폼 지원", "zh-CN": "平台支持", "zh-TW": "平台支援", ru: "Поддержка платформ", ja: "プラットフォーム対応", tr: "Platform Desteği" }, slug: "reference/platform-support" }, + { label: "Windows Code Signing", translations: { es: "Firma de código en Windows", fr: "Signature du code Windows", ko: "Windows 코드 서명", "zh-CN": "Windows 代码签名", "zh-TW": "Windows 程式碼簽署", ru: "Подпись кода Windows", ja: "Windows コード署名", tr: "Windows Kod İmzalama" }, slug: "reference/code-signing" }, + { label: "Proxy API Formats", translations: { es: "Formatos de API del proxy", fr: "Formats de l’API proxy", ko: "프록시 API 형식", "zh-CN": "代理 API 格式", "zh-TW": "代理 API 格式", ru: "Форматы API прокси", ja: "プロキシAPI形式", tr: "Proxy API Formatları" }, slug: "reference/proxy-formats" }, + { label: "Management API", translations: { es: "API de administración", fr: "API de gestion", ko: "관리 API", "zh-CN": "管理 API", "zh-TW": "管理 API", ru: "API управления", ja: "管理API", tr: "Yönetim API'si" }, slug: "reference/management-api" }, ], }, { label: "Troubleshooting", - translations: { fr: "Dépannage", ko: "문제 해결", "zh-CN": "故障排除", "zh-TW": "疑難排解", ru: "Устранение неполадок", ja: "トラブルシューティング", tr: "Sorun Giderme" }, + translations: { es: "Solución de problemas", fr: "Dépannage", ko: "문제 해결", "zh-CN": "故障排除", "zh-TW": "疑難排解", ru: "Устранение неполадок", ja: "トラブルシューティング", tr: "Sorun Giderme" }, collapsed: true, items: [ - { label: "Windows Memory Growth", translations: { fr: "Augmentation de la mémoire sous Windows", ko: "Windows 메모리 증가", "zh-CN": "Windows 内存增长", "zh-TW": "Windows 記憶體增長", ru: "Рост памяти в Windows", ja: "Windows メモリ増加", tr: "Windows Bellek Artışı" }, slug: "troubleshooting/windows-memory" }, - { label: "Disk Usage from Temp Files", translations: { fr: "Espace disque et fichiers temporaires", ko: "임시 파일 디스크 사용량", "zh-CN": "临时文件磁盘占用", "zh-TW": "暫存檔磁碟用量", ru: "Использование диска временными файлами", ja: "一時ファイルのディスク使用量", tr: "Geçici Dosya Disk Kullanımı" }, slug: "troubleshooting/disk-usage-temp-files" }, - { label: "Codex Cannot Sign In or Load", translations: { fr: "Codex ne peut pas se connecter", ko: "Codex 로그인 불가", "zh-CN": "Codex 无法登录", "zh-TW": "Codex 無法登入", ru: "Codex не может войти", ja: "Codex にサインインできない", tr: "Codex Oturum Açamıyor" }, slug: "troubleshooting/codex-cannot-sign-in" }, - { label: "Update Failed on Windows", translations: { fr: "Échec de la mise à jour sous Windows", ko: "Windows에서 업데이트 실패", "zh-CN": "Windows 上更新失败", "zh-TW": "Windows 上更新失敗", ru: "Сбой обновления в Windows", ja: "Windows で更新に失敗する", tr: "Windows'ta Güncelleme Başarısız" }, slug: "troubleshooting/update-failed" }, - { label: "Spend Ledger Refused in a Synced Folder", translations: { fr: "Registre de dépenses refusé dans un dossier synchronisé", ko: "동기화 폴더에서 지출 원장 거부", "zh-CN": "同步文件夹中的支出账本被拒绝", "zh-TW": "同步資料夾中的支出帳本被拒絕", ru: "Отказ журнала расходов в синхронизируемой папке", ja: "同期フォルダーで支出台帳が拒否される", tr: "Eşitlenen Klasörde Harcama Defteri Reddi" }, slug: "troubleshooting/spend-ledger-synced-folder" }, + { label: "Windows Memory Growth", translations: { es: "Windows Crecimiento de memoria", fr: "Augmentation de la mémoire sous Windows", ko: "Windows 메모리 증가", "zh-CN": "Windows 内存增长", "zh-TW": "Windows 記憶體增長", ru: "Рост памяти в Windows", ja: "Windows メモリ増加", tr: "Windows Bellek Artışı" }, slug: "troubleshooting/windows-memory" }, + { label: "Disk Usage from Temp Files", translations: { es: "Uso del disco desde archivos Temp", fr: "Espace disque et fichiers temporaires", ko: "임시 파일 디스크 사용량", "zh-CN": "临时文件磁盘占用", "zh-TW": "暫存檔磁碟用量", ru: "Использование диска временными файлами", ja: "一時ファイルのディスク使用量", tr: "Geçici Dosya Disk Kullanımı" }, slug: "troubleshooting/disk-usage-temp-files" }, + { label: "Codex Cannot Sign In or Load", translations: { es: "Codex no puede iniciar sesión ni cargar", fr: "Codex ne peut pas se connecter", ko: "Codex 로그인 불가", "zh-CN": "Codex 无法登录", "zh-TW": "Codex 無法登入", ru: "Codex не может войти", ja: "Codex にサインインできない", tr: "Codex Oturum Açamıyor" }, slug: "troubleshooting/codex-cannot-sign-in" }, + { label: "Update Failed on Windows", translations: { es: "Fallo de actualización en Windows", fr: "Échec de la mise à jour sous Windows", ko: "Windows에서 업데이트 실패", "zh-CN": "Windows 上更新失败", "zh-TW": "Windows 上更新失敗", ru: "Сбой обновления в Windows", ja: "Windows で更新に失敗する", tr: "Windows'ta Güncelleme Başarısız" }, slug: "troubleshooting/update-failed" }, + { label: "Spend Ledger Refused in a Synced Folder", translations: { es: "Registro de gastos rechazado en una carpeta sincronizada", fr: "Registre de dépenses refusé dans un dossier synchronisé", ko: "동기화 폴더에서 지출 원장 거부", "zh-CN": "同步文件夹中的支出账本被拒绝", "zh-TW": "同步資料夾中的支出帳本被拒絕", ru: "Отказ журнала расходов в синхронизируемой папке", ja: "同期フォルダーで支出台帳が拒否される", tr: "Eşitlenen Klasörde Harcama Defteri Reddi" }, slug: "troubleshooting/spend-ledger-synced-folder" }, ], }, - { label: "Contributing", translations: { fr: "Contribuer", ko: "기여하기", "zh-CN": "贡献", "zh-TW": "貢獻", ru: "Как внести вклад", ja: "コントリビュート", tr: "Katkıda Bulunma" }, slug: "contributing" }, + { label: "Contributing", translations: { es: "Cómo contribuir", fr: "Contribuer", ko: "기여하기", "zh-CN": "贡献", "zh-TW": "貢獻", ru: "Как внести вклад", ja: "コントリビュート", tr: "Katkıda Bulunma" }, slug: "contributing" }, ], }), // Runs after Starlight has written the site: refuses a build with a broken internal link. diff --git a/docs-site/src/components/FrontierBoards.astro b/docs-site/src/components/FrontierBoards.astro index 2cd29564cb6..db302f32cf8 100644 --- a/docs-site/src/components/FrontierBoards.astro +++ b/docs-site/src/components/FrontierBoards.astro @@ -10,7 +10,7 @@ import data from "../data/frontier-benchmarks.json"; import { FRONTIER_STRINGS } from "../data/frontier-i18n"; interface Props { - locale?: "en" | "fr" | "ko" | "zh-cn" | "zh-tw" | "ru" | "ja" | "tr"; + locale?: "en" | "fr" | "ko" | "zh-cn" | "zh-tw" | "ru" | "ja" | "tr" | "es"; /** Comma-separated board ids to render; omit for all boards. */ boards?: string; /** Show the page-level subtitle (overview pages only). */ @@ -26,7 +26,7 @@ const fill = (key: string, vars: Record): string => Object.entries(vars).reduce((acc, [k, v]) => acc.replace(`{${k}}`, v), t(key)); // The PR i18n has no column-header key for "score" — keep a tiny local map. -const SCORE_HEADER: Record = { en: "Score", fr: "Score", ko: "점수", "zh-cn": "得分", "zh-tw": "得分", ru: "Балл", ja: "スコア", tr: "Puan" }; +const SCORE_HEADER: Record = { es: "Puntuación", en: "Score", fr: "Score", ko: "점수", "zh-cn": "得分", "zh-tw": "得分", ru: "Балл", ja: "スコア", tr: "Puan" }; /** Dataset tags are kebab-case; i18n keys are camelCase (cheap-subagent → cheapSubagent). */ const tagKey = (tag: string): string => tag.replace(/-([a-z])/g, (_, c) => c.toUpperCase()); diff --git a/docs-site/src/components/Header.astro b/docs-site/src/components/Header.astro index 1e6c9e2d582..7d7dbef3385 100644 --- a/docs-site/src/components/Header.astro +++ b/docs-site/src/components/Header.astro @@ -55,8 +55,44 @@ const fr = { 'GitHub, {count} stars': 'GitHub, {count} étoiles', } as const; +const es: Record = { + "Auto": "Automático", + "Light": "Claro", + "Dark": "Oscuro", + "Theme": "Tema", + "Click to use the next theme": "Haz clic para cambiar al siguiente tema", + "Getting Started": "Primeros pasos", + "Installation": "Instalación", + "Quickstart": "Inicio rápido", + "How It Works": "Cómo funciona", + "Agent Quickstart": "Inicio rápido para agentes", + "Guides": "Guías", + "Providers": "Proveedores", + "Model Routing": "Enrutamiento de modelos", + "Combos": "Combos", + "Codex Integration": "Integración con Codex", + "Codex App Model Picker": "Selector de modelos de Codex App", + "Sidecars: Search & Vision": "Sidecars: búsqueda y visión", + "Image Bridge": "Puente de imágenes", + "Video Bridge": "Puente de video", + "Web Dashboard": "Dashboard web", + "Sub-agent Surface": "Interfaz de subagentes", + "Reference": "Referencia", + "Configuration": "Configuración", + "Adapters": "Adaptadores", + "Architecture": "Arquitectura", + "Proxy API Formats": "Formatos de API del proxy", + "Management API": "API de administración", + "Contributing": "Cómo contribuir", + "Main": "Navegación principal", + "Select language": "Elegir idioma", + "Menu": "Menú", + "GitHub": "GitHub", + "GitHub, {count} stars": "GitHub, {count} estrellas", +}; + const t = (en: K, ko: string, zh: string, ru: string, ja: string, zhTW: string, tr: string): string => - locale === 'fr' ? fr[en] : locale === 'ko' ? ko : locale === 'zh-cn' ? zh : locale === 'zh-tw' ? zhTW : locale === 'ru' ? ru : locale === 'ja' ? ja : locale === 'tr' ? tr : en; + locale === 'es' ? es[en] : locale === 'fr' ? fr[en] : locale === 'ko' ? ko : locale === 'zh-cn' ? zh : locale === 'zh-tw' ? zhTW : locale === 'ru' ? ru : locale === 'ja' ? ja : locale === 'tr' ? tr : en; const starCount = await getStarCount(); const starLocale = locale ?? 'en'; @@ -68,9 +104,10 @@ const starLabel = t( const githubAccessibleName = starCount === null ? githubLabel : starLabel.replace('{count}', starCount.toLocaleString(starLocale)); -type LanguageOption = { code: 'root' | 'fr' | 'ko' | 'zh-cn' | 'zh-tw' | 'ru' | 'ja' | 'tr'; label: string }; +type LanguageOption = { code: 'root' | 'fr' | 'ko' | 'zh-cn' | 'zh-tw' | 'ru' | 'ja' | 'tr' | 'es'; label: string }; const languages: LanguageOption[] = [ { code: 'root', label: 'English' }, + { code: 'es', label: 'Español' }, { code: 'fr', label: 'Français' }, { code: 'ko', label: '한국어' }, { code: 'zh-cn', label: '简体中文' }, diff --git a/docs-site/src/components/Landing.astro b/docs-site/src/components/Landing.astro index 8944272605e..509d9291972 100644 --- a/docs-site/src/components/Landing.astro +++ b/docs-site/src/components/Landing.astro @@ -24,7 +24,7 @@ import SiteJsonLd from './SiteJsonLd.astro'; import { GITHUB_URL, getStarCount, formatStarCount } from '../data/github-stars'; interface Props { - locale?: 'fr' | 'ko' | 'zh-cn' | 'zh-tw' | 'ru' | 'ja' | 'tr'; + locale?: 'fr' | 'ko' | 'zh-cn' | 'zh-tw' | 'ru' | 'ja' | 'tr' | 'es'; } const { locale } = Astro.props; @@ -118,8 +118,95 @@ const fr = { 'Star on GitHub, {count} stars': 'Ajouter une étoile sur GitHub, {count} étoiles', } as const; +const es: Record = { + "Install": "Instalar", + "Start the proxy": "Iniciar el proxy", + "Inject a provider into Codex": "Inyectar un proveedor en Codex", + "Codex now routes through ocx": "Codex ahora se conecta a través de ocx", + "Getting Started": "Primeros pasos", + "Installation": "Instalación", + "Quickstart": "Inicio rápido", + "How It Works": "Cómo funciona", + "Agent Quickstart": "Inicio rápido para agentes", + "Guides": "Guías", + "Providers": "Proveedores", + "Model Routing": "Enrutamiento de modelos", + "Combos": "Combos", + "Codex Integration": "Integración con Codex", + "Codex App Model Picker": "Selector de modelos de Codex App", + "Sidecars: Search & Vision": "Sidecars: búsqueda y visión", + "Image Bridge": "Puente de imágenes", + "Video Bridge": "Puente de video", + "Web Dashboard": "Dashboard web", + "Sub-agent Surface": "Interfaz de subagentes", + "Reference": "Referencia", + "Configuration": "Configuración", + "Adapters": "Adaptadores", + "Architecture": "Arquitectura", + "Proxy API Formats": "Formatos de API del proxy", + "Management API": "API de administración", + "Project": "Proyecto", + "Contributing": "Cómo contribuir", + "Run ": "Ejecuta ", + " on any LLM.": " con cualquier LLM.", + "opencodex is a local proxy that serves Codex and Claude Code from one port — translating each wire format to any provider, with streaming, tool calls, reasoning, and images in both directions. Zero client patches.": "opencodex es un proxy local para Codex y Claude Code que usa un solo puerto. Convierte cada formato de protocolo para cualquier proveedor, con streaming, llamadas a herramientas, razonamiento e imágenes en ambas direcciones. No requiere parches en los clientes.", + "Get Started": "Comenzar", + "Supported providers": "Proveedores compatibles", + "40+ providers": "Más de 40 proveedores", + "The opencodex dashboard — live proxy status, routed providers, and available models": "Dashboard de opencodex: estado del proxy en tiempo real, proveedores enrutados y modelos disponibles", + "Install. Start. Codex, rerouted.": "Instala. Inicia. Codex, con otro proveedor.", + "Install.": "Instala.", + "Start.": "Inicia.", + "Codex, rerouted.": "Codex, con otro proveedor.", + "Full quickstart": "Inicio rápido completo", + "Watch Codex run on a routed model.": "Mira cómo Codex ejecuta un modelo enrutado.", + "Codex App running a task on a routed non-OpenAI model": "Codex App ejecuta una tarea con un modelo enrutado de otro proveedor distinto de OpenAI", + "One task, streamed end to end through opencodex.": "Una tarea, transmitida de extremo a extremo a través de opencodex.", + "One proxy, the whole surface.": "Un proxy para todas las funciones.", + "Any provider": "Cualquier proveedor", + "Five adapters cover Anthropic Messages, Google Gemini, Azure, the OpenAI Responses passthrough, and every OpenAI-compatible Chat Completions endpoint — 40+ built-in providers.": "Cinco adaptadores cubren Anthropic Messages, Google Gemini, Azure, el paso directo de OpenAI Responses y cualquier endpoint de Chat Completions compatible con OpenAI. Más de 40 proveedores integrados.", + "OAuth or API key": "OAuth o clave API", + "Log in with your xAI, Anthropic, or Kimi account — auto-refreshed — forward your ChatGPT login, or paste a key.": "Inicia sesión con tu cuenta de xAI, Anthropic o Kimi, con renovación automática; reenvía tu sesión de ChatGPT o pega una clave API.", + "ChatGPT account pool": "Grupo de cuentas ChatGPT", + "Existing threads keep their account; new sessions auto-route to the lowest-usage healthy one after quota refresh.": "Los hilos existentes conservan su cuenta. Tras actualizar las cuotas, las sesiones nuevas se asignan automáticamente a la cuenta disponible con menor uso.", + "Native in the model picker": "Nativo en el selector de modelos", + "Routed models show up in Codex App with reasoning effort levels, next to the native ones.": "Los modelos enrutados aparecen en la aplicación Codex con niveles de esfuerzo de razonamiento, junto a los nativos.", + "Codex App model picker with reasoning effort levels": "Selector de modelos de Codex App con niveles de esfuerzo de razonamiento", + "Sub-agents": "Subagentes", + "Pin up to five routed or native models for Codex spawn_agent, and switch the v1 / base / v2 surface globally.": "Fija hasta cinco modelos enrutados o nativos para spawn_agent de Codex y cambia globalmente entre las interfaces v1, base y v2.", + "ocx claude launches Claude Code against the same port — every routed model in the /model picker, auto-context up to 1M, roster sub-agents, and your claude.ai login stays active.": "ocx claude inicia Claude Code en el mismo puerto: todos los modelos enrutados aparecen en /model, con contexto automático de hasta 1M y subagentes del listado. Tu sesión de claude.ai permanece activa.", + "Claude Code running a routed model through opencodex — gpt-5.6-luna-medium active in the status bar": "Claude Code ejecutando un modelo enrutado a través de opencodex — gpt-5.6-luna-medium activo en la barra de estado", + "Search & vision sidecars": "Sidecars de búsqueda y visión", + "Give non-OpenAI models real web search and image understanding through a gpt-5.6-luna sidecar.": "Añade búsqueda web y comprensión de imágenes a los modelos de otros proveedores mediante un sidecar gpt-5.6-luna.", + "ocx init writes a provider into your Codex config and shares one model catalog with Codex CLI, TUI, App, and SDK. ocx stop restores native Codex cleanly.": "ocx init escribe un proveedor en tu configuración de Codex y comparte el catálogo con Codex CLI, TUI, App y SDK. ocx stop detiene el proxy o su servicio administrado y restaura la configuración nativa de Codex.", + "Documentation map": "Mapa de la documentación", + "Explore the docs": "Explorar la documentación", + "opencodex is an independent community project, not affiliated with or endorsed by OpenAI, Anthropic, or any other provider. Some providers may restrict accounts that route traffic through third-party proxies — review each provider’s Terms of Service before connecting.": "opencodex es un proyecto comunitario independiente, sin afiliación ni respaldo de OpenAI, Anthropic u otros proveedores. Algunos proveedores pueden restringir las cuentas que enrutan tráfico a través de proxies de terceros. Revisa los términos de servicio de cada proveedor antes de conectarte.", + "Desktop beta": "Desktop beta", + "Other platforms": "Otras plataformas", + "Download": "Descargar", + "Download for macOS": "Descargar para macOS", + "Download for Windows": "Descargar para Windows", + "Download for Linux": "Descargar para Linux", + "Download OpenCodex": "Descargar OpenCodex", + "The desktop app bundles the proxy, the dashboard and a tray. Beta.": "La aplicación de escritorio incluye el proxy, el dashboard y una bandeja. Versión beta.", + "Universal · Apple Silicon and Intel · macOS 13+ · .dmg": "Universal · Apple Silicon e Intel · macOS 13+ · .dmg", + "Installer not code-signed yet": "El instalador aún no tiene firma de código", + ".deb package": "Paquete .deb", + "Recommended for your system": "Recomendado para tu sistema", + "Prefer the terminal?": "¿Prefieres la terminal?", + "Installation guide": "Guía de instalación", + "All releases and checksums": "Todas las versiones y sumas de comprobación", + "Desktop app guide": "Guía de la aplicación de escritorio", + "Code signing policy": "Política de firma de código", + "Desktop App": "Aplicación de escritorio", + "Latest release": "La última versión", + "Star on GitHub": "Dar una estrella en GitHub", + "Star on GitHub, {count} stars": "Dar una estrella en GitHub, {count} estrellas", +}; + const t = (en: K, ko: string, zh: string, ru: string, ja: string, zhTW: string, tr: string): string => - locale === 'fr' ? fr[en] : locale === 'ko' ? ko : locale === 'zh-cn' ? zh : locale === 'zh-tw' ? zhTW : locale === 'ru' ? ru : locale === 'ja' ? ja : locale === 'tr' ? tr : en; + locale === 'es' ? es[en] : locale === 'fr' ? fr[en] : locale === 'ko' ? ko : locale === 'zh-cn' ? zh : locale === 'zh-tw' ? zhTW : locale === 'ru' ? ru : locale === 'ja' ? ja : locale === 'tr' ? tr : en; const starCount = await getStarCount(); const starLocale = locale || 'en'; diff --git a/docs-site/src/components/SiteJsonLd.astro b/docs-site/src/components/SiteJsonLd.astro index 18e2403d9bd..a7ef60bbaab 100644 --- a/docs-site/src/components/SiteJsonLd.astro +++ b/docs-site/src/components/SiteJsonLd.astro @@ -11,17 +11,18 @@ const SITE_URL = 'https://opencodex.me'; interface Props { - locale?: 'fr' | 'ko' | 'zh-cn' | 'zh-tw' | 'ru' | 'ja' | 'tr'; + locale?: 'fr' | 'ko' | 'zh-cn' | 'zh-tw' | 'ru' | 'ja' | 'tr' | 'es'; } const { locale } = Astro.props; // Locale path segment (root/English has none) mapped to its BCP-47 tag. -const langs = { fr: 'fr', ko: 'ko', 'zh-cn': 'zh-CN', 'zh-tw': 'zh-TW', ru: 'ru', ja: 'ja', tr: 'tr' } as const; +const langs = { es: 'es', fr: 'fr', ko: 'ko', 'zh-cn': 'zh-CN', 'zh-tw': 'zh-TW', ru: 'ru', ja: 'ja', tr: 'tr' } as const; const homeUrl = locale ? `${SITE_URL}/${locale}/` : `${SITE_URL}/`; const inLanguage = locale ? langs[locale] : 'en'; const descriptions = { + es: "Proxy universal de proveedores para OpenAI Codex y Claude Code: usa cualquier LLM con Codex CLI, App, SDK y Claude Code.", en: 'Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI, App, SDK, and Claude Code.', fr: 'Proxy universel de fournisseurs pour OpenAI Codex et Claude Code — utilisez n’importe quel LLM avec Codex CLI, App, SDK et Claude Code.', ko: 'OpenAI Codex & Claude Code를 위한 범용 프로바이더 프록시 — Codex CLI, App, SDK와 Claude Code에서 어떤 LLM이든 사용하세요.', diff --git a/docs-site/src/content/docs/contributing.md b/docs-site/src/content/docs/contributing.md index 7fe0b09831b..3e51e117094 100644 --- a/docs-site/src/content/docs/contributing.md +++ b/docs-site/src/content/docs/contributing.md @@ -98,11 +98,14 @@ bun run build GitHub Actions intentionally stay small: -- **Cross-platform CI** (`.github/workflows/ci.yml`) runs on pull requests and `main` pushes that - touch runtime, tests, package, script, TypeScript, or workflow files. Its Bun matrix covers Linux, - Windows, and macOS with install, typecheck, tests, privacy scan, a release-helper build smoke, GUI - build, and `ocx help`. A second three-OS lane proves npm global install works without a separately - installed Bun by using the package's bundled runtime. +- **Cross-platform CI** (`.github/workflows/ci.yml`) runs the fast Ubuntu subset on pull requests. + Release-line pushes to `main`/`preview` and `workflow_dispatch` run the selected non-PR jobs, + subject to path filters and lane selection; pushes to `dev` do not run the full suite. + The full `platform-windows` test job runs only on the nightly schedule or through + `workflow_dispatch` with the default or `all` lane, not on release-line pushes. + The platform jobs cover install, typecheck, tests, privacy scan, a release-helper build smoke, + GUI build, and `ocx help`. A separate npm-global smoke matrix checks installation with the + package's bundled runtime; its Windows smoke is distinct from the full Windows test job. - **Release** (`.github/workflows/release.yml`) is manual. It does not act as a second full CI pipeline; before dry-run or publish it requires the exact release commit (`GITHUB_SHA`) to already have a successful Cross-platform CI run. @@ -161,9 +164,9 @@ description. - Target **`dev`**. Do not open feature or fix pull requests against **`main`**. - Branch from the current **`dev`** tip, not from **`main`**. The required **`enforce-target`** check rejects heads whose merge base sits on the **`main`** tip while the branch is far behind the pull request base (the failure mode seen in #644). -- Write a real description: a **Summary** of what changed and why, plus a **Test plan** (or equivalent substance). Empty bodies, placeholder-only text, and descriptions that use escaped `\n` instead of real line breaks fail the check. +- Complete the repository template's `Summary`, `Verification`, and `Checklist` sections: explain what changed and why, and document the test plan and results. Empty bodies, placeholder-only text, and descriptions that use escaped `\n` instead of real line breaks fail the check. - If the pull request changes files under `gui/`, include a screenshot of the UI change in the description; the `enforce-target` check re-runs on description edits until the screenshot is present. Drag the image into the description editor rather than committing it: an image on your branch rides the squash merge into `dev`. Maintainers uploading from the command line use the `pr-assets` branch and link by commit SHA. -- Workflow changes in this repository use **`pull_request_target`**. Updated enforcement logic applies only after the workflow is promoted to the repository default branch — the same operational caveat documented in #631. +- The trusted `enforce-target` and `label` workflows use **`pull_request_target`**, so their updated enforcement logic applies only after promotion to the repository default branch, as documented in #631. Cross-platform CI uses **`pull_request`**; its changes take effect on the pull request base branch. ## Project maintainers diff --git a/docs-site/src/content/docs/contributing/pr-quality.md b/docs-site/src/content/docs/contributing/pr-quality.md index bac390abde2..350157979bb 100644 --- a/docs-site/src/content/docs/contributing/pr-quality.md +++ b/docs-site/src/content/docs/contributing/pr-quality.md @@ -32,7 +32,7 @@ on your behalf. ## Automated gates -Three deterministic checks run before human review, and each failure message +Deterministic checks run before human review, and each failure message tells you exactly what to change: - **PR quality (`enforce-target`).** Pull requests must target `dev` and carry @@ -90,14 +90,13 @@ tells you exactly what to change: lockfile changed without its manifest each need an explicit approval label. A comment-only change to a source file is not a behavior change and owes no test. -- **Cross-platform CI.** The suite runs sharded on Linux and in full on macOS for - every pull request. Windows runs at the shipping boundary — on promotion to - `main` or `preview` — so a slow or flaky Windows runner cannot decide when your - pull request turns green. - This runs for **every** pull request, whatever its base branch — including a - stacked child whose base is another open PR's head. The `paths:` filter, not - the base branch, decides whether the jobs run at all: a PR touching only docs - or `devlog/` queues nothing. +- **Cross-platform CI.** Pull requests run the fast Ubuntu subset. Non-PR jobs run through + `workflow_dispatch` and on the release lines `main` and `preview`, subject to lane selection + and path filters. The full `platform-windows` test job runs only on the nightly schedule or + on `workflow_dispatch` with the default or `all` lane; a release-line push does not run it. + Do not add `dev` push runs or macOS/Windows pull-request platform jobs. The aggregate `ci` + check is created for every pull request; changed-path detection decides which expensive jobs + are needed, including for a stacked child whose base is another open PR's head. - **Type label.** The `label` check derives `bug` / `enhancement` / `documentation` / `chore` from your PR title. A title without a recognisable diff --git a/docs-site/src/content/docs/es/benchmarks/coding.mdx b/docs-site/src/content/docs/es/benchmarks/coding.mdx new file mode 100644 index 00000000000..803a63079da --- /dev/null +++ b/docs-site/src/content/docs/es/benchmarks/coding.mdx @@ -0,0 +1,8 @@ +--- +title: "Pruebas de programación" +description: "Instantáneas de DeepSWE, AA Coding Agent, FrontierCode, FrontierSWE, Program Bench y SWE Marathon." +--- + +import FrontierBoards from "../../../../components/FrontierBoards.astro"; + + diff --git a/docs-site/src/content/docs/es/benchmarks/frontend.mdx b/docs-site/src/content/docs/es/benchmarks/frontend.mdx new file mode 100644 index 00000000000..08a930ae54a --- /dev/null +++ b/docs-site/src/content/docs/es/benchmarks/frontend.mdx @@ -0,0 +1,8 @@ +--- +title: "Pruebas de frontend" +description: "Resultados públicos de Frontend Code Arena." +--- + +import FrontierBoards from "../../../../components/FrontierBoards.astro"; + + diff --git a/docs-site/src/content/docs/es/benchmarks/index.mdx b/docs-site/src/content/docs/es/benchmarks/index.mdx new file mode 100644 index 00000000000..29abb3d6bfe --- /dev/null +++ b/docs-site/src/content/docs/es/benchmarks/index.mdx @@ -0,0 +1,14 @@ +--- +title: "Pruebas comparativas" +description: "Instantáneas públicas de rendimiento de agentes, con fuentes y costos medidos por tarea cuando están disponibles." +--- + +Estas tablas son **instantáneas estáticas de clasificaciones públicas, actualizadas manualmente**. No son mediciones en vivo de OpenCodex. Cada panel indica la fuente, la fecha de captura y la licencia. Las clasificaciones de puntuación por dólar solo se muestran cuando la fuente aporta un costo medido por tarea para **todas las filas** del panel. + +Los paneles se agrupan por tarea: + +- [Programación](./coding/) — DeepSWE, AA Coding Agent, FrontierCode, FrontierSWE, Program Bench, SWE Marathon +- [Frontend](./frontend/) — Frontend Code Arena +- [Terminal](./terminal/) — Terminal Bench 2.1 +- [Seguridad](./security/) — Cybench +- [Inteligencia](./intelligence/) — AA Intelligence Index diff --git a/docs-site/src/content/docs/es/benchmarks/intelligence.mdx b/docs-site/src/content/docs/es/benchmarks/intelligence.mdx new file mode 100644 index 00000000000..74d5458c3f4 --- /dev/null +++ b/docs-site/src/content/docs/es/benchmarks/intelligence.mdx @@ -0,0 +1,8 @@ +--- +title: "Pruebas de inteligencia" +description: "Resultados públicos de AA Intelligence Index." +--- + +import FrontierBoards from "../../../../components/FrontierBoards.astro"; + + diff --git a/docs-site/src/content/docs/es/benchmarks/security.mdx b/docs-site/src/content/docs/es/benchmarks/security.mdx new file mode 100644 index 00000000000..a653daacb14 --- /dev/null +++ b/docs-site/src/content/docs/es/benchmarks/security.mdx @@ -0,0 +1,8 @@ +--- +title: "Pruebas de seguridad" +description: "Resultados públicos de Cybench." +--- + +import FrontierBoards from "../../../../components/FrontierBoards.astro"; + + diff --git a/docs-site/src/content/docs/es/benchmarks/terminal.mdx b/docs-site/src/content/docs/es/benchmarks/terminal.mdx new file mode 100644 index 00000000000..f9cd7911fd4 --- /dev/null +++ b/docs-site/src/content/docs/es/benchmarks/terminal.mdx @@ -0,0 +1,8 @@ +--- +title: "Pruebas de terminal" +description: "Resultados públicos de Terminal Bench 2.1." +--- + +import FrontierBoards from "../../../../components/FrontierBoards.astro"; + + diff --git a/docs-site/src/content/docs/es/contributing.md b/docs-site/src/content/docs/es/contributing.md new file mode 100644 index 00000000000..c53c775d142 --- /dev/null +++ b/docs-site/src/content/docs/es/contributing.md @@ -0,0 +1,191 @@ +--- +title: "Cómo contribuir" +description: "Desarrolla opencodex: entorno, estructura, convenciones y pasos para añadir proveedores o adaptadores." +--- + + + +## Preparar el entorno + +Para desarrollar desde el código fuente necesitas la CLI `bun` en `PATH`. El paquete npm publicado incluye su propio entorno de ejecución Bun; los scripts del paquete pueden usar esa dependencia incluida. + +```bash +git clone https://github.com/lidge-jun/opencodex.git +cd opencodex +bun install +bun run setup:hooks # retire the managed pre-push and post-merge hooks +bun run dev:proxy # proxy API in dev mode +bun run dev:gui # dashboard dev server (another terminal) +bun run typecheck # bun x tsc --noEmit +bun run test # full suite (default) +``` + +`bun run setup:hooks` elimina los hooks administrados y retirados `pre-push` y `post-merge` si no se han modificado; conserva los personalizados. Ya no se exige un hook de pre-push. `bun run prepush` sigue disponible como comprobación manual opcional. + +`bun run dev` es un alias de `bun run dev:proxy`. El servidor de desarrollo del dashboard se inicia con `bun run dev:gui`. El dashboard empaquetado que sirve `GET /` se genera con `bun run build:gui` en `gui/dist`. + +El antiguo hook `post-merge` reconstruía `gui/dist` tras cada merge. Ahora, si un merge cambia `gui/`, debes ejecutar `bun run build:gui` para actualizar el dashboard empaquetado. El servidor de desarrollo se reconstruye bajo demanda y no necesita ese paso. + + + +## Comandos de compilación y pruebas + +El paquete raíz usa TypeScript nativo de Bun, sin una compilación separada del servidor. Usa los scripts del repositorio para que los comandos locales coincidan con CI: + +```bash +bun run typecheck # strict TypeScript check +bun run test:changed # import-graph tests against the resolved dev merge base +bun run test # full suite (default) +bun test tests/routing/router.test.ts # focused test file +bun run build:gui # Vite GUI build + package preparation +bun run privacy:scan # credential/privacy scan used by CI +bun run prepare:package # refresh package launchers/assets +``` + +La suite usa Bun 1.4.3, declarado en `testRunnerBun` de `package.json`; el entorno de ejecución distribuido es 1.4.4. `scripts/test.ts` busca Bun 1.4.3 en PATH o `~/.bun/bin`, o utiliza `OCX_TEST_RUNNER_BUN`. Si falta esa versión, instálala localmente: el selector no la descarga. + +Ejecuta `bun run test` por defecto. Si la suite completa resulta desproporcionadamente costosa por el tamaño de la tarea, los recursos disponibles o la actividad de otros árboles de trabajo, ejecuta al menos las regresiones que prueben el comportamiento modificado, por ejemplo `bun test tests//.test.ts`. Explica el motivo, los comandos exactos, sus resultados y la cobertura pendiente. `bun run test:changed` complementa esa cobertura, pero no detecta todas las dependencias indirectas. Depender solo de CI o saltarse las pruebas locales no constituye una exención general. Antes del merge, los checks requeridos deben pasar para el commit actual del PR. + +`test:changed` usa la primera referencia de comparación disponible: `upstream/dev`, `origin/dev` o la rama local `dev`. Informa de esa referencia y del commit exacto obtenido con `git merge-base HEAD `, y pasa su SHA a Bun. + +Si se agota el plazo de una ejecución de pruebas, el runner muestra stdout y stderr ya capturados y termina con código 124. Tras finalizar un proceso, permite un segundo para vaciar sus tuberías, evitando que un descendiente las mantenga abiertas indefinidamente. La captura incompleta se informa y no cuenta como éxito, aunque el hijo directo haya terminado con código 0. + +Las pruebas de Bun se organizan por dominios que reflejan `src/`: `tests/server/`, `tests/providers/`, `tests/adapters/openai/`, `tests/cli/`, etc. El mapa es `scripts/test-layout/layout.json` y lo comprueba `tests/test-layout.test.ts`. Cada prueba nueva debe ir en su dominio y registrarse en el mapa; la prueba de herramientas indica qué entrada falta. `tests/helpers/` contiene fixtures compartidos y `tests/helpers/repo-root.ts` permite acceder a archivos del repositorio. `tests/e2e-style/` reúne escenarios más amplios de paridad nativa. Añade las regresiones junto a las pruebas del subsistema modificado; `bun test tests/` ejecuta un subsistema. + +Este sitio vive en `docs-site/` y usa Astro + Starlight: + +```bash +cd docs-site && bun install && bun dev +``` + + + +## Publicación de documentación + +La documentación pública se publica en GitHub Pages en . El workflow `.github/workflows/deploy-docs.yml` se ejecuta al subir a `main` cambios en `docs-site/**` o en el propio workflow; compila `docs-site` y publica el sitio generado. Antes de subir cambios de documentación, ejecuta: + +```bash +cd docs-site +bun install --frozen-lockfile +bun run build +``` + + + +## CI y versiones + +Los workflows de GitHub Actions mantienen separadas estas funciones: + +- **CI multiplataforma** (`.github/workflows/ci.yml`) ejecuta el subconjunto rápido de Ubuntu en los PR. Los pushes a `main`/`preview` y `workflow_dispatch` ejecutan los trabajos seleccionados que no son de PR, según los filtros de rutas y la selección de lane. Los pushes a `dev` no ejecutan la suite completa. El trabajo completo de pruebas `platform-windows` solo se ejecuta en el horario nocturno o mediante `workflow_dispatch` con la lane predeterminada o `all`, no al subir a las ramas de publicación. Los trabajos de plataforma cubren instalación, tipos, pruebas, privacidad, compilación de prueba del asistente de versiones, build de GUI y `ocx help`. Una matriz independiente de npm comprueba la instalación global con el Bun incluido; su prueba de instalación en Windows es distinta de la suite completa de Windows. +- **Release** (`.github/workflows/release.yml`) es manual. Antes de una simulación o publicación exige que el commit exacto de la versión (`GITHUB_SHA`) ya tenga una ejecución exitosa de CI multiplataforma; no repite toda esa validación. +- **Stale needs-info** (`.github/workflows/stale-needs-info.yml`) se ejecuta a diario en la rama predeterminada. Advierte tras 14 días sin actividad en una issue abierta con `needs-info` y la cierra como no prevista después de otros 7 días. Una actualización elimina la advertencia. Para conservar un trabajo abierto a largo plazo, retira `needs-info`, por ejemplo al pasarlo a `roadmap`. +- **Calidad de issues** (`.github/workflows/enforce-issue-quality.yml`) valida las plantillas de issues nuevas o editadas. Aplica etiquetas de tipo (`bug`, `enhancement`, `provider-compatibility`, `documentation`) y etiquetas de **área** a partir del formulario y de indicios del título y resumen: `provider`, `account-pool`, `catalog`, `gui`, `cli`, `proxy`, `platform`, `streaming`, `tools`, `install` y `service`. Las etiquetas de tipo y proceso se mantienen separadas: puedes filtrar por `bug` + `account-pool`. Usa el desplegable de área en lugar de inventar etiquetas por proveedor. El área Documentation no añade una segunda etiqueta: el formulario ya incluye `documentation`. Los mantenedores pueden volver a aplicar áreas a las issues abiertas mediante workflow_dispatch `backfill_open_areas` cuando el workflow esté en la rama predeterminada. + +Usa el asistente para preparar versiones. Primero elige la versión prevista y ejecuta `.github/workflows/dev-version-bump.yml` desde la rama predeterminada con `intended-version=` y `mode=pre-move`. Revisa y fusiona en `dev` el PR generado; después promueve a `main` o `preview` y ejecuta el asistente. Si `dev` ya supera la versión prevista, el workflow devuelve `changed=false` y no necesita un PR de incremento. La publicación sigue exigiendo CI exitoso para el commit exacto de la versión. + +```bash +bun run release # commits/pushes the bump; publish workflow is dry-run by default +bun run release --bump minor # derive the next patch, minor, or major version from tags and npm channels +bun run release --publish # publish after the CI-gated dry run is understood +bun run release:watch # watch the newest Release workflow run +``` + +`--bump patch|minor|major` permite elegir el incremento en lugar de indicar una versión explícita. Cuando una etiqueta preview abre un núcleo de versión superior, `--bump patch` rechaza continuar la línea estable anterior; la corrección debe publicarse en el núcleo de la preview abierta. + + + +## Ramas + +- `dev`: único destino de integración. Abre aquí tu PR. +- `main`: versiones, mediante promoción de `dev` controlada por los mantenedores. No es destino de PR de funcionalidades. +- `preview`: versiones preliminares. + +La línea `dev2-go` y su política de mantener dos implementaciones se retiraron. Su historial está disponible en modo de solo lectura en [lidge-jun/opencodex-go-archive](https://github.com/lidge-jun/opencodex-go-archive). TypeScript nativo de Bun en `dev` es la única línea de ejecución. + +Se aceptan PR que actualicen una rama mediante rebase. Indica en la descripción los commits originales que estás incorporando. + + + +## Pull requests + +- Usa **`dev`** como destino, tanto para funcionalidades como para correcciones; no uses **`main`**. +- Parte del commit actual de **`dev`**. El check **`enforce-target`** rechaza ramas cuya base de merge se encuentre en el extremo de **`main`** mientras estén muy por detrás de la base del PR, como ocurrió en #644. +- Completa la plantilla del repositorio: `Summary`, `Verification` y `Checklist`. Explica qué cambia y por qué y documenta el plan de pruebas y sus resultados. El check rechaza descripciones vacías, compuestas solo por marcadores o que usen `\n` literal en lugar de saltos de línea reales. +- Si cambias `gui/`, incluye una captura real de la interfaz en la descripción. `enforce-target` vuelve a comprobarla cuando se edita la descripción. Adjunta la imagen al editor; no la añadas a la rama del PR, porque el squash la incorporaría a `dev`. Para subirla por CLI se utiliza la rama `pr-assets` y un enlace fijado al SHA del commit. +- Los workflows de confianza `enforce-target` y `label` usan **`pull_request_target`**. Su lógica de control nueva solo entra en vigor al llegar a la rama predeterminada, como se documentó en #631. La CI multiplataforma usa **`pull_request`** y sus cambios se aplican desde la rama de destino del PR. + + + +## Mantenedores + +Los responsables, sus funciones y la política de revisión y merge se documentan en [`MAINTAINERS.md`](https://github.com/lidge-jun/opencodex/blob/main/MAINTAINERS.md). `.github/CODEOWNERS` declara la responsabilidad de revisión de las rutas del repositorio, incluidas las sensibles para la seguridad. + +Los PR de contribuyentes normalmente necesitan aprobación de un mantenedor. Un mantenedor actual con acceso `maintain` o `admin` puede integrar explícitamente un PR en `dev`, incluido uno propio, sin segunda aprobación. Debe registrar la decisión y la validación del commit exacto. Siguen vigentes CI, la revisión de seguridad y las objeciones pendientes de otros mantenedores. Esta excepción no cambia las reglas de `main`/`preview` ni permite pushes directos, force-pushes o eliminación. + + + +## Convenciones + +- **Módulos ES** (`import`/`export`), TypeScript y modo `strict`. Mantén en verde `bun x tsc --noEmit`. +- **Máximo aproximado de 500 líneas por archivo**: divide por responsabilidad, como los sidecars `web-search/` y `vision/`, con módulos pequeños tras un `index.ts`. +- **Errores asíncronos en los límites**: un sidecar no debe propagar una excepción a la ruta de la solicitud; debe degradarse mediante un marcador controlado. +- **Fuente de verdad de estructura**: los invariantes mantenidos viven en `structure/`, los flujos públicos en `docs-site/` y las notas de planificación e investigación en `devlog/`. +- **Conserva las exportaciones**: otros módulos pueden depender de ellas. + + + +## Añadir un proveedor al catálogo + +Los selectores y valores iniciales de proveedores se derivan del registro canónico (`src/providers/registry/entries-extended.ts`): + +```ts +{ + id: "my-provider", + label: "My Provider", + baseUrl: "https://api.example.com/v1", + adapter: "openai-chat", + authKind: "key", + dashboardUrl: "https://example.com/keys", + models: ["model-a", "model-b"], + defaultModel: "model-a", + noVisionModels: ["model-a"], // text-only models → vision sidecar describes images +}, +``` + +`src/providers/derive.ts` utiliza esa entrada en `ocx init`, `ocx provider`, los preajustes del dashboard, el inicio con clave API y la configuración inicial OAuth. `enrichProviderFromCatalog()` copia metadatos y clasificaciones de capacidades a la configuración guardada. La implementación del protocolo OAuth sigue en `src/oauth/`: los metadatos del registro por sí solos no implementan un flujo OAuth. + + + +### Evidencia para un preajuste canónico + +El registro determina a qué destino se envía la clave API del usuario. Un preajuste exige evidencia de fuentes primarias, además de código funcional. La descripción del PR que añada o promueva un proveedor debe incluir: + +- **Endpoints compatibles con OpenAI documentados por el proveedor**: la referencia de chat y, con `liveModels: true`, la del descubrimiento autenticado de modelos, normalmente `GET /v1/models`. Una prueba con fixtures valida nuestro código, pero no sustituye la evidencia del contrato del proveedor. +- **Términos de servicio y entidad legal operadora**: una página legal vacía no identifica quién opera el endpoint ni cómo trata el tráfico del usuario. +- **Autorización de reventa o enrutamiento para agregadores**: una pasarela que vende acceso a Claude, GPT, Gemini u otros modelos debe demostrar su autorización. Un preajuste integrado se presenta como una ruta mantenida. +- **Responsable de mantenimiento identificado**: quién actualiza el preajuste ante cambios de URL, autenticación o catálogo, y cómo se informan las incidencias. +- **Fecha de verificación citable**: registra la fuente primaria y la fecha comprobada, como hace `lastVerified` en `src/providers/free-directory.ts`. No atribuyas una verificación que no se realizó. + +Puedes proponer tu propio servicio; varios preajustes surgieron así. Declara la afiliación en la descripción para que los revisores la valoren. La afiliación no justifica un rechazo ni reduce la evidencia exigida. + +Si la evidencia está incompleta, añade una referencia en `src/providers/free-directory.ts`, en lugar de promoverla al registro canónico. Las filas indican su grado de `verification` (`official`, `primary`, `unverified`) y son referencias inertes: el usuario puede configurar el servicio mediante el flujo personalizado compatible con OpenAI, sin que opencodex lo presente como proveedor mantenido o recomendado. Promueve la fila solo cuando exista toda la evidencia anterior. + + + +## Añadir un adaptador + +Implementa `ProviderAdapter` en `src/adapters/`, siguiendo [Adaptadores](/es/reference/adapters/), registra su fábrica en `src/adapters/registry.ts` y convierte la salida a eventos internos `AdapterEvent`. `src/server/adapter-resolve.ts` elige el protocolo efectivo antes de delegar al registro. Reutiliza `image.ts` para imágenes y sigue `openai-chat.ts` para streaming y llamadas a herramientas normales. Usa `fetchResponse` solo si el adaptador controla los reintentos del transporte, o `runTurn` para un transporte bidireccional como Cursor. Añade pruebas enfocadas en `tests/` y exporta la fábrica desde `src/index.ts` si forma parte de la API pública del paquete. + + + +### Declarar compatibilidad + +Las declaraciones de compatibilidad viven en `src/compatibility/` y son más específicas que un adaptador: identifican el proveedor, la URL base normalizada, la autenticación, los protocolos de entrada y salida y los modelos cuyo comportamiento se probó. No extiendas una declaración a otros proveedores o destinos solo porque compartan adaptador o formato. + +Usa una de las disposiciones versionadas: `passthrough`, `translated`, `degraded` o `unsupported`. Cada declaración distinta de paso directo debe explicar su limitación. Si se basa en fixtures, cita los identificadores exactos de las aserciones que la prueban. Añade el vector de solicitud sin secretos en `tests/fixtures/compatibility/` y ejecútalo contra el adaptador de producción en una prueba enfocada. Una declaración `passthrough` solo puede citar aserciones `equals` cuyo valor esperado sea el valor original del cliente, en la misma ubicación y con un selector vinculado a esa capacidad en la prueba del manifiesto. Un campo eliminado, reescrito o ajeno a esa capacidad no demuestra ausencia de pérdidas. Separa aspectos relacionados si una ruta puede conservar uno y perder otro, como una herramienta personalizada y su gramática. Los manifiestos son datos pasivos: el router, el controlador Responses y el arranque del servidor no deben importar su catálogo ni activar Compatibility Lab. + + + +## Verificar antes de dar el trabajo por terminado + +Sigue la política de pruebas anterior. Ejecuta `bun run typecheck` para cambios de tipos y los checks exigidos por la superficie afectada. Informa de comandos, resultados y cobertura pendiente; afirma únicamente las validaciones completadas. diff --git a/docs-site/src/content/docs/es/contributing/pr-quality.md b/docs-site/src/content/docs/es/contributing/pr-quality.md new file mode 100644 index 00000000000..91707ef9ef7 --- /dev/null +++ b/docs-site/src/content/docs/es/contributing/pr-quality.md @@ -0,0 +1,62 @@ +--- +title: "Requisitos de calidad de los pull requests" +description: "Preparación para revisión, responsabilidad del contribuidor, permisos y política de cierre de los PR de OpenCodex." +--- + + + +## No necesitas permiso para corregir un problema + +Los PR no planificados que corrigen un problema que hayas encontrado son bienvenidos. Varias mejoras del proyecto llegaron así: un modelo enrutado bloqueado tras llamar herramientas, un proveedor que recibía parámetros de modelo incorrectos o imágenes que se convertían en texto dentro de los resultados de herramientas. Ninguna empezó con una conversación de planificación; exigirla habría impedido esas aportaciones. + +Abrir primero una issue ayuda en trabajos grandes o de diseño, porque acordar el enfoque evita construir algo equivocado. Es una recomendación, no un requisito de admisión. + + + +## Qué afirmas al marcar un PR como listo + +Marcar un PR como listo para revisión significa que el cambio está completo, se comprende y se ha probado. Abrirlo no transfiere la responsabilidad de la rama a los mantenedores. + +Debes entender cada línea modificada, indicar los comandos exactos y sus resultados para respaldar las afirmaciones de validación, añadir pruebas de regresión específicas para cambios de comportamiento y estar disponible para resolver los comentarios de CI y de revisión. Los mantenedores identifican problemas; no se espera que reparen las ramas de los contribuidores, escriban las pruebas faltantes o conviertan los hallazgos automáticos en parches por ti. + +Decir «probado» o «CI pasa» sin comandos ni resultados concretos no es evidencia. + + + +## Comprobaciones automáticas + +Antes de la revisión humana se ejecutan controles deterministas; cada mensaje de error indica qué corregir: + +- **Calidad del PR (`enforce-target`).** El destino debe ser `dev` y la descripción debe explicar el cambio mediante **Summary** y **Test plan**, o contenido equivalente. Si se modifican archivos de `gui/`, o GitHub devuelve una lista incompleta para un cambio grande, la descripción debe incluir una captura de la interfaz. El control mantiene el PR en borrador y comenta hasta que exista la captura. Las listas incompletas se tratan como cambios de GUI por precaución. Un mantenedor puede eximir una modificación de `gui/` o un falso positivo añadiendo `gui-screenshot-waived`; añadir o quitar esa etiqueta vuelve a evaluar el control de inmediato. Los comentarios antiguos de mantenedores, como «no gui changes», siguen reconociéndose por compatibilidad en el siguiente evento del PR, pero el comentario por sí solo ya no activa el control privilegiado. Un contribuidor no puede concederse esa exención. + Los PR de contribuidores sin permiso de escritura se abren en borrador y permanecen así hasta completar las cuatro casillas de preparación: validación local requerida superada con el alcance documentado, rama actualizada con `dev`, hallazgos correctos de Codex y CodeRabbit resueltos y confirmación de que el PR está listo. Al completar todas, el control lo marca como listo y notifica a los mantenedores de `MAINTAINERS.md`, salvo al autor. El estado y las acciones necesarias aparecen en un único comentario del bot que se actualiza en cada ejecución. La confirmación corresponde al commit exacto de la rama: un nuevo push devuelve el PR a borrador, restablece las casillas y la notificación y pide volver a validar ese código. Cambiar el destino a `dev` borra el aviso de rama incorrecta; el PR permanece en borrador hasta completar las casillas. + Antes de aceptar la confirmación, el control comprueba lo verificable: la rama debe incluir el último commit de `dev` o estar como máximo 10 commits por detrás; además, deben estar resueltos los hilos de Codex y CodeRabbit creados por bots de revisión en el commit actual. Los hilos de otros autores no bloquean. La casilla local sigue la [política de alcance de pruebas](/es/contributing/#build-and-test-commands): ejecutar la suite completa de forma predeterminada o, si resulta demasiado costosa, ejecutar las regresiones específicas y documentar la excepción. Esa casilla es una declaración del autor: los contribuidores de forks no pueden iniciar la CI del repositorio y necesitan a un mantenedor. El control no puede verificar esa declaración; un nuevo push igualmente restablece todas las casillas. Los hallazgos de CodeRabbit fuera del diff que solo aparecen en el cuerpo de la revisión actual se suman al recuento pendiente mientras quede abierto un hilo del bot; resolver todos sus hilos libera esa casilla. Una afirmación refutada desmarca la casilla correspondiente y mantiene el borrador. Con la lista completa y los controles en verde, se añade `review-ready` como indicador visible. + Editar el comentario de estado de CodeRabbit no activa el control. Un estado de commit `CodeRabbit` correcto lo activa mediante el evento `status` de la rama predeterminada de confianza. El control asocia el SHA con un único PR abierto cuya rama siga apuntando a él; después vuelve a consultar los hilos y los cuerpos de revisión antes de cambiar las casillas, las etiquetas, el comentario o el estado de borrador. Se ignoran las asociaciones ambiguas o antiguas y nunca se ejecuta código de la rama del PR con el token de escritura del control. +- **Higiene.** Los cambios de comportamiento necesitan una prueba. Añadir supresiones de lint o tipos, pruebas exclusivas u omitidas, bloques catch vacíos, cambios manuales a archivos generados o un lockfile modificado sin su manifiesto requiere una etiqueta de aprobación explícita. Un cambio de comentarios en código fuente no altera el comportamiento ni requiere una prueba. +- **CI multiplataforma.** Los PR ejecutan el subconjunto rápido de Ubuntu. Los trabajos que no son de PR se ejecutan mediante `workflow_dispatch` y en las ramas de publicación `main` y `preview`, según la lane elegida y los filtros de rutas. El trabajo completo de pruebas `platform-windows` solo se ejecuta en el horario nocturno o mediante `workflow_dispatch` con la lane predeterminada o `all`; un push a las ramas de publicación no lo activa. No se añaden ejecuciones por push a `dev` ni trabajos de plataforma macOS o Windows por PR. La comprobación agregada `ci` se crea para cada PR; la detección de rutas decide qué trabajos costosos hacen falta, también en PR hijos cuya base sea la rama de otro PR abierto. +- **Etiqueta de tipo.** La comprobación `label` deriva `bug`, `enhancement`, `documentation` o `chore` del título. Si no reconoce el prefijo (por ejemplo, `stack 3/5: …`), usa los commits. Los de la familia `chore` (`test:`, `ci:`, `refactor:`) no prevalecen sobre `fix:` o `feat:`. Si el PR mezcla tipos, se deja sin etiqueta en vez de adivinar; nunca se sobrescribe una etiqueta puesta por una persona. + +CodeRabbit revisa los PR y sus hallazgos son recomendaciones. Corrige los válidos y explica por qué descartas los incorrectos. Sus hallazgos, por sí solos, no bloquean la integración. + + + +### Cuándo entra en vigor un cambio de automatización + +`enforce-target` y `label` usan la automatización de confianza de la rama predeterminada. El control del PR se ejecuta en `pull_request_target` y en los eventos `status` de CodeRabbit, cargados desde esa rama. Por tanto, el comportamiento con permiso de escritura solo cambia al promocionar la revisión del control a `main`. La CI multiplataforma se ejecuta en `pull_request` y sus cambios surten efecto cuando llegan a la rama de destino. + + + +## Áreas que necesitan el respaldo de un mantenedor + +Los cambios de autenticación, credenciales, flujos de GitHub Actions, automatización de versiones e instalación de dependencias requieren que un mantenedor los respalde (`maintainer-sponsored`) antes de integrarlos. Una integración defectuosa en esas áreas es costosa y difícil de revertir; por eso tienen ese requisito específico. Las demás áreas están abiertas a contribuciones. + + + +## Cuándo se cierra un PR + +Un PR estancado con comentarios de revisión pendientes puede cerrarse, indicando claramente el motivo. El cierre no es un juicio sobre el contribuidor: puedes reabrirlo cuando resuelvas el motivo o sustituirlo por otro limpio. Pide una explicación si el motivo no está claro. + + + +## Actualizar una lista de preparación antigua + +Si el control detecta la redacción retirada de CI local, conserva tu descripción y pide actualizar la primera casilla. Usa la redacción del aviso del bot, desmarca las cuatro casillas y guarda. Espera a que el bot reconozca la lista sin marcar, valida el commit mostrado y después vuelve a marcar las cuatro y guarda. Cambiar solo el texto dejando las casillas marcadas no cuenta como una declaración nueva. Un push o un cambio de destino invalida ese punto de control. El control sigue en rojo y el PR en borrador hasta completar la secuencia y las verificaciones habituales. Si guardas en el mismo instante que el punto de control, vuelve a editar el cuerpo y guárdalo más tarde; editar solo el título no cuenta. diff --git a/docs-site/src/content/docs/es/getting-started/for-agents.md b/docs-site/src/content/docs/es/getting-started/for-agents.md new file mode 100644 index 00000000000..a1f96a1ba24 --- /dev/null +++ b/docs-site/src/content/docs/es/getting-started/for-agents.md @@ -0,0 +1,154 @@ +--- +title: "Inicio rápido para agentes" +description: "Instale y opere opencodex desde un terminal controlado por un agente o un script, respetando los límites del consentimiento del usuario." +--- + +Esta página está dirigida a agentes de IA y usuarios que automatizan tareas desde un +terminal. Explica los comandos, sus códigos de salida y el límite entre la automatización +y las acciones que requieren consentimiento del usuario. Para un recorrido guiado por +una persona, consulte [Inicio rápido](/es/getting-started/quickstart/). El panel sigue +disponible para la configuración interactiva; consulte +[Panel web](/es/guides/web-dashboard/). + + + +## Configurar opencodex + +Instale el paquete publicado y compruebe que `ocx` está en `PATH`: + +```bash +npm install -g @bitkyc08/opencodex +ocx --version +``` + +Elija una forma de ejecutar el proxy: + +```bash +# Foreground: blocks this terminal until stopped. +ocx start + +# Background: installs or updates the service, then starts it. +ocx service +``` + +Ejecute `ocx init` en un terminal interactivo. Si `ocx start` está ocupando +el primer plano, use un segundo terminal: + +```bash +ocx init +``` + +El asistente crea `$OPENCODEX_HOME/config.json`, normalmente +`~/.opencodex/config.json`, solo si no existe. Volver a ejecutar init conserva +la configuración existente; no hay una opción de forzado o sobrescritura. +Si la configuración no es válida o se crea al mismo tiempo desde otro proceso, +se conserva y la preparación se detiene. El asistente también puede añadir la +dirección del proxy al `config.toml` de Codex e instalar el shim opcional de +inicio automático. `ocx init` nunca inicia el proxy. Para una preparación +totalmente no interactiva, configure los proveedores mediante `ocx provider add` +como se muestra más abajo. + +:::caution[Consentimiento para dar una estrella en GitHub] +Si es un agente, nunca responda a la solicitud de dar una estrella ni ejecute `gh`, +la API de estrellas de GitHub o `POST /api/github/star` en nombre del usuario. +Dar una estrella usa la identidad del usuario y requiere un consentimiento explícito +independiente. En una ejecución controlada por un agente, la CLI suprime la pregunta +y no escribe `.star-prompted`; la API de gestión devuelve +`403 agent_consent_required`. No eluda ninguna de esas protecciones. + +Cuando el arranque imprima la solicitud, preséntela una sola vez como una elección +Sí/No que el usuario debe responder: `Star lidge-jun/opencodex? Yes / No`. +Debe aparecer cerca del inicio de la respuesta inmediatamente posterior al arranque, +no como una sugerencia informal ni al final de un mensaje largo. +Una pregunta sin respuesta queda pendiente: el silencio nunca equivale a Sí ni +a un No registrado. No repita la pregunta en respuestas posteriores. La CLI vuelve +a habilitar el aplazamiento como máximo una vez por versión de opencodex, y una +versión posterior volverá a preguntar por su cuenta. Dé la estrella solo después +de un Sí explícito. Un No explícito resuelve la decisión de forma permanente y +no se vuelve a plantear. +::: + + + +## Comprobar una instalación sin interfaz gráfica + +Use estas comprobaciones de solo lectura en scripts y ejecuciones de agentes: + +```bash +ocx status +ocx doctor +ocx health --json +``` + +`ocx status` informa del estado del proxy y del servicio. `ocx doctor` +diagnostica el entorno local, la red, el entorno de ejecución de Codex y el estado +de las cuentas. `ocx health` termina con el código `0` si el proxy está en buen +estado y con `1` en caso contrario; `--json` devuelve una salida estructurada. + +Los comandos que usan la API de gestión, como `ocx combo set`, se comunican +con el proxy en ejecución. Si no se encuentra un proxy activo o la API no está +accesible, la CLI lo trata como un fallo `503` y termina con un código distinto +de cero. Inicie el proxy en primer plano o el servicio en segundo plano antes +de reintentar. Consulte la [referencia de CLI](/es/reference/cli/) y la +[API de gestión](/es/reference/management-api/) para ver todos los comandos +y endpoints. + + + +## Añadir proveedores y combos sin el panel + +Los proveedores del registro se pueden añadir por su nombre. Por ejemplo, +este comando añade el preajuste de Anthropic con clave API y lo convierte +en el proveedor predeterminado: + +```bash +ocx provider add anthropic-apikey \ + --api-key "$ANTHROPIC_API_KEY" \ + --set-default +``` + +`ocx provider add` escribe la configuración local. Añada `--sync` si ya hay +un proxy en ejecución y quiere sincronizar los modelos con Codex de inmediato; +en caso contrario, ejecute `ocx sync` más tarde. Los proveedores personalizados +que no figuren en el registro requieren tanto `--adapter` como `--base-url`. + +Cuando todos los proveedores de destino estén configurados y el proxy esté +en ejecución, cree un combo con conmutación por error: + +```bash +ocx combo set main \ + --targets anthropic/claude-opus-4-8,openai/gpt-5.6-sol \ + --strategy failover +``` + +Los destinos usan la sintaxis `provider/model` y se separan con comas. +El modelo virtual resultante es `combo/main`. Consulte +[Combos](/es/guides/combos/) para conocer las estrategias, los pesos, la +afinidad de enrutamiento y el comportamiento ante fallos. + + + +## Escucha remota y en la red local + +Las rutas normales de modelos en loopback no requieren un token de datos. +Escuchar fuera de loopback, por ejemplo en `0.0.0.0`, requiere una credencial +de admisión de datos. Se resuelve desde `OPENCODEX_API_AUTH_TOKEN`, +`OCX_API_TOKEN_FILE` o el archivo privado `service-api-token`, accesible +solo para su propietario. `ocx service install` puede crear ese archivo +si no existe. Si utiliza un token mediante una variable de entorno, defínala +antes de ejecutar `ocx start` u `ocx service install`: + +```bash +export OPENCODEX_API_AUTH_TOKEN="your-secret-token" +ocx service install +``` + +Las solicitudes de modelos utilizan la autenticación del plano de datos. +La administración usa una credencial independiente: +`OPENCODEX_ADMIN_AUTH_TOKEN` o el token administrativo generado en un archivo +con permisos protegidos. Un token de datos no concede acceso administrativo. +El panel sigue las reglas de sesión y acceso de la +[API de gestión](/es/reference/management-api/#authentication-model). +Nunca entregue el token administrativo a un cliente de modelos. +Consulte [Acceso remoto](/es/reference/configuration/server/#remote-access) +antes de exponer el proxy fuera del equipo local. diff --git a/docs-site/src/content/docs/es/getting-started/how-it-works.mdx b/docs-site/src/content/docs/es/getting-started/how-it-works.mdx new file mode 100644 index 00000000000..af5a835f237 --- /dev/null +++ b/docs-site/src/content/docs/es/getting-started/how-it-works.mdx @@ -0,0 +1,75 @@ +--- +title: "Cómo funciona" +description: "El ciclo de vida completo de la solicitud opencodex — analiza, enruta, adapta, puente y flujo." +--- + +import { Steps } from '@astrojs/starlight/components'; + +Codex habla el OpenAI **Responses API**. opencodex acepta `POST /v1/responses` sobre HTTP con Eventos enviados por servidor, además de una actualización opt-in WebSocket en la misma ruta. Traduce la solicitud al formato de cable de su proveedor y la respuesta a Responses eventos, por lo que Codex nunca sabe que no está hablando con OpenAI. + +``` + ┌──────────────────────────── opencodex ────────────────────────────┐ + │ │ + Codex ──▶ │ parser ──▶ router ──▶ [vision] ──▶ adapter ──▶ provider │ ──▶ Codex + (/v1/ │ │ │ │ │ │ │ (SSE / WS) + responses)│ OcxParsed provider describe buildRequest parseStream │ + │ Request +adapter images + fetch AdapterEvent[] │ + │ │ │ │ + │ [web-search loop] bridge ─▶ SSE │ + └─────────────────────────────────────────────────────────────────────┘ +``` + +![Enrutamiento multicuenta de Codex: los hilos existentes conservan la cuenta de ChatGPT y las sesiones nuevas pueden actualizar la cuota y elegir una cuenta disponible con menor uso.](../../../../assets/multi-auth-routing.svg) + + + +## Codex selección de cuenta de autenticación + +Cuando el proveedor seleccionado es el passthrough ChatGPT / Codex, opencodex puede elegir una cuenta de grupo almacenada antes de que la solicitud se reenvíe aguas arriba. La regla se divide intencionalmente: + +- **Los identificadores de hilo existentes mantienen la afinidad.** Un subproceso está vinculado a la generación de cuenta que lo inició, por lo que una sesión larga de SSH, tmux o móvil Codex sigue usando una cuenta en lugar de reequilibrarse a mitad de la conversación. +- **Las sesiones nuevas pueden reequilibrarse.** Para un nuevo hilo, opencodex selecciona entre las cuentas elegibles usando `accountPoolStrategy` (`quota` por defecto, o `round-robin` / `fill-first`). La estrategia `quota` compara el uso conocido a través de las ventanas 5h, semanal y 30d y puede cambiar a una cuenta de menor uso cuando la cuenta activa cruza `autoSwitchThreshold`. Las cuentas en tiempo de reutilización o que necesitan una nueva autenticación se omiten independientemente de la estrategia. +- **Señales de cuota y fallo de alimentación de enrutamiento.** El panel de control puede forzar una actualización de cuota con `GET /api/codex-auth/accounts?refresh=1`; las respuestas ascendentes exitosas capturan encabezados de cuota, 429 ponen una cuenta en tiempo de reutilización y 401/403 la marca para su reautenticación. +- **Las ventanas que ruedan ociosas se pueden activar a tiempo.** En **Configuración avanzada**, un control de activación automática por defecto cambia las ventanas de 5 horas y semanales compatibles para todas las cuentas principales y agregadas actuales juntas. Las configuraciones mixtas se muestran explícitamente; habilitar solo se aplica a las ventanas reportadas y deshabilitar también borra las ventanas obsoletas habilitadas. Los cambios usan escrituras de configuración individual: se muestra un fallo parcial después de leer de nuevo el estado guardado, y **Reintentar** completa la acción de activación o desactivación original. Las cuentas recién agregadas no se aceptan automáticamente. En el modo Pool, en el reinicio, opencodex reutiliza su solicitud de calentamiento de cuenta mínima no almacenada a través de la cuenta exacta cuya ventana vence, une las ventanas simultáneas en una solicitud y persiste de manera duradera ambas marcas de tiempo de reinicio para evitar el trabajo duplicado después de los reinicios. Se saltan las cuentas pausadas y las cuentas que requieren reautenticación. La activación captura encabezados de cuota de respuesta exitosos; los tiempos de reinicio conocidos se comprueban localmente cada minuto sin consultas de cuota periódicas, incluso cuando el uso en caché es antiguo o el proxy se reinicia. Solo los tiempos de reinicio que faltan necesitan una consulta de metadatos después de la protección de frescura de cinco minutos. El descubrimiento no resuelto y las activaciones fallidas reintentan después de 5, 10, 20, 40, luego como máximo cada 60 minutos; estos retardos de reintento se restablecen en el reinicio del proxy. Los encabezados de respuesta exitosos siembran la siguiente ventana sin una consulta adicional cuando esté disponible. Las actualizaciones del panel de control y el sondeo opcional de reinicio-notificación permanecen independientes. Los límites de reinicio observados se conservan en los reinicios hasta que se completen, por lo que una marca de tiempo de ventana inactiva en movimiento no puede borrar una activación pendiente. La actualización de metadatos utiliza la recuperación de autenticación limitada existente; una inferencia 401 marca la credencial rechazada para la reautenticación en lugar de gastar repetidamente reintentos en ella. Las fallas solo registran una etiqueta de cuenta opaca y una razón de solo estado. Esto es independiente del enrutamiento de la ventana de reinicio: el enrutamiento elige una cuenta para el trabajo entrante, mientras que la activación envía una solicitud a una cuenta específica solo después de su propio reinicio. + +**Pauta de consulta:** La recuperación de bloqueo de la cuenta principal espera el restablecimiento de bloqueo conocido, luego consulta para confirmar la recuperación; el tiempo solo nunca desbloquea la cuenta. Sin un restablecimiento futuro, la recuperación en segundo plano utiliza un retroceso de 5/10/20/40/60 minutos mientras la cuenta permanece bloqueada. En el modo Pool, las consultas ordinarias de uso principal/de grupo comparten el retroceso de fallas (5, 10, 20, 40, luego 60 minutos) para fallas de transporte, fallas que no son de auth HTTP y 200 cuerpos inutilizables, incluidas las actualizaciones forzadas; `Retry-After` puede extender esa espera. El manejo de autenticación 401/403 existente permanece sin cambios. Solo el uso utilizable borra el retroceso; las consultas simultáneas de la misma clave comparten el resultado establecido de una lectura. Las credenciales reemplazadas tienen un estado de reintento separado, y las instantáneas obsoletas nunca se marcan como nuevas. Estos retrasos son locales de proceso; las actualizaciones forzadas principales fuera del modo Pool conservan su comportamiento independiente. + +**Nota de degradación:** Antes de ejecutar una versión anterior, quite solo `nextFiveHourResetAt` y `nextWeeklyResetAt` de la configuración de activación automática. Los lectores más antiguos rechazan estos nuevos campos y pueden deshabilitar todo el bloque de configuración de activación. + + + +## Selección del modelo de subagente + +En una instalación nueva, `subagentModels` ofrece `gpt-6-astra`, `gpt-6.1-sol` y `gpt-6-luna` en el selector de subagentes de Codex. El panel permite reordenar o sustituir hasta cinco entradas por modelos nativos o enrutados. Las opciones `injectionModel` e `injectionEffort` describen preferencias de modelo y esfuerzo en la guía redactada por el proxy; siguen siendo recomendaciones salvo que se active la sincronización de valores nativos. Consulta [Configuración de agentes](/es/reference/configuration/agents/) para las reglas de guía v1/v2 y la sincronización. + + + +## El ciclo de vida + + + +1. **Análisis** - `responses/parser.ts` valida la solicitud con un esquema de Zod (`responses/schema.ts`) y la reduce a un mensaje interno `OcxParsedRequest`: solicitud del sistema, una lista de mensajes normalizados (texto, imágenes, llamadas de herramientas, resultados de herramientas), las definiciones de herramientas, opciones de generación y banderas de características como `_webSearch` (se solicitó una búsqueda web alojada) y `_structuredOutput` (se estableció un esquema JSON / JSON -object `text.format`). Las imágenes se conservan como partes de contenido real, nunca alineadas como texto base64. + +2. **Enrutamiento** — `router.ts` resuelve el modelo en este orden: perfil de enrutamiento configurado → selector exacto de cuenta de Codex → identificador o alias de Combo configurado → `provider/model` explícito → modelo nativo de OpenAI sin prefijo (`gpt-`, `o1-`/`o3-`/`o4-`) → `defaultModel` de un proveedor → prefijos integrados (`claude-`, `llama-`/`mixtral-`/`gemma-`) → `models[]` de un proveedor → `defaultProvider`. Consulta [Enrutamiento de modelos](/es/guides/model-routing/). + +3. **Autenticar** - para un proveedor `oauth`, opencodex se intercambia en un token de acceso fresco y actualizado automáticamente como la clave portadora, de modo que los adaptadores existentes se autentican sin cambios. Para las cuentas de grupo ChatGPT / Codex, `codex/auth-context.ts` resuelve primero la cuenta y el adaptador de paso se niega a continuar si la credencial de grupo requerida no está disponible. + +4. **Sidecar de visión (opcional)** - si el modelo enrutado aparece en `provider.noVisionModels` y la solicitud lleva una imagen, opencodex describe cada imagen con el sidecar de visión ChatGPT configurado y la reemplaza con texto, por lo que un modelo de solo texto todavía puede razonar al respecto. Véase [Sidecares](/es/guides/sidecars/). + +5. **Camino rápido de paso**: si el adaptador es un paso Responses (`openai-responses` o `azure-openai`), opencodex mantiene el cuerpo Responses, aplica enrutamiento dirigido y reescribe la compatibilidad, luego retransmite la respuesta del proveedor sin convertirlo a través de `AdapterEvent` s. + +6. **Sidecar de búsqueda web (opcional)** — si Codex solicita la herramienta alojada `web_search` y el modelo enrutado no es de OpenAI, opencodex expone una función sintética `web_search` y ejecuta el modelo en un pequeño bucle de agente. Las búsquedas reales se realizan mediante `gpt-5.6-luna` de forma predeterminada, con tu sesión de ChatGPT, y los resultados se incorporan como respuestas de la herramienta. + +7. **Compacto (cuando se solicita)** - Codex v1 llama `POST /v1/responses/compact`; v2 agrega un `compaction_trigger` a un giro Responses. Las rutas de paso nativas se compactan aguas arriba, mientras que un modelo enrutado se ejecuta como un resumen sin herramientas y devuelve la forma de historial de reemplazo que espera Codex. + +8. **Adaptar** — en los demás casos, `buildRequest()` del adaptador elegido construye la solicitud HTTP al proveedor (URL, encabezados y cuerpo) en su formato nativo. opencodex envía esa solicitud mediante `fetch`. + +9. **Puente** - el adaptador `parseStream()` (o `parseResponse()`) produce `AdapterEvent` s interno (texto, razonamiento, inicio/delta/fin de llamada de herramienta, hecho, error). `bridge.ts` convierte ese flujo en Responses SSE eventos - `response.output_text.delta`, `response.reasoning_summary_text.delta`, `response.function_call_arguments.delta`, `response.completed`, y así sucesivamente. El transporte opcional WebSocket envía las mismas cargas útiles de eventos que los marcos de texto. + + + + + +## ¿Por qué un proxy y no una bifurcación Codex? + +Codex codifica el Responses API. Al traducir en el límite del protocolo, opencodex funciona con el Codex **CLI, App, y SDK** sin cambios, sobrevive a las actualizaciones Codex y le permite cambiar de proveedor por solicitud sin tocar el propio Codex. La traducción es bidireccional y fiel a la transmisión: resúmenes de razonamiento, MCP espacios de nombres de herramientas, herramientas de forma libre (`apply_patch`) y `tool_search` descubrimiento de todo el viaje de ida y vuelta correctamente. Consulte el [Referencia de arquitectura](/es/reference/architecture/) para el mapeo evento por evento. diff --git a/docs-site/src/content/docs/es/getting-started/installation.md b/docs-site/src/content/docs/es/getting-started/installation.md new file mode 100644 index 00000000000..3cd78b494f2 --- /dev/null +++ b/docs-site/src/content/docs/es/getting-started/installation.md @@ -0,0 +1,136 @@ +--- +title: "Instalación" +description: "Instale el proxy opencodex (ocx), sus requisitos previos, y compruebe que se ejecuta." +--- + +opencodex instala dos comandos equivalentes, `ocx` y `opencodex`. Ambos inician el mismo servidor HTTP local escrito para Bun. Las solicitudes se envían al proveedor seleccionado por el enrutamiento. Los sidecars opcionales de visión y búsqueda web también pueden usar tu sesión de ChatGPT cuando un modelo enrutado los necesite. + + + +## Comando terminal de escritorio + +Una instalación estable de OpenCodex Desktop configura `ocx` para las terminales nuevas al iniciar la aplicación. Abre una terminal nueva y ejecuta `ocx status` u `ocx doctor` para inspeccionar el primer ejecutable de PATH. En macOS y en instalaciones de Linux con paquetes `.deb`, un bloque administrado al final de los archivos de inicio de zsh, bash y fish coloca `~/.opencodex-desktop/bin` primero en PATH y usa el lanzador de escritorio. Windows coloca el directorio del `ocx.exe` incluido al principio del `Path` del usuario. Las terminales ya abiertas, los alias, las cachés de shell y los cambios posteriores de PATH pueden seleccionar otro comando; en Windows también puede tener prioridad una entrada del PATH del sistema. Usa el ajuste de comando de terminal de la aplicación para reparar, desactivar o eliminar esta configuración. AppImage queda excluido. + +En macOS y Linux, si todavía se ejecuta el lanzador de npm/pnpm, este delega los comandos compatibles en la CLI de Desktop cuando su registro está habilitado y supera las comprobaciones de propiedad, permisos y seguridad de archivos. Windows no usa esa delegación: las terminales nuevas seleccionan el `ocx.exe` de Desktop mediante el orden del `Path` del usuario. El error `record-unsafe` indica que el registro o su directorio no superó una comprobación de seguridad. Abre OpenCodex Desktop para reparar el comando, o usa `OCX_NO_DESKTOP_HANDOFF=1` en una invocación del paquete en macOS/Linux. La actualización o eliminación del paquete y la inspección interna conservan su ruta habitual. `OCX_NO_DESKTOP_HANDOFF=1` solo suprime la delegación de esa invocación; no cambia el lanzador de Desktop seleccionado directamente ni el PATH. + + + +## Requisitos previos + +| Requisito | Por qué | +| --- | --- | +| **[Node](https://nodejs.org) ≥ 18** | `ocx` se ejecuta con Bun, que se incluye automáticamente al instalar con npm o pnpm. **No** necesitas instalar Bun por separado. | +| **[OpenAI Codex](https://openai.com/codex)** (CLI, aplicación o SDK) | Es el cliente al que opencodex sirve como proxy. opencodex escribe en `$CODEX_HOME/config.toml` (por defecto, `~/.codex/config.toml`). | +| Una cuenta de proveedor o clave API | Anthropic, xAI, Kimi, Ollama Cloud, OpenRouter, un punto final compatible con OpenAI o su inicio de sesión ChatGPT. | + + + +## Instalar + +```bash +npm install -g @bitkyc08/opencodex +``` + +Con pnpm 10.4 o posterior: + +```bash +pnpm add -g --allow-build=bun @bitkyc08/opencodex +``` + +:::note[¿npm bloqueó el script postinstall de Bun?] +Las versiones recientes de npm pueden bloquear el script postinstall de Bun (`npm warn +install-scripts ... blocked because they are not covered by allowScripts`) y dejar sin preparar el entorno incluido. Tras intentar la recuperación permitida del entorno incluido, el lanzador puede usar un ejecutable Bun situado en un directorio absoluto de PATH si es una versión estable con la misma versión mayor y una versión menor igual o superior a la de la dependencia. Con la dependencia actual 1.4.4, esto admite 1.4.0 o posterior dentro de la versión mayor 1. Las comprobaciones de versión e identidad exigen que `bun --version` coincida con `Bun.version` informado por `bun -e`. En POSIX se comprueba toda la ruta, incluidos los directorios y componentes alcanzados mediante enlaces simbólicos. Cada directorio y enlace recorrido, y el ejecutable resuelto, deben pertenecer a root o al usuario efectivo del lanzador. Los directorios y el ejecutable resuelto no pueden permitir escritura al grupo ni a otros usuarios; no se usan los bits de permisos de los enlaces simbólicos. Se rechazan ancestros compartidos con escritura como `/tmp`, incluso con sticky bit: proteger solo el ejecutable y su directorio inmediato no basta. Un aviso de una línea en stderr identifica la versión de Bun seleccionada. Bun sigue incluido en el paquete; instalarlo por separado es opcional. + +Si no hay un entorno utilizable y falta la dependencia `bun`, el error lo indica. En macOS también muestra la CLI de Desktop si encuentra un ejecutable en +`/Applications/OpenCodex.app/Contents/MacOS/ocx` o +`~/Applications/OpenCodex.app/Contents/MacOS/ocx`. Puedes invocar esa ruta explícitamente: esta recuperación no delega automáticamente en ella ni instala un lanzador en PATH. + +Para reparar el entorno incluido, reinstala el paquete permitiendo el script de Bun. Incluye siempre el nombre del paquete: la sugerencia abreviada de npm lo omite y reinstala el directorio actual. + +```bash +npm install -g --allow-scripts=bun @bitkyc08/opencodex + +# if the original install used sudo, keep using sudo: +sudo npm install -g --allow-scripts=bun @bitkyc08/opencodex +``` +::: + +Verifique que ambos alias de comando estén en su `PATH`: + +```bash +ocx --version +opencodex --version +``` + +Antes de iniciar, detener o reiniciar el proxy, gestionar el servicio o actualizar desde la CLI de Bun, puede aparecer un aviso breve en stderr si las versiones de la CLI y el proxy no coinciden. Es informativo y conserva el código de salida; las salidas JSON y de ayuda no lo activan. Las actualizaciones de npm/pnpm que gestiona el lanzador de Node antes de iniciar la CLI de Bun no muestran este aviso. `ocx status`, `ocx doctor` y `ocx resolve` ya informan de estas diferencias en sus diagnósticos. + +Si instalas el servicio desde un shell con fnm, nvm, mise, asdf o volta, OpenCodex excluye del PATH del servicio los directorios multishell ligados a esa sesión. En Linux selecciona un lanzador `ocx` duradero si está disponible; de lo contrario usa el Bun del paquete. Ejecuta `ocx service repair` si un servicio anterior se instaló desde un directorio multishell. En macOS, la reparación recarga launchd si cambia la lista guardada. + + + +## Binario independiente (sin npm) + +Las descargas de versiones también incluyen un binario `ocx` para las plataformas compatibles de macOS, Linux y Windows. Incluye Bun y el dashboard, por lo que no requiere npm, Node ni una instalación separada de Bun. Descarga el archivo de tu plataforma, extráelo y ejecuta: + +```bash +./ocx --version +./ocx start +``` + +Los directorios extraídos `gui/dist` y `keyring` deben permanecer junto al binario. El primero sirve el dashboard y el segundo contiene el enlace nativo de la plataforma con el almacén de credenciales del sistema operativo. + +En Windows, [Firma de código en Windows](/es/reference/code-signing/) explica cómo se firma `ocx.exe` y cómo verificarlo. + + + +### Canales de liberación + +El canal estable `latest` ya incluye el catálogo de GPT-5.6 Sol/Terra/Luna para ChatGPT, la API de OpenAI con clave, OpenRouter y las rutas experimentales de Cursor. La disponibilidad sigue dependiendo de la cuenta del proveedor: una entrada de catálogo no concede acceso. Usa el canal preview solo para probar versiones preliminares de opencodex: + +```bash +npm install -g @bitkyc08/opencodex@preview +ocx update --tag preview +``` + + + +## Correr desde la fuente + +Para hackear el propio opencodex: + +```bash +git clone https://github.com/lidge-jun/opencodex.git +cd opencodex +bun install +bun run dev:proxy # starts the proxy API in dev mode (src/cli/index.ts start) +bun run dev:gui # starts the dashboard dev server (another terminal) +``` + +`bun run dev` es un alias de `bun run dev:proxy`. La API del proxy expone `/healthz`, `/v1/responses` y `/api/*`. `GET /` sirve el dashboard empaquetado cuando `bun run build:gui` ha generado `gui/dist`. Para desarrollar la interfaz, inicia el frontend por separado con `bun run dev:gui`. + + + +## Lo que se crea + +opencodex guarda sus datos en `$OPENCODEX_HOME` (por defecto, `~/.opencodex`). Los archivos de integración de Codex están en `$CODEX_HOME` (por defecto, `~/.codex`). + +| Ruta | Finalidad | +| --- | --- | +| `$OPENCODEX_HOME/config.json` | Sus proveedores, proveedor predeterminado, puerto y opciones. | +| `$OPENCODEX_HOME/ocx.pid` | PID del proxy en ejecución (guarda de instancia única). | +| `$OPENCODEX_HOME/runtime-port.json` | El PID vivo, el nombre de host y el puerto —, incluido un puerto asignado al sistema operativo cuando `config.port` es `0`. | +| `$OPENCODEX_HOME/auth.json` | Las credenciales OAuth almacenadas (cuando `ocx login`). | +| `$OPENCODEX_HOME/catalog-backup*.json` | Codex copias de seguridad del catálogo de modelos hechas antes de que opencodex lo edite. | +| `$CODEX_HOME/config.toml` | En bucle, opencodex agrega una raíz de propiedad del marcador `openai_base_url`; non-loopback une el uso `model_provider = "opencodex"` más `[model_providers.opencodex]` para que Codex pueda enviar el encabezado API-auth. | +| `$CODEX_HOME/opencodex.config.toml` | Perfil de referencia/retroceso escrito junto a la configuración principal de Codex. | +| `$CODEX_HOME/opencodex-catalog.json` | Catálogo de modelos nativos y enrutados sincronizados utilizado por Codex. | + +:::note +opencodex no borra tu configuración de Codex. Cada inyección es reversible: `ocx stop`, `ocx restore` u `ocx eject` eliminan las líneas añadidas por opencodex y restauran el uso nativo de Codex. +::: + + + +## Siguiente + +Continuar a la [Inicio rápido](/es/getting-started/quickstart/) para configurar su primer proveedor, o leer [Cómo funciona](/es/getting-started/how-it-works/) para la arquitectura. diff --git a/docs-site/src/content/docs/es/getting-started/quickstart.md b/docs-site/src/content/docs/es/getting-started/quickstart.md new file mode 100644 index 00000000000..285082623c5 --- /dev/null +++ b/docs-site/src/content/docs/es/getting-started/quickstart.md @@ -0,0 +1,143 @@ +--- +title: "Inicio rápido" +description: "Configura tu primer proveedor y conecta OpenAI Codex a través de opencodex con tres comandos." +--- + +Esta guía te lleva desde una instalación nueva hasta ejecutar Codex con un modelo de otro proveedor distinto de OpenAI. + + + +## Binario independiente, sin npm + +También puedes usar el archivo de una versión que incluye el binario `ocx` y el entorno de ejecución Bun, sin npm. Extráelo de modo que el directorio `gui/dist` quede junto al binario y ejecuta `./ocx start`. + + + +## 1. Ejecuta el asistente de configuración + +```bash +ocx init +``` + +`ocx init` te guía por estos pasos: + +1. **Elegir un proveedor**: selecciona uno de los 105 preajustes del registro integrado o `custom` para introducir una URL base y un adaptador. +2. **Clave API**: pega una clave o indica una variable de entorno como `${ANTHROPIC_API_KEY}`. +3. **Modelo predeterminado**: para proveedores con clave, locales o personalizados, acepta el preajuste o introduce un identificador de modelo. +4. **Puerto del proxy**: `10100` de forma predeterminada. +5. **¿Integrar con Codex?** En una configuración habitual de bucle local, opencodex añade `openai_base_url` en la raíz de `$CODEX_HOME/config.toml` (de forma predeterminada, `~/.codex/config.toml`) para que el proveedor integrado `openai` de Codex apunte al proxy. Las conexiones remotas o LAN usan una entrada de proveedor dedicada con un encabezado de autenticación de API. +6. **¿Instalar el shim de inicio automático?** Si lo habilitas, al iniciar `codex` se ejecuta primero `ocx ensure`. + +El resultado se guarda en `$OPENCODEX_HOME/config.json` (de forma predeterminada, `~/.opencodex/config.json`). + +`ocx init` solo crea una configuración si no existe ninguna. Si ya hay una válida, la conserva y termina; usa `ocx config` o el dashboard para actualizarla. Las entradas no válidas, ilegibles o que sean enlaces simbólicos se conservan y se notifican como errores. Si otro proceso crea la configuración durante el asistente, se conserva su archivo y el asistente se detiene antes de administrar copias de seguridad o proponer la integración. + +EOF o Ctrl+C antes de crear el archivo cancela la configuración. Cancelar después conserva el archivo guardado. Su creación inicial requiere soporte y permisos para enlaces duros en ese sistema de archivos; si falla, el asistente se detiene sin intentar sobrescribirlo. Si no termina de crear el archivo o limpiar los temporales, inspecciona el directorio antes de reintentar: puede quedar una configuración completa o un archivo temporal privado. + +Si el asistente informa de que no pudo asegurar los permisos iniciales, el sistema de archivos o la cuenta no pudieron aplicar los permisos privados requeridos (ACL de NTFS en Windows). Esto ocurre antes de escribir el contenido. Un fallo al publicar mediante enlace duro es distinto: los permisos privados se aplicaron, pero no se pudo publicar el archivo completo o no se puede confirmar el resultado. + +Inspecciona el directorio elegido antes de reintentar. Conserva cualquier `config.json` existente; no lo borres para forzar al asistente a continuar. Para una instalación nueva, elige una ubicación con permiso de escritura que admita enlaces duros y permisos privados. Un directorio local NTFS es adecuado en Windows si tu cuenta puede aplicar sus ACL. Por ejemplo, elige una ubicación nueva en la misma terminal antes de ejecutar el asistente: + +```powershell +# Windows PowerShell: choose a fresh directory on a local NTFS volume. +$env:OPENCODEX_HOME = Join-Path $env:LOCALAPPDATA "opencodex-local" +ocx init +``` + +```sh +# macOS/Linux: choose a fresh directory on a filesystem with hard links and Unix permissions. +export OPENCODEX_HOME="$HOME/.opencodex-local" +ocx init +``` + +Usa el mismo `OPENCODEX_HOME` en los comandos posteriores y en el servicio que ejecute el proxy. Cambiar esta variable selecciona otra ubicación de configuración; no migra una instalación existente. El asistente no usa como alternativa la escritura directa ni un cambio de nombre que reemplace archivos: crear un archivo exclusivo y escribir después en él podría exponer contenido parcial. + +:::note[Entradas del despliegue de GPT-5.6] +La versión estable actual incluye GPT-5.6 Sol/Terra/Luna para el paso directo de ChatGPT, OpenAI con clave API, OpenRouter y el adaptador experimental de Cursor. Solo funcionan si la cuenta del proveedor tiene acceso. Los preajustes de OpenAI con clave API y OpenRouter anuncian una ventana de contexto utilizable de 922.000 tokens; Cursor conserva los metadatos de su propio adaptador. +::: + + + +## 2. Inicia el proxy + +```bash +ocx start # defaults to port 10100 +ocx start --port 8080 +``` + +Al iniciar, opencodex: + +- Escribe su PID en `~/.opencodex/ocx.pid` y rechaza un segundo inicio. +- Descubre los modelos disponibles cuando el proveedor lo permite y **sincroniza las entradas nativas y enrutadas en el catálogo de modelos de Codex**. +- Escucha en `http://localhost:/v1`. + +Una instancia activa de opencodex con el mismo `OPENCODEX_HOME` impide iniciar otra, aunque el nuevo puerto esté libre. Detén primero esa instancia con `ocx stop`, o usa otro `OPENCODEX_HOME` para una instancia independiente. Si un proceso ajeno ocupa el puerto solicitado, `ocx start` lo identifica; elige un puerto libre con `ocx start --port `. Nunca cambia de puerto automáticamente, para evitar que queden dos proxies activos y Codex apunte al más reciente. + +Compruébalo: + +```bash +ocx status +ocx gui # open the dashboard on the live port +``` + + + +## 3. Usa Codex + +Codex se comunica con opencodex de forma transparente: + +```bash +codex "Refactor this function for readability" +``` + +Para elegir un modelo enrutado concreto, usa el formato `provider/model` que muestra el selector de Codex: + +```bash +codex -m "anthropic/claude-opus-5" "Explain this stack trace" +codex -m "ollama-cloud/glm-5.2" "Write a SQL migration" +``` + + + +## Elegir modelos de subagentes, opcional + +Una configuración nueva incluye `gpt-6-astra`, `gpt-6.1-sol` y `gpt-6-luna` en el selector de subagentes de Codex. Abra `ocx gui` para sustituirlos o reordenar hasta cinco modelos nativos o enrutados. El panel también permite elegir un modelo preferido de subagentes y su esfuerzo de razonamiento. Consulte [Interfaz de subagentes](/es/guides/sub-agent-surface/) para elegir v1/base/v2 y conocer cuándo se aplican las instrucciones, los valores nativos predeterminados y las alternativas. + + + +## Iniciar sesión en lugar de pegar una clave + +Algunos proveedores permiten iniciar sesión con una cuenta mediante OAuth y renovar las credenciales automáticamente: + +```bash +ocx login xai # or: anthropic, kimi, kiro, google-antigravity, cursor +ocx logout xai +``` + +El proveedor predeterminado de OpenAI **no necesita una clave**: reenvía directamente las credenciales existentes de `codex login`. Consulta [Proveedores](/es/guides/providers/). + + + +## Detener y restaurar + +```bash +ocx stop # stop the proxy and restore native Codex +ocx restore # restore native Codex without stopping (alias: ocx eject) +ocx restore back # route Codex through the still-running proxy again +``` + + + +## No se pudo verificar la propiedad al iniciar + +Si al iniciar aparecen `Shared-client owner could not be verified` y `refusing startup`, OpenCodex no pudo determinar de forma segura si otro proxy controla las opciones compartidas de los clientes. Se detiene antes de publicar otro entorno de ejecución o modificar esas opciones. Reintenta cuando se recupere la conectividad local; un servicio en segundo plano ya instalado reintenta mediante su gestor de servicios. Un tiempo de espera agotado no convierte permanentemente el proceso nuevo en una instancia secundaria. + +No es necesario habilitar IPv6 en el bucle local. El inicio comprueba si puede vincular cada dirección de bucle local y omite las familias no disponibles. Si se agota el tiempo de espera de una familia disponible, se detiene hasta que pueda verificar la propiedad. + + + +## Siguientes pasos + +- [Cómo funciona](/es/getting-started/how-it-works/): qué sucede con cada solicitud. +- [Proveedores](/es/guides/providers/): todas las formas de autenticación. +- [Configuración](/es/reference/configuration/): referencia completa de `config.json`. diff --git a/docs-site/src/content/docs/es/guides/chatgpt-desktop.md b/docs-site/src/content/docs/es/guides/chatgpt-desktop.md new file mode 100644 index 00000000000..e9be3dde924 --- /dev/null +++ b/docs-site/src/content/docs/es/guides/chatgpt-desktop.md @@ -0,0 +1,71 @@ +--- +title: "Shim del app-server de ChatGPT Desktop (experimental)" +description: "Experimento opcional para macOS que reescribe los campos de bloqueo por cuota general en la salida estándar del app-server incluido." +--- + +Este experimento **solo funciona en macOS y está desactivado de forma predeterminada**. Filtra la salida estándar JSON-RPC del app-server incluido con ChatGPT para abrir los bloqueos conocidos debidos únicamente a la cuota general. No aumenta la cuota de la cuenta ni obliga al servicio del proveedor a aceptar solicitudes que rechaza. + +Habilítelo en el archivo `config.json` de OpenCodex: + +```json +{ + "chatgptDesktop": { "appServerShim": true } +} +``` + +Después, ejecute: + +```bash +ocx chatgpt launch +ocx chatgpt status +``` + +`launch` crea un lanzador ejecutable en el directorio de configuración de OpenCodex, cierra ChatGPT si está en ejecución y vuelve a abrirlo con `open -a --env CODEX_CLI_PATH=`. Busca la aplicación por su identificador de paquete, `com.openai.codex`, por lo que también admite instalaciones en `~/Applications` o en otro volumen. Nunca cierra ni abre otra aplicación que simplemente comparta el nombre «ChatGPT». Guarde primero el trabajo en curso: esta operación reinicia la aplicación. No requiere un proxy de OpenCodex en ejecución. + +Para eliminar el lanzador y volver a abrir la aplicación sin esa sustitución: + +```bash +ocx chatgpt restore +``` + +La restauración conserva el valor configurado. Establezca `chatgptDesktop.appServerShim` en `false` o elimínelo para impedir futuros inicios explícitos con el shim. Abrir normalmente la aplicación desde Dock o Spotlight no aplica el shim automáticamente. + +Si ChatGPT no está instalado (no se encuentra un paquete `com.openai.codex`), `restore` solo elimina el lanzador: no puede volver a abrir ninguna aplicación y termina con un error. + + + +## Alcance de la reescritura + +Solo se consideran las notificaciones `account/rateLimits/updated` y las respuestas cuyo resultado de nivel superior contiene `rateLimits`, `rateLimitsByLimitId` u `ordinaryUsageAllowed`. Se eliminan los marcadores simples `rate_limit_reached`. Los campos conocidos de bloqueo por cuota (`allowed`, `limit_reached` / `limitReached`, `ordinaryUsageAllowed`) solo pasan al estado permitido cuando hay evidencia de que el bloqueo se debe a la cuota general: se ha eliminado un marcador de ese tipo o una ventana de uso alcanza el 100%. Un campo bloqueado por un motivo que no aparece en los datos recibidos permanece bloqueado. Las restricciones del espacio de trabajo, los créditos, los tipos desconocidos de límite alcanzado y los controles de gasto mantienen cerrado el acceso por uso. + +El uso mostrado conserva los datos reales: porcentajes, fechas de restablecimiento, duración de las ventanas, información del plan y otros campos de presentación se mantienen como se recibieron. Los mensajes JSON-RPC ajenos a este caso, la salida anidada de herramientas, los metadatos que bloquean el envío de conversaciones y las líneas malformadas se transmiten sin cambios. Solo se vuelven a serializar las líneas modificadas; los demás bytes conservan su codificación y sus finales de línea originales. La entrada estándar, la salida de errores y el código de salida del binario real mantienen su conexión directa con la aplicación. + + + +## Seguridad del ejecutable y del entorno + +El lanzador generado tiene permisos `0755` e incorpora la ruta del ejecutable actual de OpenCodex y, en instalaciones desde el código fuente, la ruta de entrada de la CLI. `CODEX_CLI_PATH` indica a ChatGPT que ejecute ese lanzador en lugar de iniciar directamente su binario incluido. Mantenga bajo su control el lanzador, su directorio de configuración y la instalación de OpenCodex: modificar esas rutas cambia el código que ejecuta la aplicación. El lanzador usa `exec` para ejecutar el binario incluido en el paquete detectado. Si ese paquete no contiene un binario app-server, `launch` rechaza la operación sin escribir el lanzador. + +Antes de escribirlo, `launch` comprueba también que el paquete y su binario app-server pertenezcan a usted o a root, que ni el grupo ni otros usuarios puedan modificarlos y que superen la verificación estricta de firma de código con el identificador de equipo de OpenAI (`2DC432GLL2`). Se rechaza cualquier paquete que incumpla una comprobación, incluido uno que pertenezca a otra cuenta. El lanzador se escribe primero en un archivo temporal y después se coloca en su destino mediante un cambio de nombre; un enlace simbólico existente en esa ruta se reemplaza, sin seguirlo. + +Antes de cerrar o abrir la aplicación, `restore` aplica las mismas comprobaciones de propiedad, permisos y firma al paquete y al ejecutable principal de la aplicación. Funciona con la opción experimental desactivada y sin un binario app-server incluido. Si falla la verificación de confianza o la reapertura, conserva el lanzador existente para permitir la recuperación. + +Ambos comandos comprueban también todos los directorios que contienen el paquete hasta la raíz del sistema de archivos. Rechazan directorios de otra cuenta, enlaces simbólicos y directorios superiores ordinarios que permitan escritura al grupo o a otros usuarios. Los directorios de instalación propiedad de root y del grupo de administradores, y los directorios de confianza con bit sticky, conservan su tratamiento habitual de permisos. Estas comprobaciones abarcan propiedad, permisos POSIX y firma; no se ha verificado el comportamiento de las ACL nativas ni de las políticas de propiedad de volúmenes. + +Esta integración no instala certificados, puertos de escucha de red, PAC ni procesos de vigilancia en segundo plano. No registra los mensajes ni el entorno de la aplicación. El estado informa si el proceso de ChatGPT en ejecución lleva la sustitución esperada del lanzador. + +Si falla la detección de la aplicación o la inspección de procesos, `status` informa `unknown` en lugar de `not running`. `launch` y `restore` se niegan a volver a abrir una aplicación si no pueden confirmar que haya terminado; en ese caso, la restauración conserva el lanzador. Resuelva el error de inspección y vuelva a intentarlo. `launch` comprueba el estado antes de escribir el lanzador, pero una inspección posterior puede fallar después de esa actualización atómica: los comandos no garantizan un reinicio íntegro o una reversión completa. + + + +## Comportamiento ante fallos y límites conocidos + +Si la plataforma no es macOS, falta el entorno de ejecución de OpenCodex o falla la autoprueba del filtro, el lanzador ejecuta el binario original con su salida estándar intacta. La ausencia del binario app-server incluido es una excepción: no hay otro binario al que recurrir y el lanzador termina con un error (véase más abajo). Si el filtro supera la autoprueba y después termina inesperadamente durante la sesión, cierra la tubería. No se ha verificado qué hace entonces el app-server incluido: podría recibir SIGPIPE o un error de escritura, y Desktop podría iniciarlo de nuevo mediante el mismo lanzador. El modo de paso directo del filtro limita este problema a su terminación o caída: una excepción de reescritura deja pasar esa línea sin cambios, y un fallo inesperado del mecanismo de reescritura hace que el resto del flujo se transmita como bytes sin procesar. + +El experimento depende de la ruta del binario incluido, de que la aplicación respete `CODEX_CLI_PATH` y de la estructura actual de los campos RPC. Las actualizaciones pueden cambiar estos elementos. Si la instalación de OpenCodex se mueve o elimina, falla la comprobación previa del lanzador y se ejecuta el binario original. Ejecute de nuevo `ocx chatgpt launch` después de mover la instalación. Si una actualización de la aplicación mueve o elimina el propio binario app-server incluido, el lanzador no puede iniciarlo: escribe en la salida de errores un mensaje que menciona `ocx chatgpt launch` y `ocx chatgpt restore`, y termina. Desktop no puede iniciar su app-server hasta que ejecute uno de esos comandos. Una sola línea de salida de más de 8 MiB se transmite sin analizar, en lugar de almacenarse en búfer. + +Este shim independiente no reescribe los metadatos de conversaciones ni enruta solicitudes a modelos. Otros bloqueos de la aplicación o rechazos del proveedor pueden seguir impidiendo el envío. Que el lanzador esté conectado o que la autoprueba del filtro pase no demuestra que los datos de bloqueo de la aplicación atraviesen esa tubería. + +Las observaciones del informante en [#6196](https://github.com/lidge-jun/opencodex/issues/6196), del 2 y el 13 de octubre de 2026, describen un shim conectado con el botón Send todavía desactivado al agotarse la cuota de forma normal. Con Desktop 26.1007.30912 y OpenCodex 2.84.0, no observó mensajes RPC de límites de uso que pudieran reescribirse, mientras que el bloqueo de la interfaz usaba otro transporte de datos de uso. El shim no puede reescribir datos que nunca llegan a su filtro de salida estándar. Son informes específicos de esas compilaciones, sin una nueva verificación en vivo ni una prueba de que todas las versiones de Desktop usen el mismo transporte. + +El comportamiento pendiente del cuadro de redacción con una sesión iniciada sigue registrado en #6196. El éxito anterior con una configuración combinada de shim e intercepción no demuestra que el shim por sí solo sea suficiente. La intercepción de #6365 se cerró sin integrarse y no forma parte de una solución publicada. diff --git a/docs-site/src/content/docs/es/guides/claude-code.md b/docs-site/src/content/docs/es/guides/claude-code.md new file mode 100644 index 00000000000..54a938694f6 --- /dev/null +++ b/docs-site/src/content/docs/es/guides/claude-code.md @@ -0,0 +1,695 @@ +--- +title: "Claude Code" +description: "Utilice cualquier modelo enrutado de Claude Code — opencodex sirve el Anthropic Messages API y el descubrimiento de modelos de pasarela en el mismo puerto." +--- + +opencodex sirve `POST /v1/messages` (más `count_tokens`) junto con `/v1/responses`, por lo que Claude Code puede usar todos los proveedores enrutados: OAuth inicios de sesión, grupos de cuentas, conmutación por error de claves y sidecars incluidos, con cero trabajo de autenticación adicional. + +En las rutas de Devin (incluyendo SWE-2) alcanzadas a través de la Messages API, las llamadas de texto y herramientas esperan a que se complete el giro aguas arriba para que su firma de razonamiento tardío pueda preceder a la respuesta. Esto evita que el resultado final de Claude Code se vuelva vacío; el razonamiento y el progreso de mantenimiento aún fluyen durante la generación. La memoria intermedia comparte el límite de traducción de 32 MiB de la solicitud y la cancelación detiene al productor. Esta corrección de orden de salida no resuelve el rechazo separado de Cognition de algún texto del sistema generado. Conserva las instrucciones del sistema y las limitaciones de seguridad. + +Para una ruta Anthropic en OAuth almacenada o una clave Anthropic API, Fast nativo está disponible en +`claude-opus-5-5`, `claude-opus-5`, y `claude-opus-4-8`: elige el modelo `--fast` fila (listado cuando las filas rápidas están habilitadas) o establecer `fastMode: true`. El propio Claude Code `/fast` toggle no es Traducido a petición: el `speed` El campo que envía no sobrevive a la traducción. El proxy envía la solicitud rápida de Anthropic y registra la `usage.speed`; sólo El uso rápido confirmado obtiene la estimación de costo equivalente a 2x API. Un rechazo reconocido y específico en la ruta de solicitud del adaptador principal obtiene un reenvío de velocidad estándar presupuestado, y un nuevo giro puede incurrir en que se negó viaje de ida y vuelta de nuevo. Las cuentas de suscripción Pro/Max necesitan créditos de uso; Las cuentas de equipo/empresa necesitan habilitación de organización, y las claves API necesitan aprovisionamiento acceso a la investigación-previsión. Véase +[Anthropic Configuración rápida](/es/reference/configuration/providers/#anthropic-fast-anthropic-speed) +para el modelo exacto y alcance de recuperación. + + + +## Valores predeterminados de nivel para CLI y lanzadores externos + +En la pestaña Claude Code, seleccione un valor predeterminado de Opus, Sonnet, Haiku o Fable y **Guardar**. Estos `claudeCode.tierModels` valores predeterminados se pasan a los nuevos lanzamientos `ocx claude`. No cambian el modelo principal seleccionado actualmente, el esfuerzo de razonamiento o las asignaciones familiares de escritorio. + +Las aplicaciones que lanzan `claude` directamente no reciben el entorno del lanzador `ocx`. Después de guardar, seleccione **Previsualizar la configuración de Claude**, revise los cambios `ANTHROPIC_DEFAULT_*_MODEL`, luego **Aplicar a la configuración Claude**. Esto cambia la configuración del usuario Claude del host OpenCodex, no el equipo de un navegador remoto. Inicie un nuevo proceso Claude para usar los nuevos valores; la operación no detiene ni reinicia las sesiones existentes. No configura el enrutamiento o la autenticación, por lo que el llamante directo ya debe estar conectado al OpenCodex. + +Los alias de enrutamiento seleccionados se emparejan con etiquetas `ANTHROPIC_DEFAULT_*_MODEL_NAME`, utilizando los mismos nombres legibles que el selector de modelos. La vista previa incluye los ID y los cambios de etiqueta; el alias sigue siendo el ID del modelo enviado. Una etiqueta existente se administra solo si coincide exactamente con el nombre generado para su alias actual. Otras etiquetas, incluyendo valores vacíos, se conservan. Una etiqueta introducida manualmente idéntica a ese nombre generado es indistinguible de una etiqueta administrada. + +Solo se aplican los ID de nivel explícitamente seleccionados. Un nivel no establecido deja intacto su ID de modelo existente y su etiqueta de visualización. Reemplazar un alias con un ID de origen u otro no alias también elimina su etiqueta generada coincidente. La vista previa muestra la eliminación de etiquetas como un reemplazo vacío; las etiquetas personalizadas y las configuraciones no relacionadas permanecen intactas. Los archivos que faltan son compatibles, pero los archivos vacíos o corruptos existentes son rechazados. Los cambios desde la vista previa requieren una nueva vista previa. Aplique brevemente mueve el documento actual a un directorio privado `model-default-backups/apply-*/settings.json` bajo el directorio de configuración Claude, valida el documento capturado y luego publica exclusivamente. Nunca reemplaza el nuevo archivo de un escritor concurrente, incluso durante la reversión. Evite editar o iniciar Claude mientras aplica: otro lector puede ver el breve intervalo de archivo faltante. El sistema de archivos debe admitir movimientos del mismo volumen y enlaces duros; las operaciones no compatibles fallan sin sobrescribirlas. Después de una aplicación interrumpida o una restauración automática fallida, inspeccione esta ubicación de copia de seguridad y reconcilie las ediciones más recientes antes de restaurar. El comportamiento del sistema de archivos Windows / Linux debe verificarse por separado; una prueba local no es una prueba multiplataforma. Verifique el proveedor/modelo resuelto en los registros de solicitudes: la selección de un nivel no es prueba del modelo real servido. Esto es especialmente útil para los clasificadores externos que solicitan Sonnet. + + + +## Claude Grupo de cuentas OAuth (experimental) + +El passthrough de suscripción nativo Anthropic retiene los encabezados de respuesta ascendente `anthropic-ratelimit-*` en la transmisión, las respuestas JSON y las respuestas de error ascendente, por lo que los consumidores compatibles Claude Code statusLine pueden leer las observaciones de cuota del proveedor. Las observaciones que faltan no están llenas de valores inventados. Este relé no cambia la selección de cuenta o el comportamiento de reintento. + +Puede iniciar sesión en varias cuentas Claude a través del panel Proveedores (`ocx login anthropic` / add-account). De forma predeterminada, cada solicitud utiliza solo la cuenta **activo**. + +El **grupo experimental de cuentas Claude**, de activación explícita (`anthropicAccountPool.enabled`), añade afinidad de sesión y selección de cuentas según el uso. No controla la recuperación ante un 429: si hay dos o más cuentas utilizables, una solicitud limitada puede pasar a otra aunque el grupo esté desactivado. Para excluir una cuenta de esa recuperación, ponla en pausa. En las sesiones **nuevas**, `anthropicAccountPool.strategy` elige entre las cuentas elegibles. `quota`, la estrategia predeterminada, selecciona el menor uso conocido en la ventana definida por `quotaWindow` (`five-hour` por defecto, o `weekly` / `max-utilization`) al superar `autoSwitchThreshold`. `round-robin` reparte las sesiones uniformemente (`stickyLimit`, por defecto `1`); `fill-first` mantiene la cuenta activa hasta que entre en enfriamiento, necesite reautenticarse o alcance el umbral, y después pasa a la siguiente. El grupo está **desactivado de forma predeterminada** y sigue siendo experimental. + +El panel de control enumera las condiciones para las que está destinado el grupo: suscripciones que posee o está autorizado a usar, el cliente genuino Claude Code y una persona que supervisa la sesión. Anthropic no ha respaldado la agrupación automatizada de cuentas, las cuentas de una organización pueden compartir una cuota (por lo que otra cuenta puede no agregar capacidad), y el cambio de cuentas no protege contra la aplicación del proveedor. OpenCodex no envía solicitudes de mantenimiento y, por defecto, no actualiza Claude tokens ni lee el uso en segundo plano: el uso se lee cuando el panel de control, la aplicación de la barra de menús o un comando `ocx` lo solicitan. Los umbrales son preferencias de selección, no límites de uso o facturación. Esta es la guía del producto, no el asesoramiento legal; consulte los términos actuales de Anthropic. + +Para vincular un modelo a cuentas Claude almacenadas en particular, agregue reglas `anthropicAccountPool.routes` ordenadas mientras el grupo está habilitado. Cada regla tiene un seguro `name`, un glob completo de `match` sensible a mayúsculas, una matriz `accounts` de ID de cuenta almacenados y un `fallback` opcional (por defecto `false`). La primera regla de coincidencia limita las selecciones activas, manuales, de afinidad, estrategia y 429 de recuperación a sus cuentas. Una afinidad saludable fuera de esa regla se ignora para esta solicitud, pero se mantiene para otros modelos; la opción enrutada no la sobrescribe. Sin reserva, una ruta vacía devuelve un 401 local, o 429 con `Retry-After` cuando todas sus cuentas declaradas se están enfriando, antes de contactar con Anthropic. La respuesta del cliente no nombra la ruta; el registro proxy registra `route:#`, donde `n` es la posición basada en la regla 1. `fallback: true` usa el grupo ordinario solo cuando la ruta no tiene una cuenta elegible, incluida su orden sucesora de llenar primero; si sus cuentas almacenadas se están enfriando, el 429 devuelto usa el tiempo de reutilización más temprano en ese grupo expandido, incluso si se ha eliminado una cuenta de ruta guardada. Un modelo sin igual sigue la política de agrupación existente; la desactivación de la agrupación deja las reglas guardadas inactivas y restaura el comportamiento de 429 de cuenta activa y de presencia. Una regla es una lista de permisos del operador, no una prueba del derecho del modelo. + +Contrato operativo cuando está habilitado: + +- Upstream **429** enfría esa cuenta, borra sus afinidades y puede rotar a otra cuenta elegible dentro de la misma solicitud (limitada). El tiempo de reutilización utiliza un `Retry-After` utilizable cuando está presente, de lo contrario el último tiempo de reinicio válido entre las ventanas Anthropic marca `rejected`, incluidas las ventanas semanales. Los plazos iniciales válidos no se acortan a un límite de tiempo fijo. Un rechazo sin un plazo utilizable vuelve a un retroceso predeterminado de 60 segundos. +- Responses reportan la utilización de 5 horas y semanal de la cuenta de servicio, y cualquiera de las dos que lleva la respuesta se registra para esa cuenta - cada ventana de forma independiente, y un rechazo cuenta, así como un éxito. La selección consciente del uso funciona desde el tráfico ordinario, sin esperar una encuesta del panel de control. Los encabezados conservan las ventanas de cuota específicas del modelo y no posponen las sondas de uso ni borran el estado no disponible de una sonda de uso fallida. Las mediciones cuyo tiempo de reinicio conocido ha pasado se descartan como desconocidas, incluidas las ventanas conservadas específicas del modelo. Los valores sin un restablecimiento conocido se conservan; los datos faltantes nunca se informan como uso cero. +- Affinity es **proceso-local** (perdido en el reinicio proxy). +- Un derecho de cuenta o rechazo de facturación **403** completo y estructurado puede rotar antes de la salida. Los casos reconocidos incluyen acceso no Claude Code, una suscripción vencida / inactiva y un saldo de crédito insuficiente Anthropic. La cuenta rechazada pierde sus afinidades y se enfría durante `Retry-After`, o diez minutos sin una fecha límite. Permiso genérico, modelo/acceso a recursos, política y errores no reconocidos permanecen en el terminal. La recuperación respeta las rutas del modelo y los límites de envío; si no es elegible ningún reemplazo, se devuelve el 403 original. Esto también funciona con la agrupación proactiva. Un 403 después de la salida del asistente nunca cambia de cuenta. +- Antes de la salida, un **401** authentication_error estructurado exacto sin código de error y el mensaje "OAuth token de acceso ha sido revocado." marca la cuenta de envío OAuth como que requiere un nuevo inicio de sesión y borra sus afinidades de sesión. Antes de la salida, una cuenta elegible en el mismo grupo puede asumir el control dentro de los límites de envío existentes. Sin reemplazo elegible, se devuelve el 401 original; la cuenta rechazada permanece excluida hasta el inicio de sesión. Otros errores 401 mantienen su comportamiento existente. +- Las fallas de credenciales de actualización de token conservan la política `needsReauth` existente. La renovación de la suscripción no requiere una reautenticación, pero la cuenta espera a que expire su tiempo de reutilización. +- Si cada cuenta elegible se está enfriando, el proxy devuelve **429** (no 401) con `Retry-After` cuando se conoce. +- Recuperación, incluyendo 429 conmutación por error, utiliza `quotaWindow` para clasificar los reemplazos elegibles sin cambiar los límites de tiempo de reutilización o conmutación por error existentes; `round-robin` ignora `quotaWindow`. +- `autoSwitchThreshold: 0` solo desactiva la conmutación basada en el uso **Proactivo**. La selección de nueva sesión y la recuperación de 429 aún consultan `quotaWindow`, por lo que la ventana es inerte solo por debajo de `round-robin`. `fill-first` evalúa su umbral de drenaje en la ventana seleccionada. + +Véase [Configuración](/es/reference/configuration/providers/#anthropicaccountpool-experimental). + + + +### Messages nativo con agrupación de cuentas + +El Messages nativo administrado muestra el esfuerzo validado de la persona que llama en Logs y `usage.jsonl`, incluyendo cada intento: un esfuerzo explícito como `xhigh` o `low`, `none` para el pensamiento desactivado o `budget:` para un presupuesto de pensamiento habilitado. Un esfuerzo explícito tiene prioridad sobre el pensamiento alternativo. El pensamiento adaptativo sin un esfuerzo explícito permanece en blanco. Estas etiquetas describen los controles de solicitud; no confirman qué esfuerzo aplicó la corriente arriba o cambia el cuerpo del cable. + +Un grupo de cuentas Anthropic habilitado prefiere Messages nativo para rutas Anthropic directas elegibles cuando ninguna de las dos banderas de despliegue nativas desactiva explícitamente esa ruta. En los proveedores → Anthropic → Account pooling → **Cómo funciona la selección de cuentas**, **Preservar solicitudes nativas Claude** almacena `anthropicAccountPool.nativeMessages` (valor predeterminado true). Apagarlo selecciona el puente heredado para las solicitudes agrupadas. Con la agrupación desactivada, la configuración de implementación nativa explícita mantiene su comportamiento. + +`protocols.rollout.managedMessagesNative: false` explícito desactiva ambas rutas nativas; `managedMessagesNativeOAuth: false` desactiva OAuth nativo. Se ha cerrado la configuración actual no válida. La casilla de verificación muestra la preferencia guardada, por lo que una casilla de verificación habilitada no anula estos indicadores ni una ruta que requiera traducción de proxy. Las solicitudes nativas conservan los puntos de interrupción del historial/caché, la afinidad de la sesión, las rutas del modelo, las exclusiones de pausa/enfriamiento y la recuperación previa a la salida limitada. + +Las solicitudes nativas CLI y de código de escritorio reconocidas conservan su preámbulo de facturación/identidad y los encabezados beta de características compatibles. Las solicitudes generadas mantienen la forma de identidad SDK. Las herramientas personalizadas declaradas usan nombres consistentes en referencias diferidas y adiciones/eliminaciones en línea, mientras que los argumentos, esquemas y marcadores de caché permanecen sin cambios. Se rechazan las declaraciones ambiguas. Un conmutador de cuenta puede iniciar una caché en frío; esto no transfiere cachés ni garantiza accesos de caché. Para los cambios de herramientas en línea en los mensajes del sistema, envíe la versión beta `inline-tools-2026-09-15` requerida; el constructor nativo de origen la conserva con bloques escritos independientemente del reconocimiento del cliente. Véase [Claude 's contrato de herramienta en línea](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages). + + + +## Inicio rápido + +```bash +ocx claude +``` + +`ocx claude` asegura que el proxy se está ejecutando, luego inicia Claude Code con el entorno cableado: + +| Variable | Valor | +| --- | --- | +| `ANTHROPIC_BASE_URL` | `http://127.0.0.1:` | +| `ANTHROPIC_AUTH_TOKEN` | Solo cuando el proxy requiere una clave API - de lo contrario NO está configurado, por lo que su inicio de sesión claude.ai (suscripción + conectores) se mantiene activo | +| `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY` | `1` (descubrimiento de selector nativo `/model`) | +| `CLAUDE_CODE_AUTO_COMPACT_WINDOW` | Umbral de compactación de contexto automático (predeterminado `829800`); solo se inyecta cuando el contexto automático está habilitado | +| `ANTHROPIC_MODEL` | `claudeCode.model` (opcional) | +| `ANTHROPIC_DEFAULT_HAIKU_MODEL` | `claudeCode.tierModels.haiku ?? claudeCode.smallFastModel` (opcional; legado) `ANTHROPIC_SMALL_FAST_MODEL` también) | +| `ANTHROPIC_DEFAULT_{OPUS,SONNET,FABLE}_MODEL` | `claudeCode.tierModels.*`; en un lanzamiento de suscripción, una ranura no establecida obtiene el `claude-opus-5-5[1m]` / `claude-sonnet-5-5[1m]` / `claude-fable-5-1[1m]` nativo, por lo que `--model opus`, `sonnet` y `fable` mantienen su contexto de 1M | +| `ANTHROPIC_DEFAULT_{OPUS,SONNET,FABLE,HAIKU}_MODEL_NAME` | La etiqueta `/model` para una ranura de nivel que OpenCodex establece en un alias encaminado, tal como `gpt-6.1-sol (native)` para `ocx-claude-native--gpt-6.1-sol`. Sin ella, Claude Code etiquetas que rema con el alias. El alias mantiene el ID de modelo seleccionado. Cuando el env del sistema está encendido, el entorno launchd y el gancho de la carcasa obtienen el mismo par de ranura y etiqueta. Una ranura o etiqueta que usted mismo establezca se deja sola | +| `CLAUDE_CODE_ALWAYS_ENABLE_EFFORT` | `1` cuando `alwaysEnableEffort` está encendido (condicional) | +| `ENABLE_TOOL_SEARCH` | `claudeCode.toolSearch` cuando está establecido (condicional; apagado por defecto - ver [Los esquemas de herramientas MCP llenan el contexto](#troubleshooting) ) | +| `CLAUDE_CODE_MAX_CONTEXT_TOKENS` | Anulación de contexto heredado cuando se establece `maxContextTokens` (condicional) | +Las variables que tú mismo exportas siempre ganan. Los argumentos adicionales pasan por: `ocx claude -p "hello"`. + +Una excepción es que aproximadamente *donde* una variable viene de, no sobre la precedencia. El paquete Bun en entorno de ejecución carga automáticamente un proyecto `.env` / `.env.local`, por lo que un `ANTHROPIC_API_KEY` extraviado en el directorio desde el que se inicia solía parecer idéntico a una exportación deliberada, y deshabilitó silenciosamente una suscripción saludable a claude.ai a favor de la facturación API. `ocx claude` ahora ignora las credenciales Anthropic que solo un dotenv de proyecto introdujo. Un valor que exportó en su shell aún gana, en cada modo auth. Para usar una clave API deliberadamente, expórtela (`export ANTHROPIC_API_KEY=...`) en lugar de dejarla en un archivo de proyecto. + + + +### Repliegue nativo cuando el enrutamiento Claude está desactivado + +`ocx claude` solía salir con un error cuando se deshabilitó el enrutamiento Claude. Ahora lanza el binario nativo `claude` en su lugar, por lo que el comando sigue siendo útil con el enrutamiento desactivado: + +| Donde el enrutamiento está desactivado | ¿Qué sucede? | +| --- | --- | +| `claudeCode.enabled: false` en configuración | Lanzamiento nativo, con un aviso de que el enrutamiento está desactivado | +| El proxy en ejecución informa `enabled: false` desde `GET /api/claude-code` | Lanzamiento nativo; volver a habilitar la intercepción bajo demanda | +| `claudeCode.enabled` ausente o `true` | Enrutado a través del proxy, sin cambios | + +Solo un `false` explícito desencadena la reserva, por lo que un proxy anterior al campo permanece enrutado. Un proxy que falta no es un disparador tampoco - con enrutamiento activado, `ocx claude` todavía inicia el proxy. + +Una sesión nativa no debe heredar el estado proxy, por lo que el respaldo elimina los valores que puede **probar** +OpenCodex posee: `ANTHROPIC_BASE_URL` solo cuando apunta a la propia dirección de bucle de este proxy y puerto configurado *y* la admisión emparejada token es uno de los proxy emitidos; el +`CLAUDE_CODE_*` palancas de descubrimiento y auto-contexto; y ranuras de modelo que solo se resuelven a través del Proxy (enrutado alias y `provider/model` ID). Cualquier otra cosa es tuya y se conserva — un sin relación `http://localhost:8080` puerta de enlace y su propio `sk-ant-` Ambas credenciales sobreviven. + +Si el valor predeterminado del selector `/model` guardado es un modelo solo de proxy, la sesión nativa vuelve a `claudeCode.model` cuando se puede usar de forma nativa y, de lo contrario, le advierte que pase `--model `. Un argumento explícito de `--model` siempre gana. + + + +## Modo de autenticación + +Claude Code necesita un token en `ANTHROPIC_AUTH_TOKEN` para hablar con una puerta de enlace, pero al establecer esa variable también deshabilita su inicio de sesión claude.ai y sus conectores. ¿Cuál de los dos desea depende de algo opencodex puede mirar hacia arriba, por lo que por defecto lo hace. + +Deje **Modo de autenticación** en **Auto** (el valor predeterminado) en **Conectar → Claude** y opencodex decide en cada lanzamiento: + +| Lo que encuentra | Lo que hace | +| --- | --- | +| Un inicio de sesión Claude (cuenta `~/.claude.json` OAuth, `.credentials.json`, el llavero macOS o un `ANTHROPIC_API_KEY` exportado) | Deja el token sin configurar, por lo que su suscripción y los conectores siguen funcionando | +| No Claude auth en absoluto | Inyecta un token de marcador de posición, por lo que Claude Code deja de pedirle que inicie sesión y rutas a través del proxy | +| No puede decir (llavero ilegible, archivo corrupto) | Asume la suscripción e imprime una advertencia: nunca mueve a un suscriptor de pago al proxy en una lectura fallida | + +Esto se vuelve a calcular cada lanzamiento, no recordado, por lo que el inicio o salida se recoge en el siguiente `ocx claude` sin nada que reconfigurar. + +Elija **Suscripción** o **Proxy** explícitamente cuando lo desee. Una opción explícita se almacena en `claudeCode.authMode` y la detección nunca la anula, incluso después de iniciar sesión o salir más tarde. Vuelve a Auto para devolver la decisión. + +En macOS, la conexión automática (`claudeCode.systemEnv`) sigue la misma resolución, por lo que una llanura `claude` lanzada fuera de `ocx` se comporta de la misma manera. Ese archivo es una instantánea actualizada cuando se inicia el proxy o se guarda la configuración, mientras que `ocx claude` siempre se resuelve en vivo. + + + +## Integración del entorno del sistema (macOS) + + + +## Claude Modos de escritorio: gateway (predeterminado) y first party + +Claude Desktop puede usar OpenCodex en uno de dos modos mutuamente excluyentes. Elija en **Conectar → Claude Desktop → Modo de conexión** en el tablero o con `ocx claude desktop apply +--first-party|--gateway`. + +> Los perfiles de biblioteca de escritorio y `_meta.json` deben ser archivos regulares de como máximo 4 MiB. OpenCodex también rechaza el perfil generado o la salida de metadatos por encima de ese límite antes de reemplazar los archivos. Realice una copia de seguridad y reduzca manualmente la configuración de gran tamaño; un rechazo de tamaño no trunca los datos existentes. Las tiendas propiedad de la conexión mantienen sus límites más estrictos existentes. + + + +### Puerta de enlace (predeterminado) + +Las nuevas instalaciones usan **gateway** de forma predeterminada. Su perfil de terceros, que se describe a continuación, cambia toda la aplicación a OpenCodex como su puerta de enlace de inferencia. El chat se ejecuta localmente a través de OpenCodex y las funciones solo claude.ai no están disponibles. Los indicadores heredados `--static` / `--hybrid` / `--discovery-only` también seleccionan la puerta de enlace. + +Los perfiles de pasarela usan distintos alias de modelo con un prefijo `claude-fable-5-` para que Claude Desktop 2.31226 pueda ofrecer su control de esfuerzo sin tratar cada modelo enrutado como el mismo modelo activo. Estos alias no cambian el modelo ascendente ni las etiquetas y los valores predeterminados de la familia que se muestran. Los alias anteriores siguen siendo decodificables para las sesiones existentes. Vuelva a aplicar el perfil de la puerta de enlace y salga / vuelva a abrir completamente el escritorio para cargar la nueva lista. El selector estático utiliza el menú de esfuerzo alternativo de Desktop; no anuncia una escalera autorizada por proveedor, y la normalización del esfuerzo normal del proveedor seleccionado aún se aplica. Este sigue siendo un mecanismo de compatibilidad específico de la versión del cliente. + +Gateway apply rechaza los archivos de configuración ilegibles o no regulares, incluidos los enlaces de metadatos colgantes, antes de crear un nuevo perfil. Si la actualización de metadatos falla, apply restaura el contenido anterior del perfil o elimina un perfil que acaba de crear, pero solo mientras el perfil aún contiene lo que se escribió; si otro programa lo cambió mientras tanto, apply mantiene esa versión y los informes "retroceder perfil omitido". Apply vuelve a comprobar el perfil antes de la copia de seguridad y el reemplazo; si detecta una edición concurrente, se niega con `desktop_profile_changed`. Revisar la edición y volver a aplicar. Si la restauración del perfil también falla después de un error de metadatos, la razón informada incluye ambos errores; reconcilia el perfil y los metadatos antes de volver a intentarlo. + + + +### Primera parte (opcional) + +:::caution[Riesgo para la cuenta] +El modo de primera parte envía su tráfico de suscripción Claude a través de un proxy de interceptación local. Anthropic puede tratar esto como una violación de sus términos y suspender la cuenta. Gateway es el default; elija la primera parte solo si acepta ese riesgo. +::: + +El escritorio en sí no está reconfigurado: permanece conectado a claude.ai, y la pestaña Chat, los conectores, las sesiones en la nube y el control remoto siguen funcionando. OpenCodex solo escribe estas variables en el bloque `env` de `~/.claude/settings.json` (honrado por `CLAUDE_CONFIG_DIR`): + +```json +{ + "env": { + "HTTPS_PROXY": "http://opencodex:@127.0.0.1:10200", + "NODE_EXTRA_CA_CERTS": "/.opencodex/claude-intercept/ca.pem", + "NO_PROXY": "127.0.0.1,localhost,::1,0.0.0.0" + } +} +``` + +`NO_PROXY` mantiene el tráfico de bucle, como un servidor local HTTP MCP en `127.0.0.1`, `localhost`, un nombre `*.localhost`, `::1` o `0.0.0.0`, fuera del proxy, que solo tuneliza HTTPS a hosts remotos. Un servidor en otra dirección `127.x` necesita que esa dirección se agregue a `NO_PROXY` usted mismo. Si ya ha establecido `NO_PROXY`, OpenCodex agrega solo las entradas de bucle invertido que faltan y registra su cambio en `opencodex-no-proxy.json` junto a `settings.json`. Desactivar first-party devuelve su valor original cuando OpenCodex podría registrarlo y no lo ha cambiado desde entonces; de lo contrario, se mantiene el valor actual, incluidas las entradas agregadas. + +Claude Desktop first-party enruta su pestaña Código y subagentes a través de OpenCodex. El Claude Code CLI independiente tiene un interruptor de primera parte separado. Ambos clientes leen el mismo proxy `~/.claude/settings.json` y la configuración de CA: si solo un conmutador está encendido, el otro cliente aún transita el proxy local, donde termina TLS, pero sus solicitudes Messages retransmiten a Anthropic sin cambios. Otros Anthropic caminos retransmiten sin cambios y los anfitriones no relacionados siguen siendo túneles ciegos. Con el interruptor CLI encendido, el `claude` independiente también enumera los modelos enrutados en `/model`; ver [Selector de modelos en el CLI](#model-picker-in-the-cli). + +:::note[Proxy del sistema en Windows: Clash, v2rayN y proxies corporativos] +Cuando la intent del selector está desactivada en el inicio de OpenCodex, su relé Windows permanece desatado. Selector de giro el modo en adelante lo inicia dentro del servicio en ejecución; OpenCodex no necesita un reinicio. Para instalaciones de selección o instalaciones pendientes sin perfil de selección aplicado, un proxy de sistema Windows se entrega a la pestaña Código como `HTTPS_PROXY`, y ese valor tiene prioridad sobre el proxy OpenCodex en `~/.claude/settings.json`. La pestaña Código entonces va alrededor de OpenCodex y los modelos enrutados fallan allí, mientras que el CLI independiente sigue funcionando. Un perfil de selector seleccionado aplicado utiliza el proxy de salida fijo de Desktop mientras está disponible, incluso cuando La falta de confianza deja al selector pendiente y `claude.ai` Retransmite a ciegas. Consejos de bypass del proxy del sistema Se aplica cuando no hay un perfil de selector disponible seleccionado. Añadir `api.anthropic.com` a la lista de bypass del sistema proxy de su cliente proxy (en Clash Verge, +`system_proxy_bypass`), a continuación, cierre completamente y vuelva a abrir Claude Desktop. `ocx doctor` informa esto bajo "Claude Proxy de escritorio de primera parte vs Windows sistema". No puede evaluar un script PAC o detección automática de proxy (WPAD, "Detectar automáticamente la configuración"), por lo que informa de ellos como desconocidos; Con cualquiera de los dos, haz que el guión regrese `DIRECT` por `api.anthropic.com` o desactivar la detección. Si el La configuración de primera parte es obsoleta, te pide que ejecutes `ocx ensure` En lugar de informar `ok`. +::: + +Los subagentes en los modelos enrutados (no Claude) no usan los hilos de mensajes del lado del servidor de Claude Code, porque solo Anthropic almacena ese estado. OpenCodex rechaza una solicitud roscada para tal modelo, y Claude Code reenvía ese giro, y los giros posteriores, con la conversación completa. + +El modo se mantiene como `claudeCode.desktopMode`. Las instalaciones que ya se aplicaban en cualquiera de los dos modos lo conservan, incluidas las instalaciones de origen desde antes de que persistiera el modo. Un modo explícito tiene prioridad; de lo contrario, una fila de pasarela seleccionada propia, una huella dactilar de pasarela aplicada o configuraciones propias de origen en `~/.claude/settings.json` determinan el modo existente antes del valor predeterminado de la pasarela. Una sincronización de catálogo o actualización de lista nunca escribe un perfil de puerta de enlace sobre una instalación de origen resuelta. Un CLI -only first-party env no es evidencia de que Desktop esté en modo first-party. La conmutación primero aplica el reemplazo, luego elimina la configuración del otro modo (solo los valores OpenCodex escritos: un `HTTPS_PROXY` o `NODE_EXTRA_CA_CERTS` extranjero, por ejemplo, un proxy corporativo, nunca se sobrescribe y en su lugar se rechaza la aplicación). Un reemplazo fallido conserva la conexión anterior. Si la retirada de la configuración anterior falla después de escribir el reemplazo, el comando informa de una limpieza incompleta; resuelva ese error antes de reiniciar Desktop. Una puerta de enlace comprometida mantiene su modo guardado y marcador de perfil incluso cuando falla la limpieza de la configuración de primera parte. Cierre completamente y vuelva a abrir el escritorio después de un cambio exitoso. `ocx ensure` refresca un env obsoleto de primera parte cuando la integración está ACTIVADA y lo elimina cuando está APAGADO. Establecer `claudeCode.intercept.enabled: false` para deshabilitar el proxy por completo; no se puede aplicar de primera parte. Se rechaza una solicitud de una instalación existente de origen cuando la intercepción está deshabilitada; las nuevas instalaciones aplican puerta de enlace. En un cliente conectado, el proxy se ejecuta en el concentrador, por lo que `ocx claude desktop apply` utiliza el perfil de puerta de enlace. + + + +### Modo de selector: modelos opencodex en el selector de pestaña de código de primera parte + +El modo Selector es parte del modo first party. En macOS y Windows está activado de forma predeterminada cuando se selecciona first-party, a menos que se establezca `claudeCode.intercept.picker: false`. Cambia el selector de pestañas de código de escritorio de primera parte para que enumere los modelos disponibles de opencodex por nombre. La primera vez que está habilitado, macOS puede pedirle que confíe en una autoridad de certificación local en el llavero de inicio de sesión, y Windows puede pedirle que confíe en el almacén raíz del usuario actual. Esa autoridad está limitada a `claude.ai` y sus subdominios. OpenCodex protege su identidad de firma exportable en el almacén de credenciales del sistema operativo y reutiliza el mismo certificado y clave validados en los reinicios normales. No se almacena ninguna clave de firma de selector de texto sin formato en el directorio de configuración OpenCodex. Todavía se aplican la validación de CA restringida completa y la verificación de confianza del sistema operativo, incluida la huella digital exacta con una hoja verificada en Windows. Con la misma identidad aprobada y un almacén de credenciales disponible, reiniciar OpenCodex no agrega ni elimina la configuración de confianza del certificado macOS. El reinicio y el estado nunca instalan confianza: si la confianza falta, se revoca o se desconoce, el selector permanece pendiente. Ejecute `ocx claude desktop picker on` o `ocx claude desktop picker trust` explícitamente para otorgar confianza, incluida la confirmación Windows cuando sea necesario. El inicio también intenta eliminar una clave de firma del selector en el disco antes de verificar si la interceptación está habilitada. La limpieza es el mejor esfuerzo y no permite la interceptación ni el bloqueo del inicio. + +La migración de una sola vez desde una identidad de selector anterior puede requerir el consentimiento para eliminar su confianza anterior. Si la limpieza no puede terminar, el selector permanece indisponible y el perfil aplicado utiliza un relé ciego hasta que la limpieza tenga éxito; `ocx claude desktop picker status` informa que el estado. macOS puede pedirle por separado que desbloquee el llavero o apruebe el acceso de una aplicación a las credenciales almacenadas. Estos mensajes de acceso nativos aún pueden ocurrir en el reinicio o la actualización. En Windows, `on` o `trust` explícito puede mostrar una confirmación para agregar la raíz. + +El modo Selector sigue sin soporte en Linux: OpenCodex no inicia ningún trabajo de CA, tienda de credenciales o proxy de selector allí. La intercepción principal Claude sigue estando disponible con la propiedad, enlace simbólico, permiso de archivo y Windows ACL comprueba la protección de sus archivos locales de CA. + +El modo Selector permite hasta 64 KiB de encabezados en las solicitudes entrantes y respuestas ordinarias HTTP, preservando las cookies de sesión del navegador. Los encabezados de respuesta ascendente más grandes devuelven 502 y registran `upstream:headers-too-large`, sin valores de cookies ni rutas de solicitud. Las conexiones actualizadas continúan retransmitiendo bytes directamente después del protocolo de enlace de solicitud. + +El modo Selector utiliza HTTP/2 con Claude Desktop, por lo que las transmisiones de chat de larga duración ya no utilizan las conexiones de Desktop a claude.ai. Las versiones anteriores podían dejar el chat atascado en "Sesión de carga cronometrada" mientras el modo selector estaba activado. Si el chat deja de cargarse con el modo selector activado, apáguelo con `ocx claude desktop picker off` e informe del problema. + +Mientras el modo selector está activado, Claude Desktop llega a la red a través de OpenCodex. Si OpenCodex se detiene, el Escritorio estará sin conexión hasta que lo reinicie completamente o desactive el modo de selección. Compruebe el estado con `ocx claude desktop picker status`; use `ocx claude desktop picker trust` para repetir el paso de confianza, o apáguelo con `ocx claude desktop picker off`. El tablero tiene el mismo interruptor de selección bajo **Conectar → Claude Desktop**. Después de seleccionar el perfil de selector, cierre completamente y vuelva a abrir Claude Desktop. + +El modo Selector es parte del modo de primera parte, por lo que el [Riesgo de cuenta de primera parte](#first-party-opt-in) también se aplica a él. El catálogo de escritorio y CLI reescribe los límites de fila y metadatos de uso compartido: si la adición de modelos enrutados supera un límite, OpenCodex devuelve el catálogo original de Anthropic sin cambios en lugar de publicar una lista parcial. + + + +### Utilice los modelos opencodex en la token Código de escritorio (enlaces de origen) + +En el modo first-party, el selector de modelos de la pestaña Código pertenece a claude.ai: sus filas (Opus 5.5, Sonnet 5, Haiku 4.5 y los modelos anteriores bajo **Más modelos**) provienen de su cuenta, y ninguna configuración local puede agregar una fila opencodex. Lo que llega a OpenCodex es el identificador de modelo Anthropic del selector en cada solicitud, por lo que une una fila de selector a una ruta opencodex: + +```bash +ocx claude desktop bind claude-sonnet-4-6 xai/grok-4.7 +ocx claude desktop bind claude-opus-4-6 native/gpt-6.1-sol +ocx claude desktop unbind claude-opus-4-6 +``` + +o utilice **Conectar → Claude Desktop → Fichas de código del modelo** en el panel de control. La selección de **Soneto 4.6** en la pestaña Código es servida por `xai/grok-4.7`. El selector guarda la etiqueta Anthropic, y el modelo todavía se presenta como ese modelo Claude por el indicador del sistema Claude Code, así que prefiere filas que no use de otra manera (las entradas **Más modelos** son buenas candidatas). Los enlaces surten efecto en la siguiente solicitud; El escritorio no necesita un reinicio. + +- Las rutas usan el vocabulario de ruta de escritorio: `provider/model`, o `native/` para el grupo nativo OpenAI. Una ruta debe ser una de las listas del panel de control como disponible. +- Un identificador de selector con fecha (`claude-haiku-4-5-20251001`) coincide con una unión sin fecha (`claude-haiku-4-5`), y `[1m]` y las selecciones de modo rápido siguen la misma unión. +- Los enlaces se almacenan en `claudeCode.intercept.modelMap` y se aplican solo al tráfico Claude Code que llega a través del proxy de intercepción local: la pestaña Código del escritorio y el `claude` CLI independiente en modo first-party. `ocx claude` sesiones y el punto final público `/v1/messages` las ignoran; el `claudeCode.modelMap` global todavía se aplica en todas partes, y un enlace lo gana para el mismo id. +- `ocx claude desktop status --json` informa de las uniones en efecto bajo `firstParty.modelBindings`. + + + +### Claude Code CLI de primera mano + +Encienda el interruptor CLI en Conecte → Claude, o ejecute `ocx claude config set --first-party on`; use `off` para deshabilitarlo. El interruptor es inmediato y rechaza `{enabled:false, cliFirstParty:true}` antes de que se guarde cualquier campo; también puede negarse a activarse si la intercepción local no está disponible, la CA no puede prepararse, la configuración no se puede leer o una configuración proxy extranjera posee las claves. Desactivar persiste incluso cuando la intercepción no está disponible; deshabilitar el enrutamiento Claude solo deja intacta una configuración propia env. Para el tráfico de terminal totalmente nativo con solo Desktop first-party activado, configure `NO_PROXY='*'` en el shell. Esto aún conlleva el riesgo de la cuenta de primera parte indicado anteriormente. Deshabilitar el enrutamiento Claude deja intactas las configuraciones de propiedad env. Mientras el oyente vinculado sigue ejecutándose, cada solicitud Messages se retransmite sin cambios; después de que se detiene, el `claude` simple no puede conectarse hasta que OpenCodex se ejecute o Desktop/ CLI sea desactivado. Nativo `ocx claude` establece `NO_PROXY=*` solo para un propietario env sin un extranjero heredado `HTTPS_PROXY` / `https_proxy`. Con un proxy externo, conserva ese valor y advierte que la intercepción propiedad de la configuración aún se aplica; desactiva o desactiva la configuración de Desktop/ CLI first party. La interfaz de usuario distingue la incertidumbre sobre si la configuración todavía apunta a su proxy (desconocido), un proxy opencodex que contiene tokens con una CA extranjera (extranjero: arreglar HTTPS_PROXY / NODE_EXTRA_CA_CERTS) y un proxy de bucle de retorno sin token al lado de una CA extranjera (local: la propiedad no está confirmada; quite HTTPS_PROXY si no se usa). Con ajustes aplicados coincidentes y un oyente vinculado pero con el enrutamiento desactivado Claude, desactivado significa que las solicitudes de retransmisión no se modifican mientras está vinculado; apague la primera parte para eliminar los ajustes. Una URL propia sin oyente se detiene; un oyente vinculado con una CA propia pero con puerto o token no coincidente se rompe incluso cuando el enrutamiento está desactivado. Con una intención en, detenido o roto, más pantallas de interceptación no elegibles routingOff: Claude enrutamiento o la intercepción está apagado, o esta máquina es un cliente de otro concentrador opencodex; habilitar la interceptación en esta máquina o a su vez de primera parte para eliminar la configuración. Cuando se detenga la interceptación, utilice **Iniciar interceptación** o `ocx claude intercept start` para volver a intentar dentro del servicio OpenCodex en ejecución. Guardar la configuración de la primera parte también lo inicia automáticamente. Un rechazo informa de enrutamiento deshabilitado, rol de cliente, un puerto público efímero, un puerto ocupado o un fallo de inicio. Para un puerto ocupado, libérelo o configure `claudeCode.intercept.port`. El inicio actualiza un entorno proxy Claude administrado existente solo después de que el proxy de intercepción se enlaza correctamente, utilizando su puerto vinculado; un puerto ocupado deja la configuración Claude sin cambios. Si un par ya está enlazado en un puerto diferente, la respuesta nombra ambos puertos; use el puerto enlazado o restaure el valor configurado. CLI no se aplica intent sin proxy; una intención con un proxy en vivo recibe el aviso de retransmisión compartida; cualquier proxy restante sin ninguna intención es residual, a menos que desconocido, extranjero o local tenga prioridad. + +- descubrimiento de puerta de enlace (`/model` → "Desde la puerta de enlace") no se utiliza, porque Claude Code solo consulta + `GET /v1/models` en una pasarela configurada. Los modelos enrutados llegan al selector de otra manera; ver + [Selector de modelos en el CLI](#model-picker-in-the-cli). También puede enlazar un Anthropic incorporado id del modelo a una ruta (`ocx claude desktop bind`(arriba) o usar `modelMap`. +- `ANTHROPIC_SMALL_FAST_MODEL` y `CLAUDE_CODE_SUBAGENT_MODEL` son elegidos por el CLI antes de que se envíe la solicitud. El `claude` de primera parte simple usa sus valores `settings.json`. Routed `ocx claude` también ofrece el [ajuste de fuerza subagente](#forced-claude-code-subagent-model) en la página Subagentes y a través del CLI. +- `ocx claude` y first-party coexisten: una sesión iniciada con `ocx claude` habla con `ANTHROPIC_BASE_URL` (plain HTTP en loopback), que `HTTPS_PROXY` no cubre, por lo que el proceso llega a OpenCodex directamente y el proxy simplemente no ve tráfico desde él. +- Claude Code honra a `HTTPS_PROXY` / `NODE_EXTRA_CA_CERTS` como se documenta para proxys corporativos; una versión CLI que deja de hacerlo dejaría de enrutar, no rompería el inicio de sesión. + + + +#### Selector de modelos en el CLI + +Con el interruptor de primera parte CLI encendido y el enrutamiento Claude habilitado, inicie un nuevo `claude` y abra `/model`. Sus modelos opencodex aparecen junto a los modelos Claude de su cuenta, etiquetados como " Grok 4.7 (xai)" y descritos con su ruta ( `opencodex · xai/grok-4.7` ). Escoger uno dirige esa sesión al modelo, al igual que un enlace. + +- Solo las nuevas `claude` sesiones recogen la lista. Reinicie cualquier sesión que ya se estaba ejecutando cuando encendió o apagó el interruptor. +- Claude Code guarda la lista durante aproximadamente una hora. Encender o apagar el interruptor, y `ocx ensure`, borrar esa copia guardada, por lo que el siguiente lanzamiento `claude` trae uno nuevo. Si faltan los modelos enrutados (el primer lanzamiento después de que se inicie OpenCodex puede fallarlos mientras los modelos aún se están descubriendo), ejecute `ocx ensure` y reinicie `claude`. +- Las filas usan identificadores de estilo Claude (por ejemplo, `claude-opus-4-8-…`), porque el CLI solo ofrece identificadores con forma de modelos Claude. La pestaña Código de Claude Desktop no se ve afectada; sigue usando [Obligaciones de primera parte](#use-opencodex-models-from-the-desktop-code-tab-first-party-bindings). + + + +## Claude Perfil de escritorio (modo puerta de enlace) + +El perfil de abajo está escrito solo en modo gateway. Claude Desktop utiliza un perfil separado del Claude Code. Abra **Conectar → Claude Desktop** en el tablero de instrumentos. La tarjeta **Modelos** tiene las dos opciones que la mayoría de la gente necesita: **Modelo predeterminado** aparece primero en Claude Desktop y se envía como el nivel Opus, y **Modelo de tarea rápida** responde a las solicitudes de nivel Haiku de Desktop. Elegir un modelo allí lo traslada a esa familia y lo convierte en el valor predeterminado de la familia. Para colocar cada ruta usted mismo, abra **Avanzado: asignación de niveles Claude**, donde cada ruta disponible se encuentra en una de las cuatro familias: Opus, Fábula, Soneto o Haiku. Todas las rutas comienzan en Opus con un nuevo perfil. La primera ruta Opus se convierte en el valor predeterminado general inicial, y cada familia no vacía siempre tiene un valor predeterminado de familia. + +Arrastre una fila a otra familia si lo desea. El arrastre es opcional: cada fila también tiene un control de movimiento visible que funciona con un mouse, un toque o un teclado. Utilice **Hacer predeterminado** para elegir el valor predeterminado de una familia y, a continuación, seleccione **Guardar y aplicar al escritorio**. Se permiten familias vacías. Si un valor predeterminado guardado no está disponible temporalmente, se utiliza la primera ruta disponible de esa familia hasta que vuelva. + +También puede administrar el mismo perfil desde la línea de comandos: + +Las instrucciones de edición de perfil a continuación describen el perfil local. La aplicación remota conectada se describe por separado a continuación. + +```bash +ocx claude desktop [apply] +ocx claude desktop show [--json] +ocx claude desktop status [--json] +ocx claude desktop move [--default] +ocx claude desktop default +ocx claude desktop export +ocx claude desktop import [--apply] +``` + +`ocx claude desktop` y `apply` aplican el modo seleccionado: la primera parte escribe el env del proxy Claude Code, la pasarela escribe el perfil actual en Claude Desktop. `show` da un resumen legible; `status` informa sobre el modo efectivo, el perfil aplicado o proxy env, drift, actividad de solicitud y (solo en modo puerta de enlace) salud de la política administrada Windows. Añadir `--json` para scripts. `export -` escribe la versión JSON a la salida estándar. Import valida el archivo completo antes de guardarlo, por lo que un archivo no válido deja el perfil actual sin cambios. Agregue `--apply` para escribir un perfil importado válido en Desktop inmediatamente. Use `none` solo para una familia vacía; cada familia no vacía debe mantener una predeterminada. + +En Windows, una directiva Claude administrada por máquina puede hacer que Desktop ignore el perfil local de terceros. OpenCodex informa esto como `present`; una política que no puede leer es `unknown`, que también es una advertencia en lugar de un resultado limpio. El diagnóstico informa solo de ese estado: no expone nombres o datos de valores de directiva, y nunca elimina ni pasa por alto la directiva. Resuelva la directiva con su administrador y, a continuación, cierre completamente y vuelva a abrir Claude Desktop. La aplicación de nuevo también conserva las claves de perfil que OpenCodex no posee al actualizar sus campos de puerta de enlace y modelo. + +Aplicar escrituras a los datos de usuario de Electron reales `configLibrary` de Claude Desktop: `~/Library/Application +Support/Claude/configLibrary` en macOS, `%APPDATA%\Claude\configLibrary` en Windows y `${XDG_CONFIG_HOME:-~/.config}/Claude/configLibrary` en Linux. Establezca `OPENCODEX_CLAUDE_DESKTOP_CONFIG_DIR` para una anulación de biblioteca explícita o `CLAUDE_USER_DATA_DIR` para una raíz de datos de usuario de escritorio alternativa. El directorio legacy `Claude-3p` no se lee ni se elimina automáticamente. + +Las rutas no Anthropic reciben alias estables como `claude-fable-5-p01q`, con un código de cuatro caracteres prefijado `p`. `claude-opus-4-8-p...` ID de perfil anteriores siguen siendo ID de compatibilidad de solo decodificación; los nuevos perfiles usan el formulario Fable. OpenCodex mantiene una ranura de fecha sintética separada internamente para que las asignaciones de perfil existentes se mantengan estables, pero no expone esa fecha como el ID de modelo de Desktop: Desktop actual construye fechas de terminal de tira al comparar modelos de sesión activa, lo que puede suprimir los cambios de modelo. Real Anthropic Claude rutas mantienen sus identificaciones reales. Las nuevas rutas son predeterminadas para la familia Opus, pero mover una ruta no cambia el proveedor o el modelo al que llama. Los indicadores de aplicación heredados `--static`, `--hybrid` y `--discovery-only` permanecen disponibles para scripts existentes. + + + +## Integración del entorno del sistema + +Cuando `claudeCode.systemEnv` se establece en `true` (por defecto: **apagado**), `ocx start` usa `launchctl setenv` para inyectar `ANTHROPIC_BASE_URL` y las variables de entorno relacionadas Claude Code en todo el sistema. Nuevas ventanas y pestañas de terminal, por lo tanto, encaminan commandos `claude` simples a través del proxy sin requerir la envoltura `ocx claude`. Los proyectiles ya abiertos no se ven afectados y deben reabrirse. El cambio de una ranura o palanca de modelo (`smallFastModel`, `tierModels`, `maxContextTokens`, auto-contexto, `autoCompactWindow`, `alwaysEnableEffort`) vuelve a aplicar la inyección de inmediato: una tecla opencodex inyectada anteriormente se actualiza, o se desactiva una vez que la configuración ya no la produce. Un valor que usted mismo establece con `launchctl setenv` antes de opencodex inyecta esa clave nunca se sobrescribe ni se elimina; una clave opencodex inyectada permanece opencodex -propiedad (refrescada, sin establecer y eliminada por `ocx stop`) incluso si cambia su valor a mano. + +`ocx stop` y el proxy shutdown **Desactivar las llaves inyectadas** (no restaura los valores anteriores - solo se eliminan las claves inyectadas por opencodex). El proxy también escribe `~/.opencodex/claude-env.sh`; `ocx start` instala un gancho de fuente `.zshrc` que lo carga automáticamente solo cuando un ejecutable Claude Code CLI está presente en `PATH`. El inicio y `ocx ensure` eliminan el gancho OpenCodex cuando Claude Code está ausente o la integración del entorno del sistema está inactiva. Claude Desktop utiliza su perfil separado y no causa la instalación del gancho de la terminal. + +Deshabilitar con `claudeCode.systemEnv: false` en la configuración o con el conmutador GUI. Esta función es solo macOS; en otras plataformas, use `ocx claude`. + + + +## Paso nativo Claude (perforación de suscripción) + +Sin ningún conjunto de anulación de autenticación, Claude Code mantiene su inicio de sesión claude.ai OAuth y lo envía al proxy. Las solicitudes de modelos genuinos `claude*` / `anthropic*` que no se reenvíen **verbatim** a `api.anthropic.com` con su credencial: betas, firmas pensantes, almacenamiento en caché rápido e identidad de facturación permanecen completamente nativas y los modelos enrutados siguen funcionando en la misma sesión a través de los alias del selector. + +**Manejo del encabezado:** encabezados salto por salto más `host`, `content-length`, `accept-encoding`, `x-opencodex-api-key` y `origin` siempre se eliminan antes del reenvío. En un enlace que no sea de bucle de retorno, el paso a través nativo también requiere una credencial proxy válida en `x-opencodex-api-key`; `Authorization` y `x-api-key` entonces pertenecen sólo a Anthropic. Se elimina un secreto de admisión de proxy que se encuentra en el encabezado de cualquiera de los proveedores, mientras que se conserva una credencial de proveedor genuina en el otro encabezado. Las cabeceras de credenciales unidas por comas ambiguas no se reenvían. + +El passthrough se activa cuando se cumplen todas estas condiciones: `nativePassthrough` no es `false`; el modelo comienza con `claude` o `anthropic`; el token portador o `x-api-key` comienza con `sk-ant-`; la resolución de alias/mapa de modelo devuelve el mismo modelo sin cambios; y, en un enlace sin retorno de bucle, la cabecera de admisión proxy dedicada es válida. Esto también significa que la advertencia "los conectores claude.ai están desactivados" ya no aparece con `ocx claude`. + +El único cambio en el cuerpo son los identificadores de llamada a herramientas. Un `tool_use.id` o `tool_result.tool_use_id` que el Anthropic rechazaría (personajes fuera de `a-zA-Z0-9_-`, o más largo que 64), tal como un modelo encaminado acuñado antes en la sesión, se vuelve a escribir a un id conforme con su par de llamada/resultado guardado. Los identificadores conformes se envían sin cambios, y un identificador vacío se responde con un identificador local 400. + +Deshabilitar con `claudeCode.nativePassthrough: false`; punto en otro lugar con `claudeCode.anthropicBaseUrl`. + + + +## Claude Desktop en un centro remoto conectado + +Cuando esta máquina está conectada a un concentrador, `ocx claude desktop apply` (o `ocx claude desktop` ) utiliza la instantánea del modelo de escritorio del concentrador. Escribe el origen del concentrador conectado y los ID de modelo emitidos por el concentrador en la configuración del escritorio local sin generar alias de reemplazo localmente. Los modos estático e híbrido copian las entradas de instantánea; el modo de solo descubrimiento usa el origen de concentrador sin incrustar la lista de modelos. + +El concentrador posee el perfil de escritorio, las asignaciones familiares y los valores predeterminados. Cambie esos en el concentrador, luego aplique nuevamente en el cliente conectado y vuelva a seleccionar el modelo en Desktop. Los alias antiguos creados solo en el cliente requieren volver a aplicar/reselección; no se migran automáticamente. Local `show`, las ediciones de perfil y la importación/exportación siguen siendo vistas y operaciones locales, no gestión de perfil de concentrador. Mientras está conectado, `ocx claude desktop import --apply` no es compatible y rechaza la importación antes de guardar. La importación sin `--apply` sigue siendo local. + +Apply lee la instantánea utilizando la credencial de datos de la conexión existente. No necesita token de administración y no carga ningún perfil. Si el concentrador es demasiado antiguo para admitir la instantánea, la respuesta no es válida o no hay modelos de escritorio disponibles, se aplican errores sin sustituir un catálogo local o un origen de bucle de retorno. Actualizar/configurar el concentrador y volver a aplicar. + +Este cambio de alias no corrige la solicitud separada de reproducción y caché de mensajes `thinking` / `redacted_thinking` en [#3719](https://github.com/lidge-jun/opencodex/issues/3719). La admisión de proxy por sí sola no permite la transferencia nativa Anthropic; las rutas traducidas Anthropic aún pueden usar el almacenamiento en caché rápido. La fidelidad de reproducción y las comparaciones de caché siguen siendo un trabajo separado. + + + +### Rotación, recuperación y desconexión de llaves + +La rotación de claves y la recuperación actualizan la credencial almacenada en el perfil de Desktop propiedad de la conexión junto con la credencial de conexión local. No se requiere volver a aplicar el escritorio manual solo para migrar la clave. Se conservan los ID de modelo existentes, las opciones de familia/predeterminado y la selección de perfil actual del usuario; la rotación no vuelve a seleccionar el perfil administrado ni vuelve a habilitar una integración deshabilitada. CLI JSON `rotation: "committed"` significa que la nueva clave está activa. `rotation: "rolled_back"` significa que la clave anterior fue retenida o restaurada, no que una nueva clave fue comprometida o la clave anterior revocada. La recuperación incierta o incompleta se informa como tal, en lugar de como una rotación exitosa. + +La primera aplicación conectada registra los ajustes y la selección administrados anteriores para la restauración. La aplicación repetida y la rotación de la tecla conservan esa línea de base original. `ocx disconnect` restaura la configuración de propiedad de la conexión al tiempo que conserva los campos agregados por el usuario actuales y los perfiles no relacionados. La selección anterior se restaura solo si el perfil administrado sigue seleccionado; una selección de usuario válida posterior permanece seleccionada. Un perfil recién creado con adiciones de usuario se conserva en modo estándar legible en lugar de eliminar esas adiciones. `--keep-catalog` mantiene el catálogo, no la credencial de conexión de escritorio. + +Para un perfil administrado más antiguo sin un registro original, OpenCodex puede migrarlo cuando pertenece inequívocamente al concentrador actual y a una clave de conexión reconocida. Aplicar, rotación / recuperación o desconexión directa puede manejar este caso sin una nueva bandera o requisito previo volver a aplicar. Una advertencia explica que la desconexión utilizará el modo estándar porque no se registraron los ajustes anteriores. Esa reserva elimina solo la configuración de la puerta de enlace propiedad de la conexión, conserva los campos de usuario y una selección válida separada, y se informa como reserva estándar, no como restauración original. + +Los campos gestionados en conflicto, las credenciales no reconocidas o los registros de restauración dañados se conservan y se notifican para su resolución. La limpieza interrumpida puede reanudarse para la misma conexión; no borra una conexión más nueva o reclama la finalización mientras la restauración permanece incompleta. Termine la recuperación de rotación pendiente antes de iniciar la desconexión y conserve la misma opción de catálogo al volver a intentarlo. + +Cierre completamente y vuelva a abrir Claude Desktop después de aplicar, rotación / recuperación o restauración: el cambio de archivos no reemplaza una credencial que ya tiene la aplicación en ejecución. OpenCodex no mata/reinicia la aplicación automáticamente. Disconnect funciona localmente sin revocar automáticamente la clave de concentrador o borrar copias externas arbitrarias; revoque por separado en el concentrador si lo desea. + + + +## El selector /model ("Desde la puerta de enlace") + +Claude Code 2.1.129+ descubre modelos de puerta de enlace a través de `GET /v1/models?limit=1000` y los enumera en el selector nativo `/model`. Una fila sin un `description` dice "Desde la puerta de enlace"; opencodex envía uno por cada fila Claude Code CLI (`Routed by OpenCodex to /`; las filas nativas usan `Routed by OpenCodex to native `, las filas rápidas agregan ` · Fast` y las filas 1M mantienen la descripción base), que Claude Code muestra 2.1.257 + en su lugar. Claude Code 2.1.278 acepta un identificador de selector que contiene `claude` o `anthropic`. Un identificador no reconocido que comienza con `claude-` se contabiliza en 200k a menos que se desactive el compacto, por lo que opencodex expone los modelos enrutados como alias estables y reversibles que contienen `claude` pero no comienzan con `claude-`: + +| Superficie | Formato | Ejemplo | +| --- | --- | --- | +| Claude Code CLI | `ocx-claude---` (plano) o `ocx-claude2-…` (escapado) | `ocx-claude-native--gpt-5.6-sol` | +| Claude Desktop 3P | `claude-fable-5-p` (ranura de perfil de base36 3-char) | `claude-fable-5-p01q` | + +El proxy elige la familia por solicitud: `?ids=cli` o `?ids=desktop` gana; de lo contrario, el agente de usuario `claude-code/*` obtiene el formulario CLI legible y otros clientes obtienen el código de escritorio. Ambas familias decodifican para siempre: un modelo guardado en `settings.json` bajo cualquier forma sigue funcionando. Cada entrada lleva un nombre de visualización honesto como `gemini-3-pro (gemini)`, más capacidades de modelo completo (escalera de esfuerzo de razonamiento, tipos de pensamiento) en la forma oficial de ModelInfo para que el modo de puerta de enlace de terceros de Claude Desktop pueda ofrecer su selector de esfuerzo. Los modelos Real Anthropic mantienen sus identificaciones canónicas. La fecha 2026 sintética es una ranura interna, no una fecha de lanzamiento. Los alias hash heredados y los identificadores `claude-ocx---` / `claude-ocx2---` de configuraciones anteriores aún se resuelven. Una identificación heredada configurada en una ranura de modelo OpenCodex (`claudeCode.model`, `tierModels`, `smallFastModel`) se envía automáticamente a Claude Code en su ortografía actual. Un id legado guardado por el propio selector de Claude Code sigue las rutas, pero Claude Code mantiene sus 200k contabilizando ese id. Elija `ocx-claude-` para una identificación guardada de `claude-ocx-`, y `ocx-claude2-` para una identificación guardada de `claude-ocx2-` escapado, por lo que se aplican tanto la ventana de contexto de catálogo efectiva como la compacta. + +Los perfiles administrados más antiguos expusieron directamente sus ranuras internas `YYYYMMDD`. El escritorio afectado crea una tira de esa fecha de terminal al comparar modelos de sesión activa, por lo que dos rutas distintas pueden parecer idénticas y no se envía ninguna solicitud de control `set_model` ([#3782](https://github.com/lidge-jun/opencodex/issues/3782)). Los perfiles actuales exponen códigos no fechados en su lugar. Después de actualizar, vuelva a aplicar el perfil de escritorio y salga completamente y vuelva a abrir el escritorio; un trabajador que ya esté en ejecución aún puede conservar su antiguo ID en forma de fecha. El proxy continúa decodificando esos identificadores antiguos para la migración, pero no puede hacer que Desktop emita un switch suprimido. + +También puede intentar seleccionar el modelo predeterminado previsto en el perfil OpenCodex Claude Desktop, volver a aplicar el perfil e iniciar una nueva conversación. Este es un paso de solución de problemas, no una solución garantizada. OpenCodex no puede observar el estado del selector; enruta la identificación del modelo que lleva cada solicitud. Confirme lo que el cliente envía bajo **Logs → requestedModel**. + +Modelos con una ventana de contexto larga (1M, o al menos el umbral de compactación predeterminado de 829.800 tokens; Claude modelos en una ruta Anthropic necesitan un genuino 1M) obtener una fila extra `…[1m]` selector: selección que hace Claude Code cuenta un contexto 1M completo para ese modelo (autocompactación se mantiene encendido) - el proxy tiras el marcador antes de enrutamiento. Al seleccionar uno, se mantiene en el campo Claude Code's `settings.json` `model`; las solicitudes entrantes resuelven el alias de vuelta al modelo enrutado. En versiones anteriores de Claude Code, el selector permanece nativo: establece ranuras a través de `ANTHROPIC_MODEL` o escribe cualquier id enrutado con `/model` (Claude Code pasa cadenas). + +**Reglas de gramática de Alias:** proveedor no debe contener `/` o `--` o igual `native`. Los identificadores de los modelos simples (no `/` o `~` ) mantienen el prefijo v1 `ocx-claude-…`. Los identificadores de modelo que contienen `/` o `~` acuñan el prefijo v2 `ocx-claude2-…` con escapes (`/` → `~s`, `~` → `~t` ), p. ej. `openrouter/anthropic/claude-opus-4-8` → `ocx-claude2-openrouter--anthropic~sclaude-opus-4-8`. Los alias v1 decodifican literalmente (de modo que se conserva un identificador de modelo histórico que contenía las secuencias de dos caracteres `~s` / `~t`); los alias v2 expanden los escapes. Las rutas que el formulario legible no puede expresar vuelven al alias hash. Los identificadores del modelo PUEDEN contener `--` (las divisiones de resolución en el primer `--` solamente); las identificadores nativas que contienen `--` vuelven a la forma hash. + +**Orden de resolución del modelo:** `[1m]` marcador despojado → alias legible decodificado → Alias de hash de escritorio decodificado → `modelMap` coincidencia exacta → coincidencia de fecha desprovista (`-20250514` eliminado) → paso. + + + +Un ID de escritorio en forma de fecha no resuelto también puede ser un modelo nativo genuino que falta en el descubrimiento. Messages y count-tokens devuelven HTTP 503 con el error `desktop_model_mapping_unavailable` fijo cuando la evidencia disponible no puede resolver ese ID; esto no establece que el modelo no es válido. Los alias de hash heredados desconocidos todavía devuelven HTTP 400. Ninguno de los casos quita la fecha o vuelve a otra ruta. Los ID conocidos, las asignaciones registradas y las coincidencias exactas `modelMap` mantienen su comportamiento existente, incluidos los ID nativos reales reconocidos. Actualizar el descubrimiento del modelo o volver a aplicar el perfil del concentrador conectado antes de volver a intentarlo; reintentar solo no garantiza la resolución. + +Cada entrada lleva un nombre de pantalla como `gemini-3-pro (gemini)`, más capacidades de modelo completo (escalera de esfuerzo de razonamiento, tipos de pensamiento) en la forma oficial `ModelInfo`. Los modelos Real Anthropic mantienen sus identificaciones canónicas en ambas superficies. + + + +### Variante de contexto `[1m]` marcador + +Estas comprobaciones utilizan la ventana de catálogo efectiva, que puede incluir un [Estimación del proveedor personalizado](/es/reference/configuration/providers/#context-windows-on-custom-providers). Una estimación no verifica la capacidad real del relé. + +Los modelos con una ventana de contexto de catálogo efectiva de 1M, o al menos el umbral de compactación predeterminado de 829.800 tokens, obtienen una fila de selectores `…[1m]` adicional; el piso es fijo, por lo que un valor de compactación personalizado no lo baja, y los modelos Claude en una ruta Anthropic necesitan un 1M genuino. Desactivar el autocontexto limita la fila a ventanas de 1M. Seleccionarlo hace que la cuenta Claude Code sea un contexto completo de 1M. El proxy quita el sufijo `[1m]` insensible a mayúsculas y minúsculas antes de la resolución y el enrutamiento de alias. + + + +## Contexto automático (modelos de gran contexto sin techo de 200k) + +Claude Code cuentas 200k tokens para cualquier modelo que no reconozca. **Contexto automático** (activado por defecto) corrige que: + +1. Las ranuras env de lanzamiento obtienen el marcador `[1m]` cuando la ventana de catálogo efectiva del modelo está por encima de 200k **y** al menos el umbral autocompacto configurado. Las filas del selector Discovery y Desktop no siguen ese umbral: usan el piso fijo de 829.800 tokens (un 1M genuino para los modelos Claude en una ruta Anthropic). +2. `CLAUDE_CODE_AUTO_COMPACT_WINDOW` (valor predeterminado `829800`, rango `100000` - `1000000`) se inyecta para que la conversación se resume automáticamente en ese punto. + +Tres estados de configuración: + +- **ausente / `true`:** habilitado (predeterminado) +- **`false`:** desactivado - sin marcadores, sin inyección de ventana de compactación +- **set legado `maxContextTokens`:** auto-contexto está implícitamente deshabilitado + +El valor de compactación es ajustable en la página Claude. **Aviso:** elevarlo más allá de la ventana real de un modelo rompe ese modelo: los errores de chat se eliminan antes de que el resumen pueda disparar. + +La ventana de contexto anunciada de un modelo no garantiza que una solicitud pesada de herramientas se ajuste al límite de entrada ascendente. Un rechazo de límite de entrada clasificado alcanza Claude Code como `invalid_request_error` con `context_length_exceeded`, redactado de la manera Anthropic palabras ( `prompt is too long: …` ), por lo que Claude Code compacta la conversación y vuelve a intentar por sí solo; una respuesta sin transmisión usa HTTP 400 en lugar de una 502 reintentable. Los proveedores en el carril nativo Messages tienen la misma redacción. + +La normalización de desbordamiento usa solo el primer **65.536 unidades de código UTF-16** del mensaje de error del proveedor, incluidos los mensajes que ya usan la redacción de Anthropic. Este es un límite de longitud de cadena, no un límite de bytes o tokens. El texto más allá se descarta sin un marcador de truncamiento o elipsis, por lo que los detalles de diagnóstico y los recuentos de tokens cerca del final pueden estar ausentes del error que recibe Claude Code. El prefijo añadido `prompt is too long:`, seguido de un espacio, puede hacer que el mensaje final sea más largo que esta parte retenida. + +Dentro de esa parte, se mantiene la redacción Anthropic reconocida; de lo contrario, OpenCodex emite `prompt is too long: tokens > maximum` solo cuando encuentra `maximum context length is tokens` seguido de `resulted in tokens` o `you requested tokens`. Utiliza el primer límite establecido y el primer recuento de solicitudes coincidentes después de él. Si ese par falta, se invierte o se corta, prefija el texto retenido con `prompt is too long:` seguido de un espacio, sin inventar cuentas. Un límite de rendimiento que solo menciona tokens (por ejemplo, "demasiados tokens por minuto") mantiene su texto y no se trata como un desbordamiento. + +Si la compactación en sí misma aún excede el límite, conserva el historial original e intenta compactar una bifurcación con menos herramientas habilitadas o esquemas MCP, si tu cliente admite ese flujo de trabajo. Un marcador `[1m]` o una configuración de contabilidad de cliente más grande no eleva el límite ascendente, y OpenCodex no elimina silenciosamente el historial o las herramientas para que encaje. + +Los modelos Anthropic nativos Sub-1M nunca se marcan automáticamente. Una ventana compacta que usted mismo exporta gana para el marcado de la ranura de lanzamiento (el proxy utiliza su valor para decidir qué modelos son seguros para marcar). Las filas de descubrimiento ignoran esa exportación y mantienen el piso fijo. Los valores de configuración no válidos editados manualmente vuelven a 829.800. + + + +### Contabilidad de contexto (1M por defecto, 200k opt-in) + +`claudeCode.contextAccounting` decide lo que opencodex escoge por defecto. Ausente (`1m`, el predeterminado), los modelos de ventana larga se ofrecen a 1M en las ranuras de env de lanzamiento, los selectores de escritorio, Desktop 3P (`prefer1m`) y subagentes generados. Configure `200k` para excluirse: nada se marca `[1m]` automáticamente, `CLAUDE_CODE_AUTO_COMPACT_WINDOW` no se inyecta y Desktop 3P cae `prefer1m` mientras mantiene `supports1m`. Un selector que usted mismo marca como `[1m]` permanece disponible (los subagentes generados y forzados aún dejan caer un marcador que la ventana del modelo no puede llevar), y el descubrimiento aún enumera las `· 1M` filas de modelos con ventanas de catálogo de al menos 1M. `200k` gana sobre el contexto automático: una ventana compacta que exporta ya no activa el marcado automático, aunque opencodex deja su propia exportación en su lugar. + +```bash +ocx claude config set --context-accounting 200k +``` + + + +### Entorno modelo eficaz + +`effectiveModelEnv` calcula seis ranuras inyectadas por `ocx claude` / system env / shell file: +`ANTHROPIC_MODEL`, cuatro `ANTHROPIC_DEFAULT_{OPUS,SONNET,HAIKU,FABLE}_MODEL`, y legado +`ANTHROPIC_SMALL_FAST_MODEL`. El haiku efectivo es `tierModels.haiku ?? smallFastModel`, alimentado a las dos variables del haiku. + +Cuando `ocx claude` se lanza en modo de suscripción, el propio inicio de sesión de Claude Code lleva una identificación desnuda de Claude como `claude-sonnet-5` directamente a Anthropic, por lo que esos id toman sus ventanas de contexto del registro del proveedor, lo que sea que otro proveedor enumere bajo la misma identificación. Una ranura Opus, Sonnet o Fable desactivada obtiene el identificador nativo Claude Code y resuelve ese alias, con el marcador `[1m]`, porque detrás de una puerta de enlace Claude Code cuenta con un identificador sin marcar en 200k. Una fila `anthropic` tapada por debajo de 1M o una entrada `claudeCode.modelMap` mantiene su identificación sin marcar, y el Haiku nunca se llena ni se marca. Cuando el lanzamiento utiliza autenticación proxy o `nativePassthrough` está desactivado, el enrutador decide, y solo cuenta la ventana de una fila enrutada. El env del sistema y el archivo de shell dejan espacios sin establecer vacíos, ya que sus valores también alcanzan lanzamientos que pasan por un concentrador. + +Cuando tanto `tierModels.haiku` como `smallFastModel` están ausentes, OpenCodex deja ambas variables auxiliares sin establecer; Claude Code luego elige su modelo de ayudante nativo (actualmente Sonnet), que puede incurrir en cargos de proveedor nativo. + + + +## Agentes de lista (injectAgents) + +Proxy inicio / asegurar, `ocx claude`, y el tablero de instrumentos relevante guarda sincronizar su lista de subagentes destacados (pestaña Subagentes, hasta 5 modelos) más `ocx-self` en `~/.claude/agents/ocx-*.md`. + +- **`ocx-self`** pines su `/model` selector predeterminado (regresando a `claudeCode.model`); omitido cuando ninguno existe. No utiliza la herencia modelo. +- Cada cuerpo de agente contiene una directiva ``: el proxy usa esto para fijar la ruta real. Por lo tanto, el argumento `model` de la herramienta Agente es inerte; pase `"haiku"` como marcador de posición. +- Frontmatter lleva el alias; el enrutamiento es impulsado por directivas. +- Solo los archivos `ocx-*.md` verificados con marcadores que contienen `generated-by: opencodex` se sobrescriben o podan; sus propios agentes nunca se tocan. +- Los archivos se sincronizan atómicamente por archivo (escribir + renombrar). +- `enabled: false` o `injectAgents: false` podan todas las definiciones de propiedad verificada. +- El éxito CLI guarda de primera parte y persiste la configuración de primera parte del escritorio también intenta la sincronización de la lista de mejor esfuerzo, incluida la configuración repetida para reparar las definiciones que faltan. La configuración y la reversión rechazadas no sincronizan los agentes. Desactivar el registro de primera persona por sí solo no deshabilita el registro del agente. +- Los cambios de GUI PUT y de lista se vuelven a sincronizar inmediatamente; cada inicio/garantía de proxy en primer plano o en segundo plano reconcilia los archivos de propiedad antes de que un lanzamiento posterior Claude Code los lea. Inicie una nueva sesión Claude después del registro para que cargue las definiciones generadas. + +Despacho: `subagent_type: "ocx-gpt-5-6-sol"`. Los objetivos con capacidad de 1M transportan automáticamente `[1m]`. + + + +## Elisión de habilidades agrupadas (blockedSkills) + +Claude Code 's incluido `claude-api` habilidad inyecta? 840KB (? 136k tokens) de Anthropic documentación que auto-dispara en Claude menciones modelo. Los modelos enrutados no están entrenados en ese paquete, por lo que por defecto opencodex reemplaza el contenido de la habilidad con un stub corto en **Enrutado** solicitudes. Native Anthropic passthrough no ha sido tocado. + +**Se manejan dos transportistas:** + +1. **Portaherramientas de resultados:** asistente `Skill(...)` llama - el cuerpo `tool_result` emparejado se reemplaza por un stub cuando la entrada JSON de carcasa inferior contiene un nombre bloqueado. +2. **Portador de bloque de texto:** un bloque de texto de usuario ≥ 10.000 caracteres a partir de `Base directory for this skill: ` - emparejado cuando el nombre base de directorio es igual a un nombre bloqueado (insensible a mayúsculas). La línea de directorio se inspecciona solo hasta 4.096 unidades de código UTF-16; una línea más larga se envía sin cambios, incluso cuando no tiene una nueva línea de terminación. + +Configurar con `claudeCode.blockedSkills` (por defecto `["claude-api"]`; `[]` deshabilita la elisión por completo). El stub mantiene intacto el emparejamiento de llamada/resultado de la herramienta. + + + +## Mapa de modelos (intercepción) + +`claudeCode.modelMap` reescribe los identificadores de modelo de entrada Anthropic antes del enrutamiento: + +```json +{ + "claudeCode": { + "modelMap": { + "claude-sonnet-4-5": "gemini/gemini-3-pro", + "claude-haiku-4-5": "gemini/gemini-3-flash" + } + } +} +``` + +Orden de búsqueda: descubrimiento alias → id exacto → id con fecha sufijo despojado (`-20250514`) → passthrough. + +Véase [Resolución de alias de escritorio](#desktop-alias-resolution) para la política de rechazo. + + + +## Matriz Sidecar: búsqueda web y comprensión de imágenes + +Los modelos enrutados no todos tienen las mismas herramientas alojadas o soporte de imágenes. opencodex llena esos vacíos antes de que el modelo principal responda: + +- El **web-buscar sidecar** ejecuta la búsqueda alojada real, luego le da al modelo enrutado la respuesta y las fuentes como resultado de la herramienta. +- El **visión sidecar** describe una imagen adjunta antes de llamar a un modelo listado en `noVisionModels`, luego reemplaza la imagen con esa descripción. + +Ambos sidecars pueden usar cualquiera de los dos backend: + +| Backend | Cómo funciona | Lo que se requiere | +| --- | --- | --- | +| `openai` | Un pequeño modelo GPT a través del proveedor ChatGPT `forward` | Un inicio de sesión ChatGPT y un proveedor habilitado `authMode: "forward"` | +| `anthropic` | Claude a través de Anthropic OAuth almacenado; la búsqueda web utiliza `web_search_20250305` y la visión envía la imagen a Claude para su descripción | Un proveedor `adapter: "anthropic"`, `authMode: "oauth"` habilitado cuya cuenta activa almacenada no está marcada como `needsReauth` | + +Un `backend` explícito siempre gana. Cuando se omite, el sidecar **web-search** siempre selecciona `openai` (`anthropic` se ejecuta solo cuando se configura explícitamente), mientras que el sidecar **visión** selecciona `anthropic` si existe una cuenta Anthropic OAuth almacenada utilizable, de lo contrario `openai`. La selección explícita de `anthropic` sin una credencial utilizable **falla cerrado**: opencodex no toma prestadas silenciosamente credenciales ChatGPT ni cambia los backends. El backend OpenAI también se mantiene apagado sin autorización de inicio de sesión y sin un proveedor de forward. + +Claude -las repeticiones enrutadas de entrada unen el inicio de sesión principal de ChatGPT a la solicitud interna, de modo que OpenAI sidecars permanecen accesibles incluso aunque el portador de entrada de Claude Code sea solo la credencial de proxy. Ese portador nunca se reenvía al proveedor principal enrutado. + +```json +{ + "webSearchSidecar": { + "backend": "anthropic", + "model": "claude-sonnet-5", + "maxSearchesPerTurn": 3 + }, + "visionSidecar": { + "backend": "anthropic", + "model": "claude-sonnet-5", + "maxDescriptionsPerTurn": 8 + } +} +``` + +`maxDescriptionsPerTurn` limita las nuevas descripciones de imágenes en un turno de modelo principal. Los hits de caché y las descripciones duplicadas en vuelo no consumen el límite. Las descripciones exitosas para las imágenes `data:` se almacenan en caché por backend, modelo, detalle, bytes de imagen y contexto de solicitud, por lo que el mismo par imagen-contexto no se describe de nuevo en cada repetición. Las imágenes remotas `https:` nunca se almacenan en caché porque su contenido puede cambiar. + +Vea el [referencia de configuración](/es/reference/configuration/server/#sidecars) para cada clave. Anthropic - OAuth búsqueda web y descripción de la imagen reutilizar el repositorio existente Claude Code OAuth huella dactilar precedente, pero aún debe ser probado en remojo con su cuenta y la carga de trabajo antes de que dependa de ellos para largas carreras desatendidas. + + + + + +## Herramientas de cliente en rutas Cursor + +Cuando Claude Code utiliza un modelo respaldado por Cursor, OpenCodex conserva nombres de herramientas de clientes reconocidos como `Bash`, `Read`, `Write`, `Edit`, `Grep`, `Glob` y `Task` en el catálogo Cursor, la guía de herramientas y las llamadas reproducidas. Esto mantiene los nombres consistentes con las instrucciones de Claude Code. Denegado Cursor -los marcos de ejecución nativos dirigen el modelo a las herramientas de cliente disponibles que giran. + +Un catálogo mixto que contiene un puente Codex `exec_command` o `shell_command` usa alias de cable como `ocx_client_Read` para evitar colisiones de herramientas Cursor; las llamadas devueltas a Claude Code todavía usan sus nombres de herramientas originales. Las herramientas Namespace MCP mantienen sus identidades namespace. OpenCodex incluye estos alias en el presupuesto de bytes de transporte de Cursor, por lo que se omite una herramienta cuya definición excedería el límite para ese turno. + + + +## Esfuerzo de razonamiento + +En las solicitudes traducidas Messages → Responses, Claude Code `/effort` Configuración de mapas de la siguiente manera: + +| Formato de alambre | Mapeo | +| --- | --- | +| `thinking.type: "adaptive"` + `output_config.effort` | Esfuerzo pasado directamente ( `minimal` `low` `medium` `high` `xhigh` `max` `ultra`) | +| `thinking.type: "enabled"` + `budget_tokens` | ≤ 4096 → `low`, ≤ 16384 → `medium`, por encima de → `high` | +| `thinking.type: "disabled"` | `reasoning: { effort: "none" }`; resumen omitido | + +Para las solicitudes traducidas, el nivel resuelto aparece en la columna **Esfuerzo de razonamiento** del registro de solicitudes. Gestionado nativo Messages registro habilitado pensamiento presupuestos como `budget:` cuando no reconoce `output_config.effort` está presente; este registro no cambia el cuerpo del cable. + + + +## Traducción entrante (Messages → Responses) + +El proxy traduce cada solicitud Anthropic Messages API al formato Codex Responses API: + +| Messages entrada | Responses salida | +| --- | --- | +| Nivel superior `system` | `instructions` (bloques de texto unidos con `\n\n`) | +| `messages[].role: "system"` | También doblado en `instructions` | +| Texto / imagen del usuario | `input_text` / `input_image` (base64 → URL de datos) | +| Texto del asistente | `output_text` | +| Asistente `tool_use` | `function_call` ( `input` → JSON -stringed `arguments` ) | +| Usuario `tool_result` | `function_call_output` (prefijo `is_error` → `[tool error]`) | +| `tool_reference` en un resultado de herramienta | Texto `Tool loaded: ` en el resultado emparejado; conserva los nombres de las herramientas cargadas sin agregar declaraciones ni habilitar el aplazamiento del lado del servidor traducido | +| `thinking` / `redacted_thinking` repetición | `reasoning` artículos con `ocxr1` sobres limitados para firmas y cargas útiles redactadas | +| Herramientas de función | `{type: "function"}` (`web_search*` → `{type: "web_search"}`). En una ruta a `api.anthropic.com`, las declaraciones `web_search_*` y `web_fetch_*` escritas también se envían a Anthropic como se declara y se ejecutan en el lado del servidor, a menos que el propio sidecar de búsqueda web suministre `web_search`. Una búsqueda o búsqueda con una llamada coincidente y entrada completa vuelve al cliente como su bloque `server_tool_use` y su bloque `web_search_tool_result` o `web_fetch_tool_result`, literalmente. Los resultados huérfanos se eliminan sin sintetizar una llamada, mientras que el texto circundante se conserva. Cuando el cliente envía un par completo en su historial, la siguiente solicitud `api.anthropic.com` lo lleva en su lugar solo si el siguiente bloque identifica de forma única su turno original. Anclajes repetidos, identificadores de llamada/resultado no coincidentes o duplicados, entrada de llamada malformada o un resultado que aparece antes de que su llamada caiga en el intercambio. La entrada de llamada debe ser un objeto con una consulta de búsqueda no vacía o una cadena de URL de búsqueda; otros destinos nunca ven el intercambio | +| `tool_choice` | `auto` → `auto`, `none` → `none`, `any` → `required`, llamada función → `{type:"function",name}`, alojada WebSearch/ web_search → `{type:"web_search"}` | +| `max_tokens` | `max_output_tokens` | +| `stop_sequences` | `stop` | + +El modo automático Claude Code siempre envía `stop_sequences`. Para los modelos de la lista `noStopModels` del proveedor enrutado, OpenCodex omite `stop` en los cables Chat Completions y Responses, por lo que los modelos de razonamiento xAI como el grok-4.7 y el grok-4.6 no devuelven `400 invalid-argument` y se marcan temporalmente no disponibles. Véase [`noStopModels`](/es/reference/configuration/providers/). + +Replay conserva los bloques firmados no ocultos (incluido el pensamiento vacío) y los bloques redactados opacos en el adaptador Anthropic previsto. `hideThinkingSummary` permanece sin cambios: el texto firmado localmente oculto no está expuesto a Claude clientes, y la reproducción sin pérdida a través de ese límite oculto Claude no se establece. Los sobres de razonamiento combinados más antiguos no pueden recuperar el orden de bloque original una vez que se ha emitido el texto de transmisión. `claudeCode.compatibility: "enforce"` todavía rechaza la repetición del pensamiento. Esto no establece la aceptación de Anthropic en vivo ni las mejoras de caché. [#3719](https://github.com/lidge-jun/opencodex/issues/3719) permanece abierto. + +**Casos de error (400):** malformado JSON; faltante/vacío `model`; faltante/vacío `messages`; papel no soportado; `tool_result` sin `tool_use_id`; `tool_use` sin id/name; nombrado `tool_choice` sin nombre. + + + +### Patrones de propiedad Unicode en esquemas de herramientas + +Un esquema JSON `pattern` escrito para JavaScript puede usar escapes de propiedad Unicode como `\p{Cc}` o `\P{L}`. OpenAI -family backends validan `pattern` compilándolo con el `re` de Python, que no admite esos escapes, y un esquema que no pueden compilar se rechaza entero, por lo que un solo patrón de este tipo en una herramienta incorporada falla cada solicitud en la sesión, no solo llamadas a esa herramienta. + +Para mantener funcionando los parámetros ordinarios de Artifact, las rutas de adaptador `openai-chat` y `openai-responses` omiten las restricciones escalares `pattern` que contienen escapes de propiedad Unicode en posiciones de esquema positivas ordinarias. Restricciones de hermanos, `required`, datos literales y regexes soportados permanecen. Una implementación de herramienta debe validar sus propias entradas porque este proxy no aplica una restricción omitida. + +`patternProperties` emparejadores y sus esquemas de valor permanecen sin cambios. La eliminación de un emparejador puede cambiar qué claves son evaluadas por el `unevaluatedProperties` de un antepasado, por lo que la apertura local no es suficiente para demostrar una transformación segura. Los patrones bajo `not`, `oneOf`, `if`, `contains`, `$defs` y `definitions` también permanecen sin cambios: relajar esos subárboles puede cambiar la negación, la selección de ramas, el recuento de coincidencias o el significado de una referencia. + +El destino valida estos esquemas conservados. Un destino compatible con ECMA puede usar el regex original; un destino que no puede compilarlo puede rechazar el esquema. OpenCodex no reemplaza silenciosamente ese contrato con uno que prohíbe argumentos previamente válidos. + +Esta es la normalización en la ruta del adaptador seleccionado, no una garantía para todo el proveedor. La configuración y autenticación del proveedor no se tocan, y un proveedor en un adaptador diferente no se ve afectado. + +Es una medida de compatibilidad, no una afirmación de que cada backend personalizado compatible con OpenAI rechaza estos patrones. Vale la pena saber lo que cuesta: una regla omitida no se conserva en ninguna parte y no se aplica en sentido ascendente, por lo que una implementación de herramienta debe validar sus propias entradas en lugar de confiar en el esquema para rechazar un argumento mal formado. + + + +## Traducción saliente (Responses → Messages SSE) + +| Responses evento | Messages SSE | +| --- | --- | +| `response.created` | `message_start` + `ping` | +| Latido del corazón | `ping` | +| Texto deltas | `content_block_start` → `content_block_delta` (texto) → `content_block_stop` | +| Razonamiento resumen/texto | `thinking` bloque con la firma reproducida, o un sobre de reserva limitado `ocxr1` | +| Razonamiento redactado | `redacted_thinking` bloques reproducidos desde el sobre de razonamiento | +| Marcos de llamada de función | Bloque `tool_use` con `input_json_delta` | +| Evento terminal | `message_delta` → `message_stop` | +| EOF antes del terminal | 502-estilo `api_error` | + +**Detener el mapeo de la razón:** `completed` → `tool_use` (si se llama alguna herramienta) o `end_turn`; `incomplete/max_output_tokens` → `max_tokens` `incomplete/content_filter` → `refusal`. + +**Taxonomía de error:** 400 `invalid_request_error`, 401 `authentication_error`, 402 `billing_error`, 403 `permission_error`, 404 `not_found_error`, 409 `conflict_error`, 413 `request_too_large`, 429 `rate_limit_error`, 504 `timeout_error`, 529 `overloaded_error`, otros 5xx `api_error`. Se conserva el `Retry-After`. + + + +## Uso rápido de caché y token + +**Anthropic -solicitudes de ruta:** el adaptador administra puntos de interrupción de la caché para herramientas, contenido del sistema y el penúltimo mensaje de usuario, además de `cache_control` automático de nivel superior. Los giros estables normalmente producen una tasa de éxito de caché del 99.9%. + +**Enrutamiento nativo OpenAI / ChatGPT:** deriva un encabezado `prompt_cache_key` de alcance de sesión (de `metadata.user_id` cuando está presente, volviendo a un hash de contenido de sistema) y `session_id` para afinidad de caché. La clave de caché incluye esquemas de modelo y herramientas completas. + +La salida **Matemáticas de token:** Anthropic resta `cached_tokens` y `cache_write_tokens` de `input_tokens`, exponiéndolos como `cache_read_input_tokens` y `cache_creation_input_tokens`. Los registros de solicitud mapean esos de vuelta al `inputTokens` inclusivo, con lecturas tanto en `cachedInputTokens` como en `cacheReadInputTokens`, escribe en `cacheCreationInputTokens`. La página Uso informa de los hits de caché y la creación de caché por separado. + +**count_tokens:** modelos enrutados utilizan una aproximación (sistema serializado + mensajes + herramientas). Los modelos nativos Anthropic con una credencial `sk-ant-` pasan la solicitud al punto final real Anthropic `/v1/messages/count_tokens`. + + + +## Captura de depuración + +`ocx debug claude on|off|status|reset`, `OCX_CLAUDE_DEBUG=1` o `PUT /api/debug {"claude": true}` controlan la captura entrante. `GET /api/claude/inbound-debug` devuelve `{enabled, entries}` (el más nuevo primero, anillo de 20). + +Cada entrada registra: `at`, `endpoint`, `model`, `resolvedModel`, `stream`, `maxTokens`, `thinkingType`, `thinkingBudgetTokens`, `outputConfigEffort`, `metadataKeys`, `hasMetadataUserId`, `hasSystem`, `anthropicBeta` en bruto y etiquetas de igualdad HMAC de ocho caracteres para el identificador de usuario / sistema. **No se almacena ningún texto de solicitud, objeto sin procesar o hash de ejecución cruzada estable.** La desactivación de la depuración Claude limpia inmediatamente el anillo. + + + +## GUI (página Claude) + +Abra **Conectar → Claude** para la configuración de una página Claude Code. La página muestra estos controles y secciones en orden: + +1. Interruptor **Claude Code CLI primera parte** +2. **Empezar** con `ocx claude` y el bloque de entorno manual +3. **Generalidades** con compatibilidad, instrucciones del agente, modo rápido y controles de contexto +4. **Modelo de ayudante de fondo** selector +5. **Interceptación modelo** editor +6. **Modelos disponibles**, la vista previa en vivo de Claude Code `/model` alias de selector +7. Interruptor **Claude conexión**, también disponible en la tarjeta Claude en la vista general de Connect + +La barra de guardado pegajosa muestra **Sin cambios** cuando la configuración guardada coincide con la página, o **Cambios no guardados** después de editarlos. **Revertir** descarta ediciones no guardadas; **Guardar** confirma la configuración editable. Los interruptores **Claude conexión** y **Claude Code CLI primera parte** se aplican inmediatamente. **Guardar** nunca cambia ninguno de los interruptores. + +**Claude Desktop** es una pestaña separada bajo **Conectar**. Su selector **Modo de conexión** ofrece gateway (predeterminado) o first-party, con el puerto proxy en ejecución en modo first-party. Solo **Guardar y aplicar** cambia los modos; **Guardar** solo almacena los carriles de perfil de pasarela para una pasarela posterior aplicada y deja el modo actual como está. + +`GET /api/claude-code` devuelve los valores predeterminados efectivos, la configuración, el registro de ventanas de contexto, el env efectivo, los identificadores de ruta disponibles, los alias y el puerto. `PUT /api/claude-code` es parcial y conserva los campos omitidos; `null` restablece los valores de contexto/lista de bloques/ventana compacta. + + + +## Solución de problemas + +**Claude Code dice "Hizo 0 búsquedas"** - Las compilaciones actuales traducen los elementos completados Responses `web_search_call` en bloques emparejados Anthropic `server_tool_use` y `web_search_tool_result`, incluido `usage.server_tool_use.web_search_requests`. Actualización opencodex si una compilación anterior completó la búsqueda, pero Claude Code todavía contaba cero. + +**Un sidecar no se activa** - Para `backend: "openai"`, confirme que ha iniciado sesión en ChatGPT y que tiene un proveedor `authMode: "forward"` habilitado. Para `backend: "anthropic"`, confirme que la cuenta Anthropic OAuth almacenada activa no está marcada como `needsReauth`. Una selección Anthropic explícita sin esa credencial falla intencionalmente. + +**"Los conectores claude.ai están deshabilitados"** - Un `ANTHROPIC_API_KEY` o `ANTHROPIC_AUTH_TOKEN` se establece en su cáscara. `ocx claude` deliberadamente NO establece `ANTHROPIC_API_KEY`; si lo tiene exportado, elimina esa variable del entorno. `ocx claude` inyecta `ANTHROPIC_BASE_URL`, descubrimiento, auto-contexto y ranuras de modelo configuradas, pero nunca `ANTHROPIC_API_KEY`. + +**Modelos que no aparecen en /modelo selector** - Verificar que `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1` está configurado (automático con `ocx claude`). Ejecute `ocx claude` para actualizar la caché del modelo de puerta de enlace en `~/.claude/cache/gateway-models.json`. Compruebe `claudeCode.enabled` no es `false`. + +**Entorno estanco después del cambio de puerto** - Si el puerto proxy ha cambiado, los shells antiguos pueden tener un `ANTHROPIC_BASE_URL` obsoleto. Abra una nueva terminal o vuelva a ejecutar `ocx claude`. + +**techo de contexto 200k a pesar de gran modelo** - Seleccione la variante `[1m]` en el selector, o active el contexto automático (activado de forma predeterminada). Si el selector no muestra la fila `[1m]`, la ventana de contexto de catálogo efectiva del modelo puede estar por debajo del piso fijo de 829.800 tokens. + +**Alto recuento de tokens de cargas de habilidad** - La habilidad `claude-api` incluida (tokens de -136k) se carga automáticamente en Claude menciones del modelo. Esto es normal para passthrough nativo; en los modelos enrutados, opencodex stubs por defecto (`blockedSkills: ["claude-api"]`). + +**Los esquemas de herramientas MCP llenan el contexto en la primera curva** - Claude Code convierte MCP herramienta de aplazamiento cuando `ANTHROPIC_BASE_URL` no es un host Anthropic de primera parte. La comprobación está en el host, no en el modelo, por lo que se aplica a cada sesión `ocx claude`: con muchos conectores configurados, cada esquema de herramienta está alineado antes de escribir nada. Vuelva a habilitar el aplazamiento con: + +```json +{ "claudeCode": { "toolSearch": true } } +``` + +Esto está desactivado por defecto porque solo vale la pena en **paso nativo Anthropic** Rutas. El aplazamiento es una optimización del lado del servidor, no una solicitud más pequeña: Claude Code todavía envía cada definición de la herramienta, y Anthropic de API es lo que mantiene los esquemas diferidos fuera del contexto del modelo y responde el `tool_search` herramienta de servidor con `tool_reference` bloques. Un traducido (enrutado) modelo nunca llega a esa maquinaria — opencodex deja caer el `tool_search` herramienta e ignora +`defer_loading` — para que el proveedor siga recibiendo todos los esquemas mientras Claude Code deja de contar y, por lo tanto, deja de compactarse. Con `claudeCode.compatibility: "enforce"` El mismo La solicitud es rechazada con 400 en su lugar. Enciéndelo cuando `ocx claude` se enruta a un Anthropic modelo; déjelo para rutas de terceros hasta que se admita el aplazamiento traducido. + +Los valores aceptados siguen el propio analizador de Claude Code: `true`, `"auto"`, `"auto:N"` (N al menos 100) y `"force"`. Un valor que usted mismo exporta siempre gana sobre el inyectado. + +**Subagente envía al modelo equivocado** — Lista de agentes (`ocx-*`) uso `` +directivas, no la herramienta del agente `model` argumento. Asegúrese de que la directiva coincida con el ruta. Pase `"haiku"` como modelo de referencia. + +Establecer `claudeCode.stabilizePromptCache` a `true` en `config.json` a Claude arnés de aviso de seguimiento de las instrucciones del sistema en las rutas traducidas. Se han retirado `N tokens left` pies reconocidos, incluidos los pies repetidos. Los recordatorios de TaskCreate aún se mueven a un mensaje de usuario final; si solo se pelaron los pies de token, no se agrega ningún mensaje de entrada. El valor predeterminado es `false`. Habilítelo solo cuando este cambio de rol sea apropiado para sus clientes. Conserva ejemplos cercados y texto sin igual; el passthrough nativo Anthropic no cambia. La clave prompt-cache sin metadatos sigue instrucciones estabilizadas. Esto no crea una identidad de conversación ni garantiza accesos de caché ascendentes. + +En cada ruta de chat traducida, los recordatorios de línea de tiempo mantienen su posición en la conversación, después de cualquier resultado de herramienta pendiente. Esto evita que un recordatorio recién agregado reescriba el indicador principal del sistema, y evita que una instrucción de conversación intermedia llegue antes de los giros que se escribió a seguir. El papel que lleva la ranura se decide por separado: un recordatorio se envía como `system` a menos que el proveedor registre `foldDeveloperRoleToSystem: false`, que establece que el flujo ascendente acepta el papel `developer` y lo reenvía en la misma posición. Un flujo arriba que no lo acepta responde `400 role 'developer' is not allowed` y el giro nunca comienza, por lo que un destino no registrado se pliega. Esto se aplica con o sin `stabilizePromptCache`, y el paso a través de Anthropic nativo no cambia. La reutilización de caché todavía requiere una identidad de sesión estable y disponibilidad de caché ascendente. Los cambios en las instrucciones o herramientas anteriores, y la compactación de la conversación, aún pueden afectar los golpes de caché; preservar el orden del recordatorio por sí solo no garantiza la reutilización. + + + +### Interceptar la recuperación de token + +El proxy autenticado en ejecución valida el token actual para cada nueva solicitud CONNECT. Una aplicación explícita de primera parte recrea un token faltante y actualiza la configuración de propiedad sin requerir un reinicio proxy; los túneles existentes no se revocan. Los archivos no válidos, vinculados, de gran tamaño o no token se rechazan en lugar de sobrescribirse. Inspeccione dicha entrada antes de eliminar solo el archivo de token obsoleto confirmado y vuelva a aplicar el modo de primera parte; nunca elimine su destino de enlace. + + + +### Marcadores de contexto de selector de primera parte + +El selector de pestañas de código de escritorio agrega `[1m]` a modelos enrutados cuya ventana de contexto de catálogo efectiva es de al menos un millón de tokens o al menos el umbral de compactación predeterminado de 829.800 tokens (por ejemplo, un modelo nativo GPT-6 elegido en su ventana 872k), por lo que Claude usa su contabilidad 1M en lugar del modelo personalizado más pequeño. Los modelos Claude en una ruta Anthropic todavía necesitan un genuino 1M. Las etiquetas, el orden del perfil y las rutas del proveedor se mantienen sin cambios. Las ventanas desconocidas y más cortas permanecen sin marcar. El selector no puede garantizar que un corredor de escritorio o remoto reciba el entorno de compactación correspondiente, por lo que un modelo de ventana larga que supere su ventana real obtiene un error `prompt is too long`, que Claude Code responde compactando. El escritorio 3P `supports1m` / `prefer1m` y los subagentes generados siguen la misma regla. La configuración de contexto automático emparejado para `ocx claude` no cambia. Una conversación existente mantiene su selector guardado hasta que vuelva a seleccionar el modelo en el selector actualizado. + + + +### Modelo de subagente forzado Claude Code + +La página Subagentes ofrece **Forzar un modelo para todos los subagentes**, una opción **desactivada de forma predeterminada**. Selecciona un identificador disponible en la lista, como `combo/tev-auto`, y después activa la opción. Primero se ofrece la lista de modelos; las entradas guardadas que ya no estén disponibles no se pueden usar como destino forzado. + +`ocx agent subagents force combo/tev-auto` conjuntos `claudeCode.subagentModelForce`; `ocx agent subagents force -` lo aclara. `ocx agent status` informa de la configuración. `GET /api/subagent-models` devuelve `force`, `forceAvailable` y `forceStatus`; `PUT` acepta `{ "force": "combo/tev-auto" }` o `{ "force": null }` sin cambiar la lista. Omitir `force` lo deja sin cambios. Los objetivos inválidos o no expuestos son rechazados en la escritura; los objetivos obsoletos son reportados y omitidos en el lanzamiento. + +Esto tiene efecto en el **siguiente inicio enrutado de `ocx claude`**, inyectando `CLAUDE_CODE_SUBAGENT_MODEL` como un alias proxy explícito (con `[1m]` cuando la ventana de catálogo efectiva alcanza el piso fijo de 829.800 tokens, y solo para una ventana genuina de 1 M en los modelos Anthropic Claude y selectores desnudos `claude-*`; los objetivos nativos Claude usan un alias nativo reversible) y `CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1`. Cada variable no vacía exportada por el shell gana independientemente. Los lanzamientos nativos no inyectan ninguna variable; el `claude` simple no se ve afectado. No hay archivos de plugin o `settings.json` son modificados por esta configuración. + +Claude Code **2.1.257 o más reciente** es necesario para la fuerza. Los argumentos de modelo de complemento y agentes incorporados (incluyendo Explorar/Planear) y por llamada se anulan. Las bifurcaciones y las habilidades de subagente con `model: inherit` mantienen el modelo de conversación principal. El bucle principal y los sidecars de pequeño-rápido no se ven afectados. Los archivos de la lista existentes permanecen disponibles. + +El panel de control advierte sobre versiones antiguas o desconocidas de CLI, objetivos no disponibles y cualquiera de las variables ya presentes en `settings.json` → `env` (que anula env de lanzamiento). La detección es de solo lectura y local en el servidor: no puede inspeccionar otro shell de lanzamiento, otra máquina o la configuración local del proyecto. Un resultado desconocido no es prueba de apoyo a la fuerza. + +Los selectores de puerta de enlace explícitos en una solicitud de agente generada tienen prioridad sobre su alternativa heredada `ocx-route`, incluso si la configuración de fuerza guardada cambia después del lanzamiento. Para las anulaciones de configuración o shell de los agentes de lista generados, use un alias de puerta de enlace explícito; los ids desnudos de Claude retienen el comportamiento de respaldo del cliente más antiguo. Los alias nativos restauran su modelo desnudo antes de las verificaciones de credenciales y mapas de modelo existentes. Los lanzamientos conectados validan los objetivos de fuerza contra un nuevo catálogo de puerta de enlace autenticado; el descubrimiento fallido omite la inyección automática de fuerza y las ventanas de contexto en caché por sí solas nunca demuestran disponibilidad. diff --git a/docs-site/src/content/docs/es/guides/codex-app-models.md b/docs-site/src/content/docs/es/guides/codex-app-models.md new file mode 100644 index 00000000000..bd631bd3746 --- /dev/null +++ b/docs-site/src/content/docs/es/guides/codex-app-models.md @@ -0,0 +1,245 @@ +--- +title: "Selector de modelos de Codex App" +description: "Cómo aparecen los modelos enrutados de opencodex en Codex App, Codex CLI y Codex TUI mediante el catálogo compartido de Codex." +--- + +opencodex no parchea la aplicación Codex. Escribe la misma configuración Codex y el catálogo de modelos que Codex CLI / TUI. El servidor de aplicaciones lee ese estado compartido, pero algunas versiones de escritorio Codex aplican una segunda lista de permisos de modelo remoto en el renderizador y aún pueden eliminar las filas enrutadas del selector. + +Las entradas de OpenAI usan dos rutas de credenciales: la sesión nativa de Codex y el transporte con clave API `openai-apikey/`. Cambiar `codexAccountMode` entre Pool y Direct no cambia por sí solo los identificadores del selector. Cuando `codexAccountPickerEnabled` y `codexAccountNamespaces` habilitan selectores por cuenta, opencodex añade filas `/` para los selectores elegibles cuyas cuentas asignadas aún existen, y oculta las filas nativas sin calificar del selector de Codex. Las etiquetas son nombres públicos elegidos por el usuario; no implican un rol de cuenta. Una fila calificada utiliza únicamente su cuenta asignada, no cambia la cuenta activa de Pool y rechaza la solicitud si esa cuenta no está disponible, en lugar de sustituirla por otra. Si el catálogo de Codex contiene un identificador de la familia OpenAI visible para una cuenta y respaldado por la API que aún no está en el conjunto estático de opencodex, se conserva exactamente en una fila calificada para los selectores elegibles de la cuenta principal. No se copia a cuentas ajenas ni se añade a las listas sin calificar o con clave API. La fila debe tener los campos de una entrada real del catálogo, lo que excluye entradas mal formadas; esto no demuestra que proceda del proveedor, porque la caché es un archivo propiedad del usuario. Véase [Selectores exactos de cuenta de Codex](/es/reference/configuration/routing/#exact-codex-account-selectors). + +`gpt-daybreak-blue-latest` está cerrada por cuenta. opencodex comprueba cada cuenta autenticada de ChatGPT propia lista de modelos Codex antes de anunciarla o enrutarla. En el modo Pool, la fila desnuda solo existe cuando al menos una cuenta Pool elegible informa la identificador. En el modo Direct, la fila desnuda sigue la cuenta utilizada por el catálogo local, y cada solicitud también comprueba la credencial de llamada reenviada (o la credencial principal almacenada cuando se sustituye una portadora de admisión OpenCodex). A +`/gpt-daybreak-blue-latest` fila solo existe cuando la cuenta asignada de ese selector lo informa. El enrutamiento Pool excluye las cuentas sin derecho. Si no se puede confirmar ninguna lista, la fila cerrada falla en lugar de gastar una prompt en un 400 ascendente. + +`gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-5.6-luna` y `gpt-6-astra` son deliberadamente **no** cerrada de esa manera: que se enumeran en cada instalación, lo que diga la lista de derechos. opencodex pregunta aguas arriba bajo una versión de cliente lo suficientemente nueva como para devolverlos, pero no puede hacer que aparezca una respuesta: una cuenta no confirmada, una búsqueda de tiempo de espera o un fragmento que no se ha puesto al día haría desaparecer el modelo del selector sin explicación. Enumerarlos significa que se envía la solicitud y en su lugar se ve el estado ascendente real. Una cuenta que no tiene uno de estos modelos obtendrá un rechazo ascendente en el momento de la solicitud en lugar de una fila ausente, y en una cuenta múltiple Pool la solicitud ya no se dirige primero a la cuenta que posee el modelo. `disabledModels` es la palanca para ocultar cualquiera de ellos. + +Una entrada separada y explícita `customModels` puede exponer el mismo identificador de cable que `openai/gpt-daybreak-blue-latest` a través del proveedor de reenvío de inicio de sesión canónico Codex: + +```json +{ + "customModels": [ + { + "id": "daybreak-codex-forward", + "provider": "openai", + "modelId": "gpt-daybreak-blue-latest" + } + ] +} +``` + +Solo ese proveedor exacto, el punto final y la identificación del modelo reciben la instantánea de capacidad de Sol fijada: 922.000 contexto, 829.800 compactación automática, la escalera de razonamiento nativa y los metadatos de la herramienta nativa Codex. La solicitud todavía envía `gpt-daybreak-blue-latest`; opencodex no lo reescribe a Sol ni otorga derecho a la cuenta. La fila `openai-apikey/daybreak-blue-latest` API facturada por separado es una ruta diferente y sus límites de 1.050.000 / 922.000 nunca se copian en la fila de inicio de sesión Codex. + +Para las filas personalizadas de Astra y Daybreak en ese destino canónico `openai` Codex-forward, las capacidades explícitas `reasoningEfforts` están limitadas por las capacidades del modelo Codex ancladas. Un `["none", "minimal", "low"]` personalizado se convierte en `["low"]` en el catálogo; una lista no vacía sin valores compatibles también vuelve al valor predeterminado nativo como una sola opción. Un `[]` explícito permanece vacío y no tiene anuncios predeterminados. Un valor predeterminado declarado se retiene solo si pertenece a la lista resultante; de lo contrario, se usa el valor predeterminado nativo cuando está presente, luego la primera opción sobreviviente. La configuración personalizada almacenada no cambia y las sincronizaciones repetidas no vuelven a agregar `max` a una lista personalizada estrecha. + +El mismo vínculo de catálogo se aplica cuando el identificador de modelo personalizado ha fijado metadatos de capacidad nativa, incluida una puerta de enlace arbitraria como `YYLJ/gpt-6-astra`. Desktop valida el ID del modelo, por lo que `none` y `minimal` se eliminan de esa fila del catálogo. La identidad nativa completa todavía requiere la identidad exacta del proveedor, el destino y el modelo respaldado por capacidades; una puerta de enlace no hereda Responses Lite, multiagente o ventanas nativas de su nombre. La elección nativa Astra `ultra` de Codex se conserva: es un modo de delegación de cliente convertido en un esfuerzo de cable soportado, distinto del [Lista de esfuerzo del modelo API](https://developers.openai.com/api/docs/models/gpt-6-astra). La normalización de catálogos no reescribe los ajustes de subprocesos existentes. Las pinzas de esfuerzo nativas de tiempo de solicitud permanecen solo canónicas. + +Cuando el mapa `codexAccountNamespaces` está vacío, las filas de selector calificadas para la cuenta están desactivadas. Si se omite `codexAccountPickerEnabled` con un mapa no vacío, se tratan como habilitados para la compatibilidad con versiones anteriores. Establezca el valor en `false` para ocultar filas calificadas generadas y restaurar filas nativas desnudas en el selector sin eliminar asignaciones ni deshabilitar el enrutamiento exacto `/`. + +Las entradas API GPT-5.6 y Daybreak usan 1.050.000 entradas de contexto / 922.000 entradas máximas, y los identificadores del selector `*-pro` se resuelven en el modelo de cable base con `reasoning.mode: "pro"` mientras que los registros, el uso y el estado del selector mantienen el identificador virtual. El catálogo API se fija a exactamente diez ids: `gpt-5.5`, `gpt-5.6`, Sol/Terra/Luna, sus tres ids virtuales Pro, `daybreak-red-latest`, y `daybreak-blue-latest`; no hay alias `gpt-5.6-pro` genérico. Las solicitudes compactas mantienen el nivel seleccionado pero envían el modelo base sin un objeto de razonamiento. + +Seleccione la ruta de credenciales representada por el identificador de selector. Cambiar Pool / Direct en la página de Proveedores; `` a continuación es una etiqueta pública elegida por el usuario mapeada a través de `codexAccountNamespaces`: + +```text +gpt-5.6-sol # bare Codex-login route via Pool or Direct +/gpt-5.6-sol # stored Codex account mapped by that selector +openai-apikey/gpt-5.6-sol # API key +openai/gpt-daybreak-blue-latest # explicit Codex-forward custom row (922,000) +/gpt-daybreak-blue-latest # account-qualified native id, only when that account reports it +openai-apikey/daybreak-blue-latest # separate API-key route (1,050,000 / 922,000) +``` + +Instalación y configuración nuevas sin modo guardado predeterminado a Pool. Las configuraciones actuales usan el marcador 2 y retienen la fuente v1 enviada en `~/.opencodex/config.json.pre-openai-tiers-v2.bak`; restaurarla con: + +```sh +cp ~/.opencodex/config.json.pre-openai-tiers-v2.bak ~/.opencodex/config.json +``` + +Las configuraciones anteriores de tres proveedores v1 migran automáticamente a la fila de una sola opción. + + + +## Limitación de lista remota de escritorio + +Si `codex debug models` y app-server `model/list` contienen un modelo enrutado pero Desktop no lo muestra, compruebe el [incidencia de Codex #19694](https://github.com/openai/codex/issues/19694) anterior. Con la directiva remota `use_hidden_models` activa, Desktop puede mantener solo los id en su lista nativa `available_models` y también puede mostrar filas nativas cuya visibilidad de catálogo es `hide`. Las actualizaciones de catálogo y los reinicios proxy solos no pueden cambiar esa directiva de renderizador. + +Para un modelo enrutado equivalente, opencodex ofrece un modo de combo con alias nativo que exige activación explícita y está desactivado de forma predeterminada. Publica una identificador desnuda listada con una etiqueta de visualización personalizada honesta y rutas que exactas identificador a través del combo configurado antes del enrutamiento canónico OpenAI. También omite las filas nativas desnudas deshabilitadas del catálogo efectivo mientras existen alias de compatibilidad, por lo que Desktop no puede resucitarlas ignorando `visibility`. Consulte [Codex Compatibilidad con la lista nativa de equipos de escritorio](/es/guides/combos/#codex-desktop-native-allowlist-compatibility) para el comando, la semántica de la clave de inhabilitación y las restricciones de seguridad. + + + +### Lo que esto significa para un modelo nativo desactivado + +Sin un alias nativo configurado, deshabilitar un slug GPT nativo desnudo no lo elimina del catálogo. La fila se queda con `visibility: "hide"`, que `/v1/models` y el tablero de instrumentos honran, dejan de enumerar el modelo, mientras que Desktop, bajo la política anterior, puede seguir mostrándolo. Por lo tanto, el modelo aún se puede elegir en Desktop después de deshabilitarlo, y las superficies no están de acuerdo sobre si existe. + +La selección no se rechaza por estar deshabilitado. `disabledModels` controla la visibilidad del catálogo, no la admisión, por lo que la solicitud se enruta según las reglas ordinarias como si el modelo estuviera habilitado: el turno se ejecuta en el modelo que deshabilitó o falla en cualquier ruta que se resuelva. De cualquier manera, el resultado no es el que implica la palanca. + +La fila se mantiene deliberadamente. Contiene los metadatos ascendentes reales, por lo que volver a habilitar el modelo restaura esos metadatos en lugar de una suposición sintetizada. Cuando necesite que la fila se vaya directamente en lugar de ocultarse, configure un combo `nativeAlias`: mientras exista, las filas nativas desnudas deshabilitadas se omiten del catálogo efectivo por completo. + +Si el archivo `config.toml` de Codex fija un `model` raíz que este proxy no expone, incluido un modelo deshabilitado, cada nueva sesión comienza con un modelo que opencodex no sirve. `ocx doctor` informa que bajo **Codex exposición del modelo por defecto**, como una advertencia en lugar de un fallo, y dice cuando no pudo determinar el conjunto expuesto en absoluto. + + + +## Ruta de integración + +`ocx init`, `ocx start`, y `ocx sync` cablear la configuración y el catálogo compartidos de Codex en el proxy; ver +[Integración con Codex](/es/guides/codex-integration/) para inyección de configuración, sincronización de catálogo, shims, WebSocket fallback, y restaurar la mecánica. + + + +## Limitación de reserva de cuota nativa + +Cuando la aplicación Codex agota su cuota nativa de cinco horas, puede cambiar a un modelo de reserva y en gris las otras filas en su selector. Informado en [#2813](https://github.com/lidge-jun/opencodex/issues/2813), esa puerta también oculta opencodex filas enrutadas, a pesar de que utilizan credenciales de proveedor no relacionadas y no consumen ninguna de la cuota ChatGPT. + +Esta puerta es aplicada por el cliente antes de que una solicitud llegue al proxy, por lo que opencodex no puede levantarla. Las filas enrutadas se escriben con `visibility: "list"`, el filtrado de catálogo consulta solo `disabledModels` y el `selectedModels` de cada proveedor, y ningún valor de cuota participa en la visibilidad enrutada. + +La selección de un modelo enrutado explícitamente no pasa por el selector. Fije el modelo en `config.toml`: + +```toml +model = "anthropic/claude-sonnet-5" +``` + +o enviarlo directamente: + +```bash +ocx access test anthropic/claude-sonnet-5 --protocol responses +``` + +Ambos caminos encaminan correctamente **Una vez que la solicitud llega al proxy** - esa parte está cubierta por pruebas. La aplicación de escritorio Codex, sin embargo, no envía el modelo configurado mientras el modo de reserva está activo: decide la reserva de su propia encuesta `wham/usage` (`luna_reserve` más un límite adicional permitido `gpt-reserve`) y fuerza la configuración del modelo a `gpt-reserve` antes de que la solicitud se vaya, por lo que la ruta `config.toml` se anula en la aplicación. Utilice `ocx access test`, Claude Code a través del proxy (`ocx claude`), o cualquier cliente `/v1` directo hasta que se restablezca la ventana. Véase [Modelos encaminados durante el modo de reserva Codex](/es/guides/codex-integration/#routed-models-during-codex-reserve-mode). + + + +## Por qué aparecen los modelos enrutados + +El selector de modelos de Codex espera entradas de catálogo en forma de Codex. opencodex construye entradas enrutadas clonando una plantilla de modelo nativa Codex y reemplazando la identidad del modelo enrutado: + +```text +slug = "anthropic/claude-sonnet-..." +display_name = "anthropic/claude-sonnet-..." +visibility = "list" +``` + +El clon mantiene campos de análisis estrictos, como niveles de razonamiento, tipo de shell, banderas de soporte API e instrucciones base. opencodex luego elimina las capacidades solo nativas que la ruta no puede cumplir, incluidos los metadatos de nivel de servicio OpenAI. + + + +## Cobertura actual del modelo estable + +El conjunto de reserva nativo incluye `gpt-5.5` y GPT-5.6 Sol / Terra / Luna. Para la familia GPT-5.5, opencodex conserva las entradas en vivo más ricas del catálogo Codex instalado y solo sintetiza una entrada faltante. La instantánea de flujo ascendente agrupada se usa solo para GPT-5.6, donde proporciona la identidad real por modelo y los metadatos en lugar de una aproximación de plantilla anterior. + +| Ruta | Identificadores de selección y metadatos de catálogo | +| --- | --- | +| Codex inicio de sesión (filas calificadas por cuenta deshabilitadas) | Desnudos ids nativos como `gpt-5.6-sol`, `gpt-5.6-terra` y `gpt-5.6-luna`; Pool o Direct se selecciona a través de `codexAccountMode`. Las filas GPT-5.6 usan una ventana de catálogo de 922.000 tokens. | +| Codex inicio de sesión (filas calificadas por cuenta habilitadas con selectores elegibles) | Una fila `/` por selector elegible y modelo nativo compatible; cada fila usa solo su cuenta asignada, y las filas nativas desnudas están ocultas para el selector. Se conservan los metadatos nativos y las ventanas de contexto. | +| Codex inicio de sesión (explícita fila de Daybreak forward) | `openai/gpt-daybreak-blue-latest` solo cuando la fila exacta `customModels` está configurada en el proveedor canónico `openai`. Mantiene el identificador de cable Daybreak y utiliza la instantánea de capacidad Sol fijada (922.000 contexto; 829.800 compactación automática). | +| OpenAI (clave API) | Exactamente diez filas de nombres: `gpt-5.5`, `gpt-5.6`, Sol / Terra / Luna, los tres `*-pro` ID virtuales y los dos alias Daybreak (1.050.000 tokens de contexto y un máximo de 922.000 tokens de entrada para los diez) | +| OpenRouter | `openrouter/openai/gpt-5.6-sol`, `openrouter/openai/gpt-5.6-terra`, `openrouter/openai/gpt-5.6-luna` (922.000) | +| Cursor | La reserva estática incluye `cursor/gpt-5.6-sol`, `cursor/gpt-5.6-terra` y `cursor/gpt-5.6-luna` (1.000.000), más filas regulares/rápidas para Grok 4.5, 4.6 y 4.7 (500.000); 4.6 y 4.7 agregan `xhigh`, y el descubrimiento de cuenta real decide qué filas permanecen visibles. | +| xAI | El descubrimiento en vivo es autoritario. El catálogo alternativo incluye `xai/grok-4.6` y `xai/grok-4.7` y por defecto a `xai/grok-4.5`; los tres tienen ventanas de 500.000 tokens. Grok 4.6 y 4.7 exponen `low` / `medium` / `high` / `xhigh` (por defecto aguas arriba: `high` ), mientras que Grok 4.5 se detiene en `high`. | + +Las entradas GPT-5.6 fijadas preservan la escalera aguas arriba exacta. Sol y Terra exponen `low` a través de `ultra`; Luna se detiene en `max`. Sol tiene el valor predeterminado de `low`, mientras que Terra y Luna tienen el valor predeterminado de `medium`. La explícita fila Codex Daybreak Blue hereda la escalera y el valor predeterminado de Sol sin cambiar su identidad de cable. `ultra` es una opción orientada al cliente para un razonamiento máximo más delegación proactiva y llega al backend como `max`. Una entrada de selector solo significa que el catálogo está listo: la cuenta conectada o la clave API aún deben tener derecho a usar ese modelo. + + + +## Conmutadores de modelo nativo y enrutado + +La página Modelos del panel de control expone `disabledModels` alterna para ids nativos desnudos y `provider/model` ids enrutados. Los identificadores `/` calificados para la cuenta también son compatibles con `disabledModels`, pero el panel de control no enumera ni cambia esas filas de selector exactas; agréguelas a la configuración manualmente: + +- Los identificadores de ruta son namespaced (`provider/model` ). Deshabilitar uno lo excluye del catálogo sincronizado y `/v1/models`. +- Los identificadores nativos calificados para la cuenta usan `/`. Agregar uno a `disabledModels` oculta solo esa fila del selector. +- Los identificadores nativos de GPT no llevan prefijo. Deshabilitar uno conserva su entrada del catálogo con `visibility: "hide"` para poder volver a habilitarla después; oculta del descubrimiento tanto la fila sin prefijo como cada copia que especifica un selector para ese modelo. +- Si hay al menos un combo con alias nativo, las filas nativas sin prefijo deshabilitadas se omiten del catálogo en lugar de conservarse ocultas, porque las versiones de Desktop afectadas ignoran esa marca de ocultación. La página Modelos también omite una fila nativa sin prefijo cuando un alias nativo ocupa su identificador; por eso esa fila no muestra un interruptor nativo. Solo las filas no sustituidas por un alias conservan su interruptor. Al volver a habilitar una de esas filas, la sincronización restaura sus metadatos nativos originales o actuales. +- Las filas nativas no sombreadas provienen del conjunto estático admitido, por lo que un modelo no sombreado desactivado permanece visible en el panel y se puede volver a activar. + +El pase de visibilidad se ejecuta después de las actualizaciones de instantáneas, y la administración API actualiza el catálogo y fuerza la caché del modelo de Codex después de un cambio. + + + +## Modo de superficie multiagente + +El control Models-page v1/base/v2 cambia qué superficie de colaboración Codex usa cada entrada del selector; vea [Superficie del subagente](/es/guides/sub-agent-surface/) para el modo canónico, la delegación, la herencia, la reserva y el comportamiento de la tarea cifrada. + + + +## Razonamiento de los niveles superiores + +La visibilidad del nivel de razonamiento es independiente del modo de superficie v1/base/v2. Las entradas con capacidad de razonamiento generadas anuncian `max` para que los sobresueldos directos de esfuerzo de subagente validen; las entradas enrutadas generadas actuales y las entradas GPT nativas más antiguas también anuncian `ultra`. Se conservan escaleras GPT-5.6 aguas arriba exactas, por lo que Luna tiene `max` pero no `ultra`. + +En el cable, los adaptadores enrutados mapean o sujetan niveles no compatibles. Para los modelos nativos más antiguos cuya escalera real se detiene en `xhigh`, `nativeEffortClamp` asigna una selección directa de `max` o `ultra` a `xhigh` (por ejemplo, GPT-5.5). Sol, Terra y Luna tienen un verdadero `max` peldaño. + +El backend de ChatGPT acepta niveles desde `none` hasta `max`, así que una solicitud nativa nunca reenvía `ultra` literalmente. Los modelos nativos con un nivel real `max` reciben `max`, incluidos Astra y GPT-6.1 Sol aunque anuncien `ultra`; los antiguos, como GPT-5.5, reciben `xhigh` como se explicó arriba. Esto se aplica tanto a `/v1/responses` como a `/v1/chat/completions`. Esa normalización nativa no afecta a los identificadores enrutados: un paso directo OpenAI Chat enrutado puede copiar `reasoning_effort: "ultra"` al proveedor sin cambios, mientras que el adaptador traducido ordinario convierte `ultra` en `max`. + +La publicidad del catálogo de los dos niveles superiores es incondicional: `ocx sync` ya no elimina `max` o `ultra` cuando el binario Codex instalado es demasiado viejo para ofrecerlos: las versiones Codex sin esos peldaños están fuera de soporte, y ocultarlos de los clientes actuales cuesta más de lo que compra. Otros peldaños todavía se intersectan con la escalera de entorno de ejecución observada, y un diagnóstico de pinza registrado por un binario anterior deja de aplicarse una vez que el binario en esa ruta informa una versión diferente (el caso de actualización en el lugar), por lo que `ocx status` y `ocx doctor` dejan de advertir sobre una pinza que el entorno de ejecución actualizado ya no necesita. La visibilidad del catálogo no es un derecho: la publicidad `max` / `ultra` no garantiza que la cuenta ascendente o el proveedor acepte el nivel, y para los modelos nativos más antiguos cuya escalera real se detenga en `xhigh`, la abrazadera de alambre de arriba aún mapea la selección en el momento de la solicitud. + + + +## Reglas de nivel rápido + +Codex almacena el modo rápido como: + +```toml +service_tier = "fast" + +[features] +fast_mode = true +``` + +Pero el catálogo de modelos y el identificador de nivel de solicitud en entorno de ejecución usan `priority`. opencodex preserva esa división. Los modelos de transferencia nativos OpenAI mantienen un soporte rápido; los proveedores enrutados tienen acceso a la capacidad: `service_tier` se elimina solo cuando el proveedor declara `supportsServiceTier: false` (el registro clasifica los canónicos OpenAI como `true`, DeepSeek y Volcengine Ark como `false`), mientras que las puertas de enlace personalizadas no clasificadas mantienen intactos los valores suministrados por el llamante y nunca reciben una inyección. Una puerta de enlace personalizada puede optar a nivel mundial con `supportsServiceTier: true`, o por poco con `modelSupportsServiceTier: { "verified-model": true }`; un `false` exacto reduce un predeterminado de proveedor de `true`, mientras que el nivel de proveedor `false` permanece cerrado por error. La misma decisión final del adaptador/modelo controla tanto los metadatos del catálogo como la inyección en entorno de ejecución, por lo que la opción rápida nunca se anuncia donde no se puede cumplir. Un destino `openai-chat` puede autorizar todos los modelos elegibles con `chatServiceTier: true`, o autorizar solo modelos exactos con `modelSupportsServiceTier`; Responses rutas no necesitan esa autorización de cable de chat adicional. + + + +### Selección ultra rápida en el escritorio Codex + +Para un proveedor que admita `service_tier: "ultrafast"`, declare esa asignación de cables una vez. opencodex publica entonces **Ultra rápido** en el menú de velocidad nativo Codex del modelo enrutado; no hay necesidad de editar `opencodex-catalog.json` después de cada sincronización. Por ejemplo, fusione estos campos en un proveedor API configurado para GPT-6.1 Sol: + +```json +{ + "models": ["gpt-6.1-sol"], + "modelSupportsServiceTier": { "gpt-6.1-sol": true }, + "fastWire": { + "kind": "service-tier", + "canonicalToWire": { "priority": "priority", "ultrafast": "ultrafast" }, + "foreignCallerTiers": "verbatim" + } +} +``` + +La asignación se aplica a todos los modelos Fast-elegibles en ese proveedor. Utilice una entrada de proveedor independiente si solo algunos de sus modelos son compatibles con Ultra Fast. Mantenga el modo rápido de opencodex en **Auto** (omit `fastMode` ) para que la selección de velocidad de la aplicación llegue al proveedor; forzó a Fast a enviar `priority`, y forzó a Default a dejar caer el nivel. Actualizar el catálogo de modelos, reiniciar el escritorio Codex si todavía tiene la lista anterior, seleccione el modelo enrutado y luego elija **Ultra rápido** en su menú de velocidad. El estándar sigue siendo el valor predeterminado. + +Solo un cable `service-tier` elegible con una asignación explícita de `ultrafast → ultrafast` agrega esta opción a las filas enrutadas; el soporte Fast ordinario o un nombre similar a GPT es insuficiente. Esa asignación enrutada no se aplica a filas nativas/de cuenta o alias combinados. La eliminación de la asignación o la desactivación del soporte de nivel de servicio de ese modelo elimina la opción enrutada generada tanto del catálogo como de la caché en la siguiente sincronización exitosa. La declaración activa también controla la opción Ultra Fast cuando Codex carga su lista de modelos sobre HTTP. + +Para filas enrutadas, `ultraFastTier` conserva los niveles Ultra Fast suministrados de forma independiente desde la misma fila persistente exacta; los niveles enrutados generados no se tratan como proporcionados por el operador. Para las filas `gpt-6-astra` / `gpt-6.1-sol` nativas desnudas y sus clones vinculados a la cuenta de confianza, habilitar `ultraFastTier` también genera una opción Ultrafast que falta sin cambiar el nivel predeterminado nativo. Al deshabilitarlo, solo se retiran los metadatos de nivel nativo rastreados según se generan; se conservan los descriptores de nivel nativo suministrados o editados de forma independiente. + +[OpenAI 's API guía](https://developers.openai.com/api/docs/guides/ultrafast-mode) documentos Ultrafast para GPT-6 Astra y GPT-6.1 Sol. API acceso y [Codex plan/acceso al espacio de trabajo](https://learn.chatgpt.com/docs/agent-configuration/speed) están separados. La elección del menú no otorga acceso al proveedor ni garantiza la velocidad medida; Ultra Fast aumenta el uso / costo, y los requisitos de características propias de Codex aún se aplican. + + + +## Selección de subagentes + +Codex ordena las entradas del catálogo visibles en el selector por `priority` ascendente y anuncia las cinco primeras como alternativas de modelo para `spawn_agent`. La página Subagentes del dashboard permite seleccionar y guardar hasta cinco identificadores nativos sin prefijo o identificadores `provider/model` enrutados. Un `subagentModels` configurado manualmente también acepta identificadores `/` que especifican una cuenta. El dashboard conserva esos identificadores exactos al guardar la lista, incluso si sus modelos ya no están disponibles en el catálogo actual. opencodex asigna prioridades bajas de catálogo en el orden seleccionado; cuando están habilitadas las filas del selector por cuenta, las selecciones nativas sin prefijo se expanden a grupos por selector. Los demás modelos siguen siendo invocables mediante su identificador exacto. + +La lista de modelos destacados está separada de la selección **Delegación de subagentes** del Dashboard. Controla que anula Codex ofrece primero; no selecciona un modelo o desencadenar delegación por sí mismo. + + + +## Servidores remotos de escritorio + +Codex El modo de servidor remoto del escritorio filtra el selector contra el propio cliente +`available_models` allowlist (activo cuando el control remoto `use_hidden_models` El ajuste está activado). Encaminado Las entradas del catálogo todavía se cargan y sirven - `model/list` devuelve y el CLI incluido lee - pero el renderizador de escritorio deja caer cualquier cosa que no esté en esa lista de permisos solo nativa antes renderizado. opencodex no tiene ningún gancho en esa lista; el error de flujo ascendente se rastrea en +[openai/codex#19694](https://github.com/openai/codex/issues/19694). + +Until Desktop expone un control para la lista de permisos: + +- Fije el modelo directamente en `~/.codex/config.toml` en la máquina remota, por ejemplo `model = "input/grok-4.5"`. El selector puede mostrar `Custom`, pero las solicitudes aún usan el modelo enrutado configurado. +- Utilice Codex CLI o TUI en lugar del selector de escritorio; no aplican la lista de permisos y la lista de modelos enrutados normalmente. + + + +## Estado del modelo refrescante + +Si el selector sigue mostrando entradas obsoletas, actualice el catálogo y reinicie la superficie de destino Codex: + +```bash +ocx sync +``` + +opencodex reescribe `models_cache.json` con un envoltorio de caché deliberadamente obsoleto cada vez que cambia la visibilidad del catálogo, la prioridad o los metadatos, por lo que la próxima actualización del modelo Codex lee el nuevo catálogo. + +Después de escribir un catálogo o modelo de caché, OpenCodex invalida su observación de aplicación-servidor en caché para que la siguiente solicitud verifique la frescura del proceso nuevamente. Una sincronización de configuración también invalida la observación cuando el contenido del catálogo no cambia. Esta actualización no reinicia los procesos Codex. diff --git a/docs-site/src/content/docs/es/guides/codex-integration.md b/docs-site/src/content/docs/es/guides/codex-integration.md new file mode 100644 index 00000000000..bf8d42ba253 --- /dev/null +++ b/docs-site/src/content/docs/es/guides/codex-integration.md @@ -0,0 +1,901 @@ +--- +title: "Integración con Codex" +description: "Cómo se inyecta opencodex en Codex, sincroniza el catálogo de modelos, instala shims y restaura limpiamente." +--- + +opencodex enruta Codex a través del proxy modificando dos elementos que Codex lee: su configuración (`$CODEX_HOME/config.toml`, por defecto `~/.codex/config.toml`) y su catálogo de modelos. Cada cambio es idempotente y reversible. + +El resumen **Conectar** incluye un interruptor de Codex para esta integración nativa. Muestra el último estado deseado guardado en OpenCodex, incluso justo después de cambiarlo; la insignia indica si se observa que Codex está utilizando el proxy. Durante la limpieza ambos estados pueden diferir brevemente. Al desactivar la integración se identifica el archivo de configuración efectivo de Codex, se eliminan los elementos de enrutamiento generados por OpenCodex y el proxy sigue disponible para otros clientes. Al reactivarla se reconstruye el catálogo con los modelos disponibles en ese momento; no se restauran los archivos de Codex byte por byte. + +El catálogo incluye metadatos de los programas de acceso autenticados tanto para los modelos nativos de Codex sin prefijo de cuenta como para las filas generadas del selector de cuentas. Los modelos sin prefijo utilizan la cuenta principal de Codex; los modelos con cuenta específica usan la seleccionada. Actualizar la integración renueva estas filas cuando cambian los programas de acceso de la cuenta. OpenCodex incorpora la información de disponibilidad de modelos de la cuenta principal que tiene la sesión iniciada a las filas nativas sin prefijo. + +El proxy expone la ruta de inicio de sesión de Codex `openai` sin prefijo, con los modos de cuenta Pool (predeterminado) y Direct, además de `openai-apikey/` para la clave API configurada. Pool incluye la cuenta principal y las añadidas; Direct utiliza únicamente la credencial de quien realiza la solicitud o la cuenta principal. Estas rutas no recurren unas a otras como alternativa. Las configuraciones v1 existentes migran al marcador 2 y conservan `config.json.pre-openai-tiers-v2.bak` para una restauración manual. + +En modo Pool, una solicitud con un inicio de sesión nativo de Codex validado puede utilizar esa sesión cuando la cuenta almacenada seleccionada está en periodo de espera y no hay otra cuenta almacenada ni una sonda de recuperación aptas. Esto también se aplica a una solicitud nueva bloqueada antes del envío, con la misma validación de identidad utilizada después de un rechazo del proveedor. Se siguen aplicando los permisos del modelo y las políticas de la cuenta principal. Esta alternativa conserva el periodo de espera de la cuenta almacenada y no guarda la credencial de quien realiza la solicitud como selección de Pool. Un enlace exacto a una cuenta permanece vinculado a ella. Fijar una cuenta manualmente en Pool expresa una preferencia; no crea un enlace exacto y todavía permite esta alternativa. Utilice un modelo con cuenta específica cuando la solicitud deba permanecer en una sola cuenta. Pausar la cuenta principal nativa observada bloquea esta alternativa para la credencial coincidente, pero no identifica ni pausa otras sesiones de quien realiza la solicitud. + +Al añadir o volver a autenticar una cuenta de Pool, se rechaza un duplicado de la sesión principal nativa con `Account is already configured as the native Codex main account.`. La comprobación compara el ID de cuenta de ChatGPT, el ámbito de suscripción personal o de espacio de trabajo y el correo electrónico; la ausencia de correo no demuestra que sea otra identidad. Se siguen admitiendo espacios de trabajo distintos, miembros diferentes de un mismo espacio y suscripciones personales y de espacio de trabajo independientes. Un fallo al consultar el uso no descarta el plan de suscripción incluido en el token de inicio de sesión. + +Los duplicados existentes se conservan, pero no pueden seleccionarse como una segunda cuenta de Pool. La lista de cuentas expone `selectionExcludedReason: "duplicate_main"` y una `selectionExcludedAction` con instrucciones. Utilice explícitamente la cuenta principal nativa o inicie sesión en Codex nativo con otra cuenta antes de reutilizar la entrada guardada. La detección sigue la observación más reciente de la sesión nativa propia, incluso después de un nuevo inicio de sesión. La consulta pasiva de cuentas y las solicitudes con credenciales de quien llama no abren las credenciales nativas para actualizar esa observación. + + + +## Inyección de configuración + +`ocx sync` elimina del catálogo los esfuerzos de razonamiento que no admite el entorno de ejecución de Codex seleccionado. Informa de la limitación cuando cambian la identidad de ese entorno, los esfuerzos eliminados o los modelos afectados. Las sincronizaciones sin cambios conservan la fecha del diagnóstico y no repiten el aviso. Esta adaptación de compatibilidad no requiere ejecutar `ocx doctor`. Si la limitación desaparece y luego vuelve, se informa otra vez. + +OpenCodex serializa su configuración Codex. En Windows, un archivo mantenido temporalmente abierto por otro proceso obtiene un breve reintento limitado. Si el acceso permanece ocupado, vuelva a intentar la operación en breve; OpenCodex conserva la evidencia de bloqueo existente y no utiliza ese fallo de acceso para hacerse cargo de la cerradura de otro escritor. + +`ocx init`, `ocx start`, y `ocx sync` Llame al inyector. En el enlace de bucle predeterminado, se mantiene Codex incorporado `openai` ID de proveedor y apunta a ese proveedor en opencodex: + +```toml +# root keys, before the first table +model_catalog_json = "/absolute/path/to/opencodex-catalog.json" +# Auto-injected by opencodex (undo: ocx restore) +openai_base_url = "http://127.0.0.1:10100/v1" +# Auto-injected by opencodex (undo: ocx restore) +experimental_realtime_ws_base_url = "http://127.0.0.1:10100/v1" + +# only when fastMode is set; unset adds no [features] table +[features] +fast_mode = true +``` + +La segunda clave es la anulación de banda lateral de voz. Codex crea una llamada de voz WebRTC a través de `openai_base_url`, pero desde el Codex 0.146 (openai/codex#35830) se une a la banda lateral de esa llamada WebSocket en `api.openai.com` directamente a menos que `experimental_realtime_ws_base_url` lo redirija. En el modo Pool, la llamada se crea bajo la cuenta opencodex selecciona, por lo que una unión directa bajo el propio inicio de sesión de la aplicación falla con `realtime websocket handshake failed` (404). La clave inyectada envía la unión de vuelta a través de opencodex (`GET /v1/live/{callId}`), donde el Pool reutiliza la cuenta que enlazó a ese par de sesión/hilo (un enlace de proceso-local). Una llamada que el propio cliente creó es la excepción: cuando ChatGPT voz manos una llamada a un Codex hilo, o Codex escritorio crea la llamada por su cuenta, la llamada pertenece a su inicio de sesión ChatGPT y sólo su banda lateral join alcanza opencodex, por lo que opencodex reenvía que se unen con la propia ChatGPT credencial de la persona que llama en lugar de una cuenta Pool. En el modo Direct ambas patas ya usan el portador actual de la persona que llama, por lo que la clave solo mantiene la unión en la ruta proxy. Está escrito solo en el formulario loopback `openai_base_url`, se elimina junto con él, y un `experimental_realtime_ws_base_url` propiedad del usuario nunca se sobrescribe. + + + +### Transporte de voz y traspasos de tareas + +Codex posee el micrófono y el altavoz, negociación de medios WebRTC, subtítulos, controles de silencio y limpieza de voz al cambiar de hilo. OpenCodex retransmite la creación de llamadas y la conexión de banda lateral; el trabajo delegado por voz utiliza la ruta de enrutamiento Responses normal. La elección de un proveedor de texto no reemplaza el modelo de voz en tiempo real ni habilita la voz en un cliente que no lo admite. + +Los [Cambio de ayudante WebRTC](https://github.com/openai/codex/commit/1b53f6a44eff890b5169bde8d3bd5b12b8766946) y [Integración de voz TUI](https://github.com/openai/codex/commit/b01c3986fd2e79b8a477a08d81430f52f22bc0dc) describen estas responsabilidades del cliente, incluyendo las respuestas finales de los traspasos de voz. Sus fechas de fusión no se establecen cuando el mismo comportamiento llegó a la aplicación de escritorio. + +Los diagnósticos opcionales `OCX_LIVE_FRAME_LOG` escriben solo la marca de tiempo de trama, la dirección, el tipo, el recuento de bytes y una bandera de caracteres de reemplazo (`ts`, `dir`, `kind`, `bytes`, `fffd`). No almacenan texto de voz o extractos de marcos. Para tramas binarias, la decodificación UTF-8 puede producir caracteres de reemplazo, por lo que la bandera sola no identifica dónde ocurrió la corrupción. Los archivos de registro existentes no se reescriben. + + + +### Modo rápido + +El `fast_mode` inyectado sigue el ajuste de tres estados `fastMode`: `true` escribe `fast_mode = true`, `false` escribe `fast_mode = false`, y unset deja un `fast_mode` existente intacto sin agregar una tabla `[features]`. + +El modo rápido está separado del transporte de voz. La descripción de la velocidad de nivel de servicio de un modelo compatible no garantiza un micrófono más bajo, WebRTC o latencia de voz de extremo a extremo hasta OpenCodex. + + + +### Canal y latencia de la familia ChatGPT + +Las solicitudes enrutadas a través de opencodex a través del proveedor canónico ChatGPT -login `openai` - adaptador `openai-responses`, `authMode: "forward"` y el punto final `https://chatgpt.com/backend-api/codex`, que cubren los modos Pool y Direct, usan el punto final público ChatGPT. El enrutamiento del proveedor o la selección de la cuenta no omite el canal ascendente ChatGPT. El flujo ascendente puede pasar tiempo poniendo en cola una solicitud antes de la primera salida incluso cuando el proxy local y la ruta de red están sanos. + +Solo algunos giros toman el transporte websocket ChatGPT, el mismo carril `responses_websockets` Codex CLI predeterminado. Un turno es elegible cuando el entorno de ejecución Bun soporta el relé limitado, la solicitud es un `POST` a la URL canónica Responses o una ruta WebSocket configurada, y su cuerpo JSON establece `stream` a `true` en la raíz. Todo lo demás permanece en SSE sobre HTTP, y un giro elegible sigue cayendo de nuevo a él cuando la solicitud no se puede preparar, la trama `response.create` excede su límite de tamaño, o la ruta proxy no puede llevar el socket. + +Para mantener el proveedor ChatGPT incorporado en HTTP / SSE, configure `providers.openai.upstreamWebsocket` a `false` en `~/.opencodex/config.json` y reinicie el proxy. Fusione este campo en el proveedor `openai` existente; conserve su modo de cuenta y otras configuraciones. Omite el campo para restaurar la selección predeterminada de aguas arriba WebSocket. Esta configuración no cambia el conmutador `websockets` orientado al cliente ni la cuenta ChatGPT utilizada para la solicitud. La dirección y la inyección nativas a mitad de giro necesitan corriente arriba WebSocket y no están disponibles mientras están apagadas. + +**Metadatos de uso del razonamiento (disponibles desde la versión 2.90.0).** Para los clientes HTTP/SSE de la ruta canónica de ChatGPT, el relé WebSocket conserva el encabezado real de respuesta de conexión `x-reasoning-included` cuando Bun lo expone, también al reutilizar una conexión. Este encabezado indica a Codex que el uso informado por el servidor ya incluye el razonamiento anterior. Los metadatos recibidos antes del primer evento de Responses tienen prioridad; los posteriores permanecen en el flujo, pero no pueden modificar los encabezados ya enviados. El relé no inventa esta señal ni altera las cifras de uso. La ausencia de la señal del servidor y el ciclo de contabilización propio de Codex son problemas distintos: este cambio por sí solo no demuestra que se haya corregido la compactación anticipada. Las conexiones WebSocket del cliente ya completaron su actualización de protocolo antes de la respuesta del servidor de origen y no pueden recibir la señal retroactivamente como encabezado de esa actualización. + +El control local del ritmo de solicitudes también puede retrasar una solicitud antes de enviarla. Por eso, una primera salida lenta puede tener varias causas, entre ellas la cola del proveedor de origen. `ocx doctor` clasifica la configuración, pero no mide esos tiempos: compara el transporte real, el control de ritmo, la red y las observaciones del proveedor antes de sacar conclusiones. + +Lo que decide si una solicitud toma ese canal público es el destino al que se resuelve, no el nombre de la entrada del proveedor. Un proveedor que resuelve en otro lugar - `openai-apikey`, o una entrada personalizada que apunta a su propio API - llega a ese punto final directamente y no ve ChatGPT en cola. Una entrada con nombre personalizado que se resuelve en `https://chatgpt.com/backend-api/codex` con auth directo toma el mismo canal público que la fila incorporada, porque la clasificación lee el adaptador, el modo de auth y el destino en lugar del nombre de la entrada. + +La pista `ocx doctor` es más estrecha que el comportamiento del punto final que describe: solo inspecciona la fila `openai` incorporada, por lo que su ausencia no le dice nada sobre dónde se resuelve cualquier otro proveedor. + +`service_tier: priority` es una preferencia de solicitud. En el backend ChatGPT el `service_tier` echo no puede confirmar o denegar el nivel concedido: los giros programados como prioridad aún pueden hacer eco `default`, por lo que los registros de solicitud muestran el nivel de respuesta como una observación con confirmación `assumed`. Para el trabajo sensible a la latencia, compare los tiempos de primera salida observados entre los proveedores que realmente usa en lugar de asumir que cualquier canal en particular es más rápido. + +Para un reenvío de puerta de enlace a un backend con la misma limitación de metadatos, declare explícitamente [`responseTierAuthoritative: false`](/es/reference/configuration/providers/#response-service-tier-authority) en ese proveedor. La solicitud sigue enviando prioridad y registra el eco sin procesar, mientras que la programación rápida real permanece sin confirmar. Las pasarelas no declaradas y el oficial API mantienen su interpretación existente basada en la respuesta. La actualización de OpenCodex por sí sola no agrega esta declaración a las entradas de pasarela existentes: sin ella, una solicitud de prioridad elegible seguida de un eco `default` todavía registra `response-declined`. + +El proxy escucha en el puerto `10100` por defecto y sirve `POST /v1/responses`, `POST /v1/responses/compact`, `POST /v1/images/generations`, `POST /v1/images/edits`, `GET /v1/models`, `GET /healthz` y la superficie de gestión `/api/*`. + + + +### Gestión de contexto experimental (Codex 0.153+) + +Para una cuenta ChatGPT elegible, habilite la función experimental en el propio Codex de `config.toml` (combine esto en una tabla `[features]` existente): + +```toml +[features] +context_management.experimental_mode = true +``` + +En la integración de loopback integrada predeterminada, el siguiente inicio `ocx sync` o proxy cambia la raíz administrada `openai_base_url` a `http://127.0.0.1:10100/backend-api/codex`. Codex comprueba esta ruta de fondo antes de habilitar sus herramientas `new_context`, historial y notas. Iniciar una nueva sesión Codex después de la sincronización. La función sigue siendo opt-in; las URL base propiedad del usuario y la inyección remota de proveedor personalizado no se reescriben. No se necesita o se añade una anulación de ventana de contexto o límite de compactación. + +El prefijo backend alias las rutas de plano de datos existentes, incluyendo Responses WebSocket actualizaciones. Las rutas originales `/v1` y la anulación de banda lateral en tiempo real permanecen disponibles. El proxy también transmite los diez puntos finales POST nativos `alpha/history/v2/*` y `alpha/notes/v2/*` a través del proveedor `openai` incorporado con el adaptador `openai-responses` y el destino directo canónico ChatGPT. Direct utiliza el inicio de sesión actual de la persona que llama / principal; Pool selecciona una cuenta Codex. `openai-apikey` utiliza su clave API configurada, y los proveedores Responses personalizados o no canónicos no son candidatos para este contexto y no reciben credenciales de cuenta Codex. Estos puntos finales privados no son implementados por otros proveedores de modelos o la ruta OpenAI API -clave. + +Los encabezados de llamada están restringidos a la lista de permisos de reenvío Codex compartida: `authorization`, `chatgpt-account-id` y los metadatos de protocolo OpenAI beta, originador, sesión y Codex aprobados. El relé de contexto reenvía adicionalmente `x-openai-encrypted-tool-arguments` y `x-openai-tool-output-truncation-policy`; no se reenvían encabezados de llamada arbitrarios tales como cookies. Una clave de plano de datos proxy presentada como portadora se reemplaza con la credencial Codex seleccionada (el inicio de sesión principal almacenado en Direct); las credenciales faltantes fallan antes del reenvío. Las credenciales de admisión de proxy nunca van hacia arriba. Los argumentos cifrados, los cuerpos de respuesta y los estados de error ascendentes se conservan. + +Una respuesta de modelo ChatGPT exitosa registra la cuenta de servicio real de la sesión raíz en un registro de propiedad local de proceso limitado. El historial y las notas usan ese propietario registrado, incluida una cuenta seleccionada explícitamente, incluso cuando cambia la cuenta activa actual. La actualización del token de cuenta almacenada puede continuar para la misma cuenta física; se rechaza una identidad de cuenta reemplazada. Direct sesiones propiedad de la persona que llama mantienen la credencial de la persona que llama y no pueden ser tomadas por un portador proxy. Esto no migra el historial del lado del servidor entre cuentas. + +La propiedad está dividida por la clave API opencodex que admitió la solicitud, por lo que dos claves nunca llegan a las sesiones de la otra incluso cuando ambas se resuelven en el mismo espacio de trabajo ChatGPT. Un identificador de espacio de trabajo nombra a una persona, por lo que el registro también vincula al usuario estable que lleva la credencial aceptada: una actualización de token ordinaria para ese mismo usuario continúa la sesión, mientras que un usuario diferente en el mismo espacio de trabajo no lo hace. Cuando la credencial aceptada no demuestra ser un usuario estable, solo continúa esa credencial exacta. Ese principal es la clave opencodex API que presenta la solicitud. Un enlace remoto ya requiere uno, por lo que la propiedad funciona allí. En el enlace de bucle de retorno predeterminado opencodex admite solicitudes sin leer una clave, y la inyección de bucle de retorno incorporada no puede llevar la cabecera `x-opencodex-api-key`, por lo que Codex no presenta ninguna clave opencodex y el historial de contexto devuelve HTTP 403. **Por lo tanto, el relé está disponible en un enlace remoto con una clave configurada, o a un cliente que envía el propio `x-opencodex-api-key`, y no a través de la integración de bucle invertido incorporada predeterminada.** Si un proxy enlazado a bucle debería poder nombrar a un llamador es una decisión de mantenimiento abierta, por lo que el comportamiento actual se niega en lugar de adivinar. + +La propiedad desconocida, vencida, desalojada, conflictiva o reiniciada-perdida devuelve HTTP 409 antes de la selección de la cuenta o la E/S ascendente. El relé no adivina a partir de la cuenta activa actual. Las sesiones existentes deben guardar un punto de control u otro resumen duradero antes de habilitar la función o restablecer el contexto. Habilitarlo no rellena la historia anterior o las notas, y una nueva observación de propiedad no prueba que exista contenido backend más antiguo. Después de reiniciar, establezca la propiedad con una solicitud de modelo exitosa antes de usar herramientas de contexto; inicie una nueva sesión cuando haya conflictos de propiedad. + +La afinidad del modelo existente, el tiempo de reutilización y las reglas de reintento no cambian. Las solicitudes de contexto no se vuelven a intentar automáticamente, incluidas las escrituras de notas; Las solicitudes de reenvío ChatGPT no usan la repetición 429 de la misma clave. El tráfico del historial no consume ni establece una sonda de recuperación de cuotas del modelo. + +Un plazo de 35 segundos cubre toda la operación de retransmisión, comenzando antes de que se lea el cuerpo de la solicitud y cubriendo la selección de credenciales, por lo que un cliente estancado no puede mantener abierta una ranura de giro admitida. Una desconexión de cliente devuelve 499 y una fecha límite caducada devuelve 504; nada se despacha aguas arriba después de ninguna de las dos. + +Para deshabilitar la función, quite la clave experimental (o configúrela en `false`), ejecute `ocx sync` e inicie una nueva sesión Codex. La base raíz administrada vuelve a `/v1`. + +Mientras que la clave está ausente o `false`, el relé no existe: los diez puntos finales responden 404 para cualquier persona que llama, incluido uno que los publica directamente, y un modelo no registra ninguna propiedad del historial. opencodex decide esto leyendo la propia configuración Codex, por lo que el switch no depende de la URL inyectada ni de nada de lo que envíe un cliente, y desactivarlo entra en vigencia sin reiniciar. + + + +### Resultados de imágenes alojadas en la aplicación Codex + +Cuando un proveedor Responses encaminado devuelve un `image_generation_call` alojado completado con datos de imagen base64, opencodex guarda la imagen validada en su directorio local `artifacts/` y entrega un mensaje de imagen de asistente final a un cliente Codex conectado localmente. La imagen permanece fuera de la sección de progreso plegable. Esto se aplica a la transmisión y no transmisión Responses, sin otra solicitud de generación o un cambio en el proveedor seleccionado. + +Cuando un cliente reproduce estos mensajes de imagen generados como historial asistente, opencodex reemplaza sus enlaces de imagen local generados con referencias de artefactos opacos antes de reenviar ese historial. Esto protege las rutas de visualización sin cambiar el mensaje de imagen que ya se muestra en la aplicación. No elimina rutas no relacionadas suministradas por el usuario. + +Esta compatibilidad de pantalla requiere la admisión de loopback y un cliente Codex reconocido. Los clientes remotos y genéricos de API conservan el formato de respuesta alojado del proveedor. Las previsualizaciones parciales y los resultados solo de URL no se representan en esta capa de compatibilidad. Los artefactos usan el límite de retención existente, así que guarda las imágenes que quieras conservar antes de que se eliminen los archivos antiguos. Una imagen no válida o una escritura local fallida produce un mensaje de error visible en lugar de un enlace de imagen roto. Los lotes de visualización rechazan identidades de imagen duplicadas, metadatos de enrutamiento sobredimensionados y salidas que exceden el límite de bytes de visualización; estos fallos devuelven HTTP 502 antes de la transmisión o un evento de terminal fallido después de que se inicia. + + + +### Generación de imágenes incorporada (`image_gen`) + +Codex 's herramienta incorporada `image_gen` no pasa por `/v1/responses` - la extensión de Codex-rs POSTs `{base_url}/images/generations` (o `/images/edits` cuando se adjuntan imágenes de referencia) directamente, con el mismo ChatGPT portador auth que utiliza para el chat. Debido a que el `base_url` inyectado apunta al opencodex, el proxy retransmite esas llamadas al OpenAI aguas arriba. + +Esto es independiente del [Puente de imagen](/es/guides/image-bridge/), que solo se activa cuando un giro **Responses** enumera la herramienta `image_generation` alojada mientras se selecciona un modelo no OpenAI. Las llamadas independientes `/images/generations` nunca entran en ese puente. + +- **Un candidato avanzado con conciencia de modo:** Pool selecciona una cuenta principal/añadida elegible y usa su credencial ChatGPT almacenada incluso cuando el cliente se autentica en opencodex con un portador de admisión proxy. Direct usa el portador ChatGPT OAuth del llamante y no puede reenviar un token de admisión proxy. El modo configurado se aplica consistentemente a la solicitud de imagen. +- **OpenAI API -proveedor clave:** se usa solo cuando ningún candidato a reenviar posee un fallo de autenticación. Una credencial Pool rota / expirada nunca se oculta detrás del uso API facturado por separado. +- **Proveedor personalizado explícito:** establece `images.provider` a la identificación de un proveedor personalizado API -key `openai-responses` cuyo punto final implementa las OpenAI Imágenes API. La selección explícita falla al cerrarse y nunca vuelve a caer en un flujo ascendente pagado diferente. Los identificadores de proveedor administrados por el registro no se aceptan aquí; omita `images.provider` para usar los niveles OpenAI incorporados. +- **xAI Imagine (Grok OAuth) relé:** cuando `images.bridgeEnabled` es `true`, se omite `images.provider`, y se configura un proveedor `xai`, `/v1/images/generations` y `/v1/images/edits` se envían a `https://api.x.ai/v1`. La credencial depende del `authMode` del proveedor: con `"oauth"` el relé reutiliza la concesión Grok CLI de `ocx login xai`; con cualquier otro modo usa la clave API del proveedor. Un inicio de sesión OAuth no arma un proveedor con llave, y viceversa. ChatGPT credenciales no se reenvían. Si falta la credencial, el proxy devuelve 400 en lugar de la facturación ChatGPT. El ajuste `images.provider` le da explícitamente `/v1/images` a ese proveedor; sus propios errores de validación se devuelven tal cual y el relé xAI nunca se intenta. El relé mapea Codex `size` / `aspect_ratio` en el cuerpo Imagine de xAI y devuelve la misma forma `{created, data:[{b64_json}]}`. Los bytes decodificados combinados y la salida codificada en base64 a través del lote (en línea `b64_json` y las URL descargadas) permanecen por debajo de 100 MiB; un lote que excedería ese límite devuelve 502. Cuando xAI devuelve una URL de imagen en lugar de bytes en línea, el proxy la obtiene sin credenciales: la URL debe ser pública HTTPS (sin redirecciones, no `file:`, sin bucles de retorno o direcciones privadas), cada descarga tiene un límite de 50 MiB y el resultado se materializa como un artefacto local que se sirve solo a través del punto final de administración autenticado. Esto es independiente del bucle de puente de imagen Responses (que permanece API solo clave). +- **Google Antigravity (CCA) fallback:** cuando no se configura ni un candidato directo OpenAI ni un proveedor con clave, `/v1/images/generations` (no `/images/edits`) vuelve al punto final Antigravity **Asistencia de código en la nube** usando el modelo `gemini-3.1-flash-image`. La reserva también se activa después de que falla la resolución de autenticación OpenAI (por ejemplo, una credencial ChatGPT caducada o faltante), no solo cuando no se configura ningún candidato OpenAI. Esto requiere `ocx login google-antigravity`; el token OAuth se envía solo al host del registro CCA anclado, nunca a una anulación de nivel de configuración `baseUrl`. La respuesta se devuelve en la misma forma `{created, data:[{b64_json}]}` que Codex espera. +- **Tampoco:** el proxy devuelve un error claro en lugar de un 404 genérico. Los proveedores enrutados (Cursor, Gemini, Kiro,...) no pueden servir el relé de la herramienta `image_generation`; si no desea que la herramienta se ofrezca en absoluto, desactívela en Codex con `codex features disable image_generation` ( `[features] image_generation = false` en `config.toml` ). + +La declaración de la herramienta sigue viajando con la solicitud Responses del modelo. Para API-llave Responses proveedores, opencodex reduce la privacidad de Codex `image_gen` espacio de nombres a un nivel seguro +`image_gen__` alias (por ejemplo `image_gen__imagegen`) Cuando ese alias utilizable reemplaza la declaración de cliente, opencodex elimina un duplicado alojado `image_generation` declaración. Se mapea Llamada a la función explícita `image_gen` espacio de nombres antes de que Codex lo vea y codifique el llamar de nuevo cuando el historial posterior se reproduce de origen. Esto mantiene la generación de imágenes del lado del cliente llamable en upstreams compatibles con el público que reservan el espacio de nombres o rechazan los nombres de funciones punteadas. ChatGPT El modo de avance permanece intacto y mantiene su forma nativa Responses Lite. + +Para una puerta de enlace personalizada compatible con OpenAI, configure un proveedor dedicado y selecciónelo solo para solicitudes de imágenes independientes: + +```json +{ + "providers": { + "custom-images": { + "adapter": "openai-responses", + "baseUrl": "https://gateway.example.com/v1", + "authMode": "key", + "apiKey": "${IMAGE_GATEWAY_API_KEY}" + } + }, + "images": { + "provider": "custom-images", + "timeoutMs": 300000 + } +} +``` + +El punto final personalizado debe aceptar `POST /v1/images/generations` y `/v1/images/edits` y devolver la forma de respuesta de Imágenes OpenAI esperada para Codex. La clave configurada por el proveedor reemplaza cualquier portador de llamada antes de la solicitud ascendente. + +> **Nota:** Esto se refiere solo a la herramienta Codex `image_generation` (relé `/images/generations`). Gemini modelos que son capaces de producir imágenes en línea de forma nativa a través del adaptador `google` (vía `responseModalities: ["TEXT", "IMAGE"]`), independiente de este relé - ver [Adaptadores](/es/reference/adapters/#google). + +Para un `hostname` sin bucle, Codex debe enviar la cabecera de autenticación API generada. Por lo tanto, el inyector utiliza un proveedor dedicado en su lugar: + +```toml +# root keys +model_provider = "opencodex" +model_catalog_json = "/absolute/path/to/opencodex-catalog.json" + +# appended at the end of the file +# Auto-injected by opencodex (undo: ocx restore) +[model_providers.opencodex] +name = "OpenCodex Proxy" +base_url = "http://your-host:10100/v1" +wire_api = "responses" +requires_openai_auth = true +env_key = "OPENCODEX_API_AUTH_TOKEN" +# supports_websockets = true # only when config.websockets is true +``` + +Cuando OpenCodex posee enrutamiento, ambos modos escriben `$CODEX_HOME/opencodex.config.toml` como una configuración de referencia/retroceso. En loopback contiene las claves de raíz que puede combinar manualmente si se eliminó la inyección automática; en non-loopback contiene el formulario de proveedor dedicado. El modo de proveedor externo deja este perfil intacto. + +:::caution +Claves de raíz como `openai_base_url`, `model_provider`, y `model_catalog_json` **debe** sentarse antes de la primero `[table]` cabecera. El inyector garantiza esa colocación, elimina su propio rancio / duplicado copia, y nunca sobrescribe una raíz propiedad del usuario `openai_base_url`; si existe, la sincronización actualiza el catálogo, pero informa que el enrutamiento no fue inyectado. +::: + + + +## Catálogo de modelos compartido + +Codex CLI, TUI, App y SDK leen todos la misma casa Codex. opencodex resuelve ese directorio desde `CODEX_HOME`, volviendo a `~/.codex`, y gestiona: + +```text +$CODEX_HOME/config.toml +$CODEX_HOME/opencodex.config.toml +$CODEX_HOME/opencodex-catalog.json +$CODEX_HOME/models_cache.json +``` + +En marcha macOS, opencodex comprueba la Codex Apps agrupadas CLI en `/Applications/ChatGPT.app` y luego `~/Applications/ChatGPT.app` después de selecciones explícitas, shims, PATH, instalaciones establecidas y el ejecutable bare `codex` fallback, requiere XML del paquete `Info.plist` identidad para ser `com.openai.codex`, y nunca reemplaza automáticamente una selección persistente ejecutable con un candidato de aplicación. + +En WSL, si `CODEX_HOME` está desactivado y el directorio Linux `~/.codex` está ausente o no mantiene el estado Codex (`config.toml`, `auth.json`, `sessions`, `history.jsonl`), opencodex también comprueba un único inicio de escritorio Windows Codex en `/mnt/c/Users/*/.codex/config.toml`. Cuando existe exactamente un candidato, utiliza ese directorio para que el modo de servidor de aplicaciones WSL y el escritorio Windows Codex compartan los mismos archivos de configuración y autenticación. Establecer `CODEX_HOME` explícitamente para anular esta detección. Cuando Windows Codex Desktop ejecuta su aplicación-servidor dentro de WSL, envía el binario Linux Codex bajo esa casa como `bin/wsl//codex`; opencodex lo encuentra allí cuando el PATH de servicio no tiene `codex`, después de cualquier entorno de ejecución y PATH configurados explícitamente. + +Si existe la casa Codex pero Codex no ha escrito `config.toml` (por ejemplo, una nueva instalación de escritorio que nunca se ha iniciado sesión en OpenAI), opencodex crea un `config.toml` allí y continúa. Si el directorio principal en sí no existe, inicie Codex una vez para que lo cree o establezca `CODEX_HOME`. + +Codex puede mantener el estado del subproceso respaldado por SQLite en un directorio separado. Las operaciones de la historia OpenCodex usan la misma precedencia que Codex: raíz `sqlite_home` en `config.toml`, luego `CODEX_SQLITE_HOME`, luego el efectivo `CODEX_HOME`. SQLite hogares resolver desde el directorio de trabajo actual. Cuando un `CODEX_SQLITE_HOME` explícito está presente durante la instalación o reparación del servicio, el lanzador durable almacena su ruta absoluta de tiempo de instalación de modo que el proxy de segundo plano continúa direccionando la misma base de datos. Si `config.toml` o su clave raíz `sqlite_home` está ausente, OpenCodex continúa en el entorno / casa. Si el archivo no se puede leer o analizar, o la clave está presente pero en blanco o no una cadena, la resolución -home SQLite se detiene en lugar de arriesgar las operaciones del historial contra una base de datos diferente. + +En Windows, un shell de Orca puede establecer `CODEX_HOME` y `ORCA_CODEX_HOME` en el hogar en entorno de ejecución incluido de Orca, mientras que la aplicación ChatGPT / Codex todavía lee `%USERPROFILE%\\.codex`. `ocx status` y `ocx doctor` advierten sobre este desajuste exacto y las rutas de destino redactadas por impresión. Si se instaló un servicio en segundo plano desde ese shell de Orca, desinstálelo primero desde el shell original, luego configure `CODEX_HOME` en el inicio de la aplicación, desactive `ORCA_CODEX_HOME`, vuelva a ejecutar la sincronización / restauración e instale el servicio nuevamente. + +En el modo de proveedor dedicado, `requires_openai_auth = true` mantiene Codex App / TUI superficies cerradas por cuenta alineadas con Codex nativo. opencodex también sirve `/v1/responses` sobre WebSocket. El proveedor dedicado anuncia `supports_websockets = true` solo cuando `"websockets": true`; en loopback Codex 's proveedor incorporado puede intentar WebSocket primero, y un proxy deshabilitado devuelve `426` así Codex cae de nuevo a HTTP / SSE. + +El proxy admite hasta 128 conexiones Responses WebSocket orientadas al cliente. Cuando una nueva conexión encuentra las 128 ranuras ocupadas, cierra la conexión inactiva menos recientemente utilizada para hacer espacio. Las conexiones con una respuesta activa, una herramienta de cliente pendiente o resultados de aprobación, una sesión de dirección/inyección nativa o una salida almacenada en búfer están protegidas. Si no se puede liberar ninguna conexión inactiva, la nueva conexión recibe la respuesta de capacidad `503` existente. Un cliente reclamado puede volver a conectarse para solicitudes posteriores utilizando el manejo de continuación existente. Esto sucede solo bajo presión de conexión, no necesita configuración y no cambia las conexiones de voz o la reutilización de la conexión ascendente. + +Si una continuación canónica hacia adelante ChatGPT hace referencia a un estado de repetición local caducado o faltante, opencodex devuelve `previous_response_not_found` antes de enviar cualquier cosa aguas arriba. El cliente Codex de WebSocket reconoce este error y puede volver a conectarse con su contexto completo retenido, incluyendo llamadas de herramientas completadas y sus resultados, dentro de su presupuesto de reintento de flujo normal. Por lo tanto, una tarea inactiva no necesita una tarea nueva únicamente porque la caché de reproducción del proxy expiró. El estado de continuación reproducido se conserva durante 24 horas y permanece limitado por su memoria, disco y límites de entrada existentes; esto no recupera el historial que el cliente ya no tiene. HTTP clientes deben manejar el error explícitamente y volver a enviar su contexto completo sin `previous_response_id`. Volver a intentar solo el mismo ID no puede recuperar el estado faltante. + +El mismo rechazo se aplica cuando el estado referenciado pertenece a un ámbito de tarea cliente diferente, incluso cuando la nueva solicitud parece llevar entrada completa. El proxy no puede probar que la entrada está completa, por lo que no elimina silenciosamente `previous_response_id` ni revela si existe un estado coincidente. Vuelva a intentar con la conversación completa y omita `previous_response_id`; los ámbitos coincidentes y las continuaciones heredadas donde ambos ámbitos están ausentes o en blanco continúan reproduciéndose normalmente. + +La misma señal de recuperación se aplica a cada destino enrutado, porque solo el paso a través nativo Responses puede responder a un giro cuya historia perdió este proxy: reenvía `previous_response_id` a un backend que almacenó la cadena. Cada uno de los otros cables reconstruye la conversación a partir de la propia entrada de cada solicitud, por lo que una expansión perdida allí enviaría el giro actual solo y perdería silenciosamente la conversación. Eso incluye los tres que parecen con estado: Devin vuelve a enviar toda la conversación a cada paso, la referencia de punto de control de Cursor vive en la misma tienda vencida y vuelve a la reproducción completa sin ella, y Kiro reconstruye su historial de conversaciones a partir de los turnos en que se entregó. También se aplica a los proveedores enrutados Responses configurados con `statelessResponses: true`, y a las solicitudes enrutadas donde una herramienta personalizada se redujo a una función pero un resultado delta no tiene llamada local para establecer su tipo original. La reproducción completa conserva la llamada, el resultado y el razonamiento juntos; opencodex no adivina el tipo de resultado ni lo descarta. Los proveedores estatales todavía resuelven la función nativa y las continuaciones personalizadas nativas por sí mismos. Estas comprobaciones siguen el protocolo de cable seleccionado y las declaraciones de la herramienta, no el nombre del modelo. Para una puerta de enlace que no puede resolver los ID de respuesta almacenados, habilite `statelessResponses` en ese proveedor; otros proveedores mantienen sus valores predeterminados. + + + +### Compactación del lado del cliente (opcional) + +El enrutamiento de bucle de retorno autenticado normalmente mantiene Codex en su identidad de proveedor `openai` incorporada. Eso preserva la identidad del hilo nativo, pero también hace que Codex solicite la compactación remota nativa. Cuando un proveedor enrutado no puede devolver una burbuja de compactación nativa, OpenCodeX almacena el resumen en su propio sobre `ocx1:` / `ocx2:`. Native ChatGPT no puede verificar ese sobre si OpenCodeX se elimina más tarde de la ruta de la solicitud. + +En una ruta de bucle de retorno autenticada, habilite la compactación en el lado del cliente para mantener el enrutamiento de subagentes V2 al tiempo que evita nuevos resúmenes de compactación `ocx1:` / `ocx2:`. Las rutas no loopback y API-key conservan su comportamiento de proveedor y autenticación existente: + +```bash +ocx system settings --client-compaction on # or "codexClientCompaction": true in config.json +ocx sync # rewrites the active config (default: ~/.codex/config.toml); restart Desktop +``` + +El ajuste predeterminado es off. Para el enrutamiento de bucle de retorno autenticado, OpenCodeX selecciona su formulario de proveedor dedicado existente con `requires_openai_auth = true`. Si `codexDesktopAuthless` también está habilitado, esa configuración de compatibilidad más fuerte tiene prioridad y escribe `requires_openai_auth = false`: + +```toml +model_provider = "opencodex" + +[model_providers.opencodex] +name = "OpenCodex Proxy" +base_url = "http://127.0.0.1:10100/v1" +wire_api = "responses" +requires_openai_auth = true +``` + +Codex luego posee compactación y almacena un resumen de texto plano portátil en lugar de un nuevo sobre OpenCodeX. La solicitud de compactación sigue enrutando a través de OpenCodeX y puede consumir cuota en el proveedor seleccionado. Las solicitudes de subagentes V2 mantienen su selección de proveedores existente y la contabilidad de cuotas. La compactación del lado del cliente no cambia la entrega de texto sin formato, el paso de tareas encriptadas a través de `allowEncryptedV2AgentTasks` o el comportamiento de recuperación y recuperación configurado. + +Esta preferencia solo afecta las compactaciones futuras, y no reescribe ninguna carga útil `ocx1:` / `ocx2:` existente en ninguna configuración, así que use el flujo de trabajo de recuperación de historial explícito para un subproceso que lo necesite. + +Si se vuelven a etiquetar los metadatos del historial de reanudación depende de la forma que tome la inyección. Por sí solo, en un enlace de bucle de retorno autenticado, la compactación del lado del cliente no vuelve a etiquetar nada: mantiene la anulación de raíz, como se describe a continuación. Habilitado junto con `codexDesktopAuthless`, o en un enlace que no sea de bucle invertido, el formulario más fuerte gana y esos formularios se comportan exactamente como lo hacen hoy, incluido su etiquetado hacia adelante existente del historial de reanudación con originales respaldados para su restauración. + +Volver de una de esas formas a Diseño B simple migra los hilos reetiquetados hacia atrás. Apagar `codexDesktopAuthless` mientras se deja la compactación del lado del cliente encendido no lo hace: eso aterriza en la forma de solo compactación, que se salta la unidad de historial, por lo que los hilos ya etiquetados `opencodex` mantienen esa etiqueta. Todavía llegan a este proxy, a través de la tabla del proveedor en lugar de la anulación de la raíz. + +En la forma de solo compactación, los hilos existentes siguen funcionando porque la inyección mantiene la raíz `openai_base_url` junto a la mesa del proveedor. Los nuevos hilos predeterminados a `opencodex` y obtener compactación del lado del cliente, mientras que un hilo ya etiquetado `openai` todavía resuelve a Codex 's proveedor integrado - que la anulación retenida todavía apunta a este proxy. Sin él, ese hilo se reanudaría contra OpenAI directamente, llevando el enrutamiento configurado con él. Las formas authless y non-loopback no pueden usar la clave raíz, por lo que siguen reetiquetando. + +Esa garantía cubre la anulación que administra OpenCodeX. Una raíz `openai_base_url` que escribió usted mismo nunca se reemplaza, y en ese caso el proveedor integrado mantiene el destino que eligió, por lo que un hilo etiquetado `openai` sigue su configuración en lugar de este proxy. Desactivar el ajuste y la sincronización elimina la tabla y vuelve a la anulación de diseño B simple, a menos que la admisión `codexDesktopAuthless` o no loopback aún requiera el formulario de tabla de proveedor; esos dos formularios no pueden usar la clave raíz y no se modifican. + +Mientras el modo está activo, la anulación de banda lateral de voz en tiempo real (`experimental_realtime_ws_base_url`) no se inyecta - el formulario dedicado de tabla de proveedores no puede llevarlo - por lo que Codex Desktop Voice utiliza su punto final nativo en lugar del proxy. + + + +### Modelo de compactación de emergencia (opcional) + +Cuando OpenCodeX traduce la compactación remota para proveedores como Google, reemplaza las imágenes de giros anteriores con notas cortas de reapertura si existe una respuesta final explícita posterior. El análisis existente y las referencias de archivo permanecen en la entrada de resumen; las imágenes después de la última respuesta final permanecen disponibles para el trabajo no resuelto. Se conservan las historias sin fase y solo comentarios. Esto afecta solo a la solicitud de compactación, no a los archivos adjuntos almacenados o a las solicitudes de modelo ordinarias. Reduce la entrada de visión repetida, pero no garantiza que un largo historial de texto se ajuste al límite de contexto del proveedor. + +`compactionRecovery` deja la compactación inicial en la ruta seleccionada de la conversación. Permite un intento de emergencia solo después de un fallo de compactación previo a la salida soportado. Está separado de `compactionRouting`, que elige otro modelo antes de que comience la compactación, y de `codexClientCompaction`, que cambia la forma del proveedor de Codex. + +```json +{ + "compactionRecovery": { + "enabled": true, + "model": "provider/emergency-model", + "allowDevinInvalidArgument": false + } +} +``` + +Utilice un modelo autorizado configurado independientemente con suficiente contexto para la entrada fallida. La habilitación de la recuperación permite al proveedor de ese modelo recibir el historial de compactación y cobrar por el intento adicional cuando se ejecuta la recuperación; las compactaciones exitosas ordinarias no incurren en ninguna llamada adicional. La opción está desactivada cuando está ausente o desactivado. La administración autenticada existente API acepta este bloque a través de `PUT /api/settings`; envíe `compactionRecovery: null` para eliminarlo. Una edición de archivo directa debe seguir el flujo de trabajo normal de configuración de stop-proxy. Esta configuración no cambia el inicio de sesión, el modelo ordinario de la conversación, el ID de proveedor de Codex o el compositor de escritorio. + +La recuperación no se reproduce después de la cancelación, la salida semántica, los efectos secundarios de la herramienta, un presupuesto de envío agotado o una autenticación, admisión o rechazo de políticas. Los errores genéricos `400` no habilitan la recuperación. Devin responde a un historial de gran tamaño con una presalida opaca `invalid_argument`; cuando el tamaño estimado de la solicitud está en o cerca de la ventana de entrada del modelo, el adaptador lo informa como `context_length_exceeded` en su lugar, por lo que Codex compacta en un giro ordinario y una compactación fallida califica como un desbordamiento de contexto sin ninguna opción específica de Devin. La estimación utiliza descripciones de herramientas después de la desinfección y truncamiento de Cognition, que coinciden con la solicitud enviada aguas arriba. Una solicitud más pequeña que obtiene el mismo código permanece como `400` simple. El estuche `allowDevinInvalidArgument` por separado cubre solo los `invalid_argument` fallos restantes, y solo en una solicitud de compactación identificada. El intento de emergencia comparte el presupuesto de envío de la solicitud original y nunca comienza un segundo intento de recuperación. + +La compactación encriptada nativa está fuera de esta ruta de recuperación: se conserva su error original. No hay modo de truncamiento local automático. Una respuesta aceptada no es prueba de que una larga conversación retuvo sus objetivos; verifique el siguiente turno en el modelo original antes de tratar un resumen de emergencia como una tarea recuperada. + + + +### Authless Codex Escritorio (opcional) + +En **Dashboard → Visión de conjunto**, **Abrir Codex sin iniciar sesión** controla esta preferencia opt-in existente. El valor predeterminado es **apagado** cuando la configuración está ausente o es falsa; un `codexDesktopAuthless: true` explícito existente permanece habilitado. El panel de control guarda la preferencia y ejecuta una sincronización completa. Reinicie el escritorio Codex después de cambiarlo. Si falla la sincronización, la preferencia guardada permanece y el panel de control muestra el error; reintente **Sincronización** antes de reiniciar. Las funciones de escritorio controladas por cuenta pueden no estar disponibles cuando se habilitan. Las credenciales ascendentes, la elegibilidad local, la autenticación de admisión remota y la configuración de la puerta de enlace propiedad del usuario conservan sus requisitos existentes. + +Codex Desktop muestra su pantalla de inicio de sesión ChatGPT cada vez que el proveedor activo requiere OpenAI auth. Si su configuración OpenCodex nunca usa credenciales ChatGPT (solo proveedores enrutados o un `chatgpt.com` bloqueado), puede optar por salir de esa puerta: + +```bash +ocx system settings --desktop-authless on # or "codexDesktopAuthless": true in config.json +ocx sync # rewrites ~/.codex/config.toml; restart Desktop +``` + +Con el interruptor activado, un enlace de bucle retro inyecta el formulario de proveedor dedicado en lugar de la anulación raíz `openai_base_url`: + +```toml +model_provider = "opencodex" + +[model_providers.opencodex] +name = "OpenCodex Proxy" +base_url = "http://127.0.0.1:10100/v1" +wire_api = "responses" +requires_openai_auth = false +``` + +El escritorio se inicia sin un inicio de sesión y las rutas de cada turno a través del proxy. La configuración sobrevive `ocx start`, reinicio, `ocx sync` y `ocx ensure`; al apagarlo (`--desktop-authless off`) hace que la siguiente sincronización restaure la forma de bucle de retorno predeterminada y `ocx restore` la despoja como cualquier otro enrutamiento inyectado. Qué esperar mientras está encendido: + +- ChatGPT -gated El cromo de escritorio (cuenta, uso, modo rápido) permanece oscuro: Codex deriva esas superficies del requisito de autenticación del proveedor. +- Los nuevos hilos se etiquetan con el proveedor `opencodex`, como en un enlace no loopback, y el historial se maneja de la misma manera. +- Las versiones de escritorio que filtran el selector de modelo contra una lista de permisos solo nativa también pueden mostrar un selector vacío o `Custom` en este modo; las solicitudes aún usan el modelo configurado. Conjunto `model = "/"` en `config.toml` como se describe en [Servidores remotos de escritorio](/es/guides/codex-app-models/#desktop-remote-servers). + +Esto solo cambia la puerta de inicio de sesión del escritorio. Non-loopback obliga a mantener `requires_openai_auth = true` y la credencial de admisión `env_key` independientemente del interruptor; nunca expone un oyente OpenCodex sin autenticación. + + + +## Identidad e historia del hilo + +El formulario de loopback predeterminado mantiene los nuevos hilos etiquetados con el proveedor nativo `openai` de Codex, por lo que el historial de reanudación normal no necesita volver a mapear. La sincronización y la restauración aplican solo un manifiesto de copia de seguridad coincidente y restauran el proveedor, la fuente y el marcador de eventos originales exactos de cada subproceso. Una fila desnuda de `opencodex` sin manifiesto se deja sin cambios; use `ocx recover-history --legacy-openai --yes` solo cuando tenga la intención explícita de forzar ese reetiquetado heredado. El comando es intencionalmente amplio: reescribe cada hilo con un mensaje de usuario actualmente etiquetado como `opencodex` a `openai`, normaliza `exec` a `cli` y establece el marcador de evento, incluido el historial legítimo de proveedores dedicados. Haga una copia de seguridad del estado y úselo solo cuando se pretenda ese alcance completo. El modo de proveedor dedicado sin loopback sigue reflejando el historial bajo el proveedor `opencodex` mientras está activo y restaura los metadatos de copia de seguridad al salir. Establecer `syncResumeHistory: false` para dejar la historia intacta. + + + +## Sincronización de catálogo de modelos + +Codex muestra modelos de un catálogo en el disco (`$CODEX_HOME/opencodex-catalog.json` de forma predeterminada). Al inicio y en `ocx sync`, opencodex: + +1. **Respalda** el catálogo prístino una vez a `~/.opencodex/catalog-backup.json` (por lo que la presentación es reversible). +2. **Muñecos** catálogos de modelos en vivo de los proveedores elegibles (en caché de 5 min; vuelve a la última buena lista, luego configuró `models[]`). La autenticación directa no tiene un punto final modelo, y Cursor utiliza su RPC `GetUsableModels` en lugar de `/models`. +3. **Combinaciones** enrutado modelos en entradas como namespaced (`provider/model`), clonado de una plantilla de catálogo nativo Codex por lo que Codex 's estricto analizador sintáctico los acepta. +4. **Filtros** `config.disabledModels` y la lista de permisos `selectedModels` no vacía de cada proveedor. +5. **Re-rangos** así que los modelos destacados ordenan primero (ver más abajo), luego escribe el catálogo fusionado de nuevo. + +Las entradas del catálogo enrutado también obtienen su identidad GPT-5 reescrita al nombre del modelo ascendente real. Los controles de razonamiento provienen de metadatos de proveedor/modelo en la escalera `low | medium | high | xhigh | +max | ultra` de Codex; los valores no compatibles se asignan o se fijan antes de la solicitud ascendente. + + + +### Diagnóstico y recuperación del coordinador + +Las escrituras de configuración/historia nativas usan un coordinador por usuario SQLite con la clave canónica `CODEX_HOME`. Si un proceso termina en la ventana de creación inicial de SQLite, puede permanecer un coordinador de cero bytes aunque no contenga ninguna fila de transición autorizada. `ocx doctor` informa la ruta exacta del coordinador y distingue los estados de cero bytes, sin versionar, sin filas, válidos, inseguros e ilegibles sin crear SQLite sidecars. La sincronización automática tolera solo un archivo de byte cero de identidad estable que se ha establecido durante al menos un segundo y cuya instantánea inmutable SQLite tiene la versión cero sin tablas; un archivo de byte cero recién creado permanece en la ruta del coordinador bloqueado. + +Para un estado que el médico prueba que es un remanente de creación de cero bytes, detenga el proxy / servicio OpenCodex y ejecute: + +```bash +ocx doctor --recover-zero-byte-coordinator --yes +ocx sync +``` + +La recuperación mueve el archivo de byte cero todavía idéntico a una ruta del mismo directorio `.zero-byte-backup-*`; no elimina la evidencia ni adopta el estado de ruta heredado. Rechaza un proxy en ejecución, bloquea la contención, vínculos simbólicos / puntos de reparación, propiedad extranjera, archivos cambiados, cada base de datos no vacía y cualquier coordinador que ya tenga una fila autorizada. El filtrado del renderizador de escritorio es una capa separada: un catálogo y un coordinador correctos no evitan por sí mismos la lista de permisos del modelo de aplicación Codex. + + + +### Herramientas locales enrutadas + +Las filas de catálogo enrutadas no nativas usan `tool_mode: "code_mode_only"`. Esto permite que Codex exponga su punto de entrada oficial `exec` y las herramientas anidadas MCP, incluido el navegador y el uso del ordenador, mientras que opencodex solo enruta la llamada de función ordinaria del modelo. La ejecución de la herramienta, los permisos y las confirmaciones permanecen locales en Codex; opencodex no implementa un segundo navegador o ejecutor de control de escritorio. + +Para los proveedores de claves Responses que no aceptan la gramática de herramientas personalizadas `exec` de Codex, opencodex codifica esa declaración y su historial como una herramienta de función ascendente, luego restaura el ciclo de vida de llamadas a funciones transmitidas a `custom_tool_call` antes de que Codex lo vea. El enrutamiento directo nativo OpenAI y la herramienta personalizada `apply_patch` soportada permanecen sin cambios. + +Si un modelo encaminado envía un parche completo a medida que la entrada `exec` de modo de código completa, opencodex lo convierte a la llamada anidada `tools.apply_patch` antes de que los eventos de finalización de herramienta alcancen Codex. Las llamadas personalizadas nativas y las llamadas a funciones convertidas usan la misma regla de finalización; las vistas previas de parches se mantienen mientras no se resuelve su forma ejecutable. JavaScript que simplemente contiene texto de parche y cargas útiles personalizadas nativas no relacionadas permanecen sin cambios. + +Un modelo enrutado también puede enviar erróneamente un objeto de argumento de shell como `{"cmd":"git status --short"}` al modo de código `exec`. Para un catálogo de modo de código verificado, opencodex convierte un objeto de shell inequívoco en `tools.exec_command(...)` JavaScript y reenvía su salida a través de `text(...)`. Las opciones de shell se conservan y Codex sigue ejecutando y autoriza el comando. Los campos de reserva de JavaScript válidos, los objetos ambiguos y los espacios de nombres de herramientas no relacionados no se convierten. Esta reparación de compatibilidad no pasa por alto los límites de velocidad del proveedor ni cambia la directiva de reintento configurada. + +La misma reparación cubre a los ayudantes de la meta. Un modelo encaminado que llama `create_goal`, `get_goal`, o `update_goal` (o una ortografía prefijada `default.` de uno) como una herramienta mientras el catálogo declara sólo el código-modo `exec` tiene la llamada convertida en la llamada coincidente `tools.(...)` dentro `exec`. Un catálogo que declara genuinamente la herramienta de objetivo desnudo la mantiene, y un catálogo que declara ni la herramienta ni `exec` todavía rechaza la llamada como no declarada. + +En las conversiones enrutadas con un catálogo `exec` de código de forma libre verificado, las llamadas estructuradas enviadas directamente al `mcp____` (incluido un prefijo `default.` añadido por el proveedor) también se envuelven como llamadas de herramienta de host anidada. Esto evita un reintento causado únicamente por un modelo que omite la envoltura `exec`. Las herramientas MCP declaradas explícitamente mantienen su comportamiento normal; una función JSON ordinaria llamada `exec` no habilita esta reparación. Las herramientas desconocidas aún fallan en el host. Los registros de llamada de herramienta impresos como texto de respuesta ordinario no se ejecutan según esta regla de compatibilidad. + +Para los giros enrutados Responses, una directiva explícita de implementación de herramientas también rechaza las llamadas a herramientas de cliente si el catálogo de herramientas declaradas de la solicitud no está disponible. Un catálogo declarado vacío rechaza cada llamada a la herramienta del cliente; Chat y Anthropic clientes conservan su propia responsabilidad de validación de herramientas. + +A los giros en modo código encaminados también se les dicen las reglas del host para los ayudantes anidados antes de la primera llamada: `tools.apply_patch` toma una cadena que se abre y se cierra con las líneas de marcador de parche desnudas, el aislado no tiene `import`, y los comandos de ejecución larga se sondean a través de `write_stdin`. Cuando un resultado ejecutivo en modo código en la ruta nativa Responses, Kiro o Cursor todavía lleva uno de los mensajes de fallo del host, opencodex añade una pista de una línea que nombra la regla. Este cambio no reescribe el código del modelo o su texto de parche. + +Las llamadas a la función Responses enrutadas ordinarias también usan el esquema de parámetros declarado original en completion: los floats integrales en campos enteros y los números integrales en campos de solo cadena son normalizado, mientras que las fracciones y las uniones numéricas permanecen sin cambios. Un explícitamente vacío completado Argumentar cadena se convierte en `{}`. Los eventos finales y el historial de continuación almacenado localmente están de acuerdo. Las ortografías de espacio de nombres punteadas inequívocas se restauran al espacio de nombres declarado y al nombre de la herramienta. + +El proveedor seleccionado debe admitir llamadas de función/herramienta. Un proveedor de solo texto sin soporte de llamada de herramienta no puede usar `exec`, Browser o Computer Use. Las filas nativas OpenAI mantienen su modo de herramienta ascendente sin cambios. + +Después de que `ocx sync` cambie estos metadatos, reinicie la aplicación Codex y abra una nueva tarea. Los procesos y las tareas existentes del servidor de aplicaciones pueden conservar el catálogo y el plan de herramientas que cargaron al iniciarse. + + + +### Visualizaciones en línea con modelos enrutados + +El complemento Visualizar de la aplicación Codex le pide al modelo que responda con una referencia envuelta en caracteres de uso privado (U + E200... U+E201). Algunos proveedores eliminan esos caracteres antes de que el modelo los vea, cada ruta Claude que revisamos lo hace, por lo que el modelo solía responder con una línea desnuda `visualize{"path":…}` que la aplicación Codex imprimió como texto. + +opencodex reescribe esas referencias en la directiva que la propia aplicación renderiza, `::codex-inline-vis{path="/absolute/path/chart.html"}`, en el texto de conversación enviado a los modelos enrutados. Cualquier modelo puede leer y repetir esa forma, por lo que la visualización se renderiza en línea. Las solicitudes de pases nativas OpenAI se reenvían sin cambios. Las respuestas que ya estaban guardadas en la forma desnuda `visualize{…}` permanecen como están; solicite la visualización nuevamente en una nueva respuesta. + + + +### Nombres de visualización de modelo personalizados + +Un modelo personalizado puede llevar un **mostrar nombre** legible por humanos que anula la etiqueta Codex muestra en su selector de modelo, sin cambiar nada acerca de cómo se enruta el modelo. El nombre de visualización se asigna solo al campo `display_name` de la entrada del catálogo: la tira de enrutamiento (`/`), el orden de colisión de alias, el proveedor y los nombres de marketing nativos OpenAI se dejan intactos. + +Agregue un nombre de visualización del CLI (el proxy sincroniza el catálogo de inmediato cuando está activo): + +```bash +ocx models add deepseek deepseek-v4 --display-name "DeepSeek V4" --context-window 128000 +``` + +Para proveedores personalizados, omitir una ventana de contexto explícito permite que el catálogo use el [reglas de respaldo de ventana contextual](/es/reference/configuration/providers/#context-windows-on-custom-providers). Las estimaciones de ID de modelo se aplican solo cuando el proveedor establece `inferContextWindow: true`; establezca una ventana explícita o un límite de contexto cuando el relé admita menos que la ventana del proveedor del modelo. + +Los clientes remotos Codex pueden obtener el mismo catálogo generado con una clave ordinaria **plano de datos**: la misma credencial que ya usan para `/v1/responses`, no un token de administración: + +```bash +dest="${CODEX_HOME:-$HOME/.codex}/opencodex-catalog.json" +tmp="$(mktemp "${dest}.XXXXXX")" +curl -fsS -H "x-opencodex-api-key: $OPENCODEX_API_AUTH_TOKEN" \ + "https://proxy.example.com/v1/catalog" > "$tmp" \ + && mv "$tmp" "$dest" +ocx sync-cache +``` + +La respuesta es el documento sin procesar `opencodex-catalog.json` (sin credenciales de proveedor). Cuando está disponible, el encabezado `x-opencodex-codex-version` informa la versión en entorno de ejecución Codex en el servidor para que los clientes puedan detectar el sesgo de versión. + +`GET /v1/catalog` existe para que la lectura de una lista de modelos no cueste un token de administración. Es de solo lectura (`GET` y `HEAD`), acepta `x-opencodex-api-key`, un token portador, o `x-api-key`, y sirve exactamente los mismos bytes que la ruta de gestión. Responses llevar un fuerte `ETag` - pasarlo de nuevo como `If-None-Match` para revalidar y obtener un `304` en lugar del documento completo - y `Cache-Control: private, no-cache`, ya que el cuerpo se sienta detrás de una credencial. + +Una clave de plano de datos admitida aquí gana **nada** en el plano de administración: `/api/catalog` y cada otra ruta `/api/*` aún requiere el token de administración o una sesión de tablero. La ruta anterior `/api/catalog` sigue funcionando sin cambios para el panel de control y para los scripts que ya tienen un token de administración. + +También puede configurarlo o editarlo a través de la administración API (`POST /api/custom-models`, `PUT /api/custom-models/` con una cadena `displayName`) y el panel de control web. Un `/` es rechazado porque colisionaría con el separador de balas enrutadas. + +El nombre que se muestra es **solo pantalla y estable a través de la regeneración**. Cada `ocx sync` y las re-derivas de actualización de catálogo enrutaron las entradas desde `config.json` (incluyendo `customModels`), por lo que el nombre configurado se vuelve a aplicar en lugar de volver a la pista enrutada. Un reinicio del servicio administrado también intenta esta sincronización poco después de que el proxy se une. Si la sincronización de arranque de mejor esfuerzo falla, por ejemplo durante un inicio de sesión sin conexión, el catálogo previamente persistente se conserva y el siguiente `ocx sync` exitoso vuelve a aplicar el nombre configurado. Los nombres nativos aguas arriba genuinos (p. `gpt-5.6-sol` → "GPT-5.6-Sol") provienen de la instantánea de aguas arriba anclada y nunca se reemplazan por un nombre de visualización personalizado. + + + +### Gerentes de proveedores externos + +Si `config.toml` ya selecciona un proveedor distinto de `openai` o `opencodex`, OpenCodex deja el archivo sin cambios y omite escrituras de perfil, actualización de catálogo/caché y restauración de metadatos de historial Codex tanto inmediata como de fondo. Las herramientas que administran un proveedor personalizado a menudo etiquetan las sesiones existentes con ese ID del proveedor; reemplazar el ID activo puede hacer que esas sesiones intactas desaparezcan de la vista del historial de Codex. La misma protección se aplica a un proveedor externo seleccionado por un perfil raíz heredado. + +Mientras que un proveedor externo posee `config.toml`, los ajustes informan que `GET /api/settings` y `ocx system settings --json` devuelven una descripción de los switches de compresión de cliente y de escritorio, y el requisito de inicio de sesión Codex, según lo controlado por ese proveedor en lugar de mostrar el estado efectivo que produciría OpenCodex. Al cambiar cualquiera de los switches se sigue almacenando la preferencia, pero `config.toml` no se reescribe; el valor almacenado tiene efecto si cambia Codex de nuevo a un proveedor OpenCodex administra y vuelve a ejecutar `ocx start`. + +Si `config.toml` existe pero no se puede leer (permisos, o una carrera de borrado de la lectura), el mismo informe retiene los valores efectivos y la respuesta de inicio de sesión como indeterminada en lugar de mostrar el estado OpenCodex computaría localmente. El registro apply mantiene esa explicación, incluso en un guardado cuya puerta de inyección ya está cerrada por una integración deshabilitada o un proxy detenido, y lo marca como reintentable, por lo que una lectura posterior de `ocx system settings --json` informa la respuesta establecida una vez que el archivo vuelve a ser legible. Con la integración Codex deshabilitada, `ocx sync` es solo para catálogo y no puede aplicarla. + +Mantenga una herramienta como propietario de la configuración del proveedor Codex. Para usar OpenCodex detrás de un administrador de proveedores existente, apunte a ese proveedor en `http://127.0.0.1:10100/v1` con Responses passthrough (`wire_api = "responses"` en Codex TOML), no Chat Completions translation. Cuando el proxy API auth está habilitado, también pase `x-opencodex-api-key` de `OPENCODEX_API_AUTH_TOKEN`, que coincide con el formulario de proveedor de no retorno de bucle anterior. Para permitir que OpenCodex inyecte el enrutamiento directamente, primero conmuta Codex de nuevo a su proveedor `openai` incorporado y elimina cualquier raíz `openai_base_url` propiedad del usuario, luego vuelve a ejecutar `ocx start`. + + + +### Explícito `tool_search` solución de problemas + +Las herramientas locales enrutadas tienen dos rutas de descubrimiento distintas. En el modo de código enrutado normal, Codex puede exponer diferido MCP/herramientas de la aplicación a través del oficial `exec` herramienta `tools` global y `ALL_TOOLS`; ese camino no requiere que el modelo vea o llame `tool_search`. + +Por separado, `tool_search` es una superficie de descubrimiento Codex ejecutada por el cliente. No es un indicador de características OpenCodex, y un valor ascendente `tool_choice: "auto"` no lo crea ni lo habilita. OpenCodex puede retransmitir la superficie explícita solo cuando Codex ya incluyó una declaración como esta en la solicitud Responses entrante: + +```json +{ + "tools": [ + { "type": "tool_search", "description": "Load deferred tools" } + ] +} +``` + +En el caso de los modelos locales/de chat enrutados, OpenCodex expone esa declaración como una función normal denominada `tool_search`. Si el modelo lo llama, OpenCodex convierte la llamada a un Responses `tool_search_call`; Codex ejecuta la búsqueda y proporciona las definiciones de herramienta resultantes en un `tool_search_output` posterior. Las definiciones cargadas de esa manera están disponibles en el siguiente turno del modelo. + +Compruebe el límite de fallos antes de cambiar la configuración del proveedor: + +1. **No `type: "tool_search"` en la solicitud entrante:** el cliente activo Codex/sesión no anunció la superficie explícita `tool_search`. OpenCodex no puede inventar esa declaración. Esto no significa que las herramientas normales de modo de código no estén disponibles: compruebe si el modelo enrutado puede usar `exec` y descubra primero la herramienta anidada necesaria a través de `tools` / `ALL_TOOLS`. +2. **La declaración entrante existe, pero ninguna función `tool_search` alcanza la solicitud enrutada:** captura solo el tipo de herramienta/lista de nombres redactados y abre un error OpenCodex. Nunca adjunte el portador, el identificador de cuenta, la entrada de conversación, los encabezados completos o el cuerpo completo de la solicitud. +3. **La solicitud enrutada contiene `tool_search`, pero el modelo local nunca lo llama:** el relé está funcionando. Utilice un modelo/plantilla con llamadas a funciones confiables e instrucciones que le indiquen explícitamente que busque una herramienta diferida que necesite. LM Studio `tool_choice: "auto"` permite el uso de herramientas; no obliga al modelo a llamar a esta función. +4. **Una llamada se emite repetidamente o las herramientas cargadas nunca se vuelven utilizables:** capturan los tipos de artículo `tool_search_call` / `tool_search_output` redactados y los identificadores de llamada. OpenCodex conserva ambos en la historia, por lo que el modelo debería ver la búsqueda completa en lugar de emitirla para siempre. + +Vea [El analizador y el puente](/es/reference/architecture/#the-parser) para la asignación explícita de cables. No hay ninguna configuración de nivel de proveedor que pueda agregar una declaración `tool_search` faltante; el descubrimiento de modo de código ordinario sigue siendo una ruta separada. + + + +### Diagnósticos de lectura en caché + +Establezca `OPENCODEX_CACHE_DEBUG=1` antes de iniciar el proxy para escribir un registro de diagnóstico por solicitud finalizada en `/cache-debug.jsonl`. El interruptor está desactivado de forma predeterminada; configúralo en `0` o retíralo para desactivar la captura. El archivo es propietario solamente (`0600`) en el directorio de configuración endurecido y rueda después de 200 líneas, reteniendo el 100 más nuevo. + +Cada registro JSONL contiene el protocolo, el proveedor/modelo enrutado, la presencia y procedencia del contador de caché, las etiquetas de igualdad local de proceso para la cuenta, la clave de caché de solicitud y los encabezados de sesión permitidos, además de huellas dactilares ordenadas para instrucciones, herramientas y bloques de mensaje/entrada. Las secciones de prefijo retienen como máximo 128 etiquetas e identifican solo la primera sección/índice divergente. El diagnóstico nunca almacena mensajes de texto, nombres de herramientas, encabezados sin procesar, identificadores de caché/sesión/cuenta sin procesar o una etiqueta duradera derivada de ellos. Su clave HMAC aleatoria se crea al inicio del proceso, separada de otras claves de depuración, y nunca persiste; las etiquetas por lo tanto comparan valores solo dentro de un proceso proxy. + + + +### Solución de problemas de catálogo + +Si falta un modelo de Codex, o el orden/visibilidad del catálogo se ve mal, compruebe en orden: + +1. **`selectedModels`** en el proveedor: una lista de permisos no vacía expone solo esos identificadores a Codex; vacía u omitida expone todos los modelos descubiertos. Un id que no está en la lista de permisos nunca llega al catálogo. +2. **`disabledModels`** (nivel superior) - oculta los modelos del catálogo y `/v1/models`, y voltea las identificadores GPT nativas desnudas a `visibility: "hide"`. +3. **`liveModels: false`** - Con `liveModels: false`, un `models` vacío u omitido inicia primero el `defaultModel` configurado, seguido de `retainModels`; los identificadores duplicados se eliminan mientras se conserva la primera aparición. Una lista `models` explícita no vacía en su lugar siembra `models` seguido de `retainModels`, sin agregar implícitamente un `defaultModel` diferente. Ese valor predeterminado todavía se puede enumerar explícitamente en `models` o `retainModels`. Si ninguno de estos campos proporciona un id, la semilla estática está vacía. Este es el orden de la semilla, no una promesa del orden final del selector. `selectedModels`, `disabledModels` y la política de proveedores desactivados todavía se aplican. `authMode: "forward"` mantiene su rama separada y no usa esta semilla estática enrutada. Estas reglas no cambian el fracaso del descubrimiento en vivo. +4. **Cursor `GetUsableModels`** - el adaptador Cursor descubre modelos a través de su protobuf `GetUsableModels` RPC, no `/models`, por lo que un cambio de lado Cursor puede alterar qué id son visibles independientemente de otros proveedores. +5. **Caché y `ocx sync`** - catálogos en vivo se almacenan en caché durante unos cinco minutos (`modelCacheTtlMs`, por defecto `300000`). Ejecute `ocx sync` para forzar una nueva búsqueda y reescribir el catálogo inmediatamente. +6. **Correr Codex `app-server`** - reescribir el catálogo en el disco no es suficiente, mientras que un Codex de larga vida `app-server` (host de escritorio / CLI de fondo) mantiene la lista anterior en la memoria. `ocx sync` y `ocx sync-cache` advierten cuando se detectan esos procesos. `ocx sync --restart-codex` reinicia esos procesos y cierra completamente y reinicia la aplicación de escritorio Codex en macOS, Linux y Windows para que el selector vuelva a leer el catálogo. Para dejar la aplicación de escritorio en ejecución, pase `--restart-app-server-only` o detenga el `app-server` correspondiente procesos usted mismo. + +:::caution[Otros procesos locales que escriben la configuración] +El catálogo escribe (`opencodex-catalog.json`, `config.toml`) son atómicos **interior** opencodex, que solo evita archivos a medio escribir cuando dos escritores propiedad de opencodex compiten. Eso sí. **no** Detener a otro proceso local, observador de archivos o agente de sincronización de reescribir la visibilidad del catálogo u ordenar después de opencodex ha escrito. Codex mantiene su separación `models_cache.json` y puede refrescarlo independientemente, cambiando la lista visible sin reescribir `opencodex-catalog.json`. Si los modelos se voltean inesperadamente mientras proxy está ejecutando, deteniendo o reconfigurando a los escritores competidores, luego ejecuta `ocx sync` — esto es un riesgo de escritura externa, no un defecto confirmado opencodex. +::: + + + +## Errores de conexión proxy + +Si Codex vuelve a intentarlo y luego falla con un error como `stream disconnected before completion: error sending request for url (http://127.0.0.1:10100/v1/responses)` - o Claude Code informa un error de conexión similar - el proxy opencodex no se está ejecutando: nada está escuchando en el puerto configurado, por lo que el cliente muestra ese error de conexión sin procesar. Reinicie el proxy: + +```bash +ocx start # foreground +ocx service install # persistent: auto-starts on login and respawns on crash +``` + +`ocx status` muestra si el proxy se está ejecutando e imprime la misma pista de reinicio cuando no lo está; `ocx doctor` informa sobre la seguridad de reinicio (cobertura de servicio/atención). + + + +### Sobrecarga ascendente antes de cualquier salida + +Cuando el backend ChatGPT declina un turno nativo agrupado de Codex con `server_is_overloaded` u otro error del servidor antes de que haya producido cualquier salida, opencodex reintenta la misma cuenta con un retroceso corto y limitado y luego mueve el turno a otra cuenta elegible de Pool. Una cuenta anclada (un modelo calificado para la cuenta) se vuelve a probar pero nunca se mueve. Una vez que cualquier salida ha alcanzado Codex el giro nunca se envía de nuevo. Si se rechaza cada intento, Codex recibe el mismo error que habría recibido sin los reintentos. Las solicitudes compactas nativas se mueven a otra cuenta Pool en un error del servidor de la misma manera. + + + +### Instancias de agentes en ejecución (Codex 0.164+) + +Codex 0.164 puede firmar cada solicitud con una aserción de agente cuando se activa `features.runtime_agent_instances`, una función desactivada de forma predeterminada. opencodex admite uno de sus dos modos: + +- `mode = "dual_header"` conserva la credencial habitual `Authorization: Bearer` y añade el encabezado `x-openai-agent-assertion`. opencodex procesa la solicitud como antes. Solo reenvía la aserción cuando el turno va a ChatGPT Direct con la credencial de quien realiza la solicitud. La elimina si la solicitud usa una cuenta de Pool, una credencial principal guardada, un proveedor enrutado o un sidecar, porque la aserción pertenece a la credencial enviada por Codex. +- `mode = "assertion_only"` sustituye el token bearer por `Authorization: AgentAssertion `. opencodex rechaza estas solicitudes con HTTP 400 y el código `agent_assertion_unsupported`. Nunca sustituye la aserción por una credencial de Pool o de proveedor, ni la reenvía o registra. Usa `dual_header` o desactiva la función cuando Codex pase por opencodex. + + + +### Codex calza de inicio automático + +Ejecute `ocx codex-shim install` para instalar el envoltorio de lanzador opcional. Ejecuta `ocx ensure` antes de que el Codex ordinario se inicie y luego reenvía los argumentos originales y el estado de salida. El comando también funciona con el `ocx` independiente incluido en paquetes de escritorio: tanto la sonda de instalación como el envoltorio instalado usan ese ejecutable, sin requerir una instalación separada de Bun o una comprobación de origen. + +En macOS y Linux, active el envoltorio privado en su shell actual después de otra configuración de PATH. Con el inicio predeterminado OpenCodex, ejecute: + +```sh +. "$HOME/.opencodex/codex-shell-env.sh" +``` + +Con un `OPENCODEX_HOME` personalizado, utilice el camino citado impreso por `ocx codex-shim install`. Agregue esa línea de origen después de otra configuración de PATH en su archivo de inicio de shell para activar futuros shells. OpenCodex no edita ese archivo ni cambia el shell principal. Las shims Unix heredadas en el lugar no se migran automáticamente; ejecute `ocx codex-shim install` explícitamente para migrarlas. + +Utilice `ocx codex-shim status` para inspeccionarlo. En macOS y Linux, `ocx codex-shim uninstall` elimina los archivos de superposición privados y deja intacto Codex nativo. Windows mantiene en su lugar los envoltorios de script; la desinstalación restaura el lanzador guardado. Ver el [CLI Referencia del ciclo de vida](/es/reference/cli/lifecycle/#ocx-codex-shim-installstatusuninstallremove). + + + +## Experimental compatibilidad de escritorio Windows + +**Codex Set → Compatibilidad con equipos de escritorio** proporciona controles locales para una prueba de compatibilidad limitada al tiempo que conserva el inicio de sesión nativo Codex. Este es un relevo experimental, no una garantía de que cada Codex estado de compilación o cuenta agotada pueda recuperar a su compositor. + +1. Inspeccione el estado, prepare el certificado cifrado y revise su huella digital antes de registrar la confianza. Windows puede solicitar confirmación. La confianza se aplica al usuario actual Windows y permite que el relé local maneje el tráfico `chatgpt.com`. +2. Comience la observación. Guarde los borradores, cierre Codex, luego use **Abierto Codex** en este panel para iniciar la aplicación empaquetada con la conexión administrada. El panel nunca cierra por la fuerza una aplicación existente. +3. Solo después de que se observe el agotamiento elegible, **Ejecutar prueba de 3 minutos** ofrece un consentimiento separado para toda la cuenta. Ajusta dos indicadores de interfaz de usuario en la cuenta de inicio de sesión, no solo en el modelo seleccionado. El uso real, los créditos, las restricciones de gasto y los límites del servidor permanecen sin cambios. Una respuesta producida por sí sola no establece que el compositor se recuperó. + +Una respuesta original que muestre el uso disponible o un estado protegido finaliza el juicio inmediatamente. Los créditos disponibles o la Reserva Luna activa también dejan la respuesta sin cambios y terminan el ensayo, incluso cuando se agota el uso ordinario. Esto preserva el estado de derecho existente de la aplicación. Si el agotamiento elegible aparece de nuevo, se requiere otro ensayo explícito; el consentimiento anterior no reactiva silenciosamente la corrección. + +**Volver a la observación** desarma la corrección. La corrección de la respuesta de límites límite de tres minutos, no el tiempo hasta que Codex refresque su visualización. Caduca y vuelve a la solicitud de observación de una nueva respuesta de uso; la aplicación puede conservar su pantalla anterior hasta que llegue esa respuesta. El panel muestra esta limitación antes del consentimiento de prueba y mientras espera la respuesta original; no puede confirmar la actualización de caché de la aplicación. **Detener el servicio** cierra sus conexiones y deja el certificado para su reutilización; las conexiones activas pueden interrumpirse. Para renovar o retirar la confianza, detenga el servicio y cierre primero el Codex. La renovación prepara un nuevo certificado no confiable; revise la nueva huella digital antes de registrarla. Una acción incierta no se vuelve a intentar automáticamente. Los certificados están restringidos a la autenticación del servidor TLS. Si el estado muestra `renewal-required`, detenga el servicio y cierre Codex, luego renueve el certificado anterior antes de comenzar de nuevo. La URL nativa API debe coincidir con la dirección del oyente y el puerto reales del proxy. Las direcciones IPv4 e IPv6 no son intercambiables aquí; `localhost` alias ambiguos son rechazados. Codex 's automático MCP actualización de la conexión y el formato de configuración no invalidan la observación. Los cambios de modelo, autenticación, perfil y enrutamiento aún requieren un contexto de observación fresco; el servicio no adopta silenciosamente esos cambios durante una prueba. + +El servicio conserva su dirección PAC y puertos de conexión local para su reutilización después de un reinicio. Con el mismo certificado de confianza, una aplicación ya configurada puede volver a conectarse a través de su PAC en caché; reiniciar el servicio nunca reanuda una prueba de corrección. Si un puerto guardado no se puede vincular o los metadatos de conexión no son válidos, el inicio se niega en lugar de asignar otra dirección de forma silenciosa. El primer comienzo exitoso posee `codex-desktop-compatibility/connection.json` bajo la casa OpenCodex. No elimine ese archivo como una solución de reinicio de rutina: una dirección diferente requiere iniciar la aplicación con una nueva conexión administrada. + +El soporte actual se limita a la versión Windows evaluada `26.924.2738.0`, inicio de sesión basado en archivos nativos. HTTP / HTTPS proxies y SOCKS5 autenticados proxies se admiten a través de la política de salida compartida; NO_PROXY puede seleccionar explícitamente una ruta directa. Las conexiones proxy fallidas no vuelven a la salida directa. El modo cliente administrado OpenCodex aún no es compatible con estos controles. Para este relé de escritorio, HTTP (S) `ALL_PROXY` también se aplica cuando `HTTPS_PROXY` no está configurado. Un `HTTPS_PROXY` no válido rechaza la operación en lugar de volver a `ALL_PROXY`. La aplicación desconocida crea una corrección de rechazos; la integración no parchea los archivos de la aplicación ni cambia al modo sin inicio de sesión. La configuración raíz nativa y su perfil seleccionado deben enrutar `openai_base_url` al oyente de datos local real de este proceso. Un proveedor, destino o anulación no admitida diferente rechaza el inicio de observación. Esta comprobación no determina el modelo seleccionado de una conversación ni prueba que las anulaciones locales de proyecto estén ausentes. Si el enrutamiento o la compilación de la aplicación instalada cambia durante una prueba, se rechaza la corrección antes de la siguiente respuesta de uso; las comprobaciones periódicas también devuelven una prueba inactiva a la observación. Las respuestas originales y otro tráfico de aplicaciones continúan retransmitiendo. El reemplazo nativo de archivos de inicio de sesión o la rotación de tokens también invalida la prueba, incluso cuando regresa la misma cuenta. Detener y comenzar la observación para vincular el inicio de sesión actual antes de otra prueba explícita; las respuestas antiguas no pueden autorizar la sesión de reemplazo. Los cambios en la configuración raíz Codex (excepto su tabla y formato de servidor MCP), la configuración del proveedor, los alias del modelo, los perfiles de enrutamiento, las rutas de reserva, la compactación o el modelo de memoria también invalidan el contexto de observación. Restaurar la configuración anterior no restablece su consentimiento: deténgase e inicie la observación, luego confirme un nuevo ensayo cuando sea elegible. Esto detecta cambios en esas rutas configuradas, no qué modelo selecciona realmente una conversación; una configuración de proveedor mixto sin cambios no es prueba de aislamiento del proveedor. + +Después de la preparación del certificado y un inicio manual exitoso, habilite **Reanudar la observación cuando se inicia OpenCodex** en el mismo panel. La configuración opcional OpenCodex `"desktopCompatibility": { "startOnProxyStart": true }` se reanuda **Sólo observación** cuando se inicia el proxy del modelo. Omission o `false` desactiva este arranque automático. Reutiliza los endpoints guardados y el certificado de confianza, nunca inicia Codex ni registra confianza, y nunca reanuda una prueba de Aplicar. La observación automática espera a que termine la sincronización de la configuración de inicio. La sincronización fallada o una espera de más de dos minutos deja la observación desactivada; inspeccione su estado e inícielo manualmente después de resolver el problema de inicio. El proxy del modelo continúa siguiendo su propia política de preparación. Si faltan requisitos previos, la observación permanece desactivada y el proxy del modelo continúa ejecutándose. Guardar esta preferencia no inicia ni detiene el servicio actual. Utilice sus controles de servicio separados para cambios inmediatos. Si no se puede confirmar un guardado, actualice su estado antes de volver a intentarlo. + +Un servicio en ejecución no establece que Codex esté conectado a través de él. Un inicio de aplicación normal o un actualizador de aplicación pueden omitir el argumento de conexión administrada. Guarde borradores, cierre Codex, luego use **Abierto Codex** en este panel para restaurar esa conexión. Este control nunca cierra la aplicación para usted. Después de una actualización Codex, una versión de aplicación no evaluada rechaza la corrección hasta que se revisa su compatibilidad; reinstalar el certificado no hace que se admita una compilación no evaluada. + +El panel también puede informar la última comprobación de compilación completada como metadatos de diagnóstico: la versión del paquete contra la que se evaluó esta compilación, la versión del paquete observada en esa comprobación, si coinciden y cuándo terminó la comprobación. Es una observación pasada, no una lectura en vivo del paquete instalado. Después de que el servicio se detiene, la aplicación se actualiza, o una comprobación todavía se está ejecutando o se interrumpió, puede retrasar la instalación real; solo una sonda completa lo actualiza, y un resultado `verified` describe el paquete observado en esa comprobación, no lo que está instalado ahora. + +En Windows, un reinicio de la aplicación completa OpenCodex explícito conserva un argumento PAC de compatibilidad de bucle invertido ya activo solo cuando el proceso OpenCodex actual posee el entorno de ejecución de compatibilidad de servicio. Se rechaza un punto final obsoleto o extraño antes de detener Codex; el reemplazo del entorno de ejecución durante el reinicio también evita el relanzamiento administrado. La aplicación se inicia a través de la activación del paquete Windows. Verifica la identidad del paquete y el argumento de enrutamiento después del inicio; argumentos de enrutamiento de la aplicación principal ilegibles o conflictivos causan un rechazo antes del reinicio. Esto no permite un modo de compatibilidad, instalar un certificado o ver y reiniciar la aplicación automáticamente. Los lanzamientos normales sin ese argumento de enrutamiento mantienen su comportamiento existente. + + + +### Cobertura de transporte y evidencia de recuperación + +El panel de compatibilidad informa las respuestas de uso JSON / SSE verificadas por identidad y los flujos actualmente vinculados por separado de las conexiones abiertas. Estas son observaciones de retransmisión de por vida, incluidas las solicitudes realizadas por clientes de diagnóstico. No identifican el proceso nativo de envío, prueban que la aplicación actualizó su caché autorizado o prueban la recuperación del compositor. No se agrega ningún cuerpo de solicitud, token, ID de cuenta o IP de origen a este estado de diagnóstico. + +[incidencia #6196](https://github.com/lidge-jun/opencodex/issues/6196) informa una compilación macOS cuyas solicitudes de puerta autorizadas se originan en el servidor de aplicaciones Rust incluido y evitan la configuración de Chromium PAC. Un PAC saludable, certificado o solicitud sintética no puede establecer la cobertura de ese transporte. Este experimento Windows no es una solución para ese bloqueador de diseño macOS. + +Antes de agregar otra plataforma o transporte, documente y valide esta secuencia: + +1. Identifique el proceso real y el transporte que envía cada solicitud de puerta autorizada. +2. Demostrar que una solicitud de origen de aplicación llega al relé previsto, por separado de los clientes de prueba. +3. Verifique el esquema de respuesta y la ruta de caché/actualización de la aplicación para la compilación instalada exacta. +4. En caso de agotamiento natural de la cuenta, verifique el envío del compositor original, la finalización del proveedor independiente y la preservación del inicio de sesión, el chat, los hilos existentes y las conexiones remotas. +5. Verifique el apagado, el inicio ordinario, reinicie y actualice el comportamiento; no infiera uno de otro. + +La presente política solo maneja `/backend-api/wham/usage` y su punto final `/stream`. La inicialización de la conversación y otros puntos finales, incluidos sus `blocked_features` y `limits_progress`, pasan sin cambios. Su presencia no es un permiso para limpiarlos: pueden representar restricciones no relacionadas. La ruta de búsqueda de renderizador a electrón de la compilación Windows no establece la ruta de red de un sistema operativo/construcción diferente o de cada RPC de servidor de aplicaciones. El enrutamiento del servidor de aplicaciones requiere su propio diseño revisado; cambiar las URL del proveedor de modelos por sí solo no es prueba de que el tráfico de cuenta, inicio de sesión o control remoto siga la misma ruta. Estos controles no instalan ningún envoltorio automático de aplicaciones-servidor, cambio de proxy global o reescritura de inicio de sesión. + + + +## Modelos encaminados durante el modo de reserva Codex + +Codex Pool puede proteger opcionalmente las cuentas de grupo almacenadas a un umbral de uso semanal o de 5 horas seleccionado. La cuenta de escritorio/principal mantiene su bloqueo separado del 98%. Establezca `codexPool.lowQuotaProtection` en configuración para pausar cuentas, registrar una alerta de registro y API o ambas; vea [configuración de enrutamiento](/es/reference/configuration/routing/#codex-pool-low-quota-protection). Una pausa tiene efecto para la siguiente selección inmediatamente, mientras que guardarla en el disco se aplaza. Las respuestas de cuota Pool pueden autorizar una pausa solo con el uso válido y una credencial capturada que todavía está actualizada. Una respuesta sin esa prueba puede actualizar el uso mostrado sin pausar una cuenta. Compruebe el historial de `GET /api/codex-auth/low-quota-events` autenticado de este servidor para alertas `logged` o errores de guardado. El reanudación manual permanece en vigor para el episodio de cuota actual. La alerta por defecto solo llega al log y API. Añadir `actions.desktop: true` para mostrar también una notificación macOS o Linux en la máquina que ejecuta el proxy; Windows permanece solo registro. + +Cuando se agote la cuota de ChatGPT de 5 horas, Codex puede ofrecer un modelo de reserva de reserva (`gpt-reserve` / Luna Reserve). Mientras que ese estado está activo, el selector de modelos Codex puede hacer **cualquier otra entrada no seleccionable, incluidos los modelos enrutados opencodex**, a pesar de que se ejecutan en proveedores independientes y credenciales y no consumen ninguna de las cuotas agotadas. + +**Este es un comportamiento del cliente Codex que el enrutamiento proxy de modelo ordinario no puede cambiar.** El estado de reserva llega desde el backend ChatGPT en la propia conexión autenticada del cliente, no a través del proxy. La aplicación de escritorio sondea `backend-api/wham/usage` y trata la reserva como activa cuando la respuesta lleva `rate_limit_upsell.banner_type = "luna_reserve"`, el `rate_limit.allowed` primario es `false`, y `additional_rate_limits[]` contiene una entrada con `limit_name = "gpt-reserve"` que todavía está permitida. Mientras eso se mantiene, la aplicación fuerza la configuración del modelo de la conversación a `gpt-reserve` y reescribe cualquier otra elección de nuevo a ella - el selector se contrae a la entrada de reserva por el cliente, y un valor `model =` en `config.toml` se anula de la misma manera. Nada de esto consulta el catálogo de modelos, por lo que ninguna representación de nuestra parte participa en la decisión. opencodex no tiene un concepto de reserva para ajustar, y la alternativa - informar mal su propia cuota a su propio cliente - sería un error peor que el que encubrió. + +**Solución:** los modelos en sí permanecen completamente utilizables; solo la selección del modelo de la aplicación Codex está cerrada. Llegue a ellos desde un cliente que no consulta la instantánea de uso ChatGPT: + +- Claude Code a través del proxy (`ocx claude`). +- Cualquier cliente HTTP contra el punto final local `/v1`. +- Las propias rutas de solicitud del panel de control. + +El comportamiento normal del selector vuelve cuando se restablece la ventana de 5 horas. + +**Lo que el proxy responde mientras ese estado se mantiene.** Una vez que la aplicación ha colapsado, el selector envía `gpt-reserve`, y sin el [opt-in de escritorio authless](#authless-codex-desktop-opt-in) opencodex no tiene derecho de reserva para enviar con él. Esa solicitud solía ser enviada como un modelo nativo ordinario y regresaba como el propio `The usage limit has been reached` del flujo ascendente, que no nombra ni la causa real ni la configuración que lo cambiaría. Ahora se rechaza localmente con un HTTP 400 que dice que `codexDesktopAuthless` está apagado y da el comando que lo enciende (`ocx system settings --desktop-authless on`). Nada se envía aguas arriba y no se gasta ninguna cuota. + +El rechazo es deliberadamente estrecho. Se aplica solo a `gpt-reserve` en una solicitud admitida en bucle que alcanzaría la ruta de avance canónica ChatGPT. Un selector `gpt-reserve` que un operador ha aliaseado o enrutado a otro proveedor sigue funcionando, una solicitud admitida en un oyente que no es loopback aún se reenvía, y un proxy que se ejecuta en el rol de entorno de ejecución `client` no cambia. Habilitar el opt-in restaura el camino normal de la Reserva en lugar del rechazo. + + + +## El selector de subagentes + +La sincronización de catálogos permite que los modelos de subagentes seleccionados estén disponibles para Codex; consulte [Codex Selector de modelos de aplicaciones](/es/guides/codex-app-models/#subagent-selection) para el pedido de selectores y [Superficie del subagente](/es/guides/sub-agent-surface/) para la delegación v1/base/v2 y el comportamiento de reserva. + + + +## Codex calentamiento de la cuenta + +Cuando se agrega o vuelve a autenticar una cuenta ChatGPT, OpenCodex normalmente la verifica antes de guardarla con una pequeña solicitud de transmisión al backend Codex Responses. Espera `response.completed`, por defecto `gpt-5.6-luna`, y vuelve a intentar con `gpt-5.5` en HTTP 400 o HTTP 404. Los errores públicos contienen categorías de fallos fijos en lugar de cuerpos de respuesta ascendentes sin procesar. + +Un HTTP 429 de un intento de calentamiento se informa como `codex_warmup_rate_limited`. Vuelva a intentar después de que se elimine la restricción temporal o se restablezca el límite de uso; iniciar sesión nuevamente no restablece estos límites. Un intento fallido de calentamiento no agrega una nueva cuenta ni reemplaza las credenciales existentes. Esto difiere del registro diferido confirmado por cuota a continuación, que puede guardar una cuenta restringida sin una solicitud de modelo. HTTP 401/403 fallos retienen la guía de autenticación. + +Si la búsqueda de uso autenticado de la nueva credencial OAuth confirma una cuota agotada de 5 horas, semanal o mensual, la cuenta se guarda sin esta solicitud de modelo y muestra **Validación pendiente**. No puede servir solicitudes de agrupación, incluso después de reiniciar o actualizar token. Una vez que se recupera la cuota, **Actualizar las cuotas** finaliza la validación: una lectura de uso nueva y completa con espacio libre permite una pequeña solicitud de modelo, y solo una respuesta completa habilita la cuenta. Las lecturas fallidas o incompletas y la validación fallida preservan la restricción. Las encuestas de cuentas pasivas no activan la validación diferida. El uso desconocido durante el registro inicial conserva la puerta de calentamiento normal. + +`ocx account refresh openai` y `ocx account list openai --quota --refresh` solo leen el uso. La validación del modelo gasta cuota y requiere una sesión de panel humano: abra `ocx gui` y haga clic en **Actualizar las cuotas** después de la recuperación. Para un host sin cabeza, acceda a su panel de control desde su navegador; un token de administrador solo no autoriza la validación. La validación se puede completar mientras una cuenta está en pausa sin reanudarla o seleccionarla. Los errores de autorización del modelo permanecen visibles hasta que la validación o reautenticación exitosa los borra. + +En **Codex Conjunto → Multi-auth**, habilite el interruptor **Codex créditos** en el encabezado **Codex Auth** para mostrar los últimos créditos observados de cada cuenta principal y de grupo directamente debajo de Week. Está desactivado por defecto y persiste como `showCodexCredits`. El saldo es un número con formato local, con advertencia ilimitada o de exceso cuando se informa; la barra indica disponibilidad, no un porcentaje, porque no se proporciona un límite de crédito total. Ocultar los créditos solo cambia su visualización, y un nuevo inicio de sesión espera su propia observación. + +Cuando una cuenta llega al 100% en una ventana de uso y aún tiene créditos, la parte superior sigue sirviéndola y obtiene el saldo. OpenCodex no deja que eso suceda de forma predeterminada: una cuenta al 100% se apaga mientras su ventana semanal o mensual (solo mensualmente en planes de 30 días) o su ventana de 5 horas está llena, y se usa nuevamente una vez que se restablece esa ventana. El orden de las otras cuentas no cambia, y cuando no hay otra cuenta disponible, la selección no encuentra nada en lugar de gastar créditos. Una solicitud para la cuenta principal se rechaza como un rechazo de bloqueo duro hasta que se restablezca. Una ventana completa de 5 horas sin un tiempo de reinicio mantiene una cuenta solo mientras esa lectura está fresca. Permitir que la cuenta principal no levante su bloqueo duro (encendido por defecto al 98%), lo que aún lo detiene primero; apague el bloqueo si la cuenta principal debe gastar créditos (un bloqueo al 100% aún lo detiene al 100%). Para permitir que las cuentas sigan funcionando desde sus créditos, active **Usar créditos** junto al interruptor **Codex créditos** en el encabezado de Autonomía Codex. El interruptor permite todas las cuentas. Para elegir cuentas una por una, abra el menú **⋯** de una tarjeta de cuenta y use **Usar créditos después del límite** allí; el interruptor de encabezado muestra una posición media cuando solo algunas cuentas están activadas. Una cuenta permitida para gastar lleva una insignia **Utiliza créditos** en su tarjeta. Comienzan nuevas cuentas. La opción se almacena en `creditCodexAccountIds` y nunca canjea créditos de reinicio; el interruptor de pantalla **Codex créditos** solo muestra saldos y nunca cambia el enrutamiento. + +En el caso de una cuenta principal con acceso opcional y sin pausa y con una ventana de uso completa, el ciclo de recuperación en segundo plano renueva las observaciones de crédito gastables a partir de los tres minutos de edad, incluso cuando el panel de control está cerrado. Prepara un token válido antes de la búsqueda de uso autenticado para que el saldo se pueda observar nuevamente antes de su límite de frescura de cinco minutos. Los créditos faltantes, nulos, restringidos o retractados mantienen la cuenta elegible para búsquedas de recuperación bajo el reintento de retroceso existente. Las solicitudes siguen siendo rechazadas hasta que se observe un nuevo saldo positivo o créditos ilimitados. `has_credits` solo o recuentos de mensajes aproximados no demuestran un saldo desembolsable. Con el consentimiento, el `Retry-After` de este rechazo de evidencia crediticia es como máximo de cinco minutos, o un restablecimiento de la cuota incluida antes; sin consentimiento, aún sigue el restablecimiento de la cuota incluida. Una búsqueda fallida o incompleta no actualiza la evidencia de equilibrio anterior. El bloqueo duro de la cuenta principal separada, la cuarentena de necesidades-reauth y los retrasos de reintentos aguas arriba aún se aplican. Esta búsqueda de metadatos no envía una solicitud de validación de modelo ni establece ni borra el estado de área de necesidades de la cuenta. + +La revalidación de fondo es separada y desactivada por defecto. Requiere Token Guardian, el `openai` proveedor `proactive` política de actualización, y `tokenGuardian.codexWarmupEnabled`. Se salta las cuentas a la espera de la validación de registro diferido. + + + +### Después de una actualización del plan ChatGPT + +Actualice la cuota de la cuenta principal en Codex Auth después de cambiar su plan ChatGPT. Cuando la respuesta de uso autenticada confirma que una ventana larga ha reemplazado la ventana de cinco horas, opencodex elimina la antigua lectura de cinco horas tanto de la admisión de solicitud como de la selección de cuenta. Una respuesta permitida con ventanas primarias y secundarias puede omitir la ventana terciaria opcional. Esta recuperación utiliza su asignación de plan incluida y no requiere habilitar **Usar créditos**. Los datos de uso parciales o no válidos retienen el bloque anterior hasta que se confirma la recuperación. + + + +### Cancelación de la reautenticación del dispositivo de la cuenta principal + +Cuando se cancela la reautenticación del dispositivo de la cuenta principal, un fallo temporal de la red o una respuesta con un estado desconocido o no terminal, mantiene el flujo activo y la indicación de fallo de cancelación para que se pueda volver a intentar la cancelación. El sondeo de estado normalmente continúa, por lo que aún se puede detectar un inicio de sesión que se complete. Si un fallo de cancelación reintentable se superpone a una respuesta de estado GET no 2xx mientras el flujo es `pending` o `committing`, cualquier orden de respuesta conserva el reintento de cancelación en ese mismo flujo, con su último código de dispositivo proporcionado por el servidor, URL de verificación y fase. El fallo GET HTTP aún deja de ser consultado, pero la cancelación puede ser reintentada sin iniciar un segundo POST de inicio de sesión. Una respuesta del terminal `failed` libera el flujo y muestra la razón normalizada del fallo; solo `succeeded` informa del éxito del inicio de sesión. Una respuesta confirmada `cancelled` libera el flujo para que se pueda iniciar un nuevo inicio de sesión del dispositivo. Una respuesta definitiva HTTP 404 con el código `unknown_flow` también libera el ID de flujo caducado para que se pueda iniciar un nuevo inicio de sesión del dispositivo, pero no informa un inicio de sesión exitoso o una cancelación confirmada. Las respuestas POST, GET o DELETE tardías de un flujo anterior no pueden cambiar el nuevo flujo o informar el éxito de inicio de sesión para él. + + + +### Por qué una cuenta dejó de servir solicitudes + +Cuando una cuenta deja la selección de grupo, la razón viaja con la decisión en lugar de ser recalculada para su visualización, por lo que una superficie nunca puede informar una cuenta saludable mientras el enrutamiento la está abandonando. `GET /api/codex-auth/accounts` lleva `reauthReason` junto a `needsReauth` en cada cuenta: `missing_credential` para una credencial que nunca se almacenó, `refresh_failed` para una actualización de credenciales que sigue fallando y `quota_unauthorized` cuando se rechazó la búsqueda de uso. + +Una actualización de la cuenta principal que no se completa todavía responde `503` con `Retry-After`, porque un reintento aún puede tener éxito. El mensaje ahora agrega que un fallo que persiste significa que la cuenta principal necesita reautenticación, en lugar de solo pedir otro intento. + + + +### Dirección de ventana inactiva opcional + +`codexPool.startIdleWindows` es un booleano opcional y por defecto a `false`. Cuando se habilita, una nueva solicitud real no vinculada puede colocarse en una cuenta elegible cuya ventana de cuota corta observada es del 0% con evidencia de que su reloj de cinco horas no ha comenzado. Esta verificación se ejecuta después de la conversación y la afinidad familiar, por lo que un enlace existente sigue siendo autorizado; también gana un pin de cuenta explícito o una preferencia de cuenta manual. Se omiten los ámbitos de cuota de modelo independientes y el cursor activo compartido permanece sin cambios. Después de la opción de ventana inactiva, la selección de estrategia normal se reanuda para otras conversaciones. + +La observación no debe ser mayor de cinco minutos, y la ventana corta debe ser explícitamente de 18.000 segundos. Su restablecimiento debe observarse dentro de los 60 segundos de `observation + 5h` (en lugar de un restablecimiento ya realizado o transcurrido). Una reserva local de proceso sincrónica evita selecciones duplicadas para la misma cuenta y ventana. El plazo de reserva es de al menos 5 horas más un minuto después de la selección; se requiere una nueva observación después de ese plazo antes de que la misma cuenta pueda ser dirigida nuevamente. Las reservas se borran cuando se reinicia el proceso proxy y nunca se mantienen en el disco. + +Habilitarlo en su configuración existente: + +```json +{ + "codexPool": { "startIdleWindows": true } +} +``` + +Si ninguna cuenta cumple con los criterios, se aplica el enrutamiento ordinario. Esta característica solo dirige una solicitud entrante real. No crea ninguna petición sintética ni temporizador. + + + +### Mantener una cuenta degradada fuera de rotación + +`codexPool.excludedPlans` enumera las claves de plan que la selección automática de grupo omite, emparejadas insensiblemente a las mayúsculas y minúsculas contra el plan almacenado en cada cuenta. Está ausente por defecto, por lo que una instalación existente gira exactamente como antes. + +```bash +ocx config set codexPool '{"excludedPlans":["free"]}' +``` + +Esta es una política de selección, no un bloqueo. Una cuenta excluida mantiene su credencial, historial de cuotas y afinidad de subprocesos, permanece visible en la superficie de la cuenta y aún se puede acceder a ella mediante una selección explícita de la cuenta, como la `work/gpt-5.5`. Lo que cambia es que la rotación automática deja de elegirlo, incluso cuando ya es la cuenta activa o ya está vinculada a un hilo, que es el estado que deja una suscripción caducada. + +La cuenta principal Codex permanece exenta de la exclusión del plan; el enrutamiento solo de selección no lee su credencial nativa vallada. Si se excluyen todas las cuentas de grupo elegibles, la selección automática no devuelve ninguna cuenta. Las rutas con calificación de cuenta explícita permanecen disponibles y aún imponen pausa, autenticación y derecho de modelo. La tarjeta de cuenta y CLI muestran el plan de enrutamiento excluido por separado del estado de la credencial. No hay una configuración `minimumPlan` porque los nombres de los planes no definen un pedido total. + + + +## Restauración de Codex nativo + +`ocx stop` detiene el proxy y cualquier servicio en segundo plano instalado, luego intenta restaurar el Codex nativo. OpenCodex elimina los artefactos de enrutamiento verificados e informa de una restauración incompleta cuando no puede recuperar archivos de configuración de forma segura. + +La recuperación puede requerir una revisión manual cuando la revista no puede verificar los archivos actuales; consulte [recuperación sin hashes de inyección](#recovery-without-injection-hashes). + +```bash +ocx stop # stop the proxy + service, restore native Codex +ocx restore # restore without stopping (alias: ocx eject) +ocx restore back # point plain Codex at the running proxy again +``` + +Cuando opencodex se ejecuta como un [servicio de fondo](/es/reference/cli/lifecycle/#background-service) administrado, establece `OCX_SERVICE=1` para que un reinicio impulsado por servicio haga **no** thrash la configuración Codex - solo un `ocx stop` / `ocx service stop` explícito restaura el Codex nativo. + + + +### Recuperación sin hashes de inyección + +La revista guarda los hashes originales `config.toml` y `opencodex.config.toml` más del estado OpenCodex inyectado. Un diario heredado o una interrupción antes de que se registraran esos hashes no pueden probar que el contenido posterior del archivo pertenezca a OpenCodex. Si cualquiera de los archivos difiere de su original guardado y carece de su propio hash de estado inyectado, la recuperación automática del diario y el error del informe de restauración nativa sin cambiar el archivo o la revista. El original guardado permanece disponible para la comparación; revíselo junto con los archivos actuales antes de elegir una acción de recuperación manual. + +Los archivos que ya son iguales a sus originales guardados se aceptan sin reescribirlos. Un archivo faltante es distinto de un archivo vacío. Los hashes inyectados verificados aún permiten la restauración normal de instantáneas y las ediciones posteriores en configuraciones respaldadas por hash conservan el comportamiento de limpieza de campo propio existente. + +Sync y `ocx restore back` también rechazan una configuración enrutada existente cuyo diario sin hash no coincide con la línea base previa a la inyección. Esto evita que un nuevo hash de inyección se adhiera a un original más antiguo. Una configuración genuinamente nativa se puede guardar como una nueva línea de base antes de la inyección. El comportamiento explícito de exclusión de proveedores externos no se modifica. + + + + +### Subagente de reserva y compatibilidad con V2 + +En **Subagentes → Configuración de delegación**, edite la cadena de reserva ordenada y su intervalo de sondeo de disponibilidad (5000-600000 ms), luego guárdela por separado de la lista destacada. Un destino configurado que ya no se anuncia permanece en la cadena hasta que lo elimine. La lista y la cadena de reserva son configuraciones separadas; este editor no hace que la lista reemplace la política de reserva. + +Cuando un modelo preferido enrutado puede recibir trabajo V2 de un padre nativo ChatGPT, el panel explica la limitación de la tarea cifrada ascendente. Las tareas legibles de los padres enrutados no se ven afectadas. La guía utiliza el modo `/api/v2` y el estado nativo del pin V1; el API actual no expone la activación de recuperación o la elegibilidad específica de la solicitud, por lo que el panel informa que son desconocidos. La delegación V1/plaintext-compatible sigue siendo una alternativa. La recuperación experimental de V2, donde es elegible y explícitamente habilitada, agrega uso de cuota, latencia, dependencia de backend y posible pérdida de fidelidad; no repara el protocolo ascendente. Véanse [superficies de subagentes](/es/guides/sub-agent-surface/) y [La limitación aguas arriba](https://github.com/lidge-jun/opencodex/issues/92). + + + +## Historial paginado de rechazo de seguridad + +Cuando un almacén de historial afectado admite registros paginados, una transición de proveedor puede devolver `history_paginated_requires_native_writer`. Esa razón ya no rechaza la configuración Codex, el perfil de referencia o el catálogo de modelos. `ocx sync` y `ocx start` todavía escriben esos archivos y establecen `model_catalog_json`, por lo que el selector de modelos Codex sigue mostrando cada modelo OpenCodex. Sólo esta razón se mantiene la conversación-historia reetiqueta hacia abajo, porque Codex asigna paginado despliegue ordinales en su propio escritor y ningún reintento cambia eso. Cualquier otro motivo de pre-vuelo de la historia - una base de datos de estado ilegible, un despliegue cuya identidad cambió, o un pre-vuelo que no pudo ejecutarse - todavía rechaza toda la transición y la devuelve, porque esos pueden tener éxito en un intento posterior. OpenCodex nunca modifica los archivos de despliegue paginados o las filas de subprocesos en este estado. Las conversaciones existentes mantienen el proveedor con el que ya están etiquetadas y no se migran; las nuevas conversaciones se enrutan normalmente a través del proxy. Cuando el reetiquetado se apaga, una tabla `[model_providers.opencodex]` que la casa ya tenía se mantiene en lugar de retirarse, incluso en la forma de anulación de raíz (loopback), por lo que las conversaciones cuyas filas están etiquetadas `opencodex` mantienen un ID de proveedor que todavía existe. Esto incluye filas heredadas en una tienda con capacidad de migración. El CLI imprime `Codex resume history: left to Codex's native writer (history_paginated_requires_native_writer)`. + +Al volver al formulario de anulación de raíz, OpenCodex conserva una definición `[model_providers.opencodex]` existente antes de confirmar la configuración, incluso si el historial de pre-vuelo pasa actualmente. Esto hace que las conversaciones más antiguas de `opencodex` se puedan resolver si Codex migra el historial después de esa confirmación o mientras se inicia el trabajador en segundo plano. Las nuevas conversaciones aún usan el proveedor raíz seleccionado; la restauración explícita mantiene sus protectores de eliminación separados. + +`ocx restore`, `ocx stop` y `ocx uninstall` Ya no se niegan a `history_paginated_requires_native_writer`. Toman cada clave de enrutamiento raíz OpenCodex y mantienen la `[model_providers.opencodex]` definición en el disco, por lo que las conversaciones cuyas filas todavía nombran ese proveedor siguen resolviendo mientras se `codex` Deja de apuntar al proxy. El resultado se informa como una restauración parcial que nombra las líneas retenidas, y `ocx restore --remove-codex-provider-table` También los elimina, después de lo cual esas conversaciones dejan de abrirse. + +Habilitar la integración en su formulario de tabla de proveedores en una casa cuyas `openai` conversaciones etiquetadas Codex ya se han paginado solía ser rechazado por completo con `history_paginated_openai_requires_native_writer`: no se escribió nada y la integración se mantuvo inhabilitada. OpenCodex ahora completa esa transición manteniendo la raíz administrada `openai_base_url` al lado de la tabla `[model_providers.opencodex]`. Codex fusiona la anulación en su proveedor `openai` incorporado, por lo que esas conversaciones siguen llegando al proxy sin ser reetiquetadas y no se toca ningún byte de despliegue o fila de hilos. Solo un formulario de enrutamiento que requiere la cabecera de admisión `x-opencodex-api-key` todavía se niega, porque el proveedor incorporado de Codex no puede llevar esa cabecera; su mensaje nombra las dos configuraciones que lo resuelven: la ruta Codex a través del oyente de bucle de retorno para que la anulación pueda conservarse, o establece `syncResumeHistory` a `false` para aceptar que esas conversaciones se reanuden contra el propio punto final OpenAI de Codex. + + + +### Filtros de proveedor de listas de hilos remotos + +El enrutamiento de tabla de proveedor cambia el identificador de proveedor predeterminado para nuevas conversaciones a `opencodex`, mientras que el historial que no se puede volver a etiquetar de forma segura puede permanecer etiquetado como `openai`. Algunas versiones nativas de app-server/mobile tratan un filtro `thread/list.modelProviders` omitido como el proveedor predeterminado actual solamente, por lo que esas conversaciones existentes pueden desaparecer de esa lista remota aunque su fila de base de datos y su despliegue estén intactos. Un cliente de lista compatible puede enviar `modelProviders: []` para solicitar todos los proveedores. OpenCodex no puede reescribir ese RPC porque el cliente remoto habla directamente con el servidor de aplicaciones nativo de Codex en lugar del proxy de inferencia. + +`ocx sync` y `ocx start` incluyen la advertencia cuando aplican una ruta de tabla de proveedores. Si una URL raíz propiedad del usuario envía el comando por la rama sin enrutamiento, el CLI omite la advertencia. En el modo de compresión cliente, el CLI puede retener esa URL, aplicar la tabla de proveedores `opencodex` e incluir la advertencia. El panel de control muestra una sugerencia de preferencia separada cuando cualquiera de las opciones está habilitada. Aparece una vez si ambas configuraciones están habilitadas, independientemente de la URL raíz. La sugerencia informa las preferencias habilitadas; no significa que Authless Desktop sea efectivo en la ruta actual. Authless Desktop solo se aplica al enrutamiento efectivo sin bucle de retorno y se ignora para el enrutamiento de clientes remotos o los oyentes que requieren un encabezado de admisión. La advertencia no es una migración: OpenCodex no edita etiquetas de proveedor simplemente para influir en un filtro de lista del lado del cliente. Verifique la conversación en Codex nativo y la versión de aplicación-servidor/cliente; no reescriba el historial paginado para hacer que una lista remota lo incluya. + +No reescriba una implementación paginada activa o una fila de hilos para migrar esas conversaciones usted mismo. Cierre la conversación afectada antes de cualquier recuperación e informe el error exacto y las versiones sin cargar el historial privado. Una copia de seguridad o un script exitoso por sí solos no prueban que la conversación sea visible nuevamente. Compruebe la conversación restaurada en Codex después de reabrir. + + + +## Dirección a mitad de giro nativa experimental + +Para un modelo compatible en la ruta canónica de reenvío ChatGPT, y un cliente que envía `response.steer`, habilite ambas opciones en `~/.opencodex/config.json` y reinicie OpenCodex antes de comenzar un nuevo turno: + +```json +{ + "websockets": true, + "codexNativeSteering": true +} +``` + +Fusione estas claves en la configuración existente; no reemplace la configuración de su proveedor/cuenta. Esta opción está desactivada por defecto. Reenvía la dirección a la misma conexión nativa WebSocket configurada explícitamente y a la cuenta seleccionada, preservando las respuestas sucesoras automáticas y las continuaciones pendientes de resultados de herramientas guardadas. Aceptación significa en cola, aún no aplicada. + +Suministre los resultados de la herramienta requerida o las decisiones de aprobación **Una vez por padre**, en el mismo carril. Los resultados pueden llegar antes de `response.steer.pending`: el relé también coincide con las llamadas y aprobaciones anunciadas del padre completado. Un `name` en un stub de salida de función pendiente es opcional en el resultado, como en el esquema nativo. Mensajes de usuario adicionales pueden acompañar estos resultados; mensajes del sistema/desarrollador, resultados duplicados e ID de llamada no relacionados son rechazados. No vuelva a ejecutar las herramientas ni vuelva a enviar el texto de dirección aceptado. Las declaraciones de modelo, cuenta, herramienta y enrutamiento permanecen sin cambios. La configuración de generación validada puede cambiar en una continuación de resultado guardado explícita como se describe a continuación. Otros cambios requieren un giro explícitamente detenido o terminado y un nuevo envío normal. Múltiples conversaciones independientes utilizan conexiones independientes. + +HTTP fallback, puertas de enlace no canónicas, rutas públicas API -key, modelos traducidos, sidecares, intentos Combo y restauración V2 de texto plano no admiten esta opción. No agrega capacidad de dirección a un modelo o un cliente que carece de ella. Las rutas no soportadas devuelven un error de protocolo en lugar de ignorar silenciosamente la entrada. La entrega desconectada o con tiempo de espera puede ser desconocida: nunca vuelva a enviar automáticamente herramientas o texto de dirección. Los controles pendientes tienen plazos de confirmación absolutos de 90 segundos por envío; las esperas de resultados de herramientas guardadas tienen un límite de 30 minutos. + +La implementación tiene cobertura sintética de protocolo y regresión, no certificación Astra / cliente en vivo. Mantenga la opción desactivada para el trabajo de producción hasta que se haya verificado la ruta de su cliente/modelo. Establezca `codexNativeSteering` en `false` y reinicie para restaurar el relé de respuesta única existente; no es necesario eliminar ningún archivo de cuenta o conversación. + + + + +### Dirección de los plazos de confirmación y contexto retenido + +Cada dirección enviada tiene una ventana de acuse de recibo fija de 90 segundos. Otras salidas y novillos adicionales no lo extienden. Una vez aceptada, la entrada permanece en cola mientras que la respuesta actual alcanza un límite seguro; las comprobaciones ordinarias de flujo inactivo aún se aplican. Después de que la respuesta termina, el sucesor debe comenzar dentro de los 90 segundos. Una solicitud de resultados o aprobación de la herramienta permite 30 minutos desde la primera notificación de este tipo. Los avisos repetidos no renuevan esta espera. El envío de los resultados guardados inicia una nueva ventana sucesora de 90 segundos, que incluye comprobaciones locales de ritmo/auth. Los reconocimientos que faltan siguen sujetos a sus plazos individuales anteriores. + +La conexión propia no tiene un límite de vida absoluto. Hasta 128 respuestas pueden compartirlo, y cada una puede consumir legítimamente su propio reconocimiento, sucesor, espera de flujo inactivo y espera de entrada requerida, por lo que los plazos por etapa anteriores se componen en el peor de los casos del orden de decenas de horas. Durante ese tiempo, el turn tiene un socket físico y una credencial anclada que no puede rotar, porque el canal deliberadamente nunca vuelve a entrar en la selección de cuenta. Tratar una conexión de dirección habilitada como un recurso de sesión de larga duración en lugar de una solicitud limitada ordinaria. + +Los marcos de dirección también comparten los límites de cuerpo y memoria configurados del proxy. Se rechaza una trama de control por encima de [`maxInboundBodyBytes`](/es/reference/inbound-body-admission/) antes de analizarla en una conexión de control establecida (una trama inicial todavía se analiza antes de que se aplique su límite basado en tipo), y se rechaza el cuerpo reconstruido enviado aguas arriba cuando excede de [`maxUpstreamBodyBytes`](/es/reference/configuration/providers/). El diario de repetición de cada conexión tiene un límite de 32 MiB y se cuenta como estado anclado contra [`appOwnedMemoryBudgetMb`](/es/reference/configuration/server/); admitir un diario degrada primero los cachés desalojables en lugar de fallar, y el agregado en los diarios en vivo tiene un límite de 128 MiB independientemente del presupuesto configurado. + +Un tiempo de espera significa **La entrega es desconocida**, no es que el servidor rechazó la entrada. No vuelva a enviar una instrucción aceptada ni vuelva a ejecutar una herramienta automáticamente. Inspeccione el estado real de la tarea antes de decidir cómo reanudarla. No se realiza ningún cambio de cuenta o reserva de pago API. La salida completada ya recibida en el cable se retiene para el historial de continuación local incluso cuando el resumen del terminal lo omite. El contenido u orden del artículo en conflicto causa un fallo explícito en lugar de una pérdida de contexto silenciosa. + +Para una comparación en vivo, use la misma versión, modelo y cuenta de cliente compatibles en conversaciones de prueba aisladas, una vez sin el proxy y una vez con él habilitado. Use una tarea de solo lectura, dirija mientras la salida está activa y compare la aceptación y la adherencia real a la instrucción del sucesor. Repita mientras el resultado o la aprobación de una herramienta sintética está pendiente y después de una desconexión explícita. Registrar solo tipos de eventos, tiempos relativos y resultados redactados, no credenciales o cuerpos de tareas. Pasar pruebas de transporte simulado no establece soporte en vivo para el cliente / backend; estas instrucciones no implican una prueba de humo de cuenta real. + + + +## Inyección experimental de resultado de función nativa + +Para un cliente compatible que envía mensajes OpenAI multiagente `response.inject`, combine estas claves en la configuración OpenCodex existente y reinicie antes de un nuevo turno. No reemplace la configuración de su proveedor o cuenta: + +```json +{ + "websockets": true, + "codexNativeInjection": true +} +``` + +El `response.create` inicial debe incluir explícitamente `"multi_agent": { "enabled": true }`. OpenCodex no lo habilita basado en un nombre de modelo. Un proveedor público OpenAI API debe usar `adapter: "openai-responses"`, `baseUrl: "https://api.openai.com/v1"`, su autenticación de clave API normal y `upstreamWebsocket: true`. Enruta el modelo inicial a través del prefijo configurado de ese proveedor. El relé agrega el token beta `responses_multi_agent=v1` requerido solo en esa conexión pública API, preservando otros tokens beta configurados. No sustituye una credencial de suscripción, crea una cuenta API o cambia automáticamente a una API facturada por separado. + +Canonical ChatGPT conexiones hacia adelante pueden optar por el mismo transporte experimentalmente, pero el contrato público API hace **no** establecer ChatGPT suscripción o Codex App / CLI apoyo. Todavía se requiere un modelo ascendente compatible y un modo de ejecución. Ver el [OpenAI Protocolo multiagente](https://developers.openai.com/api/docs/guides/responses-multi-agent). + +Devuelve un resultado de la herramienta guardada después de que la llamada a la función de desarrollador correspondiente haya finalizado: + +```json +{ + "type": "response.inject", + "response_id": "resp_example", + "input": [ + { "type": "function_call_output", "call_id": "call_example", "output": "saved result" } + ] +} +``` + +Utilice los identificadores de respuesta/llamada del **La misma conexión**, no estos identificadores de ejemplo. `response.inject` acepta solo `function_call_output` con valor de cadena. Los mensajes de usuario/sistema, matrices de salida enriquecidas, resultados de herramientas alojadas y `response.steer` simultáneos no son aceptados por esa operación. La continuación de resultado guardado más amplia a continuación es una operación separada `response.create`, no una conversión oculta de inyección rechazada. Múltiples resultados de funciones guardadas pueden compartir una sola inyección. Cada llamada se puede enviar solo una vez, incluso mientras está en cola. + +Los resultados de la herramienta paralela se ponen en cola y se envían un fotograma a la vez, ya que el evento de éxito identifica la respuesta en lugar de una inyección individual. El relé conserva `response.inject.created` y `response.inject.failed`. Mantiene la conexión activa después de que un terminal de respuesta mientras los resultados enviados esperan confirmación o las llamadas anunciadas esperan resultados, por lo que los resultados asíncronos tardíos no se descartan. + +Cuando el servidor rechaza una inyección con `response_already_completed`, use sus salidas guardadas devueltas en **Un cliente enviado** `response.create` con el `previous_response_id` completado, modelo/configuración sin cambios y el mismo carril. Incluya cada resultado sobresaliente exactamente una vez; no incluya resultados ya aceptados. El relé mantiene esa continuación en la cuenta / socket original y conserva el ritmo normal de la solicitud. Nunca ejecuta la herramienta de nuevo o crea una solicitud de recuperación en sí. Otras fallas permanecen visibles para que el cliente las maneje. + +Un acuse de recibo faltante o una entrega de medios de desconexión puede ser **Desconocido**. No vuelva a enviar un resultado automáticamente, reinicie una herramienta o cambie de cuenta para volver a intentarlo. La cola pendiente está limitada a 32 tramas y 8 MiB, con 1.024 llamadas de función anunciadas, un diario de reproducción de 32 MiB y como máximo 128 respuestas por conexión propia. Los diarios de inyección comparten el presupuesto de memoria fijado y el techo agregado de 128 MiB con los diarios de dirección; véase [límites de memoria de dirección](#steering-confirmation-deadlines-and-retained-context). El límite de cuerpo ascendente configurado se comprueba antes de que un resultado entre en la cola, incluso mientras otro resultado espera el acuse de recibo. Un rechazo `outbound_body_too_large` deja la conexión utilizable para un resultado corregido sin volver a ejecutar su herramienta. Cada inyección enviada tiene un plazo de confirmación de 90 segundos que la salida no relacionada no puede extender; una espera de resultado guardado está limitada a 30 minutos. Los límites de marco existentes y los tiempos muertos todavía se aplican. + +Los proveedores traducidos, las puertas de enlace personalizadas, las rutas Combo / sidecar y el retroceso HTTP no obtienen soporte de inyección. Los intentos no soportados devuelven un error explícito en lugar de desaparecer. La opción permanece desactivada por defecto; las pruebas de transporte sintético no son una certificación de compatibilidad en vivo. Ajuste `codexNativeInjection` a `false` y reinicie para retroceder. No es necesario eliminar ningún archivo de cuenta o conversación. + + + + +### Resultados enriquecidos de la herramienta y aprobaciones explícitas después de completar la respuesta + +Con `codexNativeInjection` habilitado, un cliente-enviado `response.create` en la misma conexión de propiedad ahora puede devolver **no enviado** resultados de función/personalizados que contienen texto, imagen o partes de archivo después de `response.completed`. Suministre el `previous_response_id` de la respuesta completada, el mismo carril y el mismo modelo / configuración sin cambios. Incluya cada resultado sobresaliente o aprobación solicitada exactamente una vez; omita los resultados inyectados ya aceptados. El proxy reenvía esta continuación enviada por el llamante usando la cuenta original y el socket con las comprobaciones de envío existentes. + +Los elementos de continuación admitidos son `function_call_output`, `custom_tool_call_output` y `mcp_approval_response`. La salida de la herramienta puede ser una cadena o una matriz de `input_text`, `input_image` y `input_file` partes. Las piezas de imagen requieren `detail` (`auto`, `low`, `high` o `original`); el detalle del archivo es opcional (`auto`, `low`, `high`). Utilice exactamente una fuente de imagen / archivo. Los datos de archivo en línea requieren un nombre de archivo. Se conserva la opción `prompt_cache_breakpoint: { "mode": "explicit" }`. Los campos no admitidos son rechazados, no eliminados. Las referencias no se descargan ni se vuelven a cargar por el proxy. Cada resultado tiene como máximo 1.024 partes de contenido dentro del límite de solicitud de 8 MiB existente. Una persona que llama al programa suministrado debe coincidir con la llamada anunciada; no puede hacerse pasar por otra herramienta o agente. El orden del contenido, las referencias de archivos y la ortografía original sobreviven. + +Para un `mcp_approval_request` emitido por el servidor, pase su ID como `approval_request_id` y un `approve: true` o `approve: false` explícito. La denegación se envía sin cambios. El proxy no decide, por defecto, aprueba automáticamente ni ejecuta la herramienta solicitada. Se rechaza una decisión faltante o no relacionada. Las acciones alojadas `multi_agent_call` y otras herramientas de ejecución de servidor son **no** funciones de desarrollador: sus eventos, salidas y mensajes de agente cifrados se conservan, nunca se ejecutan o se inyectan antes de OpenCodex. + +Esto no permite una respuesta rica / personalizada / de aprobación **inyección de respuesta media**, ni una dirección simultánea en una respuesta multiagente. Esas operaciones tienen diferentes contratos ascendentes. La inyección no admitida se rechaza antes de reservar una llamada, por lo que un resultado no enviado permanece disponible para una continuación explícita posterior. No hay conversión automática, reintento, reejecución de herramientas o cuenta / interruptor API. Un giro de dirección de agente único puede seguir un giro de agente múltiple completado como una nueva solicitud explícita utilizando enrutamiento ordinario. El soporte al cliente y el derecho de backend aún requieren verificación en vivo. + + + + +## Configuración de continuación de dirección + +Un resultado guardado explícito `response.create` puede anular `reasoning` (esfuerzo y resumen), `text` (verbosidad y formato de salida estructurado compatible) y `stream_options`. Las rutas de suscripción rechazan una anulación `max_output_tokens` en lugar de ignorarla silenciosamente. Los pines de proveedor normales, las tapas de subagente, la asignación de esfuerzos y las exclusiones de capacidad de resumen/verbosidad aún se aplican. + +Los ajustes omitidos retienen los valores efectivos actuales; el valor nulo explícito restablece ese ajuste donde el flujo ascendente acepta null. Las anulaciones reemplazan el objeto de ajuste suministrado, no los campos anidados individuales. Los valores cambiados se trasladan a continuaciones explícitas posteriores. Una anulación rechazada no reserva el resultado guardado, por lo que se puede enviar una solicitud corregida sin volver a ejecutar su herramienta. El servidor aún decide qué configuración acepta el modelo elegido. Los cambios en el modelo, cuenta, proveedor, herramientas, instrucciones o nivel de servicio requieren un turno ordinario separado. + +La dirección nativa está restringida a la ruta canónica de suscripción ChatGPT. Las rutas públicas API -clave y puerta de enlace no son dirigibles; sus respuestas ordinarias se conservan y un intento de dirección recibe un error explicativo. Esto evita que las generaciones sucesoras en un socket retenido eviten la admisión normal por solicitud. La vía de inyección multiagente pública con compuerta separada API permanece disponible. + + + +### Sonda de alambre directa contra proxy ejecutable + +Desde una comprobación de origen, ejecute el control positivo fuera de línea: + +```sh +bun scripts/steering-smoke.ts --self-test +``` + +Planifique una comparación sin leer tokens ni abrir ninguna conexión: + +```sh +bun scripts/steering-smoke.ts --direct wss://api.openai.com/v1/responses \ + --proxy ws://127.0.0.1:1455/v1/responses --model \ + --proxy-model +``` + +Para una comparación de suscripción, la URL directa es `wss://chatgpt.com/backend-api/codex/responses`. Seleccione el mismo modelo y cuenta reales en ambas rutas; el script no puede probar que una configuración proxy seleccionó la misma cuenta. La URL proxy debe ser un punto final Responses de bucle y no debe contener credenciales, parámetros de consulta ni un fragmento. + +Solo después de revisar el plan, suministre `STEERING_DIRECT_TOKEN` y `STEERING_PROXY_TOKEN` a través de su entorno de shell y agregue **ambos** `--live` y `--allow-model-requests`. Una conexión directa ChatGPT puede necesitar adicionalmente `STEERING_DIRECT_ACCOUNT_ID`; ese encabezado nunca se copia al público API o al proxy. No ponga credenciales en argumentos de comando, registros, capturas de pantalla o relaciones públicas. El script no lee el inicio de sesión Codex guardado, actualiza tokens o cambia la configuración. + +La ejecución en vivo envía cuatro solicitudes iniciales sintéticas (dos escenarios por ruta), más cualquier sucesor resultante o continuación de resultado requerido, y **puede consumir el uso del modelo**. Un escenario comprueba un sucesor automático; el otro devuelve un resultado sintético fijo solo para la función anunciada del propio script y cambia el razonamiento/verbosidad en su continuación explícita. No se ejecuta ninguna herramienta externa y no se infiere ninguna aprobación. No hay reintentos ni solicitudes de recuperación automática. Cada escenario está limitado a 120 segundos, 5.000 eventos y 2 MiB de datos recibidos. + +El informe JSON contiene solo resultados, tiempos y puntos de control booleanos. Un pase requiere una aceptación en cola, un sucesor creado y el marcador sintético en su salida completada. Las confirmaciones que faltan son `unknown`; si el modelo nunca entra en la ruta de entrada requerida, el resultado es `not_exercised`. Tampoco se cuenta como pase. El proceso sale de 0 solo si pasan los cuatro escenarios en vivo, 1 en caso contrario y 2 para argumentos no válidos o credenciales faltantes. Se trata de un **diagnóstico de alambre**, no una prueba de interfaz de extremo a extremo Codex App / CLI, certificación en vivo o instrucción para habilitar la función experimental para el trabajo de producción. + + + +## Finales de línea de streaming + +El decodificador SSE compartido acepta terminaciones de línea LF, CRLF y CR independientes, incluso cuando un delimitador abarca fragmentos de red. Esto permite a los proveedores compatibles transmitir eventos sin requerir encuadre de solo LF. + + + + +### Solicitudes y créditos calificados para cuentas + +Elegir un modelo calificado para la cuenta no permite el gasto de crédito. Las cuentas almacenadas obedecen a **Usar créditos después del límite** durante la autenticación, cuando se preparan las credenciales y antes del envío de Responses HTTP o WebSocket después de la espera de estimulación o reintento. Una solicitud retenida informa de la política de crédito, no de un fallo de autenticación; espere a que se restablezca, elija otra cuenta o habilite explícitamente el gasto de crédito de esa cuenta. + +Los ayudantes de visión de cuenta almacenada y búsqueda web también vuelven a verificar esta política antes de enviarla, incluidos los reintentos. Si el consentimiento cambia o se alcanza un límite después de la selección del ayudante, el ayudante informa el rechazo de la política sin enviar ese intento. El relé de búsqueda independiente devuelve un 429 unido por reinicio. Las credenciales Direct propiedad de la persona que llama conservan su comportamiento existente. + + + +## Optar por un proveedor personalizado para administrar el enrutamiento local + +Un proveedor personalizado como `chatgpt-http` puede usar `supports_websockets = false` para mantener el transporte HTTP. OpenCodex deja a los proveedores personalizados intactos por defecto. Para delegar solo la URL de ese proveedor en OpenCodex, ejecute: + +```sh +ocx codex-provider allow chatgpt-http +ocx start +``` + +El primer comando explica el alcance y pide confirmación, por defecto a No. Para una operación con script explícitamente aprobada, use `allow chatgpt-http --yes`. El consentimiento se aplica a este ID de proveedor en el `CODEX_HOME` seleccionado; no aprueba otros proveedores u otros hogares. Inicie y sincronice solo su `base_url` con el proxy local. Su identidad, configuración WebSocket, otros campos TOML e historial permanecen sin cambios. Mantenga el proxy en ejecución mientras usa esta ruta. Desactivar la integración Codex también impide que las actualizaciones de URL del proveedor aprobado se inicien o sincronicen; el consentimiento del proveedor guardado permanece disponible cuando lo vuelva a encender. + +Este modo admite tablas de proveedores explícitas Responses con `requires_openai_auth = true` y sin credenciales o encabezados personalizados. Los objetivos no loopback, el modo de escritorio authless y la compactación del cliente requieren la integración dedicada existente. + +`ocx stop` y `ocx restore` restauran las URL registradas mientras mantienen el consentimiento para un inicio posterior. Ejecute `ocx codex-provider status` para enumerar las aprobaciones, o `ocx codex-provider revoke chatgpt-http` para restaurar su URL administrada y eliminar el consentimiento. Una URL cambiada fuera de OpenCodex se conserva y requiere revocación seguida de una nueva aprobación; OpenCodex no adopta silenciosamente el reemplazo como una nueva línea de base. La asignación de URL original se conserva en metadatos de recuperación privados bajo `OPENCODEX_HOME`, por separado de la revista de configuración nativa. + +La seguridad de inicio reconoce la URL administrada registrada de un proveedor aprobado como enrutamiento OpenCodex. Esto no instala protección de reinicio: un proxy iniciado manualmente todavía necesita un servicio de fondo viable para recuperarse automáticamente después de un reinicio. + + + +## Validación de relé de escritorio nativo CONNECT + +El transporte CONNECT HTTP / HTTPS existente del relé de escritorio ahora rechaza las cabeceras de respuesta proxy mal formadas y los nombres de usuario básicos ambiguos HTTP que contienen dos puntos. Los pares de credenciales decodificadas están limitados a 4096 bytes UTF-8. Si el proxy seleccionado es rechazado, corrija su configuración o respuesta; el relé no cambia silenciosamente a una conexión directa. + +La selección de proxy, el soporte SOCKS5h, la verificación de certificados y el ciclo de vida de la conexión no cambian. Ambas ortografías SOCKS retienen la resolución DNS de destino remoto. diff --git a/docs-site/src/content/docs/es/guides/codex-log-guard-reclaim.md b/docs-site/src/content/docs/es/guides/codex-log-guard-reclaim.md new file mode 100644 index 00000000000..a2dedbf7807 --- /dev/null +++ b/docs-site/src/content/docs/es/guides/codex-log-guard-reclaim.md @@ -0,0 +1,106 @@ +--- +title: "Codex Log Guard Reclamación" +description: "Recupera manualmente páginas libres de SQLite en la base de datos de registros de Codex, con límites y comprobaciones de integridad." +--- + +Reclaim es la etapa manual de recuperación de espacio de Codex Log Guard. Compacta el canónico Codex `logs_2.sqlite` base de datos solo cuando la base de datos y el entorno de ejecución pasan las mismas comprobaciones de seguridad utilizadas por la protección Log Guard. + +Reclaim es **Nunca programado automáticamente** y nunca se ejecuta simplemente porque la página de almacenamiento está abierta. El panel de control requiere una acción Compact explícita y una segunda confirmación antes de enviar la solicitud de mutación. + + + +## Lo que hace Reclaim + +OpenCodex realiza una secuencia de mantenimiento sin conexión limitada: + +1. resolver el canónico `logs_2.sqlite` a través de Codex 's efectiva `sqlite_home`; +2. verificar la identidad del archivo y el esquema de registro Codex conocido; +3. Verificar que la enumeración del proceso se haya realizado correctamente y que no se esté ejecutando ningún proceso de escritura Codex compatible; +4. adquirir la cerradura dedicada de proceso cruzado Log Guard; +5. Repita la comprobación del proceso Codex mientras se mantiene ese bloqueo. +6. abrir la base de datos existente leer/escribir sin crear semántica y probar que se puede adquirir un escritor inmediato SQLite; +7. requieren que `PRAGMA auto_vacuum` ya sea `INCREMENTAL`; +8. ejecutar `PRAGMA quick_check` antes del mantenimiento; +9. ejecutar un punto de control WAL completo y rechazar un punto de control ocupado / incompleto; +10. ejecutar lotes delimitados `PRAGMA incremental_vacuum(N)`, puntos de control después de cada lote; +11. vuelva a ejecutar `PRAGMA quick_check` después del mantenimiento; y +12. informe antes/después de métricas de base de datos, WAL, recuento de páginas, lista libre y bytes recuperables. + +El objetivo por defecto del lote es aproximadamente **8 MiB de SQLite páginas**. Una sola invocación reclama como máximo aproximadamente **256 MiB de páginas**, con un límite de iteración finita adicional. Si quedan más páginas libres, el resultado se informa como parcial y puede invocar Compact de nuevo más tarde. + +Los límites de bytes se convierten en recuentos de páginas usando el tamaño de página real SQLite de la base de datos. Son límites en SQLite páginas lógicas procesadas, no afirmaciones sobre el volumen de escritura SSD / NAND. + + + +## Garantías de seguridad + +Reclamar deliberadamente hace **no**: + +- Ejecutar `VACUUM` completo; +- cambiar el modo `auto_vacuum` en una base de datos Codex existente; +- eliminar, truncar, renombrar o manipular de cualquier otra forma Codex `-wal` / `-shm` archivos directamente; +- eliminar filas de diagnóstico; +- modificar disparadores de protección Log Guard o disparadores de usuario no relacionados; +- ejecutar mientras se detecta que Codex está activo; +- proceder cuando la enumeración del proceso es incierta; +- proceder sobre un esquema de registro futuro desconocido; o +- continuar después de una comprobación de integridad SQLite fallida. + +Un bloqueo Log Guard ocupado, un escritor SQLite ocupado o un punto de control inicial ocupado se devuelven como un rechazo explícito en lugar de volver a intentarlo en segundo plano. Si la contención del punto de control aparece solo después de que un lote de vacío incremental ya se haya comprometido, OpenCodex informa que el trabajo ya se completó como un resultado parcial exitoso con `stopReason: "busy"` en lugar de afirmar que nada cambió. + +## CLI + +Inspeccione primero el espacio recuperable: + +```bash +ocx storage codex-logs status +``` + +Ejecute un pase de mantenimiento limitado: + +```bash +ocx storage codex-logs compact +``` + +Para métricas de antes/después legibles por máquina: + +```bash +ocx storage codex-logs compact --json +``` + +Si el resultado informa que queda más espacio recuperable, deténgase allí a menos que desee explícitamente otro pase limitado. OpenCodex no hace bucle indefinidamente ni programa un pase de seguimiento para usted. + + + +## API de administración + +La compactación se expone solo como un punto final de mutación: + +```text +POST /api/storage/codex-logs/compact +``` + +No hay alias GET para la compactación. Una respuesta exitosa contiene un objeto `report` con mediciones de antes/después, recuentos de páginas recuperadas, cambio de tamaño de la base de datos principal física, recuento de iteraciones, completitud, razón de detención y estado de integridad. + +Los estados de rechazo típicos incluyen: + +- `codex_running` +- `process_enumeration_failed` +- `busy` +- `unsupported_schema` +- `auto_vacuum_not_incremental` +- `unsafe_path` +- `integrity_check_failed` +- `database_error` + +Las fallas de integridad incluyen si ocurrieron antes o después del pase de mantenimiento. Un rechazo de `busy` significa que se detectó contención antes de que se cometiera cualquier lote de vacío; `stopReason: "busy"` dentro de un informe exitoso significa que al menos un lote se cometió antes de que la contención posterior del punto de control detuviera el pase. + + + +## Entender el resultado + +`pagesReclaimed` y `logicalBytesReclaimed` describen SQLite páginas de lista libre eliminadas durante el pase. `physicalDatabaseBytesReclaimed` informa de la reducción observada en el archivo de base de datos principal después de los puntos de control de mantenimiento. + +Estos números pueden diferir. SQLite /WAL/comportamiento del sistema de archivos significa que la recuperación de páginas lógicas no garantiza una reducción idéntica inmediata del archivo físico, y ninguna de estas métricas debe interpretarse como escrituras NAND, desgaste de SSD o TBW consumido/guardado. + +`complete: true` significa que la lista libre observada llegó a cero. Un resultado parcial usa `stopReason: "page_budget"` cuando el presupuesto de página por ejecución o el límite de iteración finita finaliza el pase, `stopReason: "no_progress"` cuando SQLite deja de reducir la lista libre y `stopReason: "busy"` cuando aparece la contención del punto de control después de la recuperación comprometida. Los tres son resultados limitados; ninguno causa un reintento automático. diff --git a/docs-site/src/content/docs/es/guides/codex-log-guard.md b/docs-site/src/content/docs/es/guides/codex-log-guard.md new file mode 100644 index 00000000000..a8c403a4a05 --- /dev/null +++ b/docs-site/src/content/docs/es/guides/codex-log-guard.md @@ -0,0 +1,157 @@ +--- +title: "Codex Log Guard" +description: "Inspeccione y reduzca explícitamente la persistencia del registro de diagnóstico Codex sin exponer los cuerpos de registro." +--- + +OpenCodex puede inspeccionar la base de datos persistente de registros de diagnóstico de Codex y, si lo activas expresamente, reducir las filas que Codex guarda. La inspección es de solo lectura. Activar la protección modifica la base de datos y solo se permite cuando coincide el esquema de registros conocido y Codex está detenido. + + + +## Qué muestra la inspección + +OpenCodex resuelve el valor efectivo de `sqlite_home` siguiendo la precedencia de Codex e inspecciona allí la base de datos canónica `logs_2.sqlite`. Nunca usa como destino modificable un archivo `logs_N.sqlite` heredado o de numeración superior. + +La vista Almacenamiento informa: + +- el tamaño de la base de datos principal y de sus archivos WAL y SHM; +- el total de filas y la proporción guardada con nivel `TRACE`; +- los destinos de registro con más filas, identificados por su posición en la clasificación y sin revelar sus nombres; +- el espacio de páginas libres de SQLite que podría recuperarse más adelante; y +- la compatibilidad del esquema observado con el esquema de registros de Codex conocido. + +Si `sqlite_home` está fuera de `CODEX_HOME`, la base de datos de diagnóstico se muestra por separado. Sus bytes no se suman implícitamente al almacenamiento de `CODEX_HOME`. + +OpenCodex no consulta ni expone `feedback_log_body` al generar estos diagnósticos. Los niveles se reducen al conjunto fijo conocido más `OTHER`, y los nombres de los destinos no se serializan. + + + +## Proteger los modos + +La protección está **desactivada de forma predeterminada**. Al activarla, se instala un único trigger `BEFORE INSERT`, propiedad de OpenCodex, en `logs_2.sqlite`. OpenCodex nunca reemplaza un trigger desconocido que use sus nombres reservados y solo elimina triggers cuyo SQL coincide con su propia versión. + +Hay dos modos disponibles: + +- **Compatibilidad** (`compat`) es el modo recomendado. Aplica las reglas de Log Guard v1 a los destinos de gran volumen que Codex ya filtra o guarda con un nivel inferior en su registro SQLite persistente. Conserva las filas `TRACE` de otros destinos. +- **Silencioso** (`quiet`) suprime todas las filas nuevas de nivel `TRACE` y conserva las de nivel `DEBUG`, `INFO`, `WARN` y `ERROR`. + +La protección reduce las filas que llegan al almacenamiento SQLite persistente. **No** elimina el trabajo previo de diagnóstico de Codex: los eventos aún pueden formatearse, encolarse, agruparse en transacciones y pasar por su lógica de limpieza antes de que el trigger descarte una fila. Protect reduce las escrituras persistentes; no desactiva la generación interna de diagnósticos. + +Log Guard filtros solo persisten locales SQLite filas de registro. No cambia el procesamiento de diagnóstico Codex, [transporte del adaptador](/es/reference/adapters/), las cargas útiles del proveedor, la semántica de transmisión, la autenticación, el enrutamiento, las cuotas o el estado de la cuenta. + + + +### Controles de seguridad + +Antes de que Proteger, Deshabilitar o Reparar modifiquen la base de datos de Codex, OpenCodex: + +1. Resuelve exactamente la ruta canónica de `logs_2.sqlite`. +2. Comprueba que sea un archivo regular, no un enlace simbólico, y que el esquema coincida exactamente con el conocido. +3. Comprueba que se hayan podido enumerar los procesos y que no haya ningún proceso de Codex compatible escribiendo en la base. +4. Adquiere un bloqueo de Log Guard dedicado y compartido entre procesos. +5. Repite la comprobación de procesos de Codex después de adquirir el bloqueo. +6. Abre la base de datos para lectura y escritura **sin crearla** y adquiere `BEGIN IMMEDIATE` de SQLite sin esperar si está ocupada. +7. Modifica únicamente los triggers de Log Guard propiedad de OpenCodex y vuelve a leer el resultado antes de confirmar la transacción. +8. Guarda el modo solicitado en la configuración de OpenCodex mientras sigue manteniendo el bloqueo de Log Guard. + +Si no se puede confirmar la enumeración de procesos, la base está ocupada, el esquema es desconocido o un nombre reservado pertenece a otro SQL, se rechaza la modificación. OpenCodex no cierra Codex automáticamente. + + + +## Deriva y reparación + +El modo de protección solicitado se guarda en la configuración de OpenCodex, separado de la base de datos de registros de Codex. Una migración de Codex puede reconstruir la tabla `logs`; SQLite elimina los triggers asociados a una tabla que se reemplaza. + +Si el modo guardado es `compat` o `quiet` pero ya no se observa el trigger correspondiente de OpenCodex, Log Guard informa el estado **drifted**. `ocx doctor` detecta esa divergencia, pero nunca la repara automáticamente. + +La reparación es explícita: + +```bash +ocx storage codex-logs repair +``` + +OpenCodex no vuelve a crear la protección en cada inicio. Solo se reconsideraría la reparación automática en una versión posterior si hay evidencia suficiente de que es segura entre migraciones de Codex. + +## CLI + +Leer estado: + +```bash +ocx storage codex-logs status +ocx storage codex-logs status --json +ocx doctor +``` + +Habilitar la directiva de compatibilidad recomendada: + +```bash +ocx storage codex-logs protect +``` + +Elija el modo silencioso explícitamente: + +```bash +ocx storage codex-logs protect --mode quiet +``` + +Desactivar OpenCodex protección o reparación deriva: + +```bash +ocx storage codex-logs unprotect +ocx storage codex-logs repair +``` + +Agregue `--json` a los comandos Log Guard para obtener una salida legible por máquina. Vea el [CLI referencia](/es/reference/cli/) para la sintaxis canónica de comandos y el comportamiento JSON. + +El comando existente permanece sin cambios: + +```bash +ocx storage --json +``` + +Su respuesta lleva el mismo estado de registro Codex utilizado por la página de almacenamiento. + + + +## API de administración + +El estado está disponible en: + +```text +GET /api/storage/codex-logs +``` + +Mutaciones explícitas: + +```text +POST /api/storage/codex-logs/protect +POST /api/storage/codex-logs/unprotect +POST /api/storage/codex-logs/repair +``` + +El cuerpo de Protect es `{"mode":"compat"}` o `{"mode":"quiet"}`. `GET /api/storage` también incluye el informe como `codexLogs`, para actualizar el desglose de almacenamiento y los diagnósticos de Codex con una sola solicitud de instantánea. + + + +## Semántica de instantáneas de solo lectura + +La inspección abre la base de datos en modo de solo lectura con `immutable=1` de SQLite. Así no crea ni actualiza los archivos auxiliares `-wal` o `-shm`. + +Esta decisión tiene una limitación: los agregados SQL y los metadatos de triggers describen la última instantánea consolidada mediante un checkpoint. Si Codex está escribiendo, el WAL puede contener filas o páginas de esquema más recientes. Una modificación exitosa devuelve el estado del trigger verificado dentro de su transacción de escritura. Una consulta posterior de solo lectura puede mostrar temporalmente un estado anterior hasta que SQLite consolide esas páginas. + +OpenCodex informa el tamaño del archivo WAL por separado y **no** etiqueta el resultado como tasa de escritura SSD, escritura NAND o consumo de desgaste de unidad / TBW. + + + +## Estados de compatibilidad + +Con un esquema conocido, se admiten la inspección y la protección. Si el esquema falta, no se puede leer o pertenece a una versión futura desconocida, se pueden inspeccionar los metadatos disponibles, pero no modificar la base. + +OpenCodex no presupone que un esquema desconocido sea compatible. Así puede mostrar información de una versión nueva de Codex sin tratar una estructura no revisada como segura para modificar. + + + +## La recuperación sigue siendo independiente + +Protect no ejecuta vacuum ni compacta SQLite. [**Recuperar espacio**](/es/guides/codex-log-guard-reclaim/) ofrece un proceso independiente de vacuum incremental, explícito, sin Codex en ejecución y con límites, checkpoints y comprobaciones de integridad. + +Protect nunca ejecuta `VACUUM`, nunca trunca o elimina WAL de Codex directamente, y nunca realiza una recuperación de espacio programada. diff --git a/docs-site/src/content/docs/es/guides/codex-native-context.md b/docs-site/src/content/docs/es/guides/codex-native-context.md new file mode 100644 index 00000000000..b089715b6bb --- /dev/null +++ b/docs-site/src/content/docs/es/guides/codex-native-context.md @@ -0,0 +1,89 @@ +--- +title: "Compatibilidad de contexto nativo" +description: "Elegibilidad, configuración de prueba autenticada y límites de la historia y retransmisión de notas de Codex." +--- + +OpenCodex ya transmite la historia y las notas nativas Codex. Este no es un servicio de memoria general para los proveedores enrutados, y la exposición de sus puntos finales HTTP no establece que una compilación, cuenta o modelo Codex particular pueda usarlos. Consulte [Codex integración](/es/guides/codex-integration/) para conocer los límites de propiedad, cancelación y credenciales del relé. + + + +## Dos requisitos independientes + +Codex debe activar la extensión, y OpenCodex debe identificar al llamante. Cambiar la URL de backend no resuelve ninguno de los requisitos por sí solo. + +El contrato de Codex aguas arriba inspeccionado requiere un modelo cuya entrada de catálogo nativa anuncia `supports_experimental_context`, un inicio de sesión ChatGPT elegible y un proveedor nombrado exactamente `OpenAI` con una URL base que termina en `/backend-api/codex`. Su activación automática rechaza a los proveedores que usan `env_key`, `experimental_bearer_token`, `auth` respaldado por comandos o AWS auth. El predicado de elegibilidad inspeccionado acepta ChatGPT Plus, Pro y ProLite; esta no es una afirmación de que cada cuenta en esos planes tenga puntos finales de historial de backend que funcionen. + +OpenCodex requiere adicionalmente un **plano de datos API clave** activo tanto en la solicitud de modelo satisfactoria como en las solicitudes de contexto posteriores. La inyección de bucle invertido incorporada por defecto no envía esa clave, por lo que puede servir modelos mientras las llamadas de contexto fallan con `context_principal_required` (403). El formulario de tabla de proveedor remoto autenticado por sí solo tampoco es una solución de contexto nativo: su `env_key` y el nombre del proveedor no satisfacen el contrato de activación Codex anterior. Nunca quite los cheques de principal o de propiedad de la cuenta para ocultar cualquiera de los problemas. + + + +## Sintaxis explícita de opt-in + +OpenCodex acepta ambas formas de características de raíz persistentes que Codex `FeatureToml` acepta: + +```toml +[features] +context_management = true +``` + +El formulario de tabla equivalente también funciona y es la ortografía compatible para versiones anteriores de OpenCodex que aún no reconocían la forma booleana: + +```toml +[features.context_management] +experimental_mode = true +``` + +Use una forma, no ambas. Los valores falsos, ausentes y mal formados permanecen fuera. El proxy lee su propia configuración de inicio Codex; un CLI -solo anulación o una opción de inclusión presente solo dentro de un perfil Codex no habilita su puerta de entorno de ejecución. Este cambio no infiere la aceptación de los metadatos del modelo. + + + +## Perfil de prueba nativo autenticado + +Esto es un **Configuración de prueba comprobada por fuente, no una certificación de extremo a extremo de cuenta real**. Realice una copia de seguridad de la configuración Codex y mantenga un punto de control de tareas duradero antes de realizar las pruebas. Utilice un nuevo hilo desechable; no cambie la identidad del proveedor de un hilo de trabajo existente. + +Suministre una clave de plano de datos activa OpenCodex existente en `OCX_CONTEXT_API_KEY` en el entorno del proceso Codex. No utilice un token de administración/admin ni almacene la clave en TOML. El entorno de un servicio no es heredado automáticamente por una aplicación de escritorio lanzada por separado. Mantenga el inicio de sesión nativo normal Codex ChatGPT disponible; el encabezado adicional no reemplaza OAuth. + +Con la opción de acceso de la función raíz anterior, el proveedor de reenvío canónico ChatGPT configurado en OpenCodex y un catálogo de modelo nativo actual, fusiona este proveedor y perfil de **adicionales** en la misma configuración de Codex. Ajuste el puerto al proxy local real. Deje la raíz `model_provider` y las tablas de proveedores existentes sin cambios. + +```toml +[model_providers.ocx-native-context] +name = "OpenAI" +base_url = "http://127.0.0.1:10100/backend-api/codex" +wire_api = "responses" +requires_openai_auth = true +supports_websockets = false +env_http_headers = { "x-opencodex-api-key" = "OCX_CONTEXT_API_KEY" } + +[profiles.ocx-native-context] +model_provider = "ocx-native-context" +model = "gpt-6-astra" +``` + +Inicia un nuevo hilo CLI con `codex --profile ocx-native-context`. El ejemplo utiliza HTTP / SSE para mantener la prueba inicial en la ruta de propiedad del modelo al relé; no cambia el transporte de otros perfiles ni certifica la paridad WebSocket /mid-turn-steering. Utilice el modelo solo cuando el catálogo nativo de la cuenta realmente anuncie su capacidad de contexto; nunca fuerce esa bandera a una fila Devin, Gemini u otra fila enrutada. + +El ID de proveedor personalizado es intencional. El Codex ascendente generalmente no anula a los proveedores incorporados de `model_providers.openai`; agregar un encabezado adicional allí puede ser silenciosamente ineficaz. El ID personalizado conserva el proveedor normal, mientras que el nombre exacto `OpenAI` satisface el predicado de backend nativo. No agregue `env_key` a este perfil: `env_http_headers` lleva la admisión local por separado, mientras que `Authorization` continúa llevando el inicio de sesión nativo ChatGPT. OpenCodex consume la clave local; no reenvía esa clave a ChatGPT. + +El opt-in raíz también afecta a otros perfiles nativos elegibles. **Durante esta prueba, no continúe con los hilos de bucle de retorno incorporados normales que carecen de la clave adicional.** Apague la función raíz y ejecute `ocx sync` antes de volver a esos hilos. Este no es un cambio de integración automático o predeterminado, y este perfil CLI no es una afirmación sobre el soporte de selección de perfiles de escritorio. + + + +## Verificar antes de restablecer el contexto + +Primero obtenga una respuesta exitosa del modelo nativo en el nuevo hilo. A continuación, verifique una nota escrita, lea la misma nota y consulte el historial de ese hilo. Solo después de que esas operaciones tengan éxito, una prueba desechable debe usar `new_context` y verificar que el estado guardado se pueda recuperar. Mantenga el punto de control externo incluso cuando la prueba tenga éxito. + +- **403 `context_principal_required`:** ninguna clave de plano de datos local válida alcanzó el proxy. +- **409 `context_account_unavailable`:** La propiedad está ausente o es inconsistente; no sustituya la cuenta activa actual ni vuelva a intentar escribir a ciegas. +- **404:** distinguen la respuesta de punto final deshabilitado/desconocido del proxy de un 404 ascendente. Esto último no es prueba de un defecto de enrutamiento OpenCodex o una interrupción en toda la cuenta. + +Una llamada modelo o `ocx ready` exitosa no es prueba de que las notas, la historia o la restauración del estado funcionen. El enrutamiento de modelos, los cambios de cuenta, los reinicios de proxy y la disponibilidad de puntos finales ascendentes siguen siendo preocupaciones separadas. Ninguna bandera local puede conceder la elegibilidad de backend faltante, y una operación de contexto fallida no debe ser reportada como un restablecimiento exitoso. Retire las tablas de prueba y desactive la clave de prueba cuando haya terminado; deje la función deshabilitada a menos que utilice una ruta autenticada verificada. + + + +## Contratos ascendentes inspeccionados + +Estos enlaces fijan el contrato de origen utilizado para la configuración anterior, no una promesa de implementación: + +- [FeatureToml booleano/formas de tabla](https://github.com/openai/codex/blob/78245b47af2a7aafcabe025828ceecca69db4df1/codex-rs/features/src/lib.rs) +- [Elegibilidad del contexto nativo](https://github.com/openai/codex/blob/78245b47af2a7aafcabe025828ceecca69db4df1/codex-rs/core/src/session/token_budget.rs) +- [Identidad del proveedor y reglas de fusión incorporadas](https://github.com/openai/codex/blob/78245b47af2a7aafcabe025828ceecca69db4df1/codex-rs/model-provider-info/src/lib.rs) +- [El historial/las notas utilizan los encabezados de solicitud y la autenticación del proveedor](https://github.com/openai/codex/blob/78245b47af2a7aafcabe025828ceecca69db4df1/codex-rs/ext/history-notes/src/backend.rs) diff --git a/docs-site/src/content/docs/es/guides/codex-prompt.md b/docs-site/src/content/docs/es/guides/codex-prompt.md new file mode 100644 index 00000000000..244f8f93946 --- /dev/null +++ b/docs-site/src/content/docs/es/guides/codex-prompt.md @@ -0,0 +1,192 @@ +--- +title: "Capas de instrucciones de Codex" +description: "Lea lo que Codex realmente envía, apague las piezas que no necesita y agregue sus propias instrucciones como capas." +--- + +Codex ensambla su solicitud a partir de capas: sus propias instrucciones básicas, los documentos de su proyecto, el contexto de permisos y entorno, las habilidades que ha instalado y más. **Codex Set → Prompt** muestra esa pila, le dice lo que cuesta cada capa y le permite desactivar las piezas que no desea. + + + +## Lo que muestra la lista + +Cada fila lleva su posición en el orden de montaje, la clave de configuración que la gobierna cuando hay una y el tamaño de lo que realmente envió. + +Las posiciones tienen lagunas. Eso es deliberado: los números son los índices reales de la asamblea, y dos de ellos se enumeran más abajo en **Notificaciones de transición**. Renumerar cada grupo de uno mostraría que no se usa una orden Codex. + + + +### Cinco tipos de capa + +| Tipo | Lo que puedes hacer | +|---|---| +| Conmutable aquí | Un verdadero interruptor. Escribe una clave en `config.toml`. | +| Configurado bajo `[features]` | Real, pero cambiado de la configuración de características en lugar de esta página. | +| Siempre encendido | No hay interruptor de apagado en cualquier lugar en Codex. | +| Se activa cuando cambia | Anuncia una transición, por lo que solo aparece cuando algo cambia. | +| Capas de extensión | No se puede enumerar. Codex no los expone. | + +Una capa sin interruptor de apagado no muestra ningún interruptor en lugar de uno deshabilitado. Un control en gris sugeriría que la capacidad existe y no está disponible temporalmente, lo cual no es el caso. + + + +## Leer una capa + +Haga clic en un nombre de capa para ver el texto que envía. El cuadro de diálogo lo lee desde `codex debug prompt-input`, por lo que es lo real en lugar de una descripción. + +A veces no hay nada que mostrar, y el diálogo dice qué razón se aplica: + +- **El archivo está vacío.** Su `~/.codex/AGENTS.md` es cero bytes, por lo que la capa no tiene nada que enviar. El diálogo nombra la ruta. +- **No envió nada en el turno que leímos.** Las capas solo se vuelven a enviar cuando cambian, por lo que una capa sin cambios está ausente de una sola muestra. +- **El indicador base proviene de su catálogo de modelos.** Codex lo envía fuera de la lista legible, por lo que el cuadro de diálogo lo lee desde la fila de catálogo del modelo seleccionado, o desde el archivo nombrado por `model_instructions_file` cuando ha establecido uno. Una fila que publica solo una plantilla no expandida se informa como no se muestra, porque ese texto no es lo que envía Codex. +- **El mensaje no se pudo leer.** La sonda falló en esta máquina. + +La lectura se toma de su casa global Codex (`~/.codex`), no del directorio en el que se está ejecutando el panel de control. + + + +## Capas personalizadas + +**+ Añadir capa** añade sus propias instrucciones. Las capas personalizadas componen `developer_instructions`, que es aditivo: Codex mantiene sus propias instrucciones y las tuyas se agregan a ellas. + +:::note +Esto es deliberadamente no `model_instructions_file`. Esa clave REPLACES la base más rápido que añadir a ella, por lo que el cableado **+** eliminaría el propio Codex instrucciones la primera vez que guardó una capa. Si la sustitución del indicador base es lo que quieres, eso es lo que [Variantes de prompt base](#base-prompt-variants) es por — una decisión separada, con nombre en lugar de un efecto secundario de agregar una capa. +::: + +Las capas personalizadas se numeran entre sí porque se unen en una sección en ese orden: no se entrelazan con las capas incorporadas. + +Reordene con las flechas en la fila, o con `Alt` + `Up` / `Alt` + `Down` desde cualquier lugar de la fila. El orden es el orden de composición. + +El panel muestra el tamaño combinado de las capas habilitadas frente al límite de 128 KiB para `developer_instructions`, y una vista previa plegable del texto unido: una capa que empujaría la sección sobre el límite es visible antes de guardar, no después. + +Eliminar una capa pide primero, luego ofrece **Deshacer** por unos segundos. La capa vuelve a su posición anterior, por lo que una lista sensible al orden sobrevive al desliz. + + + +### Preconfiguración + +**+ Añadir capa** ofrece cinco puntos de partida: salida concisa, plan antes de editar, explicar el razonamiento, probar primero y respuestas coreanas. Cada uno abre el editor ordinario precargado y totalmente editable: un preajuste es un punto de partida y lo que guarda es una capa personalizada ordinaria. + +Los preajustes son nuestro propio texto, escrito para destilar un enfoque en lugar de copiar el mensaje de alguien. Cada uno nombra su fuente. + + + +### Moverse entre capas mientras se edita + +El editor tiene controles previos/siguientes y un indicador de posición. Las ediciones no guardadas se mantienen mientras se mueve, por lo que puede comparar dos capas a mitad de edición y volver sin perder lo que escribió. El cierre con ediciones en otra capa pregunta antes de descartarlas. Guardar una capa también pregunta antes de descartar ediciones aparcadas en otras capas; el botón **Guardar** de la confirmación guarda solo la capa mostrada. + + + +### Advertencias de compatibilidad + +El editor advierte cuando una capa dice algo que no funcionará como está escrito: reclama una identidad diferente, nombra una herramienta que el registro define, usa marcadores de posición de plantilla, nada se expande o indica hechos del entorno que Codex genera más tarde. También señala las credenciales pegadas (una clave API en una capa se envía al modelo en texto plano en cada solicitud), fraseo que le dice al modelo que deje sus instrucciones anteriores, y una identidad no Codex reclamada en coreano. + +Estas son advertencias y nunca bloquean un salvamento. Si quieres anular Codex, puedes; la advertencia solo lo convierte en una decisión en lugar de un accidente. + + + +## Comprometer la atribución + +La fila **Comprometer la atribución** le dice al modelo que agregue un remolque `Co-authored-by: Codex` para confirmar que escribe, y una línea `Generated with Codex.` para extraer las solicitudes que abre. + +No hay ningún cambio para ello aquí, y ninguno bajo `[features]` tampoco: Codex lo resuelve de la política de atribución de su cuenta. Apagarlo en el nivel de cuenta no elimina la capa: Codex envía la instrucción **opuesto** en su lugar, diciéndole al modelo que no agregue el remolque. De cualquier manera, se envía algo, por lo que la fila se enumera como establecida por su cuenta en lugar de como siempre. + + + +## Variantes de prompt base + +El indicador base es la única capa que no se puede desactivar, porque un modelo sin indicador base no es un agente de trabajo. Sin embargo, puede **sustituto** y el interruptor en la fila **Instrucciones de base** es lo que hace eso. + +Abra la fila para ver el selector. Muévase entre las opciones deslizando hacia los lados, con las teclas de flecha izquierda y derecha, o con los botones de flecha: los botones también son lo que anuncia un lector de pantalla, por lo que la página permanece operable sin un panel táctil. + +| Opción | Qué es | Editable | +|---|---|---| +| Codex 's propio indicador de base | `model_instructions_file` está ausente de su configuración | nunca | +| Su variante | un aviso que escriba, almacenado en `~/.codex/opencodex-prompt-base/` | sí | +| Una segunda variante | Lo mismo, hasta dos | sí | + +La primera opción no tiene nada que editar y no tiene botón **Guardar**, y el diálogo dice por qué en lugar de mostrar controles en gris. El valor predeterminado no es una copia del mensaje de Codex que almacenamos, es el **ausencia** de la clave. Así que no hay texto que cambiar y ninguno que eliminar, y elegirlo simplemente elimina `model_instructions_file` de su configuración de nuevo. + +:::caution +Una variante **sustituye** Instrucciones base de Codex en lugar de añadir a ellos. A La variante de tres líneas le da un modelo con tres líneas de instrucciones: ninguna herramienta disciplina, sin hábitos de verificación, nada de lo que Codex normalmente trae. Si quieres a *añadir* Guía, utiliza un [capa personalizada](#custom-layers) en su lugar, — son aditivos. +::: + +El editor de variantes tiene las mismas barandas que el editor de capas personalizadas: las ediciones no guardadas se mantienen mientras se mueve entre las opciones, se cierra con preguntas de ediciones antes de descartarlas, y el cuerpo se cuenta contra el límite de 64 KiB por variante mientras escribe. + + + +### Si algo más ya ha reemplazado a su prompt base + +Si `model_instructions_file` puntos en un archivo opencodex no se escribieron, el selector se niega a actuar y dice dónde los puntos clave. No reorientará silenciosamente una clave tú u otro conjunto de herramientas. + +Sin embargo, no tienes que aclararlo a mano. **Importarlo como variante** convierte el archivo: la vista previa muestra el texto *exacto* que se instalará: una línea de encabezado `# ` que contiene el título variante, luego el cuerpo del archivo con terminaciones de línea y pestañas normalizadas, y puede editar el título antes de confirmar. El cuerpo puede usar como máximo 64 KiB después de la normalización (`bodyBytes` en la vista previa); el archivo completo en disco, encabezado incluido, es un poco más grande (`serializedBytes`). La confirmación está vinculada al texto previsualizado por un hash, por lo que si el archivo, o el título elegido, cambió entremedio, la importación se niega en lugar de instalar el texto que nunca vio. Despeje la clave usted mismo si prefiere comenzar desde el valor predeterminado. + +Este es el mismo principio que la importación `developer_instructions`: el panel informa lo que encuentra y usted decide. + +El cambio se aplica a las sesiones recién iniciadas, como cualquier otro cambio en esta página. + + + +## Instrucciones escritas fuera de opencodex + +Si ya existe `developer_instructions` y opencodex no lo escribió, el panel no lo sobrescribirá. En su lugar, ofrece importar el texto como una capa: primero se ve el valor existente y no se escribe nada hasta que se confirma. + + + +## Cuando algo está fuera de sincronización + +Si las capas guardadas y el valor en `config.toml` no están de acuerdo, el panel lo dice y ofrece **Reparar** en lugar de fijarlo en silencio. Dos de las rutas de reparación reescriben el texto que escribiste, por lo que permanecen deliberadas. Una escritura interrumpida ("presentación de diario") ejecuta una operación bloqueada de recuperación solamente usando las imágenes de archivo grabadas del diario; no vuelve a guardar la lista de capas actual ni inventa el contenido que falta. Si los archivos en vivo no coinciden con ninguno de los estados registrados, la recuperación se niega y conserva la evidencia. El panel actualizado informa de cualquier deriva restante. Cuando falta un archivo de capa, la reparación escribe una copia de seguridad antes de que toque algo. + + + +## Cuando los cambios surtan efecto + +Los cambios se aplican a las sesiones recién iniciadas. Una sesión que ya se está ejecutando mantiene la configuración del mensaje con la que comenzó. + + + +## Mantener el catálogo de habilidades estable + +El proxy por defecto es `skills.catalog_refresh: "per_session"`: el primer catálogo `` recibido para una conversación se reutiliza en solicitudes posteriores en esa conversación. Esto evita que el descubrimiento de habilidades y las ediciones `SKILL.md` cambien esa parte del prefijo de caché de prompt ascendente a mitad de la sesión. Una solicitud que transporta más de un bloque `` se pasa sin cambios, y una solicitud que el proxy rechaza no establece el catálogo. + +Para utilizar el catálogo suministrado por el cliente en cada turno, establezca esto en opencodex's +`$OPENCODEX_HOME/config.json` (normalmente `~/.opencodex/config.json`), luego reinicia El proxy: + +```json +{ + "skills": { + "catalog_refresh": "per_turn" + } +} +``` + +Los valores admitidos son `"per_session"` (predeterminado) y `"per_turn"`. Esta es una configuración de proxy, separada de Codex `skills.include_instructions` alternar. Las solicitudes sin una identidad de conversación confiable utilizan el catálogo suministrado por el cliente. Las instantáneas se guardan en la memoria y no sobreviven a un reinicio proxy. Caducan después de cuatro horas de inactividad y pueden ser desalojados cuando se llena el caché limitado. Un bloque de catálogo inicial de más de 512 KiB se reenvía sin almacenamiento en caché. Después de la expiración o el desalojo, el siguiente catálogo recibido se convierte en la nueva instantánea. La vista previa del panel de control sigue leyendo los archivos actuales; no muestra la instantánea retenida para una conversación en curso. + + + +## Lo que esta página lee y lo que no + +opencodex lee un archivo de configuración - su `config.toml`. Codex resuelve su configuración desde varias capas, por lo que un valor aquí es lo que dice SU archivo, no necesariamente lo que finalmente calcula Codex. + + + +## Las claves que escribe esta página + +Estos viven en su Codex `config.toml`, no en la configuración propia de opencodex. + +| Clave | Predeterminado | Capa | +|---|---|---| +| `include_permissions_instructions` | `true` | Permisos | +| `include_collaboration_mode_instructions` | `true` | Modo de colaboración | +| `include_environment_context` | `true` | Contexto ambiental | +| `include_apps_instructions` | `true` | Apps | +| `skills.include_instructions` | `true` | Habilidades | +| `developer_instructions` | Sin configurar | Sus capas personalizadas, unidas en orden | +| `model_instructions_file` | Sin configurar | Prompt base, cuando se selecciona una variante | + +Las escrituras son ediciones de línea: sus comentarios y formato sobreviven, y una clave opencodex no reconoce se deja sola en lugar de eliminarse. + +Una clave ausente se lee como su valor predeterminado en lugar de como `false`. El panel muestra el valor que realmente tiene su archivo y dice cuando no se ha establecido una clave. + +Una fila que lleva un valor explícito también ofrece **Restablecimiento a **, que elimina la línea clave en lugar de escribir el valor predeterminado. Ese es el único estado que sigue al valor predeterminado si Codex lo cambia más tarde: escribir `key = true` congelaría el valor predeterminado de hoy como una anulación. + +Este editor escalar rechaza arrays, tablas en línea y cadenas multilínea antes de escribir o restablecer una clave, preservando los bytes originales. Una importación informa explícitamente de una configuración ilegible. Las vistas previas de título de solo lectura mantienen el campo de título editable; la confirmación aún requiere una vista previa vinculada a ese título. HTTP o fallas de medición de red se muestran como fallas en lugar de como otra sonda que está ocupada. diff --git a/docs-site/src/content/docs/es/guides/combos.md b/docs-site/src/content/docs/es/guides/combos.md new file mode 100644 index 00000000000..b22dff1b8a8 --- /dev/null +++ b/docs-site/src/content/docs/es/guides/combos.md @@ -0,0 +1,705 @@ +--- +title: "Combos: conmutación por error y equilibrio de carga" +description: "Enruta un modelo virtual a varios proveedores, con respaldo ante fallos o reparto ponderado de carga." +--- + +Un **combo** es un modelo virtual que representa una lista ordenada de destinos reales de proveedor/modelo. El cliente solicita `combo/`; opencodex elige un destino, reescribe la solicitud con ese `provider/model` concreto y puede probar otro destino si el primero tiene un fallo reintentable. + +Esto es útil cuando usted quiere: + +- **Conmutación por error:** dar prioridad a un modelo y mantener otros como respaldo. +- **Equilibrio de carga:** repartir las solicitudes correctas entre modelos o proveedores en lotes ponderados. + +Los combos se evalúan antes del enrutamiento normal de proveedores. Consulta primero [Enrutamiento de modelos](/es/guides/model-routing/) si aún no conoces los selectores `provider/model`. + + + +## Consentimiento de fallback medido + +Marque un objetivo combinado de pago por uso con `"metered": true` cuando siga los objetivos de suscripción. El consentimiento omitido o falso niega el envío medido. Elija el consentimiento para su implementación: + +- **Local Claude Code o Codex:** en un proxy solo loopback, establezca `"allowMeteredTargets": true` en el combo o ejecute `ocx combo set --allow-metered-targets on`. Esto permite explícitamente a las personas que llaman locales usar sus objetivos marcados. El valor predeterminado es falso; `off` borra el consentimiento. La autenticación de loopback no lee las claves API. +- **Llamadas en red o vinculadas:** la entrada `apiKeys[]` configurada por el llamante debe tener `"allowMeteredComboTargets": true`. Un proxy con un oyente que no es loopback ignora la bandera combinada, incluso en su oyente de loopback secundario. Las personas que llaman vinculadas también retienen su requisito de consentimiento de clave configurada cuando el oyente principal es loopback. El token de entorno nunca califica. + +Los encabezados de solicitud no pueden otorgar consentimiento. Los alcances de modelo/proveedor todavía se aplican. Esto cubre la selección inicial, la conmutación por error y la recuperación a través de estrategias combinadas, compactación, Messages, Chat Completions y WebSocket, y un modelo de subagente alternativo que nombra un alias combinado. Una reserva colapsada intenta un objetivo no medido utilizable antes de rechazarlo. Los objetivos no marcados conservan el comportamiento existente; el operador declara la medición en lugar de detectarla automáticamente. + +Por ejemplo, una cadena de conmutación por error puede probar Anthropic OAuth, después Cursor y finalmente `{ "provider": "anthropic-apikey", "model": "claude-opus-5-5", "metered": true }`. Sin consentimiento, al agotar los destinos se devuelve el último error de un destino sin pago por uso, con una excepción: un rechazo de cuota anterior 429 o 402 tiene prioridad sobre un 400, 401 o 403 posterior. Si el destino de suscripción devuelve 429 y Cursor después rechaza con 401 o 403, el cliente recibe el 429 de la suscripción, porque la cuota agotada explica el fallo y el rechazo de credenciales de Cursor no. Al guardar desde el dashboard se conservan la marca de pago por uso del destino y el consentimiento del combo si se omiten; establecer cualquiera explícitamente en false lo borra. Estos campos de consentimiento se configuran mediante el archivo de configuración o la API. El indicador del combo también está disponible en la CLI; el dashboard no lo expone. + + + +## 60 segundos de inicio rápido + +Este ejemplo crea `combo/main` con Anthropic primero y OpenAI segundo. Ambos proveedores ya deben existir y estar habilitados. + +```bash +ocx combo set main --targets anthropic/claude-opus-4-8,openai/gpt-5.6-sol +``` + +La estrategia predeterminada es la conmutación por error, por lo que una solicitud normal va a `anthropic/claude-opus-4-8`. Si ese intento tiene un fallo reintentable, opencodex puede saltar a `openai/gpt-5.6-sol`. + +Utilice el modelo virtual en cualquier lugar donde normalmente proporcione un ID de modelo: + +```json +{ + "model": "combo/main", + "input": "Explain why the sky looks blue." +} +``` + +Confirme la definición guardada: + +```bash +ocx combo show main +``` + +:::tip +Comience con conmutación por error y pesos iguales. Cambie a round-robin solo cuando desee intencionalmente distribuir tráfico y añadir ponderaciones solo cuando no sea apropiada una distribución igual. +::: + + + +## Cómo funcionan los nombres combinados + +La identificación combinada en `ocx combo set ` debe comenzar con una letra o número. Puede contener letras, números, `.`, `_` o `-`, hasta 64 caracteres en total. Su modelo canónico id es siempre `combo/`; por ejemplo, id `main` se convierte en `combo/main`. + +El espacio de nombres `combo/` está reservado mientras se configuran los combos. Un proveedor llamado `combo` no puede ocuparlo, y un identificador combinado no puede duplicar un nombre de proveedor configurado. + +Un alias opcional le da al combo un nombre de modelo público diferente. Un alias: + +- utiliza los mismos caracteres que un id; +- puede estar desnudo, como `daily-fast`, o contener un `/`, como `team/daily-fast`; +- no puede ser `combo` o empezar con `combo/`; +- no puede duplicar otro alias combinado; y +- Normalmente no puede ser un nombre de familia OpenAI nativo desnudo que comienza con `gpt-`, `o1-`, `o3-`, `o4-` o `codex-`. El modo de compatibilidad de escritorio explícito a continuación es la única excepción. + +Incluso cuando se establece un alias, el formulario canónico `combo/` todavía se resuelve. La búsqueda canónica se ejecuta antes de la coincidencia de alias, por lo que un alias no puede hacerse cargo del id canónico de otro combo. + +:::note +Los alias cambian la solicitud de nombre público de los clientes; no cambian el id almacenado del combo ni el proveedor de concreto/selectores de modelos detrás de él. +::: + + + +## Compactación después de cambiar los combos + +Cuando un cliente compacta usando un nombre de modelo desnudo después de cambiar combos, opencodex puede recordar el combo que se completó con éxito más recientemente en ese carril de conversación. El modelo debe coincidir con la respuesta completada, y el combo y su objetivo aún deben existir en la configuración actual. La solicitud sigue entonces la selección combo normal y la conmutación por error. + +Los selectores explícitos de proveedor/combo y los alias combinados configurados tienen prioridad sobre esta recuperación. Las respuestas fallidas, incompletas o canceladas no reemplazan la última selección exitosa. El retiro es proceso-local y limitado a 256 conversaciones durante 30 minutos, y a 1 KiB por nombre de modelo recordado y 64 KiB en total; las entradas caducadas también se limpian en segundo plano. Una respuesta cuyo nombre de modelo es demasiado grande para retener deja intacta la selección anterior en lugar de borrarla. Recall no almacena credenciales de cuenta. Sin identidad de conversación utilizable o estado válido recordado, se aplica el enrutamiento de compactación normal. Un reinicio despeja el estado recordado. + + + +## Codex Compatibilidad con la lista de permisos nativa del escritorio + +Algunas versiones de escritorio Codex aplican una lista de permisos remota nativa `available_models` después de que el servidor de aplicaciones ya haya cargado `model_catalog_json`. Los identificadores encaminados normales tales como `Nova1/codex-gpt-5.6-sol` son entonces utilizables por el CLI pero ausentes del selector de escritorio. Este es el [Codex Error de escritorio](https://github.com/openai/codex/issues/19694) aguas arriba rastreado por [opencodex #241](https://github.com/lidge-jun/opencodex/issues/241). + +Cuando controlas un destino enrutado equivalente, un combo puede hacerse cargo explícitamente de una identificador nativa: + +```bash +ocx combo set nova-sol \ + --targets Nova1/codex/gpt-5.6-sol \ + --alias gpt-5.6-sol \ + --native-alias \ + --display-name 'Nova1 - codex-gpt-5.6-sol' +``` + +Este modo es deliberadamente opt-in y requiere tanto `--native-alias` como una etiqueta de visualización no vacía. El alias debe ser uno de los identificadores de modelo nativos soportados por esta versión opencodex; no se acepta un prefijo de familia nativa solo porque la eliminación debe ser capaz de restaurar metadatos autorizados. Cuando la respuesta de descubrimiento del destino enrutado suministra solo un id de modelo, la fila de compatibilidad rellena los metadatos de contexto, modalidad y razonamiento faltantes del id nativo que reemplaza. Los límites explícitos de objetivos aún ganan, por lo que esta alternativa nunca plantea un límite de contexto o anula las capacidades declaradas. Cambia la precedencia exacta de enrutamiento: las solicitudes para `gpt-5.6-sol` se resuelven a `combo/nova-sol` antes de la ruta canónica de la familia nativa OpenAI. El catálogo contiene una fila desnuda con la etiqueta de visualización configurada, no filas nativas y combinadas duplicadas. Sólo la identificador `gpt-5.6-sol` desnuda es capturada. Las filas calificadas por cuenta, como `main/gpt-5.6-sol`, y las filas calificadas por proveedor, como `openai-apikey/gpt-5.6-sol`, siguen siendo rutas OpenAI distintas; la ruta API calificada por proveedor nunca llega al alias nativo. + +Las claves de visibilidad permanecen inequívocas: + +- `combo/nova-sol` oculta el combo de compatibilidad del descubrimiento. +- La entrada desnuda `gpt-5.6-sol` en `disabledModels` continúa significando la fila nativa latente OpenAI; no oculta el combo que actualmente posee esa identificador pública. +- Mientras se configura al menos un alias nativo, las filas desnudas nativas deshabilitadas se omiten del catálogo efectivo Codex en lugar de conservarse como `visibility: "hide"`. Esto evita que la lista de permisos de Desktop resucite filas que no debería mostrar. La página Modelos todavía enumera los switches nativos no sombreados, y al volver a habilitar uno se restauran sus metadatos nativos conservados o actuales. + +:::caution +Un alias nativo se hace cargo intencionalmente de un ID de modelo de primera persona. Utilizarlo solo cuando el objetivo es operacionalmente equivalente y etiqueta la fila del selector honestamente. Eliminar el combo restaura la normalidad enrutado nativo e identidad de catálogo en la siguiente sincronización. +::: + + + +## Elige una estrategia + + + +### Conmutación por error: copias de seguridad y primarias ordenadas + +`failover` selecciona el primer objetivo elegible en orden de configuración. Un objetivo es elegible cuando su proveedor existe, está habilitado, no se está enfriando y puede manejar cualquier restricción de solicitud especial. Los pesos y `stickyLimit` no afectan esta estrategia. + +Dada esta orden: + +1. `anthropic/claude-opus-4-8` +2. `openai/gpt-5.6-sol` +3. `google/gemini-3-pro` + +cada solicitud comienza con Anthropic. Un fallo Anthropic reintentable mueve esa solicitud a OpenAI; un fallo OpenAI reintentable puede moverla a Google. Un error de terminal se detiene inmediatamente en lugar de intentar los objetivos restantes. + + + +### Round-robin: lotes ponderados lisos + +`round-robin` utiliza un round-robin suave y ponderado. Un peso objetivo más grande le da a ese objetivo una mayor participación a lo largo del tiempo sin enviar toda su participación como un bloque largo. `stickyLimit` controla cuántas solicitudes exitosas permanecen en el objetivo seleccionado antes de la siguiente selección ponderada. + +Crear un combo 2:1 con lotes de dos solicitudes exitosas: + +```bash +ocx combo set balanced \ + --targets anthropic/claude-opus-4-8:2,openai/gpt-5.6-sol:1 \ + --strategy round-robin \ + --sticky 2 +``` + +Llamando a los objetivos **A** (peso 2) y **B** (peso 1), las primeras seis selecciones ponderadas son `A, B, A, A, B, A`. Debido a que `stickyLimit` es 2, cada selección permanece activa para dos solicitudes exitosas: + +| Solicitud exitosa | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Objetivo | A | A | B | B | A | A | A | A | B | B | A | A | + +La cuota a largo plazo sigue siendo 2:1. Un fallo reintentable finaliza el lote pegajoso actual, enfría ese destino y selecciona otro destino elegible para la misma solicitud. + +:::caution +Los pesos son relativos, no porcentajes. Pesos `2,1` y `200,100` expresa la misma proporción. Prefiero Pequeños valores que comunican la intención. +::: + + + +### Aleatorio: sorteo ponderado por solicitud + +`random` dibuja un objetivo elegible por solicitud, con probabilidades proporcionales a `weight`. Cada solicitud es un empate independiente, por lo que el tráfico se propaga a través de los objetivos sin el patrón determinista o la pegajosidad de round-robin. `stickyLimit` no afecta a esta estrategia. + + + +### Menos utilizado: favorezca al objetivo con menos éxitos + +`least-used` enruta cada solicitud al objetivo elegible con la menor cantidad de solicitudes exitosas registradas por este proceso opencodex. Cuentas comienzan a cero en el reinicio, y los lazos mantienen el orden de configuración. Los pesos y `stickyLimit` no afectan esta estrategia. + + + +### Reset-window: siga el restablecimiento de cuota más rápido + +`reset-window` enruta cada solicitud al destino elegible cuya instantánea de cuota de proveedor en caché muestra el próximo restablecimiento de ventana más rápido (cinco horas, semanal, mensual o personalizado). Esto pasa el proveedor que actualiza primero. Los objetivos sin datos de cuota frescos, y lazos, mantienen el orden de configuración. Los pesos y `stickyLimit` no afectan esta estrategia. + +Esta clasificación y exclusión del proveedor antes del envío requieren nuevos límites de inferencia de modelo que se aplican a la clave API actual en su conjunto. OAuth /los resúmenes de cuentas actuales, las rutas de reenvío de llamadas, las claves múltiples y las instantáneas con credenciales o destinos modificados se muestran solo para esta decisión temprana. Lo mismo se aplica cuando las cabeceras `Authorization`, `x-api-key` o `x-goog-api-key` anulan las credenciales; se excluyen las ventanas de solo búsqueda y MCP. Si ningún objetivo elegible tiene un restablecimiento aplicable, el orden de configuración gana. La selección y los reintentos de la cuenta aún imponen sus límites normales. + + + +### Señales de cuota de asesoramiento para JEV + +La evidencia de cuotas es por separado opt-in **por JEV Combo**, para los tres métodos de decisión: + +```bash +ocx combo set coding --decision-quota-signals on --json +ocx combo set coding --decision-quota-tiers '{"moderate":40}' --json +``` + +Solo habilite esto en un Combo `strategy: "jev"` existente. `decisionQuotaSignals: true` agrega niveles de cuota de suscripción a la solicitud de decisión, no una regla de elegibilidad dura. Se le pide al backend de decisión que prefiera una cuota más saludable entre las opciones adecuadas; todavía elige solo entre los objetivos elegibles configurados y las listas de permisos de esfuerzo. Desconocido no se agota, y las opciones alternativas ordinarias, el tiempo de reutilización, la selección de cuentas y los límites del proveedor permanecen sin cambios. + +Los valores predeterminados son `limited: 70` y `nearlyExhausted: 90`, porcentajes incluidos utilizados. No hay un nivel moderado a menos que lo establezca explícitamente (por ejemplo, `moderate: 40`). Las anulaciones parciales se fusionan con esos valores predeterminados, entonces todos los umbrales deben ser finitos, dentro de 0-100 y estrictamente ascendentes. + +La evidencia solo proviene de instantáneas de memoria publicadas por recopiladores de cuotas existentes, encabezados de respuestas aceptadas y propietarios de credenciales/cuentas, y solo mientras al menos un JEV Combo tiene este interruptor activado: hasta entonces, opencodex no recopila nada para él, por lo que la evidencia comienza a acumularse (y se lee como desconocida) desde el momento en que lo habilita. La lectura de la evidencia de la cuota de asesoramiento nunca resuelve las credenciales, carga los almacenes de autenticación o los archivos de cuota, lee un llavero, sondea aguas arriba o inicia un repaso. La resolución normal de las credenciales de backend de decisión no cambia. Se desconocen las pruebas frías, desaparecidas, rancias (más de 30 minutos), futuras, inválidas o que hayan expirado. Cada cuenta utiliza su peor ventana válida relevante de cinco horas, semanal, mensual o estructuralmente. Un grupo de Anthropic / Codex habilitado usa su nivel de cuenta más saludable; lazos desconocidos saludables. Un grupo está casi agotado solo si cada cuenta utilizable ha conocido evidencia casi agotada. Los modelos de reserva sin barras atribuibles por separado siguen siendo desconocidos. Los resúmenes de cuentas activas, los informes de visualización de múltiples claves, los créditos y los medidores API /Spark / USD no son evidencia de cuotas para esta decisión. La cuenta separada Anthropic + Pool 2 (`anthropic2`) no es una fuente de esta evidencia, por lo que sus objetivos permanecen desconocidos. + +Antigravity aporta las ventanas Gem/Cla de cinco horas y semanales solo después de una consulta autenticada reciente para su única cuenta OAuth activa y utilizable, y únicamente al proveedor `google-antigravity` que inicia sesión con esa cuenta. Si se cambia el nombre del proveedor, su cuota se considera desconocida y no se reutiliza la de esa cuenta. La cuota corresponde al modelo nativo resuelto `gemini-*` o `claude-*`, no a su alias visible. Cambiar la cuenta, la credencial, el proyecto o el destino retira la observación anterior. Una actualización solo de visualización puede conservar los contadores de familia coincidentes, con sus marcas de tiempo originales. Las filas por modelo y las de Argon nunca se convierten en evidencia para la decisión. + +:::caution[Datos adicionales para la decisión] +La opción de envío envía los niveles de cuota, y el porcentaje/ventana/reset de demora usado disponible, a su selección backend de decisión, incluyendo alojado TypeSafe. No hay ID de cuenta, tokens o huellas dactilares de credenciales son enviados o registrados por esta característica. Los registros de decisiones locales retienen solo los recuentos de niveles limitados y el nivel seleccionado. Si la cuota supera el límite de solicitud de 64 KiB, se elimina antes de volver a intentar serialización; una decisión ordinaria de gran tamaño todavía falla abierta. +::: + +`--decision-quota-signals off` deshabilita la evidencia mientras conserva los niveles configurados; `-` despeja el interruptor. `--decision-quota-tiers -` borra anulaciones, restaurando valores predeterminados. API `null` borra; API `false` desactiva el interruptor. Los campos omitidos sobreviven a las actualizaciones de JEV, el reemplazo de objetivos y el cambio de nombre, incluidas las salvaciones a través del editor existente. Al cambiar de JEV se eliminan ambos ajustes de cuota. No se habilitan nuevos controles de editor ni el trabajo de cuota de fondo. + + + +### Fijación de sesión para JEV + +Un combo JEV decide el destino de cada solicitud; los turnos de una conversación pueden cambiar de proveedor y empezar con su caché de instrucciones vacía. `sessionPin` es una opción por combo JEV, **desactivada por defecto**, que mantiene la sesión en el destino elegido mientras siga activa: + +```bash +ocx combo set jev-auto --session-pin 20m --json +``` + +```json +{ "strategy": "jev", "sessionPin": { "ttlMs": 1200000 } } +``` + +La primera solicitud se decide normalmente. Cuando el destino aplicado por JEV completa una respuesta, las solicitudes siguientes de la sesión reutilizan ese destino y esfuerzo sin otra llamada de decisión. `ttlMs`, entre un minuto y 24 horas, es un plazo de inactividad: cada turno completado en el destino fijado, incluidas las continuaciones de herramientas, lo reinicia. Si la sesión permanece inactiva más tiempo, se decide de nuevo. + +La identidad combina el encabezado de sesión del cliente (`thread-id`, `session_id` o `session-id`, `x-codex-parent-thread-id`, o un `x-session-id` promovido), la clave API que admitió la solicitud y el combo. No se fijan solicitudes sin encabezado de sesión, `prompt_cache_key` nunca sirve como identidad de sesión y dos claves API nunca comparten una fijación. + +JEV decide de nuevo y sustituye la fijación cuando: + +- El destino no se ofrece para esa solicitud porque está desactivado, se retiró del combo, está en enfriamiento tras un 429 u otro fallo, agotó su cuota en caché, es de pago medido o resulta inelegible por otro motivo. +- El esfuerzo fijado ya no se ofrece para ese destino. +- `decisionQuotaSignals` está activo y la evidencia de cuota indica que el destino está casi agotado. +- Falla cualquier envío de la sesión fijada; esa solicitud conserva la recuperación habitual mediante otros destinos. +- La configuración cambió después de guardar la fijación. + +Cancelar una solicitud conserva la fijación. Una decisión que usa la alternativa fail-open por tiempo agotado, clave ausente o respuesta inválida no crea una. Las fijaciones viven en memoria, con un máximo de 512 sesiones, y se pierden al reiniciar. + +Los registros de uso marcan los turnos reutilizados con `jevDecision.pinned: true` y `pinReason: "session"`. Una decisión que sustituye una fijación liberada registra el motivo en `pinReason`: `expired`, `config_changed`, `target_unavailable`, `effort_unavailable` o `quota_nearly_exhausted`. `ocx combo stats` cuenta las solicitudes fijadas aparte de las decisiones; siguen contando para solicitudes correctas, cambios de modelo por fallo y tokens por modelo. + +La fijación permite reutilizar la caché, pero el acierto real depende del proveedor, la cuenta y un prefijo de instrucciones estable. `--session-pin -`, o `null` en la API, la desactiva. Cambiar a otra estrategia la elimina; guardar desde el editor del dashboard la conserva. + + + +### Método de decisión + +`strategy: "jev"` solicita una decisión de fondo para elegir el primer objetivo elegible y un esfuerzo de razonamiento compatible para la solicitud actual. Es opt-in: crea un JEV Combo y selecciona ese Combo para usarlo. Agregar una credencial de decisión no cambia los modelos, alias o valores predeterminados existentes. + +| Método | Selección combinada | Backend reportado en estadísticas | +| --- | --- | --- | +| TypeSafe (predeterminado) | Omita ambos selectores, o configure `decisionProvider: "jev"`. | `typesafe` | +| Servidor compatible con System One | Establecer `decisionProvider` en un identificador de fila configurado `jev-decision` distinto de `jev`. | `systemone` | +| Modelo opencodex | Establecer `decisionModel` a una ruta ordinaria opencodex, como `ollama/qwen3:4b`. | `model` | + +`decisionProvider` y `decisionModel` son mutuamente excluyentes. El backend se deriva de esos campos; no hay ninguna configuración `backend` almacenada. Cada método utiliza el mismo objetivo elegible y la lista de permisos de esfuerzo, el estado de decisión limitado, el tiempo de espera, la cancelación y la política de apertura por error. + + + +#### TypeSafe por defecto + +La configuración más rápida es: + +1. Abra **Proveedores**, agregue **TypeSafe JEV**, ingrese la clave TypeSafe API y pruebe la conexión. +2. En la vista general de ese proveedor, elija **Crear JEV Auto**. También puede usar la misma acción en **Modelos → Combos**. +3. Revise los objetivos Astra → Sol → Luna precargados. Agregue, elimine, reordene o reemplace antes de crear el Combo. La primera fila actualmente elegible está marcada como el objetivo de apertura a prueba de fallos, y cada escalera de razonamiento conocida se muestra al lado de su fila. + +La plantilla crea id y alias `jev-auto`, utiliza la capacidad de razonamiento adaptativo, y sigue siendo un combo editable ordinario. No se convierte en el modelo por defecto. Sus objetivos son la lista de permisos completa: JEV nunca puede seleccionar un par proveedor/modelo fuera de esa lista, y los modelos de destino originales permanecen disponibles en sus grupos de selectores normales. + +Para la configuración sin cabeza, almacene la clave explícitamente o haga referencia a la variable de entorno TypeSafe: + +```bash +ocx provider add jev --api-key "${TYPESAFE_API_KEY}" +``` + +Cuando el proveedor no tiene ninguna clave guardada, el cliente de decisión también acepta `TYPESAFE_API_KEY` directamente y el alias estándar derivado del proveedor `JEV_API_KEY` impreso por `ocx provider add`. + +```json +{ + "providers": { + "jev": { + "adapter": "jev-decision", + "baseUrl": "https://api.typesafe.ai/v1/systemone", + "authMode": "key", + "apiKey": "${TYPESAFE_API_KEY}", + "liveModels": false + } + }, + "combos": { + "jev-auto": { + "alias": "jev-auto", + "strategy": "jev", + "reasoningEffortMode": "adaptive", + "targets": [ + { "provider": "openai", "model": "gpt-6-astra" }, + { "provider": "openai", "model": "gpt-5.6-sol" }, + { "provider": "openai", "model": "gpt-5.6-luna" } + ] + } + } +} +``` + +Con el método predeterminado, OpenCodex envía una solicitud de decisión limitada al punto final fijo `https://api.typesafe.ai/v1/systemone` con el modelo `jev-latest`. Solo se ofrecen objetivos configurados elegibles actualmente. JEV elige el objetivo y el esfuerzo juntos; el esfuerzo todavía está limitado por la escalera anunciada de ese objetivo. No se pregunta de nuevo al JEV si el objetivo seleccionado tiene un fallo reintentable: el tiempo de reutilización y el bucle de recuperación de Combo existentes continúan a través de los objetivos configurados restantes. + + + +#### Servidor compatible con System One + +Un JEV Combo puede solicitar un servidor alojado o autoalojado que implemente el contrato de cable de System One. Por ejemplo, un servidor Ollama con soporte System One puede servir `tev1` a `POST /v1/systemone` sin una clave API. Agregue una fila de proveedor con `adapter: "jev-decision"` cuyo `baseUrl` es el punto final de decisión **lleno**, luego nómbrelo en `decisionProvider` del Combo: + +```json +{ + "providers": { + "ollama-tev1": { + "adapter": "jev-decision", + "baseUrl": "http://127.0.0.1:11434/v1/systemone", + "allowPrivateNetwork": true, + "defaultModel": "tev1:4b", + "liveModels": false + } + }, + "combos": { + "jev-local": { + "strategy": "jev", + "decisionProvider": "ollama-tev1", + "decisionTimeoutMs": 60000, + "reasoningEffortMode": "adaptive", + "targets": [ + { "provider": "openai", "model": "gpt-6-astra" }, + { "provider": "openai", "model": "gpt-5.6-sol" }, + { "provider": "openai", "model": "gpt-5.6-luna" } + ] + } + } +} +``` + +- El `baseUrl` de la fila debe ser la URL completa del servicio de decisión. HTTPS permite cualquier ruta, como `/v1/decisions`; HTTP sin cifrar sigue exigiendo el sufijo `/systemone`. No se aceptan credenciales de usuario en la URL, parámetros de consulta ni fragmentos. El modelo de decisión es `defaultModel` o, en su ausencia, la primera entrada de `models`. Si no hay ninguno, la fila no es utilizable y se aplica la alternativa fail-open sin enviar una solicitud (`jev-latest` es el modelo de TypeSafe y nunca se envía a un host autoalojado). La fila solo presta el servicio de decisión: nunca se publica como modelo enrutable ni puede ser un destino del combo. +- Un punto final de loopback o LAN necesita `allowPrivateNetwork: true` explícito en esa fila. Para `http:` sin cifrar, usa una dirección literal de loopback, RFC 1918 o IPv6 ULA; todas las direcciones resueltas deben pertenecer al conjunto permitido y no debe aplicarse ningún proxy saliente (añadel host a `NO_PROXY`). Los demás destinos deben usar HTTPS. Una redirección activa la alternativa fail-open al primer destino elegible. +- Solo se envía el propio `apiKey` de la fila, y solo cuando está establecido; una fila sin llave no envía la cabecera `Authorization`. Una fila cuyas referencias `apiKey` `${TYPESAFE_API_KEY}` / `${JEV_API_KEY}` u otra entrada de llavero del proveedor se rechazan como inutilizables, por lo que `TYPESAFE_API_KEY`, `JEV_API_KEY` y la clave de la fila `jev` nunca se envían a un punto final autoalojado. El identificador `jev` en sí (explícito u omitido) siempre significa el punto final TypeSafe con el modelo `jev-latest`. +- Los servicios autoalojados reciben cada opción de destino/esfuerzo como una cadena de descripción simple (por ejemplo, `Target openai/gpt-5.6-sol (provider openai, model gpt-5.6-sol) with low reasoning + effort.`), porque Ollama solo acepta descripciones de cadena o de opciones `null`. TypeSafe sigue recibiendo los objetos de opción estructurados. +- OpenCodex ofrece 2-26 opciones para una fila compatible con System One. Cada destino aporta una opción por nivel de esfuerzo de razonamiento ofrecido; usa `reasoningEfforts` en cada destino para limitar esas opciones. Si hay menos de 2 o más de 26 opciones, se aplica la alternativa fail-open al primer destino elegible sin enviar una solicitud de decisión. +- Cargar un modelo en frío puede tardar decenas de segundos, y cancelar una solicitud de decisión hace que Ollama abandone la carga. Precarga el modelo, mantenlo residente (`OLLAMA_KEEP_ALIVE=-1` o `keep_alive`) y aumenta `decisionTimeoutMs` (1000-120000 ms, por defecto 4000) si el servicio tarda más de cuatro segundos. Cualquier error o tiempo de espera agotado sigue activando la alternativa al primer destino elegible. + +El **Conexión de prueba** del proveedor envía una decisión de sondeo limitada a su punto final. **Crear JEV Auto** en un proveedor de System One (incluidas las filas sin llave) rellena previamente esa fila como proveedor de decisiones. Las filas deshabilitadas, las URL de decisión no válidas y las filas sin modelo se muestran con una razón y no se pueden seleccionar. + +Para un servicio alojado alternativo con el mismo contrato de solicitud/respuesta de decisión, agregue una fila de proveedores separada y selecciónela con el `decisionProvider` del Combo: + +```json +{ + "providers": { + "alternative-decider": { + "adapter": "jev-decision", + "baseUrl": "https://decisions.example/v1/decisions", + "apiKey": "${ALTERNATIVE_DECISION_KEY}", + "defaultModel": "decision-model-v1", + "liveModels": false + } + } +} +``` + +Establecer `decisionProvider: "alternative-decider"` en el JEV Combo existente. Su propia credencial y modelo acompañan el estado de decisión limitado; Las credenciales de entorno TypeSafe nunca se heredan. El id `jev` sigue siendo canónico. HTTPS / TLS, restricciones de destino de salida, rechazo de redirección, límites de solicitud / respuesta, tiempo de espera, cancelación y la lista de permisos de elección elegible aún se aplican. + +[Laya MLX](https://github.com/mizorewww/laya-mlx) ejecuta decisiones escritas en Apple Silicon. Para usarlo con este método, expóngalo a través de un envoltorio compatible con System One HTTP, luego configure una fila como `ollama-tev1` anterior con el URL completo de `/systemone` del envoltorio y el identificador de modelo aceptado como `defaultModel`. El entorno de ejecución de Python MLX solo no es un punto final de decisión HTTP. Para una envoltura loopback HTTP, mantenga `allowPrivateNetwork: true` y utilice su dirección loopback literal. + +Para un ejemplo alojado, un colaborador informó que el siguiente punto final de Zen System One funcionaba en [#6185](https://github.com/lidge-jun/opencodex/pull/6185). Configure manualmente como una fila ordinaria; esto no es un preajuste del registro OpenCodex o una garantía de disponibilidad actual: + +```json +{ + "providers": { + "zen-decision": { + "adapter": "jev-decision", + "baseUrl": "https://opencode.ai/zen/v1/systemone", + "defaultModel": "jev-1.13-free", + "apiKey": "${ZEN_DECISION_API_KEY}", + "liveModels": false + } + }, + "combos": { + "jev-zen": { + "strategy": "jev", + "decisionProvider": "zen-decision", + "targets": [ + { "provider": "openai", "model": "gpt-6-astra" }, + { "provider": "openai", "model": "gpt-5.6-luna" } + ] + } + } +} +``` + +Utilice la propia clave de ese punto final si se requiere autenticación; omita `apiKey` solo si el punto final acepta llamadas sin clave. Nunca reutilice `TYPESAFE_API_KEY` o `JEV_API_KEY` para ello. + + + +#### Modelo opencodex + +Un chat ordinario o modelo Responses puede hacer la misma elección de enrutamiento sin implementar `/systemone`. Configure su proveedor de inferencias como de costumbre y configure `decisionModel` en su ruta: + +```json +{ + "combos": { + "jev-chat": { + "strategy": "jev", + "decisionModel": "ollama/qwen3:4b", + "decisionTimeoutMs": 60000, + "targets": [ + { "provider": "openai", "model": "gpt-6-astra" }, + { "provider": "openai", "model": "gpt-5.6-luna" } + ] + } + } +} +``` + +Otros ejemplos son `deepseek/deepseek-v4-flash`, `openai/gpt-5.6-luna` o `opencode-zen/` para un modelo de inferencia Zen configurado. Estas son cadenas de ruta ordinarias, no preajustes de servicio de decisión; el proveedor y el modelo deben estar disponibles en la instalación. Para `openai/gpt-5.6-luna`, configure las credenciales que puede usar la llamada interna, como un inicio de sesión de grupo Codex almacenado. Un inicio de sesión hacia adelante ChatGPT propiedad de la persona que llama es insuficiente. + +El modelo recibe instrucciones fijas del router y un mensaje JSON: + +```json +{ + "state": { "user_task": "Review the requested change" }, + "options": { "": "Target description and allowed reasoning effort" } +} +``` + +`state` contiene la evidencia limitada que se describe a continuación; `options` asocia las claves generadas de las opciones con descripciones simples. La respuesta debe cumplir `{"choice":""}` y nombrar exactamente una opción ofrecida. Las instrucciones tratan el estado como evidencia, prefieren un menor uso de recursos entre las opciones adecuadas y exigen únicamente JSON. Una opción no válida o no ofrecida, una respuesta malformada o una llamada fallida activa la alternativa fail-open al primer destino elegible. + +El turno interno de decisión **no recibe credenciales del cliente**, encabezados de la llamada, herramientas, historial de sesión ni conversación. Debe usar las credenciales almacenadas del proveedor seleccionado o un proveedor local que realmente no necesite clave, como Ollama. Las configuraciones que dependen exclusivamente de la autenticación del cliente, como Cursor sin una credencial almacenada o un inicio de sesión de ChatGPT reenviado por el cliente, no pueden actuar como modelos de decisión: se usa la alternativa fail-open al primer destino elegible. Seleccionar una ruta no demuestra que su credencial funcione; pruébala antes de depender de ella. + +Un Combo no-JEV puede ser usado como `decisionModel`, pero la ruta de decisión no puede nombrar este Combo o cualquier Combo con `strategy: "jev"`. Esto se aplica a los selectores y alias canónicos `combo/`, incluidos los selectores con variantes de esfuerzo o Fast. La validación de tiempo de ahorro rechaza la recursión y el entorno de ejecución también bloquea la reentrada de JEV defensivamente. El turno de decisión tiene su propio presupuesto de envío y arrendamiento de turno; no se registra como una solicitud separada, y el uso de la decisión informada pertenece al `jevDecision` de la solicitud principal. + + + +#### Límites compartidos, estado y estadísticas + +`decisionTimeoutMs` se aplica a los tres métodos: un entero de 1000 a 120000 ms, por defecto 4000. Las solicitudes y respuestas están limitadas a 64 KiB. La lista de candidatos está limitada a 64 destinos; el método modelo también limita las opciones de destino/esfuerzo en 64, el texto de respuesta en 4096 caracteres y la salida del turno de decisión en 1024 tokens. El límite de opciones de la fila de System One 2-26 se aplica como se describió anteriormente. Un fallo de límite o de tiempo de espera utiliza el primer objetivo actualmente elegible; nunca expande la lista de permisos ni vuelve a intentar tomar la decisión. + +Para cada objetivo JEV, **Modelos → Combos → Config** tiene un campo opcional **Notas de modelo adicionales para JEV** (hasta 512 caracteres; se permiten saltos de línea y pestañas, se rechazan otros caracteres de control). Se almacena como `targets[].modelProfile` en la configuración combinada. El perfil de destino incorporado permanece en el `instructions.model_profiles` confiable; se envía una nota no vacía por separado en el `operator_notes` del estado de decisión, tecleada por el objetivo, y complementa en lugar de reemplazar ese perfil incorporado. Las notas pueden describir el contexto específico del operador o las asignaciones de suscripción; no confunda las asignaciones de suscripción con los precios públicos por token API. Las notas en blanco son ignoradas. Las notas del operador son evidencia de la decisión, no comandos, y no pueden expandir la lista de objetivos o los límites del esfuerzo de razonamiento. Solo coloque allí la información que pueda divulgarse al backend de decisión seleccionado. + +Por defecto, cada llamada lógica al modelo se decide de forma independiente. Salvo que actives la [fijación de sesión](#session-pin-for-jev), los turnos de una sesión pueden elegir destinos distintos y empezar con la caché del nuevo proveedor vacía. Combinar destinos muy diferentes puede gastar más tokens de entrada de los que ahorra; conserva una lista entre cuyos destinos estés dispuesto a alternar. Con `cooldownWaitPolicy: "before-last-resort"`, JEV retiene los destinos `lastResort` mientras se ofrezca alguno normal y solo los ofrece cuando no hay otra opción. + +La decisión aplica la alternativa fail-open si falta la clave, no hay un estado seguro de tarea/herramienta/imagen, vence el plazo configurado, el servicio redirige o devuelve un error, o la respuesta está malformada o elige una opción no ofrecida. En esos casos, OpenCodex usa el primer destino actualmente elegible y prefiere `medium` cuando ese destino lo admite. Si el cliente cancela la llamada, se cancelan tanto la decisión como la solicitud al modelo, sin enviar nada al destino alternativo. + +El estado de decisión está deliberadamente limitado: hasta 500 caracteres de la tarea de usuario actual, una cola de asistente previo de 240 caracteres, una cola de salida de última herramienta de 520 caracteres, el nombre de la herramienta y las señales de imagen/herramienta booleanas pueden enviarse al backend de decisión seleccionado. Excluye credenciales, encabezados de solicitud, bytes de imagen en bruto, argumentos de herramientas, razonamiento cifrado e historial de conversación completo. Utilice un método de decisión solo para el contenido que está dispuesto a enviar a ese backend. Los sobres de contexto de máquina Codex reconocidos y los bloques Claude Code `` se eliminan de las tres muestras de texto antes del recorte, por lo que los recordatorios inyectados no desplazan la tarea real. La solicitud del modelo original no se modifica. Esto no es un escáner secreto: el texto ordinario del asistente y de la salida de la herramienta aún puede contener contenido sensible. TypeSafe afirma que Jev no está capacitado en las solicitudes de los clientes, pero sus términos no establecen un período de retención fijo para el estado presentado y ofrecen cero retención de datos solo en los planes empresariales ([modelos](https://docs.typesafe.ai/models), [legal](https://docs.typesafe.ai/legal) ). TypeSafe también documenta el inglés como el idioma más preciso de Jev, así que revise las decisiones sobre el trabajo que no sea inglés antes de confiar en ellos. Los registros contienen solo el objetivo/esfuerzo seleccionado, una puerta de decisión aproximada, latencia, confianza/probabilidad opcional y uso numérico. Las pruebas automatizadas utilizan respuestas TypeSafe simuladas más un humo sin llave abierta; una decisión TypeSafe en vivo requiere una clave suministrada por el operador y no se ejecuta implícitamente. + +El esfuerzo seleccionado de JEV se aplica al primer niño Responses y a los niños nativos de Chat en la ruta de inscripción `protocols.rollout.nativeChatCombos`. Reemplaza el esfuerzo del llamante y elimina los controles de pensamiento conflictivos y el llamante `service_tier`; una opción explícita sin esfuerzo elimina el esfuerzo incluso cuando el Combo tiene un valor predeterminado forzado. Los pines de esfuerzo del proveedor, las tapas y la normalización del cable aún se aplican después. Los registros de solicitud e intento muestran un esfuerzo aplicado diferente como `high->xhigh` o `high->low`, reteniendo ajustes posteriores como `high->xhigh->medium`. Un esfuerzo sin cambios o una elección sin esfuerzo mantiene la etiqueta existente. Más tarde, los objetivos alternativos utilizan la política Combo ordinaria de la solicitud original, sin otra llamada JEV. + +Después de que el Combo haya servido las solicitudes, abra **Modelos → Combos → jev-auto → Estadísticas** para inspeccionar las selecciones de JEV sin reemplazar el selector de modelo normal o la página de uso. La pestaña separa los tokens de decisión informados en el backend de los tokens informados por los envíos de modelos físicos, y muestra las puertas de decisión, las selecciones abiertas, los esfuerzos de razonamiento, los reintentos / retrocesos, los tokens de caché, la latencia, la confianza y los totales por modelo durante 7 días, 30 días o todo el historial disponible. Las estadísticas provienen del libro de contabilidad de uso de solo anexar local; contienen los metadatos de decisión limitados descritos anteriormente, no las solicitudes o credenciales. Las filas de backend muestran el recuento de decisiones, el recuento aplicado y la latencia promedio para `typesafe`, `systemone` y `model`; los registros más antiguos sin backend se agrupan como `unknown`. + + + +## Qué pasa cuando un objetivo falla + +Los fallos combinados se dividen en **hop** fallos y **terminal** fallos. + +Para que un combo devuelva un error claro `fallback_refused` en lugar de pasar a otro modelo o proveedor, consulta [Desactivar el fallback](/es/guides/fallback-off/). + +| Resultado | Comportamiento | +| --- | --- | +| HTTP 401, 403, 404, 408, 429 o cualquier 5xx | Enfría el objetivo y salta al siguiente objetivo elegible. | +| HTTP 410 con un modelo explícito al final de su vida útil, retirado, obsoleto, puesta del sol, desmantelado o señal no disponible más tiempo | Enfriar ese objetivo y saltar. Las respuestas 410 no relacionadas siguen siendo terminales. | +| Autenticación clasificada, suscripción, cuota, límite de velocidad, sobrecarga o error del servidor ascendente | Enfríe el objetivo y salte, incluso cuando el estado por sí solo no sea suficiente. | +| Cancelación de clientes (499), `origin_rejected`, rechazo de ciberpolítica, desbordamiento de contexto u otra solicitud inválida | Detener y devolver el error; otro objetivo no haría que la solicitud fuera válida. | +| Exacta HTTP 400 diciendo que un modelo no es compatible cuando se utiliza Codex con una cuenta ChatGPT | Pruebe el siguiente objetivo declarado antes del compromiso de producción. El mensaje debe ser el rechazo completo en `detail`, `error.message`, o texto desnudo; competidor `detail` y `error` sobres estancia terminal. Esto no pone en cuarentena la cuenta ni enfría todos los modelos del proveedor. | +| Estructurado HTTP 400 rechazando `user` opcional, un esfuerzo de razonamiento no soportado, entrada de imagen con modelo o medios de entrada que la ruta no puede leer (`unsupported_input_modality`) | Salta antes del compromiso de salida sin enfriamiento; vea la compatibilidad de destino local de solicitud a continuación. | +| Primera llamada de herramienta de un giro Responses ejecutada por un adaptador en proceso ( `runTurn` ) que la solicitud actual no declaró, antes de cualquier efecto secundario de salida o reproducción insegura | Enfriar el objetivo y saltar con el mismo catálogo de herramientas. Después de una salida visible o un efecto secundario de repetición insegura, el rechazo es final. Chat Completions y Anthropic Messages solicitudes no han cambiado. | +| Cualquier otro error no clasificado | Detener y devolver el error. | + +Si el presupuesto de envío de solicitud compartida rechaza el primer objetivo, el combo devuelve un 429 `request_send_budget_exhausted` local sin ponerse en contacto con un proveedor. Si rechaza un objetivo posterior, el combo devuelve el último error ascendente real sin enviarlo a ese objetivo. + +Cuando `cooldownMs` está sin definir, un objetivo saltado utiliza un fallback ascendente: 5 segundos para la tasa de solicitud 429s con código ascendente `1302` o `1305`, 10 minutos para una ventana de uso de la cuenta gastada, y 60 segundos de lo contrario. Una ventana de uso es reconocida por el código ascendente (`usage_limit_exceeded`, +`usage_limit_reached`, `1308`o por la prosa `usage limit reached`, independientemente del estado HTTP — el backend ChatGPT Codex informa de una ventana gastada como 502 en lugar del 429 documentado. Credenciales y fallas de facturación que ya bloquean a todo el proveedor (`invalid_api_key`, `insufficient_quota`, +`payment_required`, y los otros códigos de alcance del proveedor) toman la misma espera de 10 minutos. Cuando se establece, `cooldownMs` +se aplica siempre que no se pueda utilizar de origen `Retry-After` o Codex señal de restablecimiento existe, incluidos los 429s. Numérico `Retry-After` segundos y se aceptan valores de fecha HTTP. Explícito Los retrasos en el servidor se limitan a 24 horas; los tiempos de reutilización derivados, configurados y de reserva se limitan 10 minutos. La precedencia es, de más fuerte a más débil, explícita. +`Retry-After` → Codex reseteo de cabeceras (`x-codex-primary-reset-at`, `x-codex-secondary-reset-at`, o +`x-codex-tertiary-reset-at`) → el combo de `cooldownMs` (cuando se establece) → el 10 minutos de espera para una ventana de uso gastado o un fallo de credencial / facturación → el retroceso de tasa de solicitud de 5 segundos para upstream códigos de límite de velocidad `1302`/`1305` → el valor predeterminado de 60 segundos. Primero se comprueba si se agotó la ventana de uso. Por eso, un fallo que incluya un código de límite de solicitudes *y* un mensaje de límite de uso activa una espera de diez minutos en lugar de cinco segundos. Una validez inmediata +`Retry-After: 0` sigue siendo una directiva ascendente inmediata en lugar de ser reemplazada por una Enfriamiento. + +Para un grupo OAuth o Codex Anthropic, un 429 vinculado a una cuenta que el grupo se ha enfriado no enfría todo el objetivo combinado. Otras cuentas detrás de ese objetivo siguen disponibles. Un 429 sin una cuenta de grupo refrigerada identificada aún enfría el objetivo, al igual que los fallos de todo el proveedor. + + + +### Objetivos de último recurso + +Un breve tiempo de reutilización de un objetivo preferido se dirige directamente a lo que viene después en la lista, incluido un objetivo que solo quería usar en una emergencia. Márcalo y dile al combo que espere primero: + +```json +{ + "strategy": "failover", + "cooldownWaitPolicy": "before-last-resort", + "waitForCooldownMs": 10000, + "targets": [ + { "provider": "provider-a", "model": "model-a" }, + { "provider": "provider-b", "model": "model-b" }, + { "provider": "provider-c", "model": "model-c", "lastResort": true } + ] +} +``` + +Con el conjunto de políticas, la selección prueba primero los objetivos normales. Si solo se están enfriando y el enfriamiento más temprano expira dentro de `waitForCooldownMs`, la solicitud espera eso en lugar de enviar el objetivo de último recurso. Ese aplazamiento no depende de la espera: un objetivo `lastResort` se salta siempre que cualquier objetivo normal esté disponible, para cada estrategia, y bajo `round-robin` o `random` no se une a la rotación en absoluto. `waitForCooldownMs` solo agrega la espera para un objetivo normal de enfriamiento, por lo que en el `0` predeterminado nada espera: el último recurso se usa tan pronto como no hay un objetivo normal disponible. Después de un intento fallido, la siguiente selección sigue la misma regla. + +**La política sólo se aplaza.** Cuando no se puede alcanzar un objetivo normal - todos se enfrían más allá del presupuesto, ya se han intentado o se han descartado - el objetivo del último recurso se envía como de costumbre. Una política que podría retenerlo convertiría una repliegue en una interrupción, que es peor que el enrutamiento prematuro que previene. Lo mismo se aplica a un combo cuyos objetivos son *todos* marcado `lastResort`: se despacha normalmente. + +`lastResort` es inerte a menos que se establezca `cooldownWaitPolicy`, y ambos se omiten por defecto, por lo que los combos existentes no se ven afectados. Solo la cadena exacta `before-last-resort` se admite. + +La solicitud actual nunca vuelve a intentar el mismo objetivo, con una excepción: una combinación de un solo objetivo que establece `waitForCooldownMs` puede volver a intentar su único objetivo una vez que el tiempo de reutilización de ese objetivo expire dentro de la misma solicitud, ya que no hay alternativa para fallar. Los rechazos de compatibilidad local de solicitud aún regresan sin ningún reintento. Las solicitudes posteriores omiten un objetivo enfriado hasta que expire el tiempo de reutilización; los rechazos de compatibilidad local de la solicitud no enfrían el objetivo. Un `Retry-After` HTTP -fecha que ya está en el pasado también se conserva como una directiva inmediata aguas arriba, al igual que `Retry-After: 0`. Establezca `waitForCooldownMs` para permitir que una solicitud posterior espere el tiempo de reutilización del objetivo elegible más temprano, hasta ese límite en cada intento de selección, y luego haga una selección nueva. Por lo tanto, una solicitud puede esperar hasta `hops × waitForCooldownMs` a través de múltiples saltos de conmutación por error. El valor predeterminado es `0`, que falla al cerrarse inmediatamente con HTTP 503 cuando cada objetivo elegible se está enfriando; ese `combo_unavailable` 503 lleva un encabezado `Retry-After` igual al primer tiempo de reutilización restante, redondeado a segundos enteros con un mínimo de 1. Las esperas no son nerviosas, por lo que es posible realizar despertares sincronizados. Una solicitud abortada cancela esta espera y devuelve la respuesta normal `client_cancelled`; no envía un objetivo de copia de seguridad después de la cancelación. Un tiempo de reutilización de destino combinado es el estado por combo de proceso local y está separado del tiempo de reutilización de cuota de nivel de cuenta Codex utilizado por el enrutamiento de cuenta nativo. + +:::note +La conmutación por error es intencionadamente limitada. Ayuda con la disponibilidad específica del objetivo, autenticación, cuota, y sobrecarga de fallos; no oculta errores de llamada o rechazos de políticas. En una solicitud Responses no combo, se reescribe una directiva xAI 403 permitida en HTTP 200. +`incomplete/content_filter` antes de que Codex lo vuelva a intentar como un fallo de transporte; véase +[Rechazos de política xAI](/es/reference/proxy-formats/#xai-policy-refusals). Combo hops todavía clasificar el HTTP 403 original como un salto. +::: + +Para las solicitudes de transmisión, el estado ascendente HTTP no es la decisión final. OpenCodex almacena un prefijo de presalida limitado del Responses SSE del hijo seleccionado. Si el flujo informa de un terminal `response.failed` reintentable antes de cualquier texto, razonamiento, llamada de herramienta u otro evento de salida, el hijo se registra como fallido y el combo puede intentar su próximo objetivo elegible. Una salida cero `response.incomplete` sigue la misma ruta cuando su razón falta o es `adapter_eof`, `missing_terminal_event` o `upstream_stall_timeout`. Las razones semánticas explícitas como `max_output_tokens` y `content_filter` siguen siendo terminales, al igual que una razón explícita nula. También se mantiene una instantánea final sin razón que ya contiene elementos de salida. Una vez que comienza cualquier evento de salida, el destino se confirma: se devuelve un fallo de flujo posterior al cliente y nunca se reproduce en otro proveedor, lo que evita la ejecución duplicada de texto y herramientas. Si la memoria intermedia de pre-salida alcanza su límite de seguridad sin un terminal o límite de salida, OpenCodex también confirma el objetivo actual en lugar de aumentar la memoria sin un límite. + + + +## Compatibilidad con objetivos locales de solicitud + +Al enrutar Claude Code al backend canónico ChatGPT Codex, OpenCodex elimina el campo de metadatos de nivel superior no compatible `user` sin cambiar la clave de sesión/caché, los mensajes de entrada, los esquemas de herramientas o los identificadores de seguridad. Las pasarelas públicas Responses API y las pasarelas directas no canónicas mantienen ese campo. + +Un combo también puede avanzar después de un HTTP 400 `invalid_request_error` intacto que rechaza específicamente `user`, informa `unsupported_value` para `reasoning.effort` / `reasoning_effort`, o informa `param: input` con un rechazo `does not support image inputs` con alcance de modelo exacto. Una ruta que rechaza los medios de comunicación de la solicitud con el código `unsupported_input_modality`, como la entrada de imágenes enviada a una ruta del proveedor CLI sin un contrato multimodal verificado, avanza de la misma manera. Este es un desajuste para esa solicitud, no evidencia de que el objetivo no sea saludable, por lo que no registra ningún enfriamiento. Esta recuperación de compatibilidad no cambia silenciosamente `none` en un esfuerzo diferente ni amplía esta excepción a solicitudes arbitrarias no válidas. Las denegaciones de políticas, la cancelación y la producción ya comprometida siguen siendo no reproducibles. Una solicitud de un solo objetivo todavía devuelve un rechazo ascendente no resuelto. + + + +## Las llamadas de herramientas permanecen en un objetivo + +Cuando un modelo le pide a su cliente que ejecute una herramienta, la solicitud que devuelve el resultado de la herramienta finaliza el mismo turno de asistente. OpenCodex envía esa solicitud al objetivo que emitió la llamada a la herramienta, siempre que el objetivo aún esté habilitado, aún en el combo y fuera del tiempo de reutilización. Esto se aplica a todas las estrategias, incluido JEV, que omite su decisión para esa solicitud. El siguiente mensaje de usuario elige un destino normalmente. + +El seguimiento utiliza el hilo o el identificador de sesión del cliente, por lo que un cliente que no envía ninguno recibe una selección normal. Si el objetivo original no está disponible o falla, el combo falla como de costumbre, y el nuevo objetivo recibe las llamadas a la herramienta anterior de la forma que acepta. DeepSeek modelos de pensamiento obtienen un marcador de posición de razonamiento de un espacio para una llamada de herramienta que otro modelo emitió sin razonamiento. Gemini obtiene el marcador de posición de firma documentado de Google. Anthropic recibe una simple llamada de herramienta y resultado. Las versiones anteriores podían enviar DeepSeek una llamada de herramienta desnuda aquí y fallar con `The reasoning_text in the +thinking mode must be passed back to the API`. + + + +## Esfuerzo de razonamiento por defecto + +`defaultEffort` suministra un esfuerzo configurado cuando el objetivo seleccionado tiene una escalera soportada no vacía conocida. Con el valor predeterminado `defaultEffortMode: "fallback"`, un esfuerzo explícito de la persona que llama mantiene la precedencia. `defaultEffortMode: "force"` anula un esfuerzo de llamada válido con el valor predeterminado configurado; requiere un `defaultEffort` válido, no nulo y puede aumentar el costo y la latencia. El modo de fuerza es una elección explícita del operador a través de la configuración o administración combinada. + +La escalera anunciada del objetivo sigue siendo autorizada. Se conserva un valor soportado exacto; de lo contrario, se selecciona el peldaño soportado más alto en o por debajo de él, o el peldaño soportado más bajo cuando ninguno es inferior. Las escaleras desconocidas o vacías nunca causan la inyección predeterminada. El modo de fuerza no repara el esfuerzo del llamador mal formado en una solicitud costosa válida. Otros campos de razonamiento, incluyendo `reasoning.summary`, se conservan. + +`reasoningEffortMode` sigue siendo independiente de `defaultEffortMode`: las escaleras vacías explícitas eliminan los controles de esfuerzo / pensamiento no compatibles, y las escaleras adaptativas desconocidas también lo hacen, como se describe a continuación. Estrictas escaleras desconocidas preservan la petición de la persona que llama sin forzar un valor predeterminado. Los valores predeterminados admitidos son `low`, `medium`, `high`, `xhigh`, `max` y `ultra`; omita `defaultEffort` o configúrelo en `null` para deshabilitar la inyección predeterminada en modo de retroceso. + + + +### Grupos de capacidades mixtas (`reasoningEffortMode`) + +En modo estricto, los niveles de esfuerzo publicados por un combo son la intersección de los niveles de sus destinos. Si un destino indica explícitamente que **no** admite control de esfuerzo, su conjunto vacío participa en la intersección y la deja vacía para todo el combo, aunque los demás destinos permitan ajustar el esfuerzo. + +Configure `reasoningEffortMode: "adaptive"` para excluir esos conjuntos vacíos de la intersección publicada. El selector muestra los niveles comunes de los destinos restantes; el destino sin control de esfuerzo sigue siendo elegible para el enrutamiento. Los destinos cuyos niveles son simplemente *desconocidos* se tratan como comodines en ambos modos. + +```json +{ + "combos": { + "mixed": { + "targets": [ + { "provider": "openai-apikey", "model": "gpt-5.6-luna" }, + { "provider": "local", "model": "no-effort-model" } + ], + "reasoningEffortMode": "adaptive" + } + } +} +``` + +El valor predeterminado es `"strict"`, que mantiene el comportamiento original del selector. Esta configuración no cambia el orden de destino ni la política de conmutación por error. En el momento del despacho, una escalera de destino explícitamente vacía tiene sus controles de esfuerzo / pensamiento no soportados eliminados en cualquier modo mientras se conservan los campos de razonamiento sin esfuerzo soportados, como `reasoning.summary`; `"adaptive"` aplica la misma normalización a una capacidad de destino desconocida, mientras que los objetivos no vacíos conocidos mantienen su resolución de esfuerzo por objetivo existente. En el tablero de instrumentos se encuentra el interruptor **Escala de razonamiento adaptativo** en la sección Capacidades de un combo. + + + +## Capacidad de imagen / multimodal + +De forma predeterminada, un combo publica el **intersección** de las modalidades de entrada de sus objetivos (la imagen solo está habilitada cuando cada objetivo la anuncia). Establecer `imageInput: "disabled"` para forzar solo texto incluso cuando cada destino admite imágenes: el catálogo cae `image` desde `inputModalities`, y las solicitudes que llevan imágenes se rechazan con HTTP 400 antes de que se llame a cualquier destino. `"auto"` (u omitir el campo) mantiene la intersección automática. + +En el panel de control, el interruptor **Imagen / multimodal** se puede habilitar siempre que cada objetivo tenga capacidades conocidas de entrada de imagen o texto. Los miembros de la imagen nativa permanecen sin cambios; los miembros de solo texto se declaran automáticamente solo texto en guardar (`modelCapabilities[model].inputModalities = ["text"]`), por lo que el [Visión Sidecar](/es/guides/sidecars/) describe sus imágenes. La sugerencia del switch nombra a los miembros que se inscribirán. Un miembro cuyas modalidades son desconocidas o no tienen entrada de texto (por ejemplo, un modelo de solo audio) no puede ser cubierto por el sidecar; mantiene el interruptor no disponible y se nombra en la sugerencia. Si el [Visión Sidecar](/es/guides/sidecars/) está deshabilitado globalmente, habilitar el interruptor muestra una advertencia que enlaza con el tablero: la inscripción aún se guarda, pero las imágenes se reemplazan con una nota de omisión y las solicitudes continúan sin descripciones de imágenes hasta que se vuelve a habilitar el sidecar. Desactivar el interruptor desactiva la entrada de imagen para el combo pero mantiene esas declaraciones del proveedor, y `PUT /api/combos` acepta la misma inscripción como una matriz opcional `visionSidecarTargets` de nivel superior de objetivos `{ provider, model }` exactos (solamente solicitud; nunca se almacena en el combo y se rechaza mientras `imageInput` es `"disabled"` cuando la lista de inscripción no está vacía). Las entradas que ya aceptan la entrada de imagen o se declaran sin texto se rechazan con HTTP 400 en lugar de sobrescribirlas, las entradas que el sidecar ya cubre se omiten y se rechaza un guardado antes de que la publicación restaure el combo y cada declaración juntos. Eliminar un miembro del combo no elimina su declaración de solo texto; límpialo en el editor del proveedor si ya no lo deseas. + + + +## Tareas de subagentes encriptadas v2 + +Hay una limitación importante para los subagentes Codex v2 ([incidencia #92](https://github.com/lidge-jun/opencodex/issues/92)). Un padre nativo puede enviar la tarea de un trabajador recién generado solo como texto cifrado acuñado para el backend nativo ChatGPT. Un proveedor externo no puede leer esa carga útil. + +Para tal solicitud, un combo filtra sus objetivos elegibles a rutas canónicas nativas ChatGPT, incluso después de un fallo reintentable. Si el combo no tiene un objetivo con capacidad de descifrado, opencodex se detiene antes del envío y devuelve HTTP 400: + +```json +{ + "error": { + "type": "invalid_request_error", + "code": "unreadable_encrypted_agent_task" + } +} +``` + +Esto protege la tarea de ser enviada a un proveedor que no recibiría instrucciones legibles. Las tareas de texto plano legibles utilizan la estrategia combo normal. + +Tienes cuatro opciones de recuperación: + +1. Seleccione un modelo nativo ChatGPT para el niño. +2. Agregue un objetivo canónico nativo ChatGPT al combo. +3. Utilice la superficie v1 para la delegación a través de diferentes proveedores. +4. Si controla al llamante, vuelva a enviar la tarea como contenido de texto sin formato v2 `agent_message`. + +Consulte [Superficie del subagente](/es/guides/sub-agent-surface/) para ver los modos v1/base/v2 y el flujo de trabajo de tareas cifrado completo. + + + +## Administrar combos + + + +### Panel + +Abra el panel de control local y elija **Modelos → Combos**. El espacio de trabajo crea, edita, renombra y elimina combos. Sus selectores de modelos incluyen modelos ocultos: la visibilidad del catálogo solo controla las listas de modelos externos, no la selección Combo interna, y seleccionar un modelo oculto no lo hace visible externamente. El selector de destino aún excluye los proveedores deshabilitados, los combos anidados y el proveedor JEV solo para credenciales. **Crear JEV Auto** abre el mismo editor Combo con una plantilla de destino de decisión editable; en lugar de crear un duplicado se informa de un id o alias `jev-auto` existente. Un JEV Combo también muestra **Servicio de decisión** (TypeSafe JEV o un proveedor configurado `jev-decision`) y **Tiempo de espera de decisión (ms)**, y la vista general de Combos enumera cada servicio de decisión, punto final y tiempo de espera de JEV Combo. + +Cada objetivo también muestra una insignia de cuota en vivo: **Disponible**, **Fuera de cuota** o **Cuota desconocida**. El editor bloquea Guardar y Crear para la cuota solo cuando cada destino utilizable tiene un límite de inferencia agotado confirmado por el servidor actual para su credencial configurada. La cuenta, el modelo, la búsqueda y la cuota MCP de solo visualización, o la evidencia de enrutamiento faltante o caducada, no causan este bloque. El bloqueo expira en el límite de reinicio o frescura aplicable y se vuelve a verificar cuando la página se vuelve activa o visible; Actualizar recarga tanto los datos combinados como la cuota. El editor del panel de control aún no expone `cooldownMs` o `waitForCooldownMs`; use el archivo de configuración o la administración API hasta que la interfaz de usuario de seguimiento termine. + +### CLI + +Los comandos principales son: + +```bash +ocx combo list +ocx combo show +ocx combo set --targets provider/model[:weight],... +ocx combo remove --yes +``` + +`set` también acepta `--strategy`, `--sticky`, `--effort`, `--alias`, `--native-alias`, `--allow-metered-targets on|off`, `--display-name`, `--description`, `--decision-provider`, `--decision-timeout` y `--rename-from`. Utilice `-` como el valor de `--effort`, `--alias`, `--display-name`, `--description`, `--decision-provider`, o `--decision-timeout` para borrar ese campo. Las dos opciones de decisión solo se aplican cuando la estrategia efectiva es JEV: al indicar `--strategy jev` o al omitir `--strategy` en un combo JEV existente. En un combo existente, `--targets` solo sustituye la lista de destinos; sin `--strategy`, conserva la estrategia guardada y sus ajustes JEV. `--native-alias` requiere un alias de modelo nativo desnudo actualmente soportado y un nombre de visualización no vacío. `create` y `update` son alias para `set`; `delete` es un alias para `remove`; y los mismos subcomandos están disponibles bajo `ocx route combo`. + + + +### API de administración + +Los clientes sin cabeza usan `GET`, `PUT` y `DELETE` en `/api/combos`. `GET` enumera definiciones combinadas normalizadas, `PUT` crea o reemplaza una (y puede cambiar el nombre de una), y `DELETE` toma el parámetro de consulta id. Los detalles de autenticación y solicitud / respuesta se encuentran en el [Gestión API referencia](/es/reference/management-api/). Cuando un cuerpo `PUT` omite `cooldownMs` o `waitForCooldownMs`, el API conserva el valor ya almacenado para ese combo; envíe un valor explícito para cambiarlo. Un `cooldownMs` explícito (incluso `60000`) se persiste tal cual porque anula el retroceso de la tasa de solicitud. Un `cooldownMs` almacenado solo puede eliminarse editando el archivo de configuración; `waitForCooldownMs` se restablece a su valor predeterminado cuando un `PUT` envía explícitamente `0`, porque el serializador escaso omite ese valor predeterminado. Omission conserva ambos valores y el panel de control no los expone todavía. Omitir `defaultEffortMode`, `reasoningEffortMode`, `imageInput` o `cooldownWaitPolicy` también mantiene el valor almacenado. Para una solicitud que mantiene `strategy: "jev"`, el método de decisión se mantiene solo cuando se omiten tanto `decisionProvider` como `decisionModel`: el envío de cualquiera de los dos reemplaza el método almacenado, por lo que `decisionModel: null` sin `decisionProvider` selecciona TypeSafe. `decisionTimeoutMs` se mantiene por su cuenta cada vez que se omite. Una estrategia diferente deja caer los tres, y un objetivo reenviado sin `lastResort` mantiene la bandera de ese objetivo (igualada por proveedor y modelo). El tablero de instrumentos siempre envía `imageInput` y `reasoningEffortMode`, y para un JEV Combo `decisionProvider`, `decisionModel` y `decisionTimeoutMs` (`null` por defecto), por lo que al cambiarlos de nuevo al valor predeterminado, todavía reemplaza el valor almacenado. + +Para la configuración completa persistente, véase [Configuración](/es/reference/configuration/). + + + +## Referencia de configuración + +Los combos se almacenan en el objeto `combos` de nivel superior, con la clave de identificación combinada: + +```json +{ + "combos": { + "balanced": { + "targets": [ + { "provider": "anthropic", "model": "claude-opus-4-8", "weight": 2 }, + { "provider": "openai", "model": "gpt-5.6-sol", "weight": 1 } + ], + "strategy": "round-robin", + "stickyLimit": 2, + "defaultEffort": "high", + "alias": "team/balanced" + } + } +} +``` + +| Campo | Requerido | Predeterminado | Normas | +| --- | --- | --- | --- | +| `targets` | Sí | — | Matriz ordenada no vacía de objetivos `{ provider, model, weight?, lastResort? }` configurados. Se rechazan los pares duplicados proveedor/modelo. | +| `targets[].weight` | No | `1` | Entero de 1 a 10.000. Utilizado por round-robin y aleatorio; ignorado por failover, menos utilizado, reset-window y JEV. | +| `targets[].lastResort` | No | `false` | Marca un objetivo solo de emergencia. Inert a menos que `cooldownWaitPolicy` esté establecido. Nunca hace que un objetivo sea permanentemente inelegible: cuando no se puede alcanzar un objetivo normal, se envía como de costumbre. | +| `strategy` | No | `"failover"` | `"failover"`, `"round-robin"`, `"random"`, `"least-used"`, `"reset-window"` o `"jev"`. JEV decide solo el objetivo inicial elegible y el esfuerzo; Combo ordinario posee intentos posteriores. | +| `stickyLimit` | No | `1` | Número entero de 1 a 100 solicitudes exitosas por selección de round-robin. Solo se aplica a round-robin. | +| `cooldownMs` | No | unset → upstream fallback (5 s para la tasa de solicitud 429 códigos `1302` / `1305`, 10 min para una ventana de uso gastado o un fallo de credencial / facturación, de lo contrario 60 s) | Entero de 1 a 600000. Cuando se establece, se aplica como el tiempo de reutilización por objetivo siempre que no exista una señal de reinicio de flujo ascendente `Retry-After` o Codex utilizable, incluida la tasa de solicitud 429s; cuando no se establece, utiliza el retroceso de flujo ascendente. | +| `waitForCooldownMs` | No | `0` | Entero de 0 a 600000. Tiempo máximo para esperar el objetivo de enfriamiento elegible más temprano antes de regresar `combo_unavailable`; el aborto cancela la espera. | +| `cooldownWaitPolicy` | No | Sin configurar | `"before-last-resort"` aplaza los objetivos marcados como `lastResort`: solo se usan cuando no hay un objetivo normal disponible, para cada estrategia, y `waitForCooldownMs` solo agrega la espera para un objetivo normal de enfriamiento, por lo que en su `0` predeterminado no hay nada que esperar y el último recurso se usa tan pronto como no hay un objetivo normal disponible. Solo esa cadena exacta se selecciona. La espera diferida y la espera ordinaria comparten un presupuesto de `waitForCooldownMs` por intento de selección. | +| `defaultEffort` | No | `null` | `low`, `medium`, `high`, `xhigh`, `max` o `ultra`; resuelto contra la escalera anunciada de cada objetivo. | +| `defaultEffortMode` | No | `"fallback"` | `"fallback"` preserva el esfuerzo explícito de la persona que llama. `"force"` anula el esfuerzo del llamante válido, requiere un valor predeterminado no nulo válido y puede aumentar el costo y la latencia. | +| `reasoningEffortMode` | No | `"strict"` | `"strict"` intersecta los niveles de esfuerzo anunciados por todos los destinos conocidos: si uno no anuncia ningún control de esfuerzo, el selector del combo queda vacío. `"adaptive"` excluye esas listas vacías de la intersección publicada. Al enviar la solicitud, una lista explícitamente vacía, o desconocida en modo adaptativo, elimina los controles de esfuerzo/pensamiento no admitidos y conserva los campos de razonamiento independientes del esfuerzo que sí se admiten, como `reasoning.summary`. Los destinos con niveles conocidos y no vacíos mantienen la resolución de esfuerzo existente. | +| `imageInput` | No | `"auto"` | `"auto"` o `"disabled"`. `"auto"` publica soporte de imagen solo cuando cada objetivo soporta imágenes; `"disabled"` fuerza el texto solamente (cae la imagen de las modalidades publicadas y rechaza las solicitudes portadoras de imágenes antes del envío). | +| `alias` | No | Ninguno | ID de modelo público recortado opcional; use las reglas de alias anteriores. Un valor vacío se almacena como ningún alias. | +| `nativeAlias` | No | `false` | Permitir explícitamente que un `alias` nativo desnudo actualmente soportado tenga prioridad de enrutamiento y catálogo. Nunca se infiere del alias. | +| `displayName` | No | Ninguno | Etiqueta de catálogo limitada. Requerido y no vacío cuando `nativeAlias` es verdadero. | +| `description` | No | Ninguno | Descripción de la fila del catálogo solo para mostrar, limitada como `displayName` (como máximo 128 caracteres, sin caracteres de control). Sin configurar, conserva el texto generado `Routed via opencodex → combo (combo).`. Las escrituras de la API de administración que omiten este campo conservan el valor guardado; una cadena vacía lo borra. | +| `decisionProvider` | No | `"jev"` | Sólo JEV. Id de proveedor del servicio de decisión: `"jev"` (TypeSafe, válido sin una fila de proveedor; lo mismo que omisión) o una fila `adapter: "jev-decision"` configurada con una URL de decisión HTTPS completa o una URL local HTTP `/systemone`, tal como una Ollama `tev1` autohospedada. | +| `decisionTimeoutMs` | No | `4000` | Solo JEV. Entero de 1000 a 120000: plazo de la decisión antes de usar la alternativa fail-open al primer destino elegible. | + + + +## Solución de problemas + + + +### ¿Por qué `combo/` ¿Error 404? + +La identificación combinada es desconocida. La respuesta es HTTP 404 con el tipo `invalid_request_error`. Ejecute `ocx combo list`, compruebe la ortografía y el caso, y confirme que el comando de administración se escribió en la misma instancia opencodex en ejecución que recibe las solicitudes del modelo. + + + +### ¿Por qué tengo `combo_unavailable`? + +Todos los objetivos no son elegibles actualmente: por ejemplo, su proveedor está deshabilitado, se está enfriando, ya se ha intentado para esta solicitud o una tarea cifrada v2 lo excluye. Compruebe el estado del proveedor de destino y los errores recientes de flujo ascendente. Cuando no se intentó ningún objetivo, el mensaje de error enumera por qué se omitió cada objetivo, por ejemplo, `No available targets for combo: fast (openai/gpt-6: quota exhausted; anthropic/claude-opus-5-5: cooldown 42s)`. Para tiempos de reutilización, siga primero un valor de `Retry-After` observado; Las cabeceras de reinicio Codex también tienen prioridad sobre `cooldownMs`. Si no se puede usar ninguna señal ascendente, se aplica la configuración `cooldownMs`, o se aplica la reserva ascendente cuando no está configurada (5 segundos para los códigos de tasa de solicitud `1302` / `1305`, 10 minutos para una ventana de uso gastada o un fallo de credencial/factura, de lo contrario 60 segundos). `Retry-After` retrasos explícitos tienen un límite de 24 horas; los otros tiempos de reutilización tienen un límite de 10 minutos. + + + +### ¿Por qué fue rechazado mi alias? + +Compruebe primero la gramática del alias y los nombres reservados. Un alias duplicado o forma no válida se rechaza como HTTP 400. Un alias recortado cuyo primer segmento es un espacio de nombres de cuenta Codex configurado se rechaza como HTTP 409; elija un espacio de nombres de alias diferente. El CLI y el panel de control muestran el mensaje de validación exacto del servidor. + + + +### ¿Por qué se detuvo la conmutación por error después del primer error? + +El error fue terminal en lugar de específico del objetivo. Corrige entradas no válidas, reduce un contexto de gran tamaño, maneja un rechazo de directiva o corrige el origen de la solicitud rechazada. Los combos no saltan para esos casos. diff --git a/docs-site/src/content/docs/es/guides/composer-usage-gate-fallback.md b/docs-site/src/content/docs/es/guides/composer-usage-gate-fallback.md new file mode 100644 index 00000000000..f2daa60a89d --- /dev/null +++ b/docs-site/src/content/docs/es/guides/composer-usage-gate-fallback.md @@ -0,0 +1,135 @@ +--- +title: "Alternativa ante límites de uso de Composer" +description: "Envía texto bajo demanda a la cola de un hilo existente de Codex sin cambiar la autenticación ni el enrutamiento de OpenCodex Desktop; las cuotas del servidor siguen aplicándose." +--- + +Un bloqueo por uso del **cuadro de mensajes (Composer)** de Desktop puede impedir nuevas entradas aunque la ruta de OpenCodex configurada para el hilo todavía tenga capacidad. En una instalación compatible, `codex queue` usa la cola nativa del app-server de Codex sin pasar por ese cuadro. No parchea la aplicación, intercepta TLS, instala certificados ni cambia la autenticación. + +Esto **no es una solución para cada estado de límite de uso**. No restablece la cuota agotada ni desbloquea el selector de modelos. Un hilo que ya usa `gpt-reserve` mantiene ese modelo; el texto en cola no lo cambia a otro proveedor. La autorización del lado del servidor, las cuotas de proveedores, las aprobaciones y la configuración de ejecución del subproceso aún se aplican. + + + +## Identificar la capa bloqueada + +Un compositor deshabilitado antes del envío es diferente de un rechazo real del proveedor después del envío. Una etiqueta de modelo personalizada no demuestra ser un proveedor independiente ni la capacidad disponible. Utilice este recurso solo para un subproceso seleccionado deliberadamente con una ruta que de otro modo se podría usar; compruebe las aprobaciones pendientes, los giros activos y la conectividad aplicación-servidor por separado. + +El bloqueo de la cuenta principal sigue siendo autorizado. Es un guardia de admisión previo al agotamiento, no una forma de restaurar una cuenta ya agotada. Este ayudante no deshabilita esa protección ni cambia el proveedor que usa un subproceso. No cambie las respuestas de cuota ni desactive la guardia para ejecutar una solicitud de cuenta nativa en cola. + + + +## Integración y propiedad de OpenCodex + +Mantener la configuración existente [Codex integración](/es/guides/codex-integration) y [modelo de enrutamiento](/es/guides/model-routing). El camino es: + +```text +helper -> native Codex queue -> the selected thread's app-server + -> the thread's configured provider -> OpenCodex, when already routed there +``` + +Los ayudantes no implementan otro router de proveedor. Envían solo el destino y el texto, no el modelo, la cuenta, el nivel de servicio, la aprobación, el sandbox o las anulaciones de la URL base. Un proveedor `openai` incorporado enrutado a OpenCodex y un proveedor personalizado `opencodex` mantienen su configuración existente. Pool / Direct selección, cuentas vinculantes, credenciales de proveedor y verificaciones de admisión siguen siendo propiedad de OpenCodex y el demonio de servicio. La aceptación de colas por sí sola no prueba que se haya llamado a un proveedor. + +Utilice el **mismo `CODEX_HOME` y compatible CLI /app-server** como la instalación de escritorio. `CODEX_HOME` por defecto es `~/.codex`; otra casa puede descubrir otro daemon y almacenamiento de hilos. `OPENCODEX_HOME` es el hogar del proxy, no un sustituto de `CODEX_HOME`. Los ayudantes dejan ambas variables y los archivos de configuración de ambas aplicaciones sin cambios. En PowerShell, los hijos nativos heredan la ubicación del sistema de archivos del shell, incluso cuando `CODEX_HOME` es relativo. + +El proxy ya debe estar ejecutándose y el subproceso de destino ya debe usar la ruta prevista. El ayudante no inicia/sincroniza/reconfigura OpenCodex, vuelve a habilitar una integración deshabilitada o reemplaza silenciosamente una ruta OpenAI directa. No se requiere alternar `codexDesktopAuthless`. Una URL de proveedor remota OpenCodex no es lo mismo que un servidor de aplicaciones remoto Codex: estos ayudantes utilizan el descubrimiento de demonios locales, no el enrutamiento automático a una conversación en otro equipo. + +Estos son **Ayudantes de repositorio bajo demanda**, no un comando `ocx queue` instalado o un control de tablero. La lista de permisos de archivos del paquete npm no incluye `scripts/`; use una comprobación de repositorio coincidente o el comando nativo `codex queue`. Este recurso restringido evita agregar un segundo monitor de transporte, escucha persistente, caché de estado de cuenta o límite de uso a OpenCodex. + + + +## Activación/desactivación y comportamiento normal + +Hay **sin interruptor de activación/desactivación persistente**: la ejecución del ayudante es la opción de una presentación. Simplemente instalar/actualizar OpenCodex o mantener los scripts en disco no los ejecuta. + +| Situación | Lo que hace este fallback | +| --- | --- | +| No invocado, tanto si hay contingente disponible como si se ha agotado | Nada: ningún proceso, temporizador, sondeo, oyente de fondo o solicitud originada por el ayudante. | +| Invocado normalmente mientras el uso está disponible | Hace colas para un mensaje ordinario. No se salta solo porque el compositor de escritorio está trabajando. El uso/facturación normal del proveedor se puede aplicar cuando se envía. | +| Invocado mientras solo el compositor está bloqueado | Intenta el mismo envío de cola nativa. La ruta configurada debe estar autorizada y disponible. | +| El proveedor real no tiene capacidad ni autorización | No pasa por alto esa restricción ni cambia de proveedor/cuenta; la ejecución en sentido ascendente aún puede fallar después de la aceptación de la cola. | +| `-DryRun` / `--dry-run` | Selecciona un destino y comprueba la ayuda del CLI, pero nunca envía texto ni comprueba la cuota de la cuenta, el estado del demonio o la disponibilidad del proveedor. | +| El bloqueo por uso se levanta más tarde | Vuelve a usar el cuadro de mensajes normal. No hay ajustes específicos de los scripts auxiliares que debas revertir. | + +Para dejar de usar la reserva, deja de invocarla. Ejecute **no** `ocx restore` o deshabilite la integración Codex solo para desactivar este ayudante; eso también cambia el enrutamiento OpenCodex normal. Si ha programado el comando de forma independiente, desactive esa programación externa. Los elementos de cola ya aceptados pertenecen a Codex y aún pueden ejecutarse: eliminar el script, salir de su proceso o recuperar la cuota no los cancela. Inspeccione/elimine elementos no deseados a través de los controles de cola normales en la misma conversación. No envíe el mismo mensaje tanto en el ayudante como en el compositor. + + + +## Compruebe la compatibilidad antes de enviar + +Prefiera el CLI empaquetado en la aplicación; un `codex` instalado por separado en PATH puede ser más antiguo. Compruebe `codex queue --help` para `--thread` y `--message`. Los ayudantes prueban esta capacidad CLI, pero solo una solicitud real puede verificar el soporte `thread/queue/add` del demonio. Si Codex informa un método de cola no compatible, guarde el trabajo en curso antes de actualizar/reiniciar la instalación correspondiente. Los ayudantes nunca reinician un demonio o reintentan con otro servidor. No agregue `--no-daemon` a un comando de cola. Las actualizaciones de la aplicación CLI pueden cambiar la compatibilidad. + +Primero abra la conversación prevista y confirme su proyecto, modelo y proveedor. Prefiera su **UUID explícito**; el nativo CLI también acepta un nombre de sesión exacto: + +```powershell +codex queue --thread 'my-project-review' --message 'continue with the next step' +``` + +Desde una comprobación del repositorio, el ayudante Windows puede descubrir el paquete nativo `codex.exe`: + +```powershell +.\scripts\codex-queue.ps1 -Thread 'my-project-review' -Message 'continue with the next step' +``` + +En macOS / Linux, utilice Bash (incluyendo macOS 's Bash 3.2): + +```bash +bash scripts/codex-queue.sh --thread 'my-project-review' --message 'continue with the next step' +``` + +Fijar un binario de confianza coincidente con `-CodexExe 'C:\path\to\codex.exe'`, `--codex '/path/to/codex'` o `CODEX_EXE`. Una selección explícita no válida falla en lugar de seleccionar silenciosamente otro ejecutable. En Windows use un `.exe` nativo, no un npm `.cmd` o una shim PowerShell, para mantener el mensaje citando `cmd.exe`. Los paquetes de aplicaciones compatibles con colas y los diseños independientes se prueban antes de PATH. El descubrimiento automático de PATH ignora entradas vacías y relativas en lugar de sondear un CLI del proyecto actual implícitamente. Un binario local de confianza todavía se puede seleccionar explícitamente con `--codex './codex'` o `-CodexExe '.\codex.exe'`. Las raíces de instalación configuradas y las entradas absolutas de PATH aún deben ser confiables para el operador; este ayudante no verifica las firmas binarias. Discovery no prueba una versión de la aplicación que coincida. + + + +### Diagnósticos privados y descubrimiento opcional de última generación + +Una ejecución seca oculta rutas ejecutables, UUID de subprocesos/nombres y el cuerpo del mensaje de forma predeterminada: + +```powershell +.\scripts\codex-queue.ps1 -Thread 'my-project-review' -DryRun +``` + +Informa de la capacidad CLI y la selección de destino solamente, no la validación exitosa del lado del servidor. Para las tiendas basadas en despliegue heredado, `-Latest` / `--latest` opta explícitamente por un **última heurística de archivo**. Para ver esa selección, utilice un terminal privado no redireccionado: + +```powershell +.\scripts\codex-queue.ps1 -Latest -DryRun -ShowTarget +``` + +```bash +bash scripts/codex-queue.sh --latest --dry-run --show-target +``` + +`-ShowTarget` / `--show-target` requiere una ejecución en seco y una salida de terminal local. Revela la ruta seleccionada y UUID/nombre solo por esta solicitud explícita, escapa a los caracteres de control y rechaza la salida redirigida, como la captura de CI. No lo use en terminales grabados/compartidos ni publique la salida públicamente. Nunca imprime el mensaje. La salida nativa ordinaria Codex durante una presentación real se pasa a través y puede contener identificadores; revíselo antes de compartir registros. + +El último descubrimiento busca `CODEX_HOME/sessions` por tiempo de modificación, con el orden del nombre del archivo como desempate. Es **No es la conversación de escritorio actual** y puede seleccionar otro proyecto o un subagente. Verifique la vista previa local y, a continuación, envíe con el UUID explícito elegido. Latest también puede enviar cuando se proporciona un mensaje, pero sigue siendo una suscripción deliberada a esta heurística. + +Los nombres de archivo `rollout-*.jsonl` reconocidos contienen un UUID de subproceso, a veces seguido de `_`; el ayudante usa el primer UUID. Los nombres mal formados se omiten. Las tiendas que faltan o son ilegibles fallan sin seleccionarlas de otra casa. Los almacenes solo migrados/paginados y las conversaciones solo remotas pueden no tener un despliegue local coincidente; use un UUID/nombre explícito. + +Mantenga todo el mensaje en un solo argumento. Bash acepta `--message '- start with this'` o `-- '- start with this'`; PowerShell acepta `-Message '- start with this'`. El historial de shell y los listados de procesos locales pueden exponer el texto de la línea de comandos, así que no incluya credenciales en las solicitudes. + + + +## En cola no significa ejecutado + +`Queued message ... for thread ...` confirma la **aceptación en la cola**, no la ejecución del modelo ni su finalización. Un hilo ocupado puede estar esperando a que termine su turno actual o se resuelva una aprobación. Según la implementación, un hilo guardado que no está cargado puede conservar el mensaje hasta que otro cliente lo reanude. + +Comprueba la cola y la actividad en la **misma conversación**. Si el hilo no está cargado, ábrelo en la aplicación o usa `codex resume ` sin volver a añadir el mensaje. Revisa las aprobaciones pendientes y el estado de la cola. Cada invocación puede crear otro elemento; si el fallo es ambiguo, inspecciona el estado antes de reintentar. Los scripts auxiliares conservan el código de salida de la CLI y nunca reenvían automáticamente. + +El CLI nativo tiene `--remote` opciones explícitas (véase `codex queue --help`), a diferencia de asumir que la conexión de control remoto del escritorio se reutiliza. Mantener la configuración de autenticación sin cambios no repara errores de autenticación/red no relacionados ni garantiza la continuidad del control remoto. + + + +## Iniciar o reanudar el trabajo sin el compositor + +`codex exec ''` inicia una tarea no interactiva, **no** un mensaje en el subproceso de escritorio abierto. Compruebe su directorio de trabajo, proveedor, permisos y configuración. `codex resume ` reanuda una sesión explícita. `codex resume --last` normalmente se filtra por directorio de trabajo actual; `--all` deshabilita ese filtro, mientras que otros filtros de elegibilidad aún pueden aplicarse. Una selección global no es necesariamente la sesión del sistema de archivos visible o más reciente. Prefiere una identificación explícita para el trabajo de escritorio en curso. + + + +## Alcance y verificación + +Esta alternativa deja solos los derechos de la cuenta y los archivos de la aplicación. No es una reparación consciente del proveedor del compositor / selector de modelos, una función automática de recuperación de cuotas o la limpieza de los cambios de proxy / certificado no relacionados de experimentos anteriores. + +La sonda original Windows (escritorio `26.917.9434.0`) reportó aceptación de cola para un hilo en vivo y un error esperado para un hilo inexistente. Eso no es una inferencia general de extremo a extremo, hilo descargado, control remoto o garantía multiplataforma. La fuente aguas arriba se comprobó en `7dae8c53d97e61cd774e4d6bcca5243c29ca615c`: + +- [Opciones de cola CLI](https://github.com/openai/codex/blob/7dae8c53d97e61cd774e4d6bcca5243c29ca615c/codex-rs/cli/src/queue_cmd.rs) y [presentación de app-server](https://github.com/openai/codex/blob/7dae8c53d97e61cd774e4d6bcca5243c29ca615c/codex-rs/tui/src/session_queue_commands.rs). +- [Envío de cola de hilo cargado](https://github.com/openai/codex/blob/7dae8c53d97e61cd774e4d6bcca5243c29ca615c/codex-rs/ext/queue/src/service.rs) y [Opciones de selección de reanudación](https://github.com/openai/codex/blob/7dae8c53d97e61cd774e4d6bcca5243c29ca615c/codex-rs/cli/src/main.rs). + +Ejecute regresiones de envoltura sin conexión con `node --test scripts/codex-queue.test.mjs` (Node 20+). Utilizan CLIs nativos falsos y hogares temporales, nunca cuentas reales o solicitudes de modelos. El flujo de trabajo **Codex ayudantes de cola** ejecuta estas pruebas en Windows PowerShell 5.1 y PowerShell 7, macOS Bash y Linux Bash; falla un shell requerido faltante en lugar de omitirlo silenciosamente. Los accesorios de configuración-preservación cubren la configuración del proveedor incorporado/personalizado y ambos valores del estado de uso, no el enrutamiento OpenCodex en vivo. Valide el despacho de escritorio real, el éxito del proveedor y la continuidad del control remoto por separado en las instalaciones compatibles. diff --git a/docs-site/src/content/docs/es/guides/cursor-private-inference.md b/docs-site/src/content/docs/es/guides/cursor-private-inference.md new file mode 100644 index 00000000000..d39d6d79b37 --- /dev/null +++ b/docs-site/src/content/docs/es/guides/cursor-private-inference.md @@ -0,0 +1,140 @@ +--- +title: "Inferencia privada de Cursor" +description: "Utilice los modelos con enrutamiento opencodex dentro de la compilación de agente local de Cursor, en macOS, Windows o Linux, sin un túnel público." +--- + +El Cursor regular no puede hablar con un proxy en su propia máquina. Cuando establece "Override OpenAI URL base", el backend de Cursor crea el mensaje y llama a esa URL desde los servidores de Cursor, que rechazan el loopback, la LAN y las direcciones privadas. Es por eso que cada receta de la comunidad para Cursor + modelos locales termina con ngrok, Cloudflare Tunnel o un VPS. + +Cursor también envía una segunda compilación de escritorio, **Cursor Inferencia privada**, cuyo bucle de agente se ejecuta localmente y llama a una puerta de enlace compatible con OpenAI que configura. Señalado en opencodex, utiliza sus modelos enrutados sin túnel, sin parches de aplicaciones y sin TLS. Esta página cubre esa construcción. + + + +## Antes de empezar + +Lea esta sección primero; es la parte que la gente extraña. + +- **opencodex no distribuye esta compilación.** Cursor tampoco lo documenta. No está vinculado desde cursor.com, puede cambiar sin previo aviso y puede dejar de estar disponible. Si aún no lo tiene, esta guía no se aplica; use el puente de la comunidad [`ocx-cursor`](https://www.npmjs.com/package/ocx-cursor) con un punto final público HTTPS en su lugar. +- **El inicio de sesión Cursor todavía es necesario.** El muro de inicio de sesión viene antes del diálogo de puerta de enlace. +- **Los modelos propios de Cursor no están disponibles.** En el modo local, el selector solo muestra lo que devuelve la puerta de enlace. Finalización de la pestaña, catálogo de Cursor (Compositor, Auto) y Cloud Agents están apagados. Todavía puede llegar a los modelos Cursor -proveedor a través de las rutas opencodex propias de `cursor/*` si ha configurado ese proveedor. +- **Cada vuelta lleva Cursor 's sistema local**, aproximadamente 23k tokens en el segundo y posteriores turnos. Presupuesto para cuando elijas un modelo. +- **Comparte la identidad con Cursor regular.** Mismo identificador de paquete, mismo `~/.cursor`, mismo `Application Support/Cursor` ( macOS), `%APPDATA%\Cursor` ( Windows) o `~/.config/Cursor` ( Linux). Inicie con `--user-data-dir ` para mantener los dos separados, y deje "Importar datos de la instalación Cursor existente" sin marcar en la primera ejecución a menos que desee copiar la configuración. + + + +## Identificar la construcción instalada + +Ambas versiones se denominan " Cursor " en el Dock y comparten una identificación de paquete, así que verifique `product.json`: + +| Plataforma | product.json | +|---|---| +| macOS | `/Applications/Cursor Private Inference.app/Contents/Resources/app/product.json` | +| Windows | `%LOCALAPPDATA%\\Programs\\cursor-private-inference\\resources\\app\\product.json` | +| Linux | `/resources/app/product.json` (primero debe extraerse una AppImage). El tablero de instrumentos busca raíces de instalación `cursor*` bajo `/opt`, `/usr/share` y `~/.local/share`. | + +`nameLong` es `"Cursor Private Inference"` para el agente local y `"Cursor"` para el regular; `version` es la construcción (3.18.25 en el momento de la escritura). La tarjeta Integrations.Cursor del panel de control ejecuta la misma verificación y enumera lo que encontró. El modo local se activa dentro del paquete de banco de trabajo, no en `product.json`, por lo que no hay bandera para voltear: si `nameLong` dice Cursor regular, esa instalación no puede llegar a una puerta de enlace de bucle. + +El bucle de agente que habla con la puerta de enlace vive en un archivo bajo la misma raíz de instalación, `extensions/cursor-agent-exec/dist/main.js`. opencodex lo lee (solo lectura, limitado) para aprender la tabla de esfuerzo de razonamiento de Cursor; véase "Modelos y esfuerzo de razonamiento". + + + +## Configurar la puerta de enlace + +opencodex necesita estar en funcionamiento (`ocx service status`). Entonces cualquiera de estas obras; ambos terminan en el mismo lugar. + +**En la aplicación.** Configuración → Modelos → Pasarela → Configurar la puerta de enlace: + +| Campo | Valor | +|---|---| +| URL base | `http://127.0.0.1:10100/v1` (incluya `/v1`; se acepta el bucle de `http://`) | +| Clave API | una clave de OpenCodex aceptada por el servicio cuando está habilitada la admisión con clave API: puede ser `OPENCODEX_API_AUTH_TOKEN` o una clave de cliente configurada; use `opencodex-loopback` solo cuando la configuración permita ese marcador de posición | + +Haga clic en **Actualizar lista de modelos**. El selector se llena con opencodex `/v1/models`; encienda las filas que desee. + +**Con variables de entorno.** La aplicación lee esto al principio: + +```text +CURSOR_LOCAL_AGENT_BASE_URL=http://127.0.0.1:10100/v1 +CURSOR_LOCAL_AGENT_API_KEY=opencodex-loopback +CURSOR_LOCAL_AGENT_HEADERS= # optional, newline-separated "Header-Name: value" lines +``` + +`CURSOR_LOCAL_AGENT_HEADERS` rechaza `User-Agent` y `{...}` marcadores de posición no resueltos; `{gitOrgRepo}` y `{gitBranch}` se expanden. + +Precedencia, el más alto primero: credenciales por modelo → la puerta de enlace guardada en Configuración → `CURSOR_LOCAL_AGENT_*` → `ANTHROPIC_BASE_URL` / `ANTHROPIC_AUTH_TOKEN` (alternativa por compatibilidad). El entorno no anula una puerta de enlace guardada; límpiela primero en Configuración si tiene la intención de cambiar a través del entorno. + +Cursor Private Inference es una aplicación GUI, por lo que un perfil de shell interactivo no es suficiente por sí solo; la variable tiene que estar en el entorno de lo que sea que lance la aplicación. + +| OS | Dónde colocarlo | +|---|---| +| macOS | `launchctl setenv CURSOR_LOCAL_AGENT_BASE_URL http://127.0.0.1:10100/v1` para la sesión de inicio de sesión actual, o un LaunchAgent con `EnvironmentVariables` para que sea persistente. Iniciar la aplicación desde un terminal también funciona. | +| Windows | `setx CURSOR_LOCAL_AGENT_BASE_URL http://127.0.0.1:10100/v1` (alcance del usuario; afecta a nuevos procesos) o Propiedades del sistema → Variables de entorno. Reinicie la aplicación después. | +| Linux | `~/.profile` o `~/.pam_environment` para una sesión de administrador de pantalla, o `systemctl --user set-environment CURSOR_LOCAL_AGENT_BASE_URL=http://127.0.0.1:10100/v1` cuando el escritorio se ejecuta bajo una sesión de usuario systemd. La AppImage lanzada desde un terminal hereda el entorno de ese shell. | + +La construcción existe para macOS (arm64, x64, universal), Windows (x64, arm64) y Linux (x64, arm64). La configuración es idéntica en todos ellos. + + + +## Desde el panel de control + +El panel de control opencodex tiene una pestaña **Cursor** en Integraciones (`/#integrations/cursor`). Es de solo lectura hacia Cursor: nunca escribe la base de datos de configuración de Cursor, la entrada de llavero o el paquete de aplicaciones, por lo que no hay ningún interruptor para cambiar. Lo que hace es entregarte los valores y mostrarte si los tomaron. + +- **Construcción instalada.** Si Cursor Inferencia privada (con su trayectoria y versión) y regular Cursor (sencillamente trayectoria) están presentes. Si solo se encuentra el Cursor normal, la pestaña lo dice, enlaza aquí y ofrece un botón **Busque el instalador de Inferencia privada**. Al presionarlo, se le pregunta al canal de actualización propio de Cursor qué instalador de modo local anuncia para esta plataforma y CPU (el canal `cursor-local` en `api2.cursor.sh`) y muestra esa versión con un enlace al instalador `downloads.cursor.com/local-mode/`. Nada se solicita hasta que pulse el botón: abrir la pestaña y su actualización periódica nunca contacto canal de Cursor. opencodex solo muestra el enlace: nunca descarga, lanza o instala nada. La respuesta se almacena en caché durante 30 minutos (5 después de un fallo). Cuando no se puede alcanzar el canal, las respuestas con algo inutilizable, o Cursor no se envía ninguna construcción para este equipo (solo x64 y arm64 en Windows, macOS y Linux tienen uno), la pestaña dice que el instalador no se pudo resolver; los valores de puerta de enlace a continuación permanecen válidos de cualquier manera. Regular Cursor sí mismo todavía rutas endpoints personalizados a través de Cursor 's servidores, por lo que no puede llegar a un proxy loopback. +- **Valores de entrada.** La URL base en el propio puerto de escucha del proxy (de su registro en entorno de ejecución, por lo que un panel de control con el proxy inverso aún muestra el puerto Cursor en esta máquina), con un botón Copiar. La fila de claves API depende de la vinculación: cuando no necesita credenciales, la fila es `opencodex-loopback` con Copiar; cuando está activada la autenticación API o cualquier tecla opencodex API está configurada, la fila le indica que use una de sus propias claves y enlaces a la pestaña Claves API. Cualquier tecla configurada funciona, no solo `OPENCODEX_API_AUTH_TOKEN`. +- **Conexión.** La última solicitud `/v1/models` cuyo User-Agent es exactamente `Cursor/` (el entorno de ejecución del agente local del encabezado Cursor envía), con el tiempo y la versión. Se lee "nunca visto" hasta que Cursor llama al proxy; presionar **Actualizar lista de modelos** en Cursor es lo que lo hace girar. La tarjeta se actualiza cada 15 segundos mientras la pestaña está abierta. +- **Lo que mostrará el Cursor.** Una tabla Modelo / Razonamiento / Contexto para los modelos opencodex anuncia (se aplican modelos desactivados y listas de proveedores, al igual que la lista sin procesar), siguiendo las reglas en la siguiente sección. Es una predicción: Cursor escoge la escalera de Razonamiento de su propia tabla. + + + +## Modelos y esfuerzo de razonamiento + +El selector es opencodex lista cruda `/v1/models`. Dos cosas deciden si una fila modelo obtiene un control **Razonamiento**: + +1. opencodex debe anunciar capacidades en la fila (`api_types` más un objeto `capabilities`). Lo hace, a partir de v2.41. Los proxies más antiguos muestran los modelos pero no controlan el esfuerzo. +2. El ID del modelo, después de despojar todo hasta el último `/` y cualquier sufijo `@…`, debe coincidir con la tabla de esfuerzo propio de Cursor. Esa tabla está compilada en la aplicación (`extensions/cursor-agent-exec/dist/main.js`); opencodex lo lee desde la instalación detectada, por lo que la predicción del panel sigue a una actualización Cursor, y la tarjeta dice qué compilación leyó o "espejo estático" cuando no se encontró nada. Cursor decide la escalera, no opencodex, y no `/v1/models` campo puede añadir un modelo a esa tabla. La matriz a continuación es la instantánea 3.18.25 que lleva el espejo estático: + +| ID del modelo (después del último `/`) | Escalera Cursor espectáculos | Campo de alambre | +|---|---|---| +| `gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-5.6-luna` | Bajo, Medio, Alto, Extra Alto | `reasoning.effort` | +| `gpt-5`, `gpt-5.x` | Bajo, Medio, Alto, Extra Alto | `reasoning.effort` | +| `claude-opus-5`, `claude-sonnet-5`, `claude-opus-4.7`, `claude-opus-4.8` | Bajo, medio, alto, extra alto, máximo | `output_config.effort` | +| `claude-opus-4.6`, `claude-opus-4.5`, `claude-sonnet-4.6` | Bajo, medio, alto, máximo | `output_config.effort` | +| `grok-4.3`, `grok-4.5`, `grok-4.6`, `grok-build-latest` | Mínimo, bajo, medio, alto, extra alto | `reasoning_effort` | +| `gemini-*` (necesita `supports_reasoning` ) | Mínimo, Bajo, Medio, Alto | `reasoning_effort` | +| Cualquier otra cosa, incluyendo `claude-fable-5-1`, `kimi-k3` | sin control | — | + +Así que `anthropic/claude-opus-5` trabajos, y opencodex de `max`/`ultra` Los niveles para GPT-5.6 no son accesible desde este selector. + + + +### Modelos sin control + +`anthropic/claude-fable-5-1`, `cursor/kimi-k3`, y cualquier otra cosa fuera de la tabla no obtiene ningún control de Razonamiento, y Cursor registra una línea por tal identificación cuando la puerta de enlace anuncia `supports_reasoning`: "Proveedor local anuncia soporte de razonamiento para un modelo sin familia de esfuerzo de Bottlerocket codificada". Dos formas de elegir un esfuerzo: + +- **Esfuerzo filas** (`cursorEffortRows: true` en la configuración opencodex, default off): la pasarela publica una entrada de selector por esfuerzo para modelos sin tabla, como `anthropic/claude-fable-5-1--high` o `cursor/kimi-k3--max`, y encamina cada uno al modelo base con ese esfuerzo aplicado. Los modelos Cursor ya no obtienen filas adicionales, y un identificador de modelo conocido exacto siempre gana sobre el sufijo `--`. Pulsa Actualizar lista de modelos después de activarla. La tarjeta del panel de control cuenta las filas que publicó por modelo. Elegir una fila es una opción explícita, por lo que su esfuerzo también gana una directiva `ocx-effort` en la solicitud. +- **Un valor predeterminado fijo** (`modelDefaultReasoningEfforts` en el proveedor): se aplica cuando Cursor no envía ningún esfuerzo. + + + +### "Max" es dos cosas diferentes + +Regular Cursor muestra un **Max** alternar junto a algunos modelos. Ese es el modo Max, una ventana de contexto más grande, no un nivel de razonamiento. En la construcción de agente local aparece la misma idea que una entrada **Contexto** en el menú del modelo, y opencodex la ilumina para la familia nativa GPT-5.6: **272K** (predeterminado) o **922K** (el opt-in 1M, marcado como que cuesta más). El valor que eliges es el que convierte el contexto. Los modelos enrutados muestran una sola ventana y ninguna entrada de contexto; un límite de contexto del proveedor por debajo de 922K también elimina la entrada para las filas nativas. + +Razonamiento-esfuerzo **Max** (opencodex `max` / `ultra`) es el otro significado, y que uno no es alcanzable: Cursor toma la escalera de esfuerzo de su propia mesa en lugar de la puerta de enlace, y la entrada GPT-5.6 se detiene en Extra High. + +Debido a que opencodex anuncia `responses` en `api_types`, este agente de envío de compilación se convierte en `/v1/responses` con `reasoning.effort`, no en `/v1/chat/completions`. + +Esa elección de cable tiene un efecto secundario para Claude filas: Cursor envía Claude esfuerzo solo como `output_config.effort` en el cable Anthropic Messages, por lo que con un `/v1` URL Base una fila Claude que muestra un control aún se ejecuta en el proveedor predeterminado. Una URL base que termina en `/messages` lo invierte: se envía Claude esfuerzo y se elimina OpenAI -esfuerzo familiar. Una entrada de puerta de enlace no puede servir a ambas familias; filas de esfuerzo (arriba) paso lateral esto porque opencodex aplica el esfuerzo en sí. + + + +## Verificar + +`ocx observe logs` muestra los giros como `inboundProtocol: responses` con `admissionKind: loopback`. + +| Síntoma | Comprobar | +|---|---| +| 401 desde la puerta de enlace | la credencial no coincide con un token de datos o una clave de cliente aceptados; use una clave autorizada. El marcador de posición solo sirve en loopback cuando la configuración admite solicitudes sin autenticación de datos | +| El selector está vacío | opencodex no se está ejecutando, o falta la URL base `/v1`; presione Actualizar lista de modelos después de la fijación | +| modelos enumerados pero sin control de razonamiento | opencodex más antiguo que v2.41, o el id no está en la tabla de Cursor (el panel lo marca - ); encienda `cursorEffortRows` o configure un proveedor predeterminado | +| No se recoge un cambio de esquema | Cursor cachés `/models` por cadena de URL base sin caducidad; La lista de modelos de actualización la vuelve a leer, de lo contrario, reinicia la aplicación o guarda temporalmente una ortografía diferente de la URL (`localhost` vs `127.0.0.1`) | +| 23k-token primera vuelta | esperado; esto es el aviso del sistema local de Cursor | diff --git a/docs-site/src/content/docs/es/guides/desktop-app.md b/docs-site/src/content/docs/es/guides/desktop-app.md new file mode 100644 index 00000000000..76fe1ec5730 --- /dev/null +++ b/docs-site/src/content/docs/es/guides/desktop-app.md @@ -0,0 +1,172 @@ +--- +title: "Aplicación de escritorio" +description: "Instala y usa OpenCodex Desktop en macOS, Windows y Linux." +--- + +OpenCodex Desktop combina una bandeja nativa con el dashboard web. Su CLI incluida busca un proxy local existente; la aplicación solo inicia su propio entorno de ejecución cuando confirma que no hay ninguno. + +El dashboard se sirve desde la dirección del proxy local encontrado (puerto `10100` de forma predeterminada). La aplicación de escritorio integra ese dashboard y su entorno de ejecución. + + + +## Instalar + +### macOS + +Descarga `OpenCodex--macos.dmg` desde la [última versión](https://github.com/lidge-jun/opencodex/releases). Abre el DMG y arrastra `OpenCodex.app` a Aplicaciones. Se requiere macOS 13 o posterior. + +Las versiones publicadas de `OpenCodex.app` tienen firma de Developer ID y certificación de Apple. Al abrirlas por primera vez, macOS normalmente solo pide la confirmación habitual para una aplicación descargada. Si sigue bloqueándola, usa **Configuración del Sistema → Privacidad y seguridad → Abrir de todos modos**. + +### Windows + +Descarga `OpenCodex--windows-x64.msi` y ejecuta el instalador. La firma de código a través de SignPath Foundation se está incorporando ([firma de código en Windows](/es/reference/code-signing/)). Hasta que una versión incluya esa firma, Windows SmartScreen puede advertir que el instalador no está firmado. Elige **Más información → Ejecutar de todas formas** después de confirmar que lo descargaste de la página de versiones. + +### Linux + +Descarga `OpenCodex--linux-x86_64.AppImage` o `OpenCodex--linux-amd64.deb` desde la página de versiones. + +Para AppImage: + +```bash +chmod +x OpenCodex--linux-x86_64.AppImage +./OpenCodex--linux-x86_64.AppImage +``` + +Para distribuciones basadas en Debian: + +```bash +sudo apt install ./OpenCodex--linux-amd64.deb +``` + +El icono de la bandeja requiere un entorno de escritorio compatible con AppIndicator. + + + +## Primer inicio + +La aplicación ejecuta `ocx resolve --json` con su CLI incluida y se conecta al proxy local si ya hay uno accesible. Solo inicia su propio entorno de ejecución cuando la CLI confirma que no existe otro; un resultado incierto se muestra como un fallo de inicio. Después abre el dashboard en su vista web, usando la dirección de bucle local encontrada. Si se inicia oculta en la bandeja al abrir sesión, conserva la página ligera de arranque y carga el dashboard cuando lo abres desde la bandeja o vuelves a iniciar la aplicación. + +Usa **Open dashboard** (abrir dashboard) u **Open in browser** (abrir en el navegador) en la bandeja para alternar entre el dashboard integrado y tu navegador habitual. La bandeja también permite buscar actualizaciones. + +En Windows, aceptar **Take over** (tomar el control) permite hasta 90 segundos para detener de forma segura el entorno de ejecución existente, transferir su control e iniciar el que incluye la aplicación. El tiempo que tardes en decidir no cuenta para ese límite. Mantén la aplicación abierta mientras termina; si falla, usa **Retry** (reintentar) para volver a buscar el entorno de ejecución actual. + +En macOS, cerrar el dashboard mantiene la aplicación en la barra de menús. Vuelve a abrir OpenCodex desde el Dock o Finder para recuperar el dashboard sin reiniciar el proxy. + +En Windows, **Start at Login** (iniciar al abrir sesión) registra la ruta del ejecutable entre comillas para el usuario actual, incluidas las instalaciones en `Program Files`. Los registros habilitados se actualizan una vez al iniciar la aplicación. Las entradas que hayas deshabilitado desde la bandeja o el Administrador de tareas permanecen deshabilitadas. + + + +## Usar la CLI ocx con Desktop + +Las instalaciones estables de macOS, Windows y del paquete deb de Linux configuran automáticamente el comando `ocx` incluido para las terminales nuevas al iniciar Desktop. Abre **Comando de terminal**, junto a **Actualización de Desktop** en la barra lateral del dashboard, o **Terminal command…** en la bandeja, para desactivarlo, repararlo o quitarlo. Desactivar **Usar el comando ocx de Desktop en las terminales nuevas** elimina la configuración administrada. **Quitar comando de terminal** también conserva esa opción desactivada para los próximos inicios. AppImage y los inicios en desarrollo no realizan esta configuración. + +macOS y Linux usan un shim en `~/.opencodex-desktop/bin`, el archivo auxiliar compartido `path.sh` y bloques administrados en los archivos de inicio de zsh, bash y fish. Desktop registra la propiedad y los datos de recuperación en `~/.opencodex-desktop/cli.json`; borrar ese registro no elimina el comando ni sus bloques de shell. El archivo `/usr/bin/ocx` del paquete deb no cambia. Windows añade el directorio de instalación al principio del `Path` del usuario y conserva las demás entradas. Un comando del `Path` del sistema puede seguir teniendo prioridad; Desktop informa de ese conflicto como configuración parcial y no modifica el `Path` del sistema. + +Después de habilitar o reparar el comando, abre una terminal nueva. Comprueba `type -a ocx` en macOS/Linux, o `Get-Command ocx -All` y `where.exe ocx` en Windows. Las terminales ya abiertas, los alias, las rutas absolutas y los cambios posteriores de PATH todavía pueden seleccionar otro ejecutable. La configuración persiste después de cerrar Desktop. Si falta el paquete de la aplicación, el shim POSIX falla con instrucciones para repararlo o quitarlo, en lugar de seleccionar otro `ocx` sin avisar. + +En POSIX, el shim conserva las opciones de Anthropic exportadas por la shell cuando dispone de las herramientas de verificación del inicio. Si esa verificación falla, o si se ejecuta directamente en Windows, la CLI incluida sigue eliminando las opciones de entorno de Anthropic que no sean de confianza. + +En macOS, Linux y Windows, `ocx status` y `ocx doctor` identifican OpenCodex Desktop cuando verifican que la aplicación ejecuta su proxy incluido, incluso si no existe un registro de propiedad. `ocx status` muestra `Runtime supervisor: OpenCodex Desktop`; ninguno de los dos comandos recomienda reparar un servicio de CLI para ese entorno. En macOS y Linux, activa **Start at Login** en el menú de OpenCodex en lugar de instalar un servicio en segundo plano. La protección del inicio solo reconoce a la aplicación cuando verifica su registro de inicio de sesión; si no puede verificarlo, sigue las indicaciones de Desktop que muestra el estado. + +La página de inicio muestra entonces **En ejecución · Inicio de sesión no verificado** en la fila de Desktop. En macOS, **Start at Login** solo aparece marcado cuando se puede verificar ese mismo registro. En caso contrario, queda sin marcar y explica la causa: + +- **disabled by macOS** abre Configuración del Sistema → General → Ítems de inicio y extensiones, donde puedes permitir que OpenCodex se abra al iniciar sesión. +- **another OpenCodex copy** indica que el registro pertenece a otra copia de la aplicación; desactívalo desde esa copia. +- **registered app is missing** indica que la aplicación registrada ya no existe; elimina `~/Library/LaunchAgents/OpenCodex.plist` y vuelve a activar la opción. +- **status unknown** indica que no se pudo leer el registro. + +Mientras la aplicación ejecute el proxy, el instalador del servicio en segundo plano permanece deshabilitado en la página de inicio. Para usar ese servicio, cierra OpenCodex y ejecuta `ocx service install` en una terminal. El shim de inicio de Codex sí se puede instalar desde esa página. + +Si al iniciar Codex el shim no encuentra un proxy, espera a que OpenCodex lo reinicie. En macOS, puede abrir OpenCodex si estaba cerrado y su propiedad registrada coincide con un registro válido de **Start at Login**; en los demás casos informa de un error en lugar de iniciar un segundo proxy. La reapertura automática usa la ruta de la aplicación de ese registro y comprueba que su ejecutable principal coincida con el ejecutable de Desktop registrado. Si el registro falta, está desactualizado o es incoherente, abre OpenCodex manualmente; no se elige otra copia con el mismo identificador como alternativa. Si el shim muestra "activation not confirmed", añade `. ~/.opencodex/codex-shell-env.sh` al archivo de inicio de tu shell después de las demás opciones de PATH. + +La CLI incluida está en `/Applications/OpenCodex.app/Contents/MacOS/ocx` en macOS y en `/usr/bin/ocx` para el paquete deb de Linux. Ejecuta ese archivo con `status` para comprobar el proxy de la aplicación. Windows también verifica la supervisión activa, pero allí **Start at Login** permanece sin verificar y Desktop no se considera una protección del inicio. + +Mientras la CLI detecte que Desktop supervisa el proxy, `ocx service install`, `repair`, `start` y `restart` se rechazan antes de modificar el servicio, incluso sin propiedad registrada o sin un inicio de sesión verificado. Cierra OpenCodex y ejecuta `ocx service install` para transferir la gestión del inicio a la CLI. Un `ocx start` duplicado identifica a Desktop como supervisor. + +Usa **Check for Updates…** en la bandeja para actualizar la aplicación. La CLI compilada incluida informa `installer: "standalone"` y `reason: "standalone_install"` mediante `ocx system update check`, con `canUpdate: false` e instrucciones para usar las actualizaciones de Desktop. `ocx update` rechaza reemplazar el paquete mientras Desktop supervise el proxy, incluso si se trata de otra instalación de npm/Bun; cierra OpenCodex antes de actualizar esa instalación. Si se acepta `ocx restart`, informa de que Desktop iniciará el reemplazo y espera a que esté disponible. Una CLI más reciente del PATH no puede usar `ocx restart` para reemplazar el proxy de la aplicación por su propio entorno de ejecución. + +El comando de terminal `ocx stop` detiene el proxy, pero Desktop puede volver a iniciarlo tras una espera breve. Usa **Stop proxy** o **Quit** en la bandeja para mantenerlo detenido. La salida habitual de `stop` recuerda esto por stderr; `ocx stop --json` omite tanto la comprobación de supervisión como ese aviso. + +Estas protecciones son avisos preventivos de las CLI y los entornos de ejecución actuales; las versiones anteriores pueden carecer de ellos. Una comprobación que detecte Desktop pero no termine de verificarlo también bloquea la operación. Una vez bloqueada, otra comprobación inconclusa no elimina el bloqueo: es necesario confirmar que Desktop ya no supervisa el proxy. Si nunca se detectó Desktop, una comprobación inconclusa o incompatible mantiene el comportamiento previo del comando. Las protecciones basadas en la propiedad registrada se aplican de forma independiente. + + + +## Protección del inicio en macOS y Linux + +La protección del inicio reconoce **Aplicación de escritorio** cuando un diagnóstico reciente verifica que la aplicación supervisa su proxy incluido y confirma el registro de **Start at Login** de esa misma aplicación. La propiedad registrada se conserva por separado; detectar supervisión no crea una declaración de propiedad. + +En Linux, el componente de inicio automático escribe la entrada en `~/.config/autostart/OpenCodex.desktop`, incluso si se definió `$XDG_CONFIG_HOME`. La protección del inicio lee esa entrada y el identificador de instalación bajo `~/.config`. Si `$XDG_CONFIG_HOME` apunta a otro lugar, la sesión busca un directorio distinto de inicio automático; por eso el estado permanece **En riesgo**. + +La entrada solo cuenta si no tiene `Hidden=true` ni `X-GNOME-Autostart-enabled=false`, y tampoco condiciones `OnlyShowIn`, `NotShowIn` o `TryExec`. Su campo `Exec` debe contener una ruta absoluta a `opencodex-desktop` sin comillas, espacios, escapes ni códigos de campo, seguida exactamente por `--autostart`. El ejecutable resuelto debe seguir llamándose `opencodex-desktop` y tener el `ocx` incluido a su lado. La protección del inicio lee dos veces toda la cadena de evidencias y solo reconoce la protección cuando ambas lecturas coinciden. + +Las instalaciones AppImage permanecen **En riesgo**: el inicio automático registra la ruta del archivo AppImage externo, mientras el proceso de Desktop se ejecuta dentro de su punto de montaje. Esa relación no se puede verificar y no se reconoce como protección. + +Una comprobación ausente o desactualizada mantiene el estado **En riesgo**. Si Desktop tiene la propiedad del proxy pero no se puede verificar su protección, vuelve a abrir OpenCodex y comprueba **Start at Login**. La instalación o reparación del servicio y del lanzador permanece deshabilitada mientras exista esa propiedad; `ocx restore` sigue disponible para deshacer el enrutamiento de Codex. + +Las actualizaciones normales de Desktop reemplazan la CLI incluida por la versión con la comprobación de inicio corregida. No necesitas conservar un parche local entre actualizaciones. + +## Zoom + +En macOS y Linux, Cmd (macOS) o Ctrl (Linux) con `+`, `-` y `0`, o Ctrl con la rueda del ratón, cambia el zoom entre el 50 % y el 300 % en pasos del 10 %. `0` vuelve al 100 %. La barra lateral muestra ese mismo nivel junto al selector de tema: `-`, el porcentaje actual y `+`. Pulsar el porcentaje restablece el 100 %. El nivel se guarda y se vuelve a aplicar al iniciar la aplicación. + +El dashboard procede del proxy al que se conecta la aplicación. Si ese proxy es antiguo, conserva el comportamiento anterior (pasos del 20 %, sin guardar el nivel ni mostrar controles en la barra lateral) hasta que se actualice el proxy. Windows usa el zoom propio del motor del navegador, que no se guarda. + + + +## Mantener el proxy en ejecución + +La aplicación mantiene en ejecución el proxy que inició. Si ese proxy se reinicia a sí mismo —después de **Conectar como Child**, de reiniciar la memoria desde el dashboard o de desconectar un Child— la aplicación inicia el nuevo proxy en el mismo puerto y recarga el dashboard abierto. Suele tardar alrededor de un segundo, o algunos segundos si ya se había reiniciado en los dos minutos anteriores. Así, **Stop proxy** sigue alcanzando al proxy y **Quit** también lo termina. + +Si el proxy termina sin que se le haya pedido (por un fallo o por `ocx stop` desde una terminal), la aplicación vuelve a iniciarlo tras una espera que aumenta de 3 a 30 segundos mientras sigan los fallos. Si deja de responder en su puerto, la aplicación lo detecta en unos 15 segundos y se recupera del mismo modo. Para un proxy que no inició ella (por ejemplo, un servicio en segundo plano o uno iniciado manualmente), primero espera aproximadamente un minuto a que vuelva. + +Durante la recuperación, la aplicación no detiene ni reemplaza un proxy que otro proceso ya ejecute en ese puerto: se conecta a él sin pedir tomar su control. Esto incluye el proxy de un Child que un servicio haya reiniciado después de **Conectar como Child**; la aplicación se conecta y muestra el dashboard del Child. Si el puerto lo ocupa algo que no puede utilizar, como un proxy vinculado a otra dirección distinta de `127.0.0.1`, deja de reintentar y espera a que eso cambie. Si la recuperación termina mientras está abierta la página de actualización, esa página permanece visible. + +**Stop proxy** y **Quit** en la bandeja mantienen el proxy detenido. El botón **Detener** del dashboard no detiene un proxy ejecutado por la aplicación, porque esta volvería a iniciarlo: muestra la explicación y no cambia nada. Las decisiones y sus motivos se registran en `runtime-supervisor.log`, dentro del directorio de registros de la aplicación (`~/Library/Logs/com.opencodex.desktop` en macOS). + + + +## Uso en la bandeja + +En macOS y Windows, pulsa el icono de la bandeja para abrir una ventana compacta de uso. **Show usage** también la abre, incluidos los escritorios Linux cuya bandeja no transmite los clics. En Linux, el dashboard se abre al iniciar, incluso cuando el entorno de escritorio no muestra un icono de bandeja. + +La ventana muestra los totales de hoy y de 30 días, el gráfico de uso configurado, una lista compacta de modelos y los límites por proveedor o cuenta. Junto a las barras aparecen las cuentas regresivas de restablecimiento de cuota; pasa el puntero para ver la hora exacta. Las opciones de **Barra de menús y widget** controlan las secciones y el gráfico visibles. Los proveedores ocultos se excluyen del título, los totales, las cuotas y el gráfico. + +El gráfico incluye la actividad del intervalo actual. Un indicador de datos parciales significa que algunos datos no se pueden atribuir con fiabilidad. La ausencia de mediciones no se representa como uso cero. En Windows y Linux, desplázate dentro de la ventana para llegar a Actualizar y Dashboard al final de una lista larga de cuentas. + +En macOS, la ventana usa controles nativos SwiftUI y un panel AppKit desplazable. Se usa Liquid Glass de Apple en macOS 26 o posterior; los sistemas anteriores usan el material nativo de los paneles emergentes. El encabezado y los botones Actualizar y Dashboard permanecen visibles al desplazarse por listas largas de cuentas. También puedes abrir la ventana con **View → Show Usage** (Comando-Mayús-U). Pulsa Escape o haz clic fuera para cerrarla. + +El menú de la bandeja muestra las solicitudes y los tokens de hoy, con el costo estimado si está habilitado. Usa el mismo día local que el widget. Elige **Refresh now** para actualizar inmediatamente; la aplicación también actualiza los datos cada 60 segundos. Las preferencias de visualización están en **Barra de menús y widget** del dashboard. Desactivar **Hoy** oculta el resumen y desactivar **Costo** quita el costo del resumen. + +El uso no disponible o expresamente no medido se muestra como `—`, en lugar de como un cero medido. Elegir el encabezado de solo icono elimina el contador anterior. Las abreviaturas conservan los ceros enteros: diez millones de tokens son `10M`, no `1M`. + + + +## Actualizaciones + +Elige **Check for Updates…** en la bandeja para buscar actualizaciones inmediatamente. Las versiones publicadas también las buscan después del inicio y cada seis horas. + +Cuando el actualizador de Tauri encuentra una versión más reciente, aparece un punto azul en el icono de la barra de menús de macOS o en la bandeja de Windows/Linux, cuando esta está disponible. El dashboard integrado muestra la misma señal de actualización de Desktop. Un navegador conectado al mismo proxy sigue mostrando el estado de actualización del paquete del proxy. Si la aplicación deja de informar durante unos tres minutos, el indicador integrado pasa a estado desconocido hasta que se reconecta. El punto indica disponibilidad; la instalación sigue requiriendo una acción explícita. + +En Desktop, pulsa el botón de actualización del dashboard para abrir la página de actualización de la aplicación. Allí puedes buscar de nuevo, instalar una actualización firmada pendiente o volver al dashboard. La misma instalación está disponible desde la bandeja. Si falla, la actualización sigue disponible para reintentar. La aplicación también recupera el proxy que detuvo para instalarla, de modo que Codex no se quede sin proxy por una actualización fallida. Esta página funciona también en Linux sin icono de bandeja. El dashboard de un navegador normal administra, en cambio, la instalación del paquete de ese proxy. + +Antes de instalar, las actualizaciones se verifican con la clave pública del actualizador firmado del proyecto. En macOS, las actualizaciones desde la aplicación descargan `OpenCodex--macos.app.tar.gz`; el DMG se usa para la primera instalación. El manifiesto de publicación solo se genera cuando está configurado el secreto de la clave del actualizador y exige entonces que las cuatro plataformas tengan firma. + +## Widget + +La aplicación macOS incluye la extensión WidgetKit de OpenCodex. Consulta la [guía de la aplicación de barra de menús de macOS](/es/guides/macos-menu-bar/) para configurar el widget y conocer los detalles de las instantáneas locales. + + + +## Desinstalar + +Antes de desinstalar una versión de Desktop compatible, abre **Comando de terminal** en el dashboard o **Terminal command…** en la bandeja y elige **Quitar comando de terminal**. Desktop solo elimina su configuración administrada que no haya sido modificada. Los bloques o archivos modificados se conservan y se notifican; resuelve esos problemas antes de borrar la aplicación. Desinstalar directamente no garantiza que se limpien los archivos de shell o el `Path` del usuario. + +En macOS, arrastra `OpenCodex.app` desde Aplicaciones a la Papelera. En Windows, quita OpenCodex desde **Aplicaciones instaladas**. En sistemas Linux basados en Debian, ejecuta: + +```bash +sudo apt remove opencodex +``` + +Para AppImage, elimina el archivo descargado. + +Si no se puede leer la configuración guardada de la barra de menús, se rechazan las ediciones parciales para conservar el archivo. Restáuralo o restablece expresamente la configuración del complemento antes de editar de nuevo. diff --git a/docs-site/src/content/docs/es/guides/factory-droid.md b/docs-site/src/content/docs/es/guides/factory-droid.md new file mode 100644 index 00000000000..f7606a5212d --- /dev/null +++ b/docs-site/src/content/docs/es/guides/factory-droid.md @@ -0,0 +1,158 @@ +--- +title: "Puente Factory Droid" +description: "Conecte los modelos Factory Droid a opencodex a través de un puente local compatible con Responses." +--- + +Factory Droid es un entorno de ejecución del agente, no un punto final de inferencia compatible con OpenAI documentado. Si un proveedor personalizado apunta a una URL interna de Factory LLM devuelve `403 Forbidden`, cambiar solo el adaptador opencodex o agregar encabezados de proveedor no convierte esa ruta privada en una API pública admitida. + +La integración de trabajo es: + +```text +Text-only Responses client + -> opencodex (http://127.0.0.1:10100/v1/responses) + -> local Responses bridge (http://127.0.0.1:11435/v1/responses) + -> official droid exec command + -> Factory account and selected model +``` + +Esto mantiene la credencial de fábrica dentro del cliente oficial Droid. OpenCodex recibe un token de puente separado, solo local. + + + +## Qué falló y por qué + +| Síntoma | Causa | Arreglar | +| --- | --- | --- | +| `403 Forbidden` desde una URL de fábrica LLM | La URL no es un punto final OpenAI de propósito general documentado para clientes de terceros. | Invoque la fábrica a través de los oficiales Droid CLI o SDK | +| `404` en `/models/models` | La URL base del proveedor ya terminó en `/models` | Utilice una raíz API como `baseUrl`; nunca incluya la ruta de descubrimiento | +| La búsqueda de modelos falla | El puente no expone un catálogo completo en vivo | Establecer `liveModels: false` y proporcionar una lista estática `models` | +| El proveedor de Loopback es rechazado | El acceso a la red privada se deniega de forma predeterminada | Establecer `allowPrivateNetwork: true` solo para el puente de bucle | +| `${DROID_BRIDGE_TOKEN}` no está resuelto | La variable falta en el entorno de servicio opencodex | Inyéctelo en el proceso de servicio, no solo un shell interactivo | +| `OutputTextDelta without active item` | El puente emitió un delta de texto antes de abrir un elemento de salida y una parte de contenido. | Emitir el ciclo de vida completo Responses SSE en orden | + +Por lo tanto, la misma credencial de Factory puede funcionar en `droid exec`, mientras que una solicitud directa a una URL LLM indocumentada aún devuelve `403`. Estos resultados prueban diferentes productos y no deben ser tratados como contradictorios. + + + +## Requisitos previos + +1. Instale e inicie sesión en el [Droid CLI](https://docs.factory.ai/droid-cli/quickstart). +2. Confirme que una solicitud sin cabeza limitada funciona: + + ```bash + droid exec --model glm-5.2 --output-format json "Reply with DROID_OK only." + ``` + +3. Ejecute un puente local que invoque `droid exec` (o el oficial Droid SDK) y exponga: + + - `GET /healthz` + - `GET /v1/models` + - `POST /v1/responses` + +Factory documenta `droid exec` como su superficie de automatización no interactiva y recomienda la salida JSON para scripts. Para una integración más duradera, Factory también documenta el stream JSON -RPC y los SDK oficiales de TypeScript y Python en el [Droid Guía ejecutiva](https://docs.factory.ai/droid-exec/overview). + + + +## Contrato de puente + +Antes de aceptar entradas, el puente debe escuchar únicamente en `127.0.0.1`, exigir un token bearer aleatorio, limitar el tamaño de las solicitudes y permitir solo los identificadores de modelo de una lista explícita. El puente mínimo acepta únicamente estas formas de `input` de Responses: + +- Una cadena no vacía; o +- Una matriz formada exclusivamente por elementos `message`. Cada mensaje debe usar el rol `user`, `developer`, `system` o `assistant` y contener una cadena o partes solo de texto: `input_text` para los roles de entrada y `output_text` para el historial del asistente. + +Valida toda la solicitud antes de invocar Droid. Si una parte de entrada es una imagen o un archivo, `tools` contiene alguna definición de herramienta, o `input` incluye una llamada o resultado de herramienta (`function_call`, `function_call_output`, `custom_tool_call` o `custom_tool_call_output`), devuelve HTTP `400` con un `invalid_request_error` de formato Responses. Usa un código estable del puente, como `unsupported_bridge_input`, e identifica el campo rechazado. Rechaza la solicitud antes de iniciar SSE, incluso con `stream: true`; nunca descartes ni conviertas silenciosamente el contenido no compatible en texto del prompt. + +```json +{ + "error": { + "type": "invalid_request_error", + "code": "unsupported_bridge_input", + "param": "tools", + "message": "The minimal Droid bridge does not accept tool definitions." + } +} +``` + +Para una solicitud aceptada, el puente debe: + +1. Convierta el Responses `input` aceptado en un mensaje. +2. `droid exec --model --output-format json `. +3. analizar los `result` y `session_id` finales; +4. devolver un sobre OpenAI Responses; y +5. mapear `previous_response_id` al ID de sesión Droid cuando se requiere continuación. + +Para las respuestas de transmisión, emita este ciclo de vida en orden: + +```text +response.created +response.output_item.added +response.content_part.added +response.output_text.delta +response.output_text.done +response.content_part.done +response.output_item.done +response.completed +``` + +No exponga el puente en `0.0.0.0` y no reutilice la credencial de fábrica como el token de portador de puente. + + + +## Configuración del proveedor OpenCodex + +Cree el proveedor personalizado con el ID de proveedor explícito `droid`: + +```bash +ocx provider add droid \ + --adapter openai-responses \ + --base-url http://127.0.0.1:11435/v1 \ + --default-model glm-5.2 \ + --allow-private-network +``` + +Esto crea la entrada de configuración `providers.droid`. En el panel de control, abra **Proveedores → droid → Editar JSON** y reemplace el valor de ese proveedor con: + +```json +{ + "adapter": "openai-responses", + "baseUrl": "http://127.0.0.1:11435/v1", + "responsesPath": "/responses", + "allowPrivateNetwork": true, + "authMode": "key", + "apiKey": "${DROID_BRIDGE_TOKEN}", + "liveModels": false, + "models": ["glm-5.2", "glm-5.2-fast", "kimi-k3"], + "defaultModel": "glm-5.2" +} +``` + +Los ID de modelo son ejemplos. Mantenga solo los modelos que `droid exec` puede usar para la cuenta de Factory iniciada. No agregue cabeceras de inferencia específicas de Factory a este proveedor: su origen es el puente local, no un punto final de Factory HTTP. + +Después de guardar un proveedor o cambiar su catálogo estático, sincronice y reinicie Codex para que las nuevas sesiones lean el catálogo actualizado: + +```bash +ocx sync --restart-codex +ocx doctor +``` + +`--restart-codex` reinicia los servidores de aplicaciones y cierra y vuelve a lanzar completamente la aplicación de escritorio Codex, que finaliza las conversaciones en vivo. Use `--restart-app-server-only` para dejar la aplicación de escritorio en ejecución. Ejecute el reinicio solo después de terminar o guardar esas sesiones. + + + +## Verificar la ruta completa + +Compruebe cada límite por separado: + +```bash +curl -fsS http://127.0.0.1:11435/healthz +ocx doctor +ocx access test droid/glm-5.2 --protocol responses +``` + +Una fila de proveedores o una entrada de selector de modelos solo prueban la visibilidad del catálogo. La integración solo funciona después de que la sonda Responses regrese a través de la ruta `droid/`. + + + +## Limitación actual + +El puente mínimo de arriba traduce el texto y el ciclo de vida Responses SSE. Hace **no** implementa el protocolo de llamada de herramienta/función Codex bidireccional completo. Codex App y `codex exec` normalmente envían definiciones de herramientas incluso cuando un mensaje indica que no se deben llamar a las herramientas, y el Codex CLI actual no tiene ninguna bandera general que elimine esas definiciones. El puente mínimo debe rechazar esas solicitudes con el contrato `400` anterior. Las definiciones de herramientas, las llamadas de herramientas, los resultados de herramientas, los permisos, la cancelación y los eventos ricos de Droid requieren un puente con estado construido en el modo de transmisión JSON -RPC de Factory o un Droid SDK oficial. Tratar el éxito de `ocx access test` como una verificación de ruta de texto, no como una verificación de agente o ruta de herramienta de Codex. diff --git a/docs-site/src/content/docs/es/guides/fallback-off.md b/docs-site/src/content/docs/es/guides/fallback-off.md new file mode 100644 index 00000000000..74469d0e588 --- /dev/null +++ b/docs-site/src/content/docs/es/guides/fallback-off.md @@ -0,0 +1,122 @@ +--- +title: "Desactivar el fallback" +description: Desactiva el fallback de modelos o proveedores por alcance y consulta qué ocurre cuando un Remote Link Child no puede acceder a su Home. +--- + +OpenCodex puede atender una solicitud con otro modelo o proveedor si falla el elegido: un [combo](/es/guides/combos/) pasa al siguiente destino, un [perfil de enrutamiento](/es/guides/routing-profile-editor/) prueba el siguiente candidato, un subagente recorre su cadena de modelos alternativos y el bloqueo estricto de la cuenta principal puede usar su modelo alternativo configurado. Todos estos mecanismos están habilitados por defecto. + +Desactiva un tipo de fallback cuando prefieras recibir un error claro en lugar de una respuesta de un destino que no elegiste. + + + +## Qué se considera fallback + +Un fallback es un salto a un **modelo diferente** o un **proveedor diferente**: + +| Tipo | Ejemplo | Ajuste | +|---|---|---| +| Fallback de modelo | Falla `anthropic/claude-opus` y respondería `anthropic/claude-sonnet` | `model` | +| Fallback de proveedor | Falla `anthropic/claude-opus` y respondería `openai/gpt-6-sol` | `provider` | + +La rotación entre cuentas o claves API de **un mismo pool de proveedor** para el mismo modelo no es fallback. Permite absorber el límite de tasa de una cuenta y sigue funcionando con cualquier ajuste de esta página. Tampoco se consideran fallback los reintentos al mismo destino ni los cambios de transporte que conservan ese destino. + + + +## Desactivar el fallback + +```bash +ocx fallback off # model and provider fallback, everywhere +ocx fallback off --kind provider # only cross-provider hops +ocx fallback off --route combo/coding # one combo, routing profile or model selector +ocx fallback off --provider anthropic # hops that leave one provider +ocx fallback on --route combo/coding # an exception under a global off +ocx fallback clear --route combo/coding # remove an override +ocx fallback status # current settings and the last fallback +``` + +Los mismos ajustes aparecen en el dashboard: la tarjeta **Fallback**, al final de **Dashboard**, contiene los ajustes globales, las excepciones y el último fallback ejecutado o rechazado. + + + +### Prioridad + +1. Un **dispositivo** configurado en off siempre rechaza el fallback (consulta los [ajustes por dispositivo](#per-device-settings)). Este alcance solo puede denegarlo: activarlo no permite un salto que otro alcance rechaza. +2. En los demás casos, tiene prioridad el ajuste más específico: **ruta**, después **proveedor** y finalmente **global**. +3. Si no hay ningún ajuste, el fallback está permitido, que es el comportamiento actual. + +Los ajustes se guardan en `config.json`, bajo `fallback`: + +```json +{ + "fallback": { + "provider": false, + "routes": { "combo/coding": { "provider": true } }, + "providers": { "anthropic": { "model": false } }, + "devices": { "lnk_0123456789abcdef": { "localFallback": false, "model": false } } + } +} +``` + +Un valor final mal formado se ignora, de modo que la resolución de políticas usa el siguiente alcance aplicable y los diagnósticos de `ocx config` lo identifican. En cambio, una escritura de la configuración completa que contenga ese valor se rechaza. + + + +## El error recibido + +Un fallback rechazado devuelve el **estado del fallo que lo provocó**: un 429 rechazado sigue siendo 429, conserva `Retry-After` y devuelve este cuerpo: + +```json +{ + "error": { + "type": "fallback_refused", + "code": "fallback_refused", + "message": "combo/coding: anthropic/claude-opus failed (rate_limited). Provider fallback to openai/gpt-6-sol is off for route combo/coding, so OpenCodex did not send the request there. To allow it: ocx fallback on --kind provider --route combo/coding", + "fallback": { "kind": "provider", "scope": "route", "scopeKey": "combo/coding", + "from": "anthropic/claude-opus", "to": "openai/gpt-6-sol", "trigger": "rate_limited" } + } +} +``` + +La respuesta también incluye `x-opencodex-fallback: refused`. Si ya se sabe que el primer destino no está disponible, el rechazo ocurre antes de enviar nada y nunca se contacta al destino alternativo. El estado depende del motivo por el que se omitió el primer destino: + +- Primer destino de un combo en enfriamiento o sin cuota: 429. +- Primer destino de un combo deshabilitado o no apto para la solicitud: 503. +- Cuenta principal bloqueada: 429. +- Modelo de subagente no disponible: 503. + +Después de un fallo real del proveedor, el rechazo conserva el estado de ese fallo. + + + +## Remote Link Children y clientes Hub + +Un Remote Link Child y un cliente Hub nunca atienden solicitudes con sus proveedores locales. Cuando el Home no está disponible, el Child devuelve un `503` reintentable (el relé del dashboard de un cliente Hub devuelve `502`) con: + +```json +{ "error": "link tunnel unavailable", "code": "home_unreachable", "message": "The Home is unreachable, and OpenCodex did not serve this request from this device's local providers. …" } +``` + +No se envía nada a un proveedor local y la clave de enlace y el cuerpo de la solicitud nunca salen del dispositivo. + + + +### Ajustes por dispositivo + +En el Home, cada dispositivo enlazado tiene dos ajustes en **Remote Link** o mediante la CLI: + +```bash +ocx fallback local on --device mac-studio # permission for local fallback while the Home is down +ocx fallback off --device mac-studio # refuse model and provider fallback for this device's requests +``` + +`--device` acepta un alias o identificador de enlace de `ocx link status`, o el identificador de una clave de datos del Hub. + +**Fallback local** es un permiso que consulta GOAT: al activarlo, GOAT puede trasladar el trabajo del dispositivo a sus propias sesiones mientras el Home no esté disponible. OpenCodex sigue devolviendo `home_unreachable` y nunca atiende al dispositivo localmente. Está desactivado hasta que lo actives. + + + +## Estado + +`ocx status --json` incluye un objeto `fallback` (en un Child, se consulta el del Home mediante el enlace). `GET /api/fallback` devuelve el mismo documento `ocx.fallback/1`: ajustes globales efectivos, excepciones, permiso de fallback local de cada dispositivo y los últimos 20 fallbacks ejecutados o rechazados, con fecha, ruta, origen, destino, motivo y alcance que tomó la decisión. La lista se guarda en memoria y se vacía al reiniciar el proxy. Nunca contiene cuerpos de solicitudes, claves ni identidades de cuentas. + +Un Home compatible anuncia `fallback-policy/1` en `features` de `GET /readyz`. diff --git a/docs-site/src/content/docs/es/guides/grok-build.md b/docs-site/src/content/docs/es/guides/grok-build.md new file mode 100644 index 00000000000..680aa2f2fc4 --- /dev/null +++ b/docs-site/src/content/docs/es/guides/grok-build.md @@ -0,0 +1,124 @@ +--- +title: "Grok Build" +description: "Usa modelos enrutados por opencodex desde Grok Build CLI de xAI; se registran en ~/.grok/config.toml mientras el proxy está activo." +--- + +opencodex sirve un OpenAI -compatible `POST /v1/responses` en su puerto local, y Grok Build soporta modelos personalizados contra OpenAI -compatible con servidores. A partir de esta integración, opencodex registra todo su catálogo visible en Grok Build automáticamente, sin necesidad de edición de configuración manual. + + + +## Auto-registro + +Cuando `~/.grok` existe, `ocx start` (y `ocx ensure` / `ocx restart`) escribe un bloque administrado en `~/.grok/config.toml`: + +```toml +# >>> opencodex managed block — do not edit (removed by `ocx stop`) >>> +[model_providers.opencodex] +base_url = "http://127.0.0.1:10100/v1" +api_backend = "responses" +api_key = "opencodex-loopback" +extra_headers = { "x-opencodex-grok" = "1" } + +[model.ocx-gpt-5-6-sol] +model = "gpt-5.6-sol" +model_provider = "opencodex" +name = "OCX gpt-5.6-sol" +context_window = 272000 +supports_reasoning_effort = true +reasoning_effort = "low" + +[[model.ocx-gpt-5-6-sol.reasoning_efforts]] +id = "low" +value = "low" +label = "Low" +description = "Quick, fast implementations" +default = true +# ... remaining rungs for this model, then one [model.ocx-*] table per visible model, +# each referencing model_provider = "opencodex" ... +# <<< opencodex managed block <<< +``` + +- **Aditivo:** su propia configuración fuera de la valla nunca se toca. Antes de la primera inyección en un archivo preexistente, se escribe una copia de seguridad de una sola vez en `~/.grok/config.toml.bak-opencodex`. +- **Idempotente:** cada `ocx start` (y `ocx ensure` mientras el inicio automático está habilitado) reemplaza el bloque cercado con el catálogo actual. +- **Eliminado en desmontaje:** `ocx stop`, `ocx eject`, `ocx uninstall`, y el elegante daemon sin servicio de apagado desmonta el bloque vallado y restaura tu archivo byte por byte. Bajo un administrador de servicios, el desmontaje pasa por `ocx stop` / `ocx + uninstall` (los procesos en modo servicio mantienen el bloque intencionalmente en todas las reapariciones). +- **Conflict-safe:** alias ya definidos por sus propias mesas `[model.*]` (opencodex sufijos de sus propias entradas); una valla dañada (marcador de inicio sin marcador final) rechaza cualquier cambio automático y pide reparación manual. + +A continuación, elija un modelo dentro Grok Build: + +```bash +grok models # lists ocx-* entries alongside native grok models +grok -m ocx-anthropic-claude-opus-4-8 -p "hello" +# or in the TUI: /model ocx-anthropic-claude-opus-4-8 +``` + + + +## Esfuerzo de razonamiento + +Grok Build 's `/effort` (y `--effort`) sólo funciona para los modelos cuya entrada de catálogo anuncia la escalera: su lista de modelos lee la respuesta cruda `GET /v1/models`, y las entradas allí deben llevar `supports_reasoning_effort` más `reasoning_efforts` opciones de menú. Una proyección compatible con Grok de esa escalera se escribe en cada tabla `[model.*]` administrada ( filas `supports_reasoning_effort`, `reasoning_effort` predeterminadas y `[[model..reasoning_efforts]]` de selector) de modo que el menú está presente cuando Grok lee el modelo desde `config.toml`. Para las entradas de modelo enrutadas, opencodex refleja los niveles de proveedor configurados ( `reasoningEfforts` / `modelReasoningEfforts`, y el valor predeterminado de `modelDefaultReasoningEfforts`). Estos metadatos describen la escalera enrutada configurada por proxy. Los adaptadores pueden emular el razonamiento o mapear niveles en campos específicos del proveedor. Los modelos enrutados con una escalera configurada muestran el control de esfuerzo en Grok Build al igual que lo hacen en Codex. Los modelos con una lista de niveles vacía no mantienen ningún control de esfuerzo, igualando el comportamiento de Codex. Las entradas nativas de GPT-5.6 están separadas: preservan y exponen sus escalas de razonamiento ascendente ancladas en lugar de los metadatos enrutados configurados por el proveedor. Los Grok peldaños válidos, incluidos los `none` y `minimal`, se conservan cuando se anuncian. Los peldaños no soportados o duplicados, incluyendo Codex -sólo `ultra`, se omiten del archivo, manteniendo cada opción de selector emitida seleccionable. + +Grok Build habla con opencodex sobre el Responses API. Cuando la ruta anuncia una escalera de razonamiento, el paso Responses avanza `reasoning.summary` según lo configurado, por lo que las trazas de pensamiento alcanzan Grok de forma nativa como Responses elementos de razonamiento. Establecer `reasoning.summary: "none"` si un cliente quiere que el modelo piense sin devolver el rastro. Un `reasoning.summary` explícito gana sobre el valor predeterminado de la ruta. + + + +## Nota de autenticación + +Grok Build requiere una clave API no vacía para modelos personalizados incluso en bucle. Las entradas inyectadas llevan un marcador de posición (`opencodex-loopback`) - opencodex ignora las claves de admisión para las conexiones de bucle invertido, por lo que no hay ningún secreto real involucrado. + +**El registro automático es solo loopback.** Cuando opencodex enlaza un host no loopback - incluyendo los comodines `0.0.0.0` y `::`, que exponen todas las interfaces - las solicitudes necesitan su token de admisión real, y un bloque administrado no puede llevar uno de forma segura. Escribir el token literal pondría tu secreto en `~/.grok/config.toml` y sobrescribiría lo que establezcas allí en el siguiente `ocx start` / `ensure` / `restart`. Por lo tanto, opencodex no escribe nada en ese caso (y elimina cualquier bloque sobrante de un enlace de bucle de retroceso anterior), y configura los modelos usted mismo fuera de los marcadores administrados, donde nada opencodex puede golpearlos. Vea [Receta manual](#manual-recipe-without-auto-registration) para la tabla exacta, y establezca `base_url` (un host que es realmente accesible desde donde ejecuta `grok`) y `api_key` (su `OPENCODEX_API_AUTH_TOKEN`). + +No reemplace `api_key` con `env_key` aquí. Un `env_key` que no se resuelve no detiene la solicitud - Grok cae a través de su token de sesión xAI y lo envía a cualquier `base_url` los nombres de entrada, que para una implementación de LAN es un punto final HTTP de texto plano que no es xAI. + +El `api_key` inyectado en la entrada del proveedor se encuentra primero en la cadena de credenciales de Grok para estos modelos, por lo que las vueltas contra opencodex no necesitan un inicio de sesión Grok adicional. Mantenga su configuración normal `grok login` / `XAI_API_KEY` para los modelos de grok nativos y cualquier función de arnés que contacte directamente con xAI. + + + +## Receta manual (sin auto-registro) + +Si no te gusta `~/.grok/config.toml` — o opencodex está en un enlace no loopback — agregar a `[model_providers.opencodex]` tablas de bloques y por modelo que hacen referencia a él, fuera del +`# >>> opencodex managed block` marcadores: + +```toml +[model_providers.opencodex] +base_url = "http://127.0.0.1:10100/v1" +api_backend = "responses" +api_key = "opencodex-loopback" + +[model.ocx-opus] +model = "anthropic/claude-opus-4-8" +model_provider = "opencodex" +``` + +Para un proxy accesible a través de la red, el punto `base_url` en la dirección `grok` puede marcar y usar su token de admisión: + +```toml +[model_providers.opencodex] +base_url = "http://192.168.1.10:10100/v1" # the reachable host, not 127.0.0.1 +api_backend = "responses" +api_key = "your-OPENCODEX_API_AUTH_TOKEN" + +[model.ocx-opus] +model = "anthropic/claude-opus-4-8" +model_provider = "opencodex" +``` + +Esto usa la herencia `[model_providers.]`, que requiere Grok Build 0.2.109 o posterior (liberado 2026-07-21). En versiones anteriores, el heredado `base_url` no se aplica al enrutamiento de inferencia - actualización, o volver a los campos directos por modelo (`base_url` / `api_backend` / `api_key` en cada tabla `[model.*]`). + +Citar cualquier alias que contenga un punto: bare `[model.grok-4.5]` es una ruta clave de tres segmentos, no el id `grok-4.5`. Los alias generados evitan los puntos completamente por esta razón. + + + +## Limitaciones conocidas + +- **Instalación del servicio `ocx restart`:** el proxy en ejecución posee la autorización de reinicio y la coordinación de drenaje, mientras que el administrador de servicios instalado inicia el reemplazo después de que finalice el proceso anterior. La supervisión del servicio permanece instalada. En el registro automático de bucle de retorno, el bloque administrado también permanece en su lugar a través del traspaso; en su lugar, las implementaciones que no son de bucle de retorno utilizan la configuración administrada manualmente Grok. El comando solo tiene éxito después de que un proceso diferente verificado por identidad esté activo en el mismo puerto. +- **Configure el tiempo de lectura:** inicia primero opencodex, luego lanza `grok` para obtener los resultados más predecibles. Grok Build observa `~/.grok/config.toml` y se recarga cuando la tabla `[model]` realmente cambia (aproximadamente un segundo de rebote, en comparación con el contenido), por lo que un bloque actualizado alcanza una sesión abierta sin reiniciar. Para confirmar lo que Grok analizó, ejecute `grok inspect`: enumera las fuentes de configuración que cargó y advierte sobre cualquier campo que rechazó. No imprime la lista de modelos resueltos. El modelo Grok Build actual informa y omite campos de modelo no válidos mientras conserva el resto de la entrada del modelo. Un error de sintaxis TOML aún evita que el archivo se cargue. opencodex escribe atómicamente, por lo que Grok observa un documento completo en cada recarga. +- **Actualizaciones del catálogo:** el bloque vallado refleja el catálogo en el momento de la inyección. Después de agregar proveedores o modelos, ejecute `ocx ensure` (o reinicie el proxy) para actualizarlo. + + + +## Límites de solicitudes Devin + +Si Devin rechaza una solicitud directa con un límite de velocidad antes de producir una salida o realizar una acción, OpenCodex devuelve HTTP 429 con un error JSON. Grok puede reconocer entonces el límite en lugar de mostrar un error genérico 500 de un flujo de HTTP 200 fallido. Si la respuesta incluye `Retry-After`, siga ese retraso antes de volver a intentarlo. Las cuotas agotadas sin una sugerencia de reinicio no reciben un retraso predeterminado. La conmutación por error de la cuenta OAuth existente todavía se aplica. Este manejo HTTP 429 también se aplica a las solicitudes Responses que no son de transmisión. + +Para las solicitudes de transmisión, OpenCodex espera hasta el tiempo de espera configurado para este rechazo temprano. Si esa espera expira, se abre la respuesta SSE y permite que el supervisor de flujo existente maneje las paradas. Después de que se envían las cabeceras HTTP, un fallo posterior permanece en la secuencia como `response.failed`. diff --git a/docs-site/src/content/docs/es/guides/image-bridge.md b/docs-site/src/content/docs/es/guides/image-bridge.md new file mode 100644 index 00000000000..ad422118bc4 --- /dev/null +++ b/docs-site/src/content/docs/es/guides/image-bridge.md @@ -0,0 +1,83 @@ +--- +title: "Puente de imágenes" +description: "Enruta las llamadas a la herramienta alojada image_generation hacia xAI Grok Imagine al usar un proveedor distinto de OpenAI." +--- + + + +## Descripción general + +Cuando se enruta Codex a través de un modelo no OpenAI (Claude, Gemini, Grok, etc.), el `image_generation` **herramienta alojada** normalmente no funciona - se requiere OpenAI 's entorno de ejecución del lado del servidor. El puente de imágenes detecta estas llamadas y las redirige de forma transparente a xAI Grok Imagine, por lo que el modelo con el que estás chateando aún puede generar imágenes. + + + +## Requisitos previos + +- **Activa el puente** con `images.bridgeEnabled: true`. Está desactivado de forma predeterminada para evitar cargos inesperados de xAI; consulta [Configuración](#configuration). +- Añade un proveedor `xai` con una **clave API**. El puente Responses usa el destino de imágenes de xAI del registro (`https://api.x.ai/v1`) e ignora cualquier cambio de `baseUrl` para esas llamadas. OAuth o `ocx login xai` por sí solos **no activan este bucle sidecar**. La misma opción `bridgeEnabled` sí activa el relé independiente de `/v1/images`, que permite al cliente integrado `image_gen` usar Imagine con la autorización de Grok CLI. Consulta [Generación de imágenes integrada](/es/guides/codex-integration/#built-in-image-generation-image_gen). Si falta esa autorización o una clave API de xAI, `/v1/images` devuelve un error y no recurre a ChatGPT. + + El relé solo administra esa ruta si no se ha configurado un proveedor de imágenes: requiere `images.bridgeEnabled` en `true` y que se omita `images.provider`. Si estableces `images.provider` explícitamente, `/v1/images` usa ese proveedor y devuelve sus errores de validación sin volver a intentar mediante xAI. + + ```json + { + "providers": { + "xai": { "adapter": "openai-chat", "apiKey": "xai-…", "authMode": "key" } + } + } + ``` + +- Un modelo no OpenAI seleccionado como su proveedor activo. (Cuando el proveedor activo es OpenAI, la herramienta alojada nativa se usa directamente y el puente se pasa por alto.) + + + +## Configuración + +Las opciones de puente de imagen viven bajo `images` en `~/.opencodex/config.json`. Bridging es **opt-in** - debe configurar `bridgeEnabled: true` para habilitar la generación de imágenes pagada xAI Grok: + +```json +{ + "images": { + "bridgeEnabled": true, + "bridgeModel": "grok-imagine-image-quality", + "maxRounds": 3, + "timeoutMs": 60000 + } +} +``` + +| Opción | Predeterminado | Descripción | +| --- | --- | --- | +| `bridgeEnabled` | `false` | Interruptor maestro. Establecer `true` para permitir el puente. Desactivado por defecto para evitar cargos inesperados de xAI. | +| `bridgeModel` | `grok-imagine-image-quality` | El identificador de modelo de imagen xAI para enviar mensajes. | +| `maxRounds` | `3` | Iteraciones máximas de bucle de generación de imágenes por turno. Fijado a un número entero y fijado a `[0, 10]`; los valores no finitos vuelven a `3`. | +| `timeoutMs` | `60000` | Fecha límite xAI por llamada en milisegundos. Los valores positivos finitos se minimizan y pasan a la solicitud xAI. | +| `artifactsKeepCount` | `200` | Número máximo de archivos retenidos bajo `artifacts/`. Cuando se excede, los archivos más antiguos se eliminan después de cada llamada completada. Establezca en `0` o un valor negativo para deshabilitar la poda. | + + + +## Retención de artefactos + +Las imágenes generadas se escriben en `~/.opencodex/artifacts/`. Para evitar el crecimiento ilimitado del disco en sesiones de larga duración, el directorio se poda automáticamente después de cada llamada de imagen completada (una vez que el lote completo para esa llamada está en el disco): los archivos más antiguos (por tiempo de modificación) se eliminan cuando el recuento excede el máximo configurado (por defecto 200, configurable a través de `images.artifactsKeepCount`). Solo las rutas que sobreviven a la poda se devuelven al modelo. + + + +## Cómo funciona + +El puente de imágenes intercepta únicamente turnos **Responses** que incluyan la herramienta alojada `image_generation` en `tools` de `/v1/responses` al usar un modelo **de otro proveedor que no sea OpenAI**. La herramienta integrada `image_gen` de Codex sigue otra ruta: envía un POST directamente a `/v1/images/generations` o `/images/edits` y usa un relay integrado independiente, descrito en [Integración con Codex](/es/guides/codex-integration/#built-in-image-generation-image_gen). + +1. OpenCodex detecta `image_generation` en `tools` durante el preprocesamiento de la solicitud Responses. +2. Sustituye la herramienta alojada por una **función sintética** que el modelo enrutado puede invocar, en lugar de una herramienta alojada que no puede ejecutar. +3. Cuando el modelo la invoca, OpenCodex intercepta la llamada y envía el prompt a la API de generación de imágenes de xAI. +4. Guarda las imágenes en `~/.opencodex/artifacts/` y devuelve al modelo la **ruta local del archivo** como resultado de la herramienta. +5. El modelo continúa la conversación con la información de la imagen generada y su ubicación. + +Desde la perspectiva del modelo, nada cambió: llamó a una herramienta y obtuvo un resultado. Desde la perspectiva del usuario, la generación de imágenes funciona con cualquier proveedor enrutado en lugar de fallar silenciosamente. + + + +## Limitaciones + +- **Solo xAI Grok Imagine es compatible.** DALL-E y otros proveedores de imágenes se pueden agregar más tarde. +- **La búsqueda web tiene prioridad** cuando la solicitud es apta para el bucle de búsqueda web. Si se solicitan búsqueda y generación de imágenes en el mismo turno apto, se ejecuta la búsqueda y se omite la generación de imágenes. Esto incluye adaptadores `runTurn` aptos, como Cursor, mediante `runTurnWebSearchLoop`. El puente de imágenes solo puede atender esos turnos con ambas herramientas si la búsqueda web no resulta elegible. +- **Se aplican costos de xAI.** La generación de imágenes a través de xAI requiere una suscripción activa a xAI o créditos API. +- **Sólo streaming.** El puente funciona interceptando el flujo de respuesta SSE; las solicitudes con `stream: false` se rechazan con un error 400. diff --git a/docs-site/src/content/docs/es/guides/integrations.md b/docs-site/src/content/docs/es/guides/integrations.md new file mode 100644 index 00000000000..8d43fc2c79a --- /dev/null +++ b/docs-site/src/content/docs/es/guides/integrations.md @@ -0,0 +1,518 @@ +--- +title: "Integraciones" +description: "Conectar opencodex a OpenCode, Pi, Gentle Shell, OMP, Hermes, OpenClaw, Kimi Code, gjc, DeepSeek Harness, MiniMax Code, ZCode, Prime Agent, Aside, Raycast, omo, Cline CLI, Kilo, Command Code y Factory Droid desde el panel — un interruptor por cliente, con una copia de seguridad tomada antes de cada escritura." +--- + +La página **Conectar** escribe el bloque de proveedor de opencodex en el propio archivo de configuración de un cliente y lo elimina de nuevo. Veinte clientes trabajan de esta manera, cada uno con un interruptor: + +| Cliente | Archivo de configuración | Formato | Cuando el cambio entra en vigor | Credenciales | +|---|---|---|---|---| +| OpenCode | `~/.config/opencode/opencode.json` | JSON | Próximo lanzamiento directo | `OPENCODEX_OPENCODE_API_KEY` | +| Pi | `~/.pi/agent/models.json` | JSON | Nuevas sesiones | marcador de posición loopback | +| Gentle Shell | `~/.gentle-shell/agent/models.json` (hogar seleccionado persistente) | JSON | después de reiniciar Gentle Shell | marcador de posición loopback | +| OMP | `~/.omp/agent/models.yml` | YAML | después de reiniciar OMP | `opencodex-loopback` marcador de posición | +| Hermes | `~/.hermes/config.yaml` | YAML | Nuevas sesiones | `OPENCODEX_HERMES_API_KEY` | +| OpenClaw | `~/.openclaw/openclaw.json` | JSON5 | inmediatamente, en una puerta de enlace en ejecución | `OPENCODEX_OPENCLAW_API_KEY` | +| Kimi Code | `~/.kimi-code/config.toml` | TOML | en el reinicio, o `/reload` | marcador de posición loopback | +| gjc | `~/.gjc/agent/models.yml` | YAML | nuevas sesiones, o cuando abres `/model` |marcador de posición de bucle de retroceso no secreto | +| DeepSeek Harness (DSH) | `$DSH_HOME/profiles/desktop/cordis.patch.yml` (por defecto `~/.dsh/profiles/desktop/cordis.patch.yml` ); `$DSH_HOME/settings.yaml` hasta que DSH Desktop cree ese perfil | YAML | recarga caliente | marcador de posición portador de bucle de retorno no secreto | +| MiniMax Code | `~/.minimax/config.yaml` | YAML | nuevas sesiones, o después de abrir el selector de modelos | marcador de posición loopback | +| Prime Agent | `~/.prime/agent/models.json` | JSON | Nuevas sesiones | marcador de posición loopback | +| ZCode | `~/.zcode/v2/provider_config.json` (schemaVersion 1); retroceso legado: `~/.zcode/v2/config.json` | JSON | al reiniciar | marcador de posición loopback | +| Aside | `~/.aside/u//models.json` | JSON | después de cerrar Aside por completo y volver a abrirlo | marcador de posición loopback | +| Raycast | `~/.config/raycast/ai/providers.yaml` | YAML | inmediatamente en guardar - Raycast mira el archivo | ninguno - solo loopback | +| omo (Pi / senpi) | `~/.omo/agent/models.json` | JSON | Nuevas sesiones | marcador de posición loopback | +| Qoder | `settings.json` en `$QODER_CONFIG_DIR`, por defecto `~/.qoder` | JSON | Nuevas sesiones | marcador de posición loopback | +| Cline CLI | `~/.cline/data/settings/providers.json` y hermano `models.json` | JSON pareja | después de detener y reiniciar Cline | marcador de posición loopback | +| Kilo | primero existente `kilo.jsonc`, `kilo.json`, `opencode.jsonc`, `opencode.json`, o `config.json` bajo `~/.config/kilo` | JSONC | Nuevas sesiones | `OPENCODEX_KILO_API_KEY` | +| Command Code | `~/.commandcode/providers.json` (en Windows con el inicio predeterminado: usar `HOME ?? USERPROFILE` solo si no está en blanco y Windows-absoluto, de lo contrario `homedir()`; se conserva una vivienda suministrada por separado; adjuntar `.commandcode\providers.json`) | JSON | Lanzamiento del Command Code | Ninguno - Loopback sin llave ( `apiKey: false` ) | +| Factory Droid | `~/.factory/settings.json` ( `%USERPROFILE%\.factory\settings.json` en Windows) | JSON | inmediatamente a través de la observación de archivos | ninguno - sin llave | + + + +## Gentle Shell + +Elija **Conectar → Gentle Shell**, o utilice los mismos comandos de integración administrada: + +```bash +ocx export --client gentle-shell --json +ocx integration client enable --client gentle-shell +ocx integration client disable --client gentle-shell +``` + +Gentle Shell tiene un destino separado y un historial de reversión de Pi. Solo se gestionan `providers.opencodex`; otros proveedores y preferencias permanecen intactos. Los cambios de catálogo actualizan un bloque ya conectado, sin cambios. Un bloque copiado manualmente existente es un conflicto, no un permiso para sobrescribirlo: inspeccione la vista previa y use la confirmación explícita de sobreescritura solo si tiene la intención de reemplazarla. + +El `home` guardado en `~/.gentle-shell/config.json` selecciona el destino. Gana una ruta personalizada guardada; el modo aislado/por defecto usa `GENTLE_SHELL_HOME` o `~/.gentle-shell/agent`. `GENTLE_SHELL_CONFIG` selecciona una configuración de lanzador alternativa. Estas variables de entorno deben establecerse en el **Proceso OpenCodex**, no solo en un shell posterior. Los selectores deben ser rutas absolutas; las rutas literales `~` y relativas se niegan. Las banderas `gentle-shell --home` únicas no pueden ser descubiertas por un proxy de fondo. + +El modo de enlace o un aliasing de inicio Pi se niega con un remedio de integración Pi; use **Conectar → Pi** para ese archivo compartido en su lugar. OpenCodex no cambia las preferencias del lanzador. Se rechaza una configuración de lanzador ilegible/insegura; la configuración malformada JSON vuelve a ser aislada, coincidiendo con el lanzador. Si mueves una casa conectada, desactívala usando sus selectores originales antes de volver a conectar la nueva. Reinicie Gentle Shell después de una actualización de catálogo. Esta integración conserva la política de exportación de Pi solo loopback y no almacena ninguna clave API real. + +"omo" nombra tres productos que comparten la carpeta `~/.omo`. La pestaña **omo** administra el omo basado en Pi (el motor senpi) a través de `~/.omo/agent/models.json`, como en la tabla anterior. El omo basado en Codex (LazyCodex) tiene su propia sección en la misma pestaña, mostrada solo cuando se detecta LazyCodex, descrita en [omo ( Codex / LazyCodex) modelos de rol](#omo-codex--lazycodex-role-models). OpenCode-based omo (oh-my-opencode) mantiene su propia configuración bajo OpenCode; opencodex no lo lee ni lo escribe. + +Qoder IDE / qodercli admite la exportación y la configuración administrada a través del panel de control y CLI: + +```bash +ocx export --client qoder --json +ocx integration client enable --client qoder +ocx integration client disable --client qoder +``` + +Qoder usa `settings.json` en `QODER_CONFIG_DIR` cuando esa variable está establecida, y `~/.qoder/settings.json` de lo contrario; se rechaza un relativo `QODER_CONFIG_DIR`. Habilitar fusiona las entradas `providers.opencodex` y OpenCodex en `modelConfigs.customModels`, preservando otros proveedores, modelos personalizados y configuraciones. Desactivar elimina las entradas OpenCodex grabadas; la restauración utiliza el flujo de trabajo de instantáneas existente. El modelo predeterminado del proveedor es el primer modelo de la exportación ordenada. Los modelos personalizados utilizan su ventana de contexto de catálogo, volviendo a 128000 tokens de entrada. La clave API generada es un marcador de posición no secreto: la integración de Qoder requiere acceso de bucle de retorno y rechaza un enlace de no bucle de retorno autenticado. Cuando el oyente de bucle de retorno dedicado no autenticado está habilitado, exporta Qoder a ese oyente. `ocx sync` y los cambios de catálogo actualizan una integración de Qoder ya habilitada como los otros clientes administrados. + +Los catálogos generados incluyen solo modelos habilitados de cada selección de proveedor. Esto se aplica tanto a las descargas como a las integraciones administradas, incluidas Pi y Aside. La lista de modelos de administración aún muestra la lista completa para que pueda habilitar modelos adicionales. + +`ocx uninstall` deshabilita las integraciones registradas, incluyendo todos los perfiles de propiedad de Aside, antes de eliminar el estado de recuperación de OpenCodex. La propiedad ilegible, el registro de perfil faltante o una edición en conflicto detiene esa eliminación. La limpieza es secuencial: las inhabilitaciones anteriores no se deshacen cuando una posterior falla. Si la compensación también falla, un archivo cliente puede dejarse en un estado intermedio. Inspeccione los archivos del cliente reportados y las instantáneas de recuperación retenidas antes de volver a intentar; el estado retenido no significa que todos los clientes se restauraron o se dejaron sin cambios. + +Para los preajustes incorporados de Gajae, mantenga la opción de enrutamiento en `~/.gjc/agent/config.yml`: + +```yaml +modelProfile: + proxyProvider: opencodex + proxyMode: always +``` + +Mantenga su `modelProfile.default` elegido para aplicarlo cuando se inicie la llanura `gjc`. La integración administrada posee solo `providers.opencodex` en `models.yml`; actualizar o deshabilitar ese proveedor no reescribe su opción preestablecida. Actualizar la integración después de cambiar la selección del modelo exportado. + +Los modelos GJC con una escalera de razonamiento-esfuerzo compatible exportan `reasoning: true`, `thinking.levels` y `compat.supportsReasoningEffort`, por lo que GJC puede ofrecer una opción de esfuerzo. Los modelos nativos Codex reciben su escalera estándar incluso cuando el catálogo la omite. Los modelos sin una escalera conocida omiten estos campos; `none` y `ultra` no se ofrecen porque `none` no envía ningún esfuerzo y `ultra` se pliega a `max` en el cable. Actualice la integración para actualizar estas opciones de modelo. + +La integración administrada de OpenCode controla dos bloques: `provider.opencodex` (OpenCode V1) y `providers.opencodex` (OpenCode V2). Ambos incluyen los mismos esfuerzos de razonamiento y valores predeterminados declarados por modelo. El bloque heredado usa un mapa de variantes y las opciones del modelo; V2 usa la configuración del modelo y un array nativo de variantes. Los dos se escriben y mantienen sincronizados, identifican los mismos proveedores y modelos, y OpenCode V2 los combina en una sola entrada. Aplicar, Actualizar, Desactivar y Restaurar actúan sobre ambos bloques. Los demás proveedores, agentes, atajos de teclado y entradas MCP se conservan. + +Ambos fragmentos se construyen a partir de los metadatos del modelo canónico efectivo, al igual que la exportación de Kilo y el lanzador `ocx opencode`. Una anulación explícita personalizada siempre gana, y una escalera que se vacía permanece vacía; una escalera de razonamiento o predeterminada nunca se inventa para un modelo que no declara ninguno. Un límite de contexto autorizado se lleva con un presupuesto de salida al lado: un valor de salida conocido - explícito o de metadatos de catálogo - gana, de lo contrario el esquema requerido 32000 reserva sujeta al contexto, y sin un contexto autorizado se omite todo el bloque de límite. Las capacidades, escalas de esfuerzo, valores predeterminados y un límite de entrada opcional aparecen solo cuando se conocen; el objeto de capacidades nativas del bloque V2 requiere un valor de herramientas conocido, por lo que cuando se desconoce el soporte de la herramienta se omite por completo en lugar de escribirse parcialmente, y la modalidad heredada permanece. Tampoco añade un esfuerzo seleccionable. Las variantes seleccionables anulan el valor predeterminado por modelo: `none` incluido, que se ofrece solo cuando la escalera declarada del propio modelo lo contiene. Sea lo que sea que el cliente seleccione, la política de razonamiento ascendente del proxy aún rige la solicitud que la abandona. + +El soporte de DSH administrado tiene un piso de compatibilidad de **DSH 0.1.0-rc.6**. DSH 0.1.7+ lee las rutas del proveedor desde `[id=llm-pi-ai].config.providers.opencodex` en el parche de perfil de escritorio, `$DSH_HOME/profiles/desktop/cordis.patch.yml`, que recarga DSH en caliente. OpenCodex escribe esa fila cuando existe el perfil de escritorio y su parche. Si existe `$DSH_HOME/profiles/desktop/package.json` pero falta `cordis.patch.yml`, Aplicar se niega: cree `cordis.patch.yml` que contiene `[]` (el parche vacío que DSH escribe para un nuevo perfil), luego habilite la integración nuevamente. Solo cuando no hay perfil de Escritorio, OpenCodex usa `llm-pi-ai.providers.opencodex` en `$DSH_HOME/settings.yaml`. OpenCodex solo posee ese fragmento de proveedor: Aplicarlo y Actualizarlo, Desactivarlo lo elimina y Restaurar devuelve una instantánea grabada. Estas operaciones no cambian el modelo predeterminado del usuario o el proveedor nativo `deepseek-official`. La integración DSH administrada es actualmente solo loopback y nunca escribe una credencial real. + +MiniMax Code sigue `MINIMAX_DATA_DIR`, luego `MAVIS_DATA_DIR`, antes de caer de nuevo a `~/.minimax`. Su bloque administrado posee solo `custom_provider.opencodex`. No cambia `defaultModel`, la fuente de credenciales MiniMax seleccionada o el inicio de sesión MiniMax del usuario. Elija una entrada `custom_provider:opencodex/` en MCode después de conectarla. La actualización de la integración también actualiza las ventanas de contexto autorizadas por modelo y las opciones de esfuerzo de razonamiento; se omiten las capacidades desconocidas y se conserva el esfuerzo actual de MCode. + +Prime Agent sigue a `PRIME_AGENT_CODING_AGENT_DIR` antes de caer de nuevo a `~/.prime/agent`; un valor relativo es rechazado por lo que el proxy y el agente no pueden estar en desacuerdo sobre qué archivo se quiere decir. Su bloque administrado posee solo `providers.opencodex`, por lo que otros proveedores y cualquier `modelOverrides` que haya establecido permanecen intactos. Prime Agent lee `models.json` cuando se inicia una sesión, así que inicie una nueva sesión después de conectarla. + +Aside mantiene un catálogo de modelos separado para cada perfil registrado, incluidos los perfiles locales. OpenCodex enumera todos los perfiles registrados, incluidos los perfiles locales, y puede sincronizarlos o controlar un perfil a la vez. Cambiar una integración nunca cambia la cuenta activa de Aside. Una conexión anterior de Aside habilita todos los perfiles de forma predeterminada; las exclusiones individuales sobreviven a las sincronizaciones posteriores. + +Una advertencia específica de Aside: la aplicación en ejecución reescribe el propio `models.json`, por lo que se cierra y vuelve a abrir completamente Aside después de aplicar, de la misma manera que Claude Desktop necesita un reinicio. El bloque de Aside es solo loopback y nunca lleva una credencial real. + +La integración administrada de Raycast soporta **macOS y Windows**. Custom Providers es una característica **Raycast Pro**: en un plan gratuito, el archivo todavía está escrito, pero `ocx integration client status --client raycast` y la página **Conectar** informan una advertencia, porque Raycast no lo leerá. En macOS o Windows, abra Raycast → Ajustes → AI → **Revelar proveedores Config** una vez que exista la carpeta `ai`. En estas plataformas compatibles, opencodex utiliza esa carpeta como su señal de instalación e informa que el cliente no está instalado hasta que existe. Linux no es compatible, incluso si la carpeta existe. + +El campo de estado `aiDirPresent` informa solo si existe `~/.config/raycast/ai`, independientemente de si la aplicación Raycast está instalada o si la plataforma es compatible. No prueba que Raycast esté instalado o sea utilizable. El CLI imprime `plan` en una línea separada y agrega la instrucción de configuración macOS / Windows cuando `aiDirPresent` es falso; `--json` preserva el estado en bruto, incluyendo el bloque anidado `raycast`. Raycast lee `~/.config/raycast/ai/providers.yaml` en macOS y Windows por igual y no honra `XDG_CONFIG_HOME`, por lo que ese camino no es reubicable. + +El bloque administrado es un elemento, `id: opencodex`, en la secuencia `providers` del archivo: `name: OpenCodex`, `base_url: http://:/v1`, y cada modelo enrutado con su `abilities`: el exportador establece `tools` y `system_message` a `true` como una convención cliente-exportación, `vision` sigue las modalidades de entrada del catálogo, `reasoning_effort` se establece cuando el modelo tiene una escalera de esfuerzo y `temperature` se apaga para los modelos de razonamiento. Otros proveedores en el archivo se conservan, y deshabilitar elimina solo el elemento OpenCodex. Raycast recoge el cambio tan pronto como se guarda el archivo, no se necesita reiniciar; los modelos aparecen en el selector de modelos de Raycast agrupado bajo **OpenCodex**. Raycast apoya `api_keys` opcional, pero OpenCodex intencionadamente los omite y rechaza objetivos nonloopback o autenticados por la admisión; esta integración no puede suministrar el encabezado de admisión requerido de OpenCodex. + +La preferencia privada macOS es solo una sugerencia Pro de asesoramiento; Windows nunca lo lee e informa que el plan es desconocido. La detección de planes no autoriza ni bloquea una escritura. Los metadatos de exportación no tienen un indicador autorizado de soporte de herramientas, por lo que `tools: true` no prueba que todos los modelos enrutados soporten herramientas. Las banderas de visión y esfuerzo siguen los metadatos del catálogo; desactivar la temperatura para una escalera de esfuerzo es un comportamiento de exportación conservador. Se conservan los valores de los proveedores; No se garantiza que el formato YAML y los comentarios sobrevivan. El formato está documentado en [manual.raycast.com/ai/proveedores personalizados](https://manual.raycast.com/ai/custom-providers). + +Las exportaciones y descargas del panel de Raycast CLI utilizan la política de destino y admisión del servidor en ejecución, incluido un oyente de bucle de retorno no autenticado configurado. `ocx ensure` no actualiza Raycast desde su instantánea de configuración guardada: eso puede diferir del servidor en ejecución. El inicio del servidor y la sincronización explícita siguen siendo las rutas de actualización del catálogo. + + +Cursor tiene una pestaña, pero no es uno de estos interruptores. Regular Cursor llama a los puntos finales personalizados desde su propio backend, por lo que un proxy de loopback es inalcanzable sin un túnel público, y la construcción de inferencia privada separada de Cursor se configura dentro de Cursor. La pestaña **Cursor** es de solo lectura: detecta qué compilación está instalada, muestra la URL base y la clave API para pegar en Cursor e informa la última solicitud Cursor realizada al proxy. Véase [Cursor Inferencia privada](/es/guides/cursor-private-inference/). + +Los caminos honran el propio entorno de cada cliente anulan donde tiene uno. Para OMP, `OMP_PROFILE` gana sobre `PI_PROFILE` por presencia, incluso cuando está explícitamente vacío. Un perfil con nombre utiliza `PI_CONFIG_DIR` como un nombre de directorio en relación con el hogar del usuario e ignora `PI_CODING_AGENT_DIR`; sin un perfil con nombre, `PI_CODING_AGENT_DIR` gana. OMP soporta cabeceras a nivel de proveedor, pero esta integración inicial es deliberadamente solo bucle; cableado remoto `x-opencodex-api-key` es diferido. Los caminos `HERMES_HOME`, `KIMI_CODE_HOME` y `XDG_CONFIG_HOME` reubicados se siguen de manera similar en lugar de adivinarse. La tabla muestra el valor predeterminado de cada cliente. + +Para los modelos nativos OpenAI, el bloque OMP generado selecciona su nivel de modelo Responses API, preservando la entrada de imágenes y los controles de esfuerzo de razonamiento. Los modelos enrutados conservan el dialecto Chat Completions del proveedor para que sus adaptadores existentes sigan siendo compatibles. + +OpenClaw tiene varios, y hacen diferentes trabajos. `OPENCLAW_CONFIG_PATH` selecciona el archivo; `OPENCLAW_STATE_DIR`, `OPENCLAW_PROFILE` y `OPENCLAW_HOME` seleccionan el directorio de estado, que es también lo que la detección observa, por lo que un perfil o una casa reubicada aún se lee como instalado, mientras que una anulación de ruta de configuración mueve solo el archivo. Si todavía está en el diseño anterior `.clawdbot`, también se encuentra: el directorio moderno gana cuando existe y el heredado se usa cuando es el único allí. + +Estos deben ser **Caminos absolutos** o comenzar con `~`. Se rechaza uno relativo en lugar de resolverlo, porque significaría cualquier directorio en el que se inicie cada proceso, y esa ruta se almacena con la copia de seguridad, por lo que tiene que nombrar el mismo archivo mañana que hoy. + +opencodex lee esto desde su propio entorno. Si su puerta de enlace se ejecuta con un perfil o una casa reubicada, inicie opencodex con el mismo conjunto de variables, o seguirá correctamente una instalación diferente. + + + +## Las otras cinco superficies no son interruptores + +**API Llaves** administra las credenciales propias de opencodex y no es un cliente en absoluto. **Codex CLI** es cableado por el propio servicio proxy - a partir de opencodex se aplica, deteniéndolo restaura el enrutamiento nativo - por lo que no hay nada que cambiar por archivo. **Claude** mantiene su propio indicador de habilitación y el flujo Guardar/Aplicar del Escritorio, y **Grok Build** mantiene su valla de modelo select-then-apply. Esas semánticas son anteriores a esta característica y no cambian. **Cursor** no escribe nada en absoluto: su pestaña muestra la detección, los valores de la puerta de enlace y la última solicitud vista, y el resto ocurre dentro de Cursor Private Inference. + + + +## Reversión + +Cada escritura exitosa toma una instantánea de su archivo *primero*, por lo que el estado que tenía siempre es recuperable: + +- **Deshacer** aparece en la operación más reciente cuando su archivo aún coincide con lo que escribimos. +- **Restaurar este punto...** aparece en operaciones anteriores, o cuando el archivo cambió después de esa operación. Restaurar a través de tal cambio pide una segunda vez antes de reemplazar sus ediciones más recientes, y también las respalda, para que la propia restauración también se pueda deshacer. +- Se mantienen 10 copias de seguridad por cliente. Más allá de eso, los archivos de instantáneas más antiguos se eliminan y sus filas de historia leen **La copia de seguridad expiró**. + +Desactivar elimina solo las entradas opencodex registradas como propias. Si su archivo ha cambiado Después de que lo escribimos, lo que sucede depende de si nuestras propias entradas aún están intactas. y en el formato del archivo. Para configuración estrictas JSON (OpenCode, Pi), una edición **al lado** +nuestro bloque — agregando un servidor MCP, un proveedor de su propio — se muestra como **Actualización necesaria**: refrescante se fusiona alrededor de sus entradas y las mantiene, aunque el formato puede ser normalizado. La excepción es algo JSON no puede reescribir exactamente — un no-finito número como `1e999`, un número que una reescritura redondearía (un entero muy grande, o un tan pequeño que colapsa a cero), `-0`, la misma clave escrita dos veces en un objeto, o anidando más profundamente que 1000 niveles — que bloquea el interruptor en su lugar, por lo que nada se cambia o se cae silenciosamente. +**OMP, DSH y Hermes** no se ven afectados por las ediciones de hermanos también, por una razón diferente: sus escritores parchear solo sus propios rangos de proveedores administrados en byte, por lo que el resto de la El archivo nunca se reescribe. Para el resto de formatos que pueden contener comentarios (OpenClaw, Kimi Code, gjc, MiniMax Code, Raycast — JSON5 y TOML escritos como documentos completos, o genéricos YAML sin preservación de la fuente), o cada vez que nuestras propias entradas fueron editadas, el interruptor se bloquea y desactiva. que adivinar qué ediciones eran tuyas. + +Esa cerradura ya no es un callejón sin salida. Un cliente en conflicto muestra **Sustituir** al lado de su interruptor, tanto en la tarjeta de visión general como en la propia página del cliente. Reemplaza lo que contiene nuestra configuración con el bloque opencodex que escribiría, y pregunta primero: el diálogo nombra el archivo, dice lo que se pierde y señala la instantánea que permite deshacer el reemplazo. El switch en sí permanece bloqueado, porque el switch no puede saber qué ediciones pretende mantener, solo usted puede decirlo. Nada más está relajado: un archivo que no podemos analizar, o uno cuya estructura no podemos razonar, todavía se niega. + + + +## Afinidad de sesión Hermes + +El bloque generado `providers.opencodex` incluye `session_affinity_header: session-id` para todos los modelos. Conserva ese valor salvo que quieras únicamente correlacionar registros. Si cambias `session_affinity_header` a `x-hermes-conversation-id`, Hermes envía ese encabezado en lugar de `session-id`. OpenCodex usa `x-hermes-conversation-id` solo como alternativa para correlacionar registros de solicitudes, no como identidad para enrutamiento nativo ni para terminar turnos. Por tanto, el cambio elimina la afinidad de sesión nativa y la asignación de carril, aunque permite correlacionar los bucles del agente en los registros. El ajuste nombra un encabezado; Hermes aporta el identificador dinámico de la conversación. OpenCodex no escribe un identificador estático compartido ni cambia `api_mode` para activar la afinidad. + +Utilice una versión de Hermes compatible con [Opciones de solicitud por proveedor](https://hermes-agent.nousresearch.com/docs/user-guide/configuring-models#per-provider-request-options). Las versiones anteriores pueden ignorar o descartar la opción; una configuración válida por sí sola no prueba que Hermes envíe el encabezado. El aislamiento de la conversación, el linaje de compactación y las solicitudes auxiliares / infantiles siguen la semántica de afinidad de Hermes. Esta configuración no garantiza una tasa de éxito de caché particular. + +Para una integración administrada existente, abra **Conectar → Hermes**, revise **Aplicar** y confirme la actualización. Hasta entonces, muestra **Actualización necesaria** y la actualización implícita del catálogo lo deja sin cambios, incluida su lista de modelos. Leer la página no actualiza la configuración. Después de aplicar, la actualización normal del catálogo se reanuda y conserva la configuración; **Sustituir** también lo incluye. + +Si ya agregó exactamente `session_affinity_header: session-id` dentro del bloque administrado, Apply puede adoptarlo cuando todas las demás configuraciones administradas aún coincidan con el registro de propiedad. Esta es la estrecha excepción a la regla de conflicto anterior: otras ediciones, un nombre de encabezado diferente o un bloque sin un registro de propiedad coincidente aún requieren resolución de conflictos. La configuración y los comentarios YAML no relacionados permanecen intactos, y el flujo de trabajo de instantánea y restauración existente se aplica a la actualización. + + + +## Vista previa y confirmación de cambios + +En el panel, Aplicar, Reemplazar, Deshabilitar y Restaurar comienzan con una vista previa. El cuadro de diálogo muestra exactamente qué configuración administrada cambiará, incluidas las rutas de cambio limitadas y si cada cambio agrega, actualiza o elimina un valor. Revisa ese plan antes de confirmarlo. + +Cuando un plan informa que no hay cambios, significa que el documento del cliente administrado ya tiene el estado solicitado. Para un perfil de Aside seleccionado, la confirmación puede guardar la preferencia de sincronización de ese perfil aunque el documento administrado no cambie. + +Si el archivo cambia después de revisarlo, la escritura se rechaza como obsoleta. El cuadro de diálogo reemplaza el plan anterior por el actualizado y le pide que confirme nuevamente; nunca vuelve a intentar la escritura automáticamente. Si una vista previa no está disponible temporalmente, vuelva a cargar la página normalmente e inicie la acción de nuevo. + +Aside utiliza la misma vista previa y flujo de confirmación para un perfil seleccionado a la vez. **Sincronizar todos los perfiles** sigue siendo una acción masiva separada y no está vinculada a una vista previa combinada. + + + +## Qué esperar, honestamente + +**Los archivos de configuración administrados están limitados a 4 MiB (4,194,304 bytes UTF-8).** El lector de integración compartida rechaza los archivos más grandes como inseguros para leer, y el escritor rechaza una configuración combinada que excede el mismo límite con `write_failed`, dejando la configuración original sin cambios. El marcador de recuperación de Cline también tiene este límite; incluye el contenido de antes y después de ambos archivos más metadatos, por lo que Cline puede alcanzar el límite incluso cuando cada archivo individual es menor de 4 MiB. + +Realice una copia de seguridad de la configuración del cliente usted mismo, luego elimine las entradas innecesarias o reduzca la lista de modelos exportados antes de volver a intentar. **Sustituir** no pasa el límite. Si la configuración debe permanecer más grande, adminístrela manualmente en lugar de usar el interruptor Conectar. + +**El formato generalmente no se conserva.** La aplicación analiza una configuración y la vuelve a escribir, por lo que JSON, JSON5 y TOML pueden reformatearse y los comentarios en JSON5 o TOML se pierden. OMP, DSH y Hermes son las excepciones: OMP y Hermes parche sólo `providers.opencodex`. DSH corrige solo `[id=llm-pi-ai].config.providers.opencodex` en el parche de perfil de escritorio, o `llm-pi-ai.providers.opencodex` en `settings.yaml` cuando no hay perfil de escritorio. Sus redactores de YAML conservan comentarios de proveedores no relacionados y formatean byte por byte. Si ese rango de fuente exacto no se puede identificar de manera segura, la operación se niega. Para otros clientes, utilice Restaurar cuando necesite los bytes de archivo anteriores: la instantánea es una copia literal. + +**Si un valor no puede ser reescrito fielmente, el interruptor se niega.** El viaje de ida y vuelta cubre los tipos de valor que estos formatos usan en la práctica, y donde no lo hace - un archivo TOML usando `inf` o `nan`, por ejemplo, que el analizador sintáctico disponible para nosotros no puede leer con precisión - aplicando paradas y lo dice en lugar de escribir un valor cambiado y llamarlo éxito. Verá el archivo con nombre y nada en el disco se habrá movido. La edición de ese archivo a mano todavía funciona; es solo nuestra reescritura automática la que disminuye. + +Las fechas y horas TOML también rechazan las reescrituras administradas: el paso de combinación convertiría estos valores escritos en cadenas cotizadas. Esto incluye valores dentro de matrices y tablas en línea. Las cadenas de fecha citadas siguen siendo compatibles; una fecha no citada debe conservarse editando la configuración manualmente. + +**Pi, Kimi Code, gjc, MiniMax Code, Prime Agent, Aside, Raycast, omo y la integración DSH administrada solo funcionan contra un enlace de bucle.** Los primeros cuatro no tienen campo de configuración para el encabezado `x-opencodex-api-key` que requiere un enlace sin bucle. DSH tiene un mapa de cabeceras genérico, pero rc.6 no documenta esa cabecera de admisión dedicada como un contrato de integración compatible, por lo que el escritor administrado falla en lugar de adivinar. El bloque de proveedor de Prime Agent acepta encabezados, pero el cableado remoto de credenciales se aplaza desde su integración inicial. Dales acceso de loopback a través de un túnel SSH o un reenviador local que agregue el encabezado. + +**La integración OMP generada también es deliberadamente solo bucle.** OMP admite encabezados a nivel de proveedor, pero esta integración inicial no emite cableado remoto de credenciales `x-opencodex-api-key`. La configuración remota manual de OMP está fuera de la integración administrada por ahora. + +**Kimi El código no puede contener una referencia de entorno,** por lo que su configuración lleva un marcador de posición `opencodex-loopback` en lugar de una clave. Nunca se escribe una credencial real en ninguna configuración de cliente. + +**Para `ocx opencode`, el proveedor del lanzador bloquea la victoria.** Ese lanzador inyecta `provider.opencodex` y `providers.opencodex` a través de `OPENCODE_CONFIG_CONTENT`, que supera a las mismas entradas en el disco - el resto de su configuración de código abierto todavía se aplica como de costumbre. Esos bloques se construyen a partir de los mismos metadatos de modelos canónicos efectivos que las exportaciones, por lo que el lanzador y la integración administrada describen los mismos modelos, límites y opciones de razonamiento. El interruptor aquí es lo que importa cuando se inicia `opencode` directamente. + + + +## Desde la terminal + +Las mismas operaciones están disponibles sin rumbo: + +```bash +ocx integration client status +ocx integration client enable --client hermes +ocx integration client disable --client hermes +ocx integration client history --client hermes +ocx integration client restore --op [--confirm-drift] +``` + + + +### Previsualizar y enlazar una escritura de terminal + +Los comandos directos existentes siguen siendo compatibles. Para vincular una escritura a una observación revisada, inspeccione el estado y guarde primero una vista previa: + +```bash +ocx integration client preview --help +ocx integration client status --client hermes --json +ocx integration client preview --client hermes --operation apply --json > hermes-preview.json +``` + +Revisa `state`, `foreignEdit`, los cambios estructurales de `changes`, `canApply` y `willChange`. Una vista previa válida que rechaza aplicar el plan, o que no propone cambios, termina con código 0: la inspección tuvo éxito y no se aplicó nada. El plan no contiene valores secretos ni el diff completo de los archivos. Usa la evidencia pasiva del catálogo ya disponible y nunca actualiza los proveedores de forma oculta. Si el catálogo no está disponible, resuelve ese problema por separado antes de solicitar otra vista previa. + +Solo después de revisar un plan aplicable y elegir la escritura: + +```bash +PLAN_FINGERPRINT="$(jq -er 'select(.canApply == true) | .fingerprint' hermes-preview.json)" +ocx integration client enable --client hermes --plan-fingerprint "$PLAN_FINGERPRINT" --json +ocx integration client status --client hermes --json +``` + +La huella sirve para comprobar la concurrencia; no concede autorización. La confirmación acepta `pN:` seguido de 32 dígitos hexadecimales en minúscula. Un plan rechazado con `pN:unbound` no se puede confirmar. Repite exactamente el cliente, la acción, el perfil y las opciones de la vista previa. La operación `overwrite` corresponde a habilitar con `--overwrite-conflict`; `disable`, a deshabilitar. Si la observación quedó obsoleta, la confirmación sale con código 5, explica en stderr cómo obtener una nueva vista previa y deja stdout vacío. Nunca adopta automáticamente una huella de reemplazo ni reintenta. Los demás errores usan los códigos 2 para uso incorrecto, 4 para recurso no encontrado y 1 para errores de ejecución o datos mal formados, con un mensaje seguro en stderr en lugar de un objeto de error JSON. + + + +### Inspeccione la deriva de restauración antes de reemplazarla + +Utilice una historia real opId; `op-example` abajo es ficticio: + +```bash +ocx integration client history --client aside --profile 1 --json +ocx integration client restore --op op-example --client aside --profile 1 --preview --json +``` + +Si se rechaza la deriva, inspeccione las ediciones. Al reemplazarlos se pretende explícitamente, vista previa con `--confirm-drift`, revisar, a continuación, vincular esa misma intención: + +```bash +ocx integration client restore --op op-example --client aside --profile 1 --preview --confirm-drift --json > restore-preview.json +``` + +Después de la revisión: + +```bash +RESTORE_FINGERPRINT="$(jq -er 'select(.canApply == true) | .fingerprint' restore-preview.json)" +ocx integration client restore --op op-example --client aside --profile 1 --confirm-drift --plan-fingerprint "$RESTORE_FINGERPRINT" --json +ocx integration client status --client aside --profile 1 --json +``` + +Aparte de vista previa / escrituras vinculadas requieren un perfil, no un objetivo agregado. La restauración genérica omite el cliente/perfil; el servidor deriva el cliente no auxiliar de opId. El plan devuelto no contiene opId o todas las entradas de comandos originales, así que mantenga ese contexto. `--preview` no puede combinarse con `--plan-fingerprint`. + + + +### Retirar un registro de recuperación antiguo + +Esto retira permanentemente el registro y la copia de seguridad; no restaura ni deshabilita la integración. Después de inspeccionar el historial y elegir perder ese punto de recuperación: + +```bash +ocx integration client history remove --op op-example --client aside --profile 1 --yes --json +ocx integration client history --client aside --profile 1 --json +``` + +Utilice el opId seleccionado. Ningún selector se dirige a la revista global; `--client aside` +direcciones agregar el historial de Aside y opcional `--profile` Lo acorta. Otro cliente Los selectores son rechazados para su eliminación. La última fila está protegida. Un recibo con +`snapshotRemoved:false` se ha comprometido la jubilación con limpieza incompleta y salida 1; no es reversión y no debe desencadenar la eliminación repetida. `journal remove` Es un alias. + +`--overwrite-conflict` es la forma terminal de **Sustituir**: + +```bash +ocx integration client enable --client zcode --overwrite-conflict +``` + +Como `--confirm-drift`, nunca se asume - sin él un conflicto todavía se rechaza. Se aplica solo a `enable`; forzar un *desactivar* sobre un conflicto eliminaría un bloque que nunca escribimos, por lo que la combinación es rechazada. + +Para MiniMax Code, conecte el proveedor una vez y ejecute a través del envoltorio verificado: + +```bash +ocx integration client enable --client mcode +ocx mcode +``` + +Una vez conectados, `ocx sync` y `POST /api/sync` actualizaron los catálogos MCode, Pi, Aside, Raycast, omo, OpenCode y Kilo con la selección actual del modelo, las ventanas de contexto y las escaleras de esfuerzo de razonamiento. El inicio proxy actualiza un catálogo de Raycast propio. Los cambios en la visibilidad del modelo, la selección del proveedor o los ajustes preestablecidos también actualizan los catálogos Pi, Aside, Raycast, omo, OpenCode y Kilo conectados. Los bloques perdidos, editados en el extranjero o inseguros permanecen intactos, al igual que los bloques de propiedad anterior que eliminó manualmente. Un perfil Aside habilitado es una excepción a la actualización habitual de solo propiedad: si existe su directorio de cuenta y nunca ha tenido un bloque propio, la sincronización puede crear su primer bloque cuando esa ranura está vacía. De forma predeterminada, una conexión anterior de Aside habilita este comportamiento para todos los perfiles registrados. La sincronización no crea directorios de cuenta faltantes ni reemplaza los bloques manuales. Una actualización rechazada o superpuesta se informa por separado para cada cliente. Inicie una nueva sesión de Pi, OpenCode o Kilo o salga completamente y vuelva a abrir. Aparte de cargar el archivo actualizado. Además de la actualización requiere un [proxy de ejecución compatible](#aside-profile-controls). + +Si Models informa **"Selección de modelo guardada"** junto con una advertencia de actualización del cliente, la selección ya está guardada; no se pudieron actualizar uno o más archivos de cliente. La advertencia nombra al cliente afectado y al perfil de Aside, cuando corresponda, y explica el rechazo. Abra **Conectar** para inspeccionar ese cliente o perfil antes de comenzar una nueva sesión. Resuelva el problema reportado, luego vuelva a intentar `ocx sync`; una operación de superposición debe terminar primero. Si la advertencia incluye una ruta de respaldo o dice que la recuperación no terminó, inspeccione ese estado de recuperación antes de volver a intentarlo. Una selección exitosa guardar solo no confirma la recuperación de archivo de cliente. + +La plataforma separada MiniMax CLI (`mmx`) no es una integración de archivos. Sus comandos de texto usan el punto final compatible con MiniMax de Anthropic, por lo que OpenCodex proporciona un lanzador aislado de credenciales y solo loopback: + +```bash +ocx mmx text chat --model anthropic/claude-opus-5 --message "Hello" +ocx mmx text repl --model openai/gpt-5.6-sol +``` + +Sólo `mmx text chat` y `mmx text repl` están representados. Ejecute los comandos `mmx` para MiniMax -native image, video, speech, music, visión, search, quota, auth, config, file y update. El contenedor utiliza una configuración temporal que contiene solo un marcador de posición de bucle de retroceso no secreto; nunca carga sus credenciales `~/.mmx` OAuth o API -clave, y rechaza las anulaciones `--api-key`, `--base-url` y `--region`. Consulte [MiniMax clientes](/es/guides/minimax/) para conocer el flujo de trabajo y los límites completos. + +`--confirm-drift` nunca se asume. Si el archivo cambió después de la operación que está restaurando, el comando se niega y le dice, porque reemplazar sus ediciones más recientes es su decisión de hacer. + +Los detalles del cliente se verificaron con el formato de configuración de cada proyecto; consulte las notas de investigación en `devlog/_fin/260802_client_toggle_api/002_client_toggle_matrix.md` para ver qué se verificó y cuándo. + + + +## Aside controles de perfil + +Aparte de los controles de perfil y la actualización de Aside realizada por `ocx sync` requieren un proxy ocx en ejecución que admita las API de perfil de Aside. La actualización del CLI por sí sola no actualiza un proxy que ya se esté ejecutando. Si el proxy no está disponible o es demasiado antiguo, la operación Aside no puede completarse; el CLI nunca vuelve a escribir los archivos de perfil Aside localmente. + +Actualice la instalación ocx utilizada por el proxy y luego reinicie el proxy (o inícielo si se detiene). Reintentar `ocx sync` o el comando de perfil. Después de que los archivos de perfil se actualicen correctamente, salga completamente y vuelva a abrir Aside para que cargue los nuevos catálogos. + +```bash +ocx integration client status --client aside --json +ocx integration client enable --client aside +ocx integration client disable --client aside --profile 1 +ocx integration client history --client aside --profile 1 +ocx integration client restore --client aside --profile 1 --op +``` + +El número de perfil es el ID de cuenta mostrado por el comando status. Omitir `--profile` en una palanca de Aside aplica el estado deseado a cada perfil registrado. Un cambio de perfil deja a los hermanos sin cambios. La configuración de sincronización deseada se guarda antes de que cambie el archivo; se informa del estado real y de cualquier rechazo para cada perfil. Un resultado parcial de una operación sobre varios perfiles no significa que todos se hayan actualizado: la CLI termina con un código distinto de cero. Deshacer restaura la intención de sincronización del perfil seleccionado, así como su archivo, por lo que una sincronización posterior no invierte silenciosamente Deshacer. + +El [perfil API](/es/reference/management-api/#aside-profile-controls) devuelve HTTP 200 para una operación a granel exitosa y HTTP 207 con `ok: false` si cualquier perfil se niega. Inspeccione cada entrada en `results`: los perfiles exitosos no se revierten cuando otro falla. La configuración deseada permanece guardada, así que vuelve a intentarlo después de abordar el perfil afectado en lugar de asumir que todo el cambio falló. Si se produce un error al guardar esas configuraciones, no se cambiarán los archivos de perfil. + +Para una actualización específica de los perfiles de Aside elegibles, en lugar de una amplia sincronización de catálogo: + +```bash +ocx integration client sync --client aside --json +ocx integration client status --client aside --json +``` + +Esto utiliza el propietario certificado existente de Aside y no tiene un selector de perfil o reserva local. `{results:[]}` sale de 0 y significa que no hay perfiles elegibles, no escrituras aplicadas. Cualquier fila fallida devuelve la salida 1 mientras los perfiles exitosos permanecen actualizados. Preservar el rechazo por perfil, residual y por separado etiquetaron la información de copia de seguridad redactada; inspeccionar el perfil afectado antes de volver a intentar. Esta actualización es independiente del flujo de trabajo de previsualización/mutación vinculado de cada perfil. + +Sincronizar actualiza solo los perfiles cuya preferencia de sincronización está activada, por lo que un resultado vacío no es un error. Si `ocx integration client status --client aside` muestra un perfil como `off (stale)`, el estado imprime los comandos para volver a conectarlo: revise `ocx integration client preview --client aside +--operation apply --profile N` y ejecute `ocx integration client enable --client aside --profile N` solo si la vista previa permite el cambio y usted lo acepta. Nada se vuelve a habilitar automáticamente. Un bloque `asideProfileSync` mal formado en `config.json` desactiva cada perfil y registra una advertencia cuando se carga la configuración. + +Cada perfil tiene una propiedad e historia separadas. Se rechazan las ediciones de usuarios existentes, las rutas inseguras y los catálogos vinculados; los controles explícitos existentes de sobreescritura y confirmación de deriva permanecen disponibles. Sal completamente de Aside y vuelve a abrirlo para que cargue los archivos de modelos actualizados. + + + + +## ZCode 3.14 y posteriores + +De forma predeterminada, ZCode 3.14 almacena sus proveedores personalizados en `~/.zcode/v2/provider_config.json` y deja `~/.zcode/v2/config.json` accesible solo a través de una importación de una sola vez que se ejecuta cuando falta el nuevo archivo. ZCode crea el nuevo archivo la primera vez que se ejecuta, por lo que en cualquier instalación que se haya lanzado, la importación ya está gastada y una escritura a `config.json` no alcanza nada. + +ZCode puede reubicar su raíz de datos con un `dataBaseDir` absoluto en `~/.zcode/v2/setting.json`. Este archivo bootstrap siempre se queda bajo la casa predeterminada; el almacén del proveedor se mueve a `/.zcode/v2/provider_config.json`. `ZCODE_DATA_DIR` tiene prioridad y nombra directamente la raíz `.zcode`, mientras que `ZCODE_PERSONAL_PROVIDER_CONFIG_FILE` tiene prioridad para el archivo del proveedor. `ZCODE_DATA_BASE_DIR` es un selector nativo separado y no es un alias para `ZCODE_DATA_DIR`. + +Los ajustes de arranque ilegibles, mal formados o relativos dejan la raíz activa desconocida. El arranque debe ser un archivo regular de como máximo 4 MiB; los enlaces simbólicos y los archivos especiales se rechazan durante el descubrimiento de la ruta de integración y exportación. Repare el archivo bootstrap o proporcione un `ZCODE_DATA_DIR` explícito para seleccionar la raíz de datos deseada. Aplique, sobrescriba y actualice la basura con un mensaje de reparación en lugar de reclamar una escritura heredada exitosa. Un archivo de proveedor explícito existente todavía puede establecer el almacén activo. La propiedad registrada en la configuración o tienda predeterminada original mantiene su trayectoria, huellas dactilares e historial de deshacer; deshabilitar elimina ese bloque original antes de que una habilitación posterior pueda usar la tienda reubicada. Un viejo deshacer también se niega, mientras que otro camino es dueño de la integración. Si un selector explícito anterior ya no identifica el archivo propio, restaure ese selector antes de deshabilitarlo; opencodex retiene el registro y se niega a abandonar el bloque. + +opencodex escribe `provider_config.json` directamente donde puede. Al habilitar la integración se agrega la regla del proveedor `opencodex` a ese archivo, una actualización del catálogo lo actualiza y la desactivación elimina exactamente lo que opencodex puso allí. Todas las demás reglas en el archivo se dejan solas, incluida una regla que otro proveedor mantiene para un ID de modelo que también aparece en la nuestra. Una regla que lleva el id `opencodex` que opencodex no escribió es un conflicto más bien que algo para asumir; resolverlo en ZCode o usar el sobrescribir explícito. + +Un almacén de proveedor ilegible o que no es de archivos también se niega a escribir; no se trata como un almacén ausente que permite la importación heredada. + +Otras dos situaciones aún se niegan en lugar de escribir. Un bloque opencodex aplicado antes de que ZCode moviera su tienda mantiene la integración en `config.json`: desactívelo allí primero, luego habilitelo nuevamente para escribir la nueva tienda. Y un `provider_config.json` cuyo `schemaVersion` no es uno opencodex ha observado se informa en lugar de fusionarse, porque ese archivo contiene todos los proveedores que ZCode tiene y afirmar una forma en él cambiaría una opción silenciosa por una pérdida silenciosa. El estado nombra el archivo que ZCode lee cuando la integración no lo está escribiendo. + +En ese segundo caso, agregue el proveedor en la configuración de ZCode: URL base `http://127.0.0.1:10100/v1` (ajuste el puerto a su enlace), cualquier clave no vacía y los ID de modelo de `ocx export --client zcode`. La eliminación de `provider_config.json` para volver a activar la importación de ZCode no es compatible: descarta todos los proveedores que ZCode mantiene allí. + +## Cline CLI + +Esta integración se dirige al almacén de proveedores CLI /shared SDK de Cline, cuyo esquema nativo tiene `version: 1`. La extensión `globalState` /secret no se migra ni se detecta como esta integración. Ejecute Cline una vez para inicializar su directorio de configuración. + +**Detenga Cline antes de habilitar, sincronizar, deshabilitar o restaurar la integración.** OpenCodex escribe `providers.opencodex` tanto en `providers.json` como en el hermano `models.json`. El primer archivo contiene la conexión OpenAI Responses con un marcador de posición de bucle de retroceso no secreto; el segundo contiene el catálogo de modelos enrutados filtrados, incluyendo el contexto disponible y los metadatos de imagen. Las entradas de proveedor existentes y la selección de proveedor predeterminada permanecen sin cambios. + +```bash +ocx integration client list --json +ocx integration client enable --client cline +ocx integration client history --client cline +ocx integration client restore --op +``` + +Después de habilitar, reinicie Cline y seleccione OpenCodex, o inicie con `cline --provider opencodex --model `. Los cambios de catálogo externos se leen cuando Cline se reinicia. Cline se excluye de la actualización de catálogo desatendida; después de cambiar la selección del modelo enrutado, detenga Cline y ejecute `ocx sync` o habilite la integración nuevamente para actualizarla. Un modelo seleccionado se conserva mientras sigue siendo encaminado y borrado si se elimina del catálogo exportado. + +`CLINE_PROVIDER_SETTINGS_PATH` anula el archivo principal. De lo contrario, `CLINE_DATA_DIR` selecciona el directorio de datos, luego `CLINE_DIR` selecciona la raíz, luego se usa `~/.cline`. El archivo de modelo es siempre `models.json` junto al archivo de proveedor seleccionado. Las anulaciones deben ser absolutas o comenzar con `~`. El comando Mirror-local Cline `--config` traza con `CLINE_PROVIDER_SETTINGS_PATH` cuando se inicia OpenCodex. Se rechaza una ruta primaria llamada `models.json` porque los archivos deben ser distintos. + +Cada reemplazo de archivos es atómico, pero ninguna operación del sistema de archivos reemplaza a ambos simultáneamente. Una operación de diario captura ambos archivos originales; un error de escritura o contabilidad compensa ambos. Una operación interrumpida conserva un registro de recuperación privado. Informes de estado de recuperación incompleta como inseguro, y la siguiente mutación explícita se recupera sólo si ni el archivo ni su propiedad tiene una edición no relacionada. Si la recuperación se niega, preservar los archivos y la ruta de recuperación reportada por la operación; resolver el conflicto antes de volver a intentar. + +Deshacer restaura **ambas cadenas de bytes originales**, incluyendo un archivo que originalmente no existía. Las ediciones después de la operación requieren el `--confirm-drift` explícito existente; primero se realiza una copia de seguridad del par editado. Una entrada OpenCodex ocupada requiere la opción `--overwrite-conflict` existente. Deshabilitar elimina las dos entradas administradas; no restaura una entrada externa anterior. Usa Deshacer para eso. La retención y caducidad de instantáneas siguen las mismas reglas que otras integraciones. + +La descarga `cline-config-bundle.json` contiene dos miembros nativos del documento: `settings` para `providers.json`, y `catalog` para `models.json`. No es en sí mismo un archivo de configuración de Cline. Prefiera el comando de integración para una combinación y una reversión con journal. El cableado de admisión remota no es compatible con esta integración generada; requiere acceso de bucle de retorno no autenticado. + + + +## GitHub Copilot App + +La aplicación de escritorio GitHub Copilot puede usar opencodex como proveedor de modelos compatible con OpenAI. Esta es una configuración manual del cliente sin interruptor en **Conectar**, y es independiente del proveedor de `github-copilot` aguas arriba, que utiliza una suscripción Copilot como backend para opencodex. + +1. Inicie opencodex y confirme que responde: + + ```bash + curl http://127.0.0.1:10100/healthz + curl http://127.0.0.1:10100/v1/models + ``` + +2. En la aplicación Copilot, abre **Configuración → Proveedores de modelos → Añadir proveedor** e ingresa: + + | Campo | Valor | + |---|---| + | Nombre | cualquier etiqueta, por ejemplo `OpenCodex` | + | URL base | `http://127.0.0.1:10100/v1` (ajustar el puerto a su enlace) | + | API clave | Dejar en blanco en loopback | + +3. Sincronice modelos desde el punto final, o agregue uno por su id `provider/model`, y selecciónelo. + +La aplicación utiliza `GET /v1/models` para el descubrimiento y `POST /v1/chat/completions` para los giros. Esos turnos pasan por el modelo de enrutamiento normal de opencodex, por lo que las credenciales del proveedor, las cuentas OAuth y los combos se aplican como lo hacen para cualquier otro cliente. Los campos de solicitud aceptados se enumeran en el [Referencia de formatos proxy](/es/reference/proxy-formats/). + +Si la aplicación informa que no hay modelos, compruebe que la URL base termina en `/v1` en lugar de `/v1/chat/completions` y que `/v1/models` devuelve una matriz `data` no vacía. Cuando opencodex escucha en una dirección que no es de bucle, ponga una clave de admisión de datos (el token descrito en [acceso remoto](/es/reference/configuration/server/#remote-access), o una clave `ocx_…` generada en el panel de control) en el campo de clave API de la aplicación. La aplicación lo envía como `Authorization: Bearer`, que `/v1/chat/completions` acepta como admisión proxy y nunca reenvía aguas arriba; ver el [matriz de autenticación](/es/reference/proxy-formats/#authentication-matrix). + + + +## modelos de rol omo (Codex / LazyCodex) + +Cuando LazyCodex está instalado, la pestaña omo muestra una sección **omo (Codex / LazyCodex)** debajo de los controles omo basados en Pi, enumerando cada función de agente Codex que se encuentra en `$CODEX_HOME/agents/*.toml`, con el modelo al que está anclado cada uno. Codex ejecuta un rol en ese pin sin importar qué modelo pida el padre, así que aquí es donde se decide realmente el modelo de un rol. LazyCodex cuenta como instalado cuando el plugin `omo@sisyphuslabs` Codex está habilitado en `$CODEX_HOME/config.toml` y una copia instalada bajo `$CODEX_HOME/plugins/cache/sisyphuslabs/omo/` lleva su `lazycodex-install.json`. Una carpeta `~/.omo` por sí sola no cuenta, porque el omo basado en Pi también lo crea. Sin LazyCodex, la sección está oculta y la línea de comandos informa que no está instalada. Elija un modelo y un esfuerzo de razonamiento en una fila y presione Guardar. Una fila cuyo rol no tiene pin de modelo puede ahorrar un esfuerzo por sí misma; el rol sigue heredando su modelo: + +- opencodex actualiza solo las claves raíz `model = "..."` y `model_reasoning_effort = "..."` del archivo de ese rol. Las clavijas que faltan se insertan cerca de la parte superior. La elección de **Heredar el esfuerzo**, disponible en cada fila, envía `"effort": null` para borrar el pin de esfuerzo, eliminando su línea y el comentario final. Las instrucciones del papel, otros comentarios y otras claves se dejan exactamente como estaban. +- El modelo está escrito a `[codex].agents..model` en `~/.omo/omo.jsonc`, que LazyCodex 5.1.1 y posteriores leen, y un esfuerzo cambiado LazyCodex soporta va a `[codex].agents..reasoning` en la misma entrada. Si ese archivo no existe, no se crea. Si contiene comentarios, se deja sin tocar, porque guardarlos los eliminaría; la pestaña lo dice y puede establecer el valor allí a mano. Los symlinks y archivos no regulares son rechazados; en macOS y Linux, una FIFO es rechazada sin esperar a un escritor. Un espejo omitido no deshace el archivo de rol guardado. + +Si el archivo de rol guardado tiene éxito pero la escritura omo.jsonc falla, el botón de la fila se convierte en **Reintentar omo.jsonc**, que reenvía la misma opción de esfuerzo, incluyendo un borrado **Heredar el esfuerzo** (`null`). Hasta que ese reintento tenga éxito, una solicitud posterior de Guardar o Asignación automática para el rol que deja el esfuerzo solo lleva consigo la elección pendiente; un esfuerzo explícitamente elegido toma su lugar. + +Nada sucede hasta que presiona Guardar; la sincronización o el reinicio de opencodex nunca cambia un archivo de rol. Las nuevas Codex sesiones recogen el cambio. Los mismos controles existen en la línea de comandos: + +```bash +ocx agent roles +ocx agent roles set explorer xai/grok-4.5 +``` + +`ocx agent roles set --effort ` también establece el esfuerzo de razonamiento del rol: inserta o reemplaza el valor `model_reasoning_effort` del archivo de rol y escribe `[codex].agents..reasoning` en omo.jsonc cuando LazyCodex tiene ese nivel (`ultra` permanece solo en el archivo de rol y se elimina un `reasoning` anterior). En `PUT /api/codex-agent-roles/{role}`, omitiendo `effort` mantiene el pin, un nivel lo establece, y `null` elimina la línea `model_reasoning_effort` del archivo de rol, su comentario final y el omo.jsonc `reasoning`. A Guardar que cambia solo el modelo deja ambos valores de esfuerzo como estaban. Omitir `model` deja el pin `model` del archivo de rol y el omo.jsonc `model` exactamente como estaban, por lo que un rol sin un pin sigue heredando su modelo mientras su esfuerzo cambia o se borra; el tablero de instrumentos envía esta solicitud de solo esfuerzo para tal fila. Cuando omo.jsonc puede ser escrito, un rol sin una entrada obtiene uno que contenga solo `reasoning` si el esfuerzo guardado es compatible con LazyCodex (`none` se escribe como `off`); para tal rol, despejar el esfuerzo o guardar `ultra` no agrega entrada. Se rechaza un modelo `null` con 400 `invalid_model`, porque un guardado nunca elimina un pin de modelo, y se rechaza una solicitud con ni `model` ni `effort` con 400 `empty_update` antes de que se lea el archivo de rol u omo.jsonc. `ocx agent roles set` siempre toma un modelo. Solo se puede eliminar un valor de cadena de una línea existente; se rechaza un valor multilínea o no de cadena con 409 `unsupported_model_value`, dejando ambos archivos sin cambios. El borrado elimina solo la anulación propia del rol: Codex resuelve el esfuerzo como lo hace para cualquier rol sin uno (un valor de generación explícito, el valor predeterminado `[agents]` o la sesión principal), no un modelo predeterminado fijo. + + + +### Asignación automática + +Auto-assign es parte de omo (Codex / LazyCodex): se encuentra por encima de la tabla de roles en esa sección y existe solo mientras se detecta LazyCodex. Sin él, el tablero de instrumentos no muestra ninguno, el API responde 409 `lazycodex_not_detected` y `ocx agent roles suggest` es rechazado. + +Auto-assign propone un modelo para cada rol a la vez. opencodex le hace una pregunta a su modelo predeterminado Codex (la raíz `model` en Codex `config.toml`): para cada rol, dada su descripción y el inicio de sus instrucciones, ¿qué nivel de capacidad (rápido, estándar o frontera) y cuánto razonamiento (mirada, medido, minucioso o exhaustivo) necesita? Ese modelo nunca elige un modelo. opencodex luego elige el modelo más barato de su lista de selectores que alcanza el nivel: + +- Los modelos enumerados bajo `codexRoleTiers` en la configuración opencodex (`{ "fast": [...], "standard": [...], "frontier": [...] }`) tienen ese nivel. +- Otros modelos con un precio conocido se clasifican por precio y se dividen uniformemente en los tres niveles. Con solo uno o dos modelos de precio, el más caro es la frontera y el otro, si lo hay, es estándar. +- Los modelos sin precio y sin nivel listado nunca son propuestos. Enumerarlos para incluirlos. + +Cada propuesta muestra el modelo, el nivel, el esfuerzo de razonamiento, una razón de una línea y lo que lo movería hacia arriba o hacia abajo. Un papel que el modelo no podría dimensionar claramente se muestra como no dimensionado, con la razón, y no se puede aplicar. No se escribe nada hasta que presione Aplicar en una fila o Aplicar todo. La aplicación utiliza el mismo guardar como picking a mano. Cada rol de tamaño cuyo modelo elegido tiene una escalera de esfuerzo no vacía recibe una propuesta de esfuerzo, y Aplicar o `--apply` inserta o reemplaza su valor `model_reasoning_effort`. El esfuerzo se coloca en los propios niveles del modelo elegido: su más bajo, su predeterminado, uno por encima del predeterminado o su más alto. Una escalera vacía no da ninguna propuesta de esfuerzo (`proposedEffort: null`); Aplicar omite `effort` y deja cualquier pin de esfuerzo existente como estaba. Una propuesta nula nunca borra un alfiler. + +```bash +ocx agent roles suggest +ocx agent roles suggest --model xai/grok-4.5 --apply +``` + +## Kilo + +Kilo CLI, VS Code y JetBrains comparten una configuración global. Esta integración escribe `provider.opencodex` en el primer archivo existente entre `kilo.jsonc`, `kilo.json`, `opencode.jsonc`, `opencode.json` y `config.json` en `~/.config/kilo` (`XDG_CONFIG_HOME` reubica ese directorio). Si no existe, el destino es `kilo.jsonc`. Las configuraciones del proyecto nunca se escriben. Kilo fusiona todos estos archivos globales. Si otro candidato también define `provider.opencodex`, el estado nombra todos los archivos competidores y Aplicar y Reemplazar rechazo; elimine `provider.opencodex` de esos archivos antes de habilitar la integración. Un candidato ilegible o inseguro también bloquea la escritura. Deshabilitar aún puede eliminar un bloque perteneciente al archivo grabado mientras otro candidato entra en conflicto o no se puede analizar; el otro candidato se deja intacto. + +El fragmento de propiedad es solo `provider.opencodex` (forma OpenCode V1: `npm`, `options`, `models`). El esquema publicado de Kilo no tiene la clave OpenCode V2 `providers`, por lo que el bloque no se emite; Kilo recibe las opciones de razonamiento por modelo como un mapa variante dentro de su bloque de proveedor, construido a partir de los mismos metadatos canónicos efectivos que la exportación de OpenCode. `$schema`, `model`, `enabled_providers`, MCP, y otras claves permanecen propiedad del usuario. Seleccione `opencodex/` en Kilo después de aplicar. + +Loopback utiliza `{env:OPENCODEX_KILO_API_KEY}` como `options.apiKey`. Un enlace sin bucle retro mueve la admisión a `options.headers["x-opencodex-api-key"]` y nunca serializa una clave real. Apply reescribe todo el archivo global como bastante JSON, por lo que los comentarios y las comas posteriores en otras claves no se conservan. Kilo está en el catálogo de salida implícita: `ocx +sync`, `POST /api/sync`, y visibilidad, proveedor, o cambios preestablecidos actualizar un bloque de Kilo propiedad bajo las mismas reglas de propiedad segura como cualquier otro cliente, y una nueva sesión de Kilo carga el archivo actualizado. + +```bash +ocx integration client enable --client kilo +ocx export --client kilo --out ./kilo.jsonc +``` + + + +## Command Code + +Command Code mantiene sus proveedores personalizados en `~/.commandcode/providers.json`. Esta integración escribe `provider.opencodex` en ese archivo y es solo loopback. + +**La raíz que escribe.** El Command Code resuelve su mapa de proveedor como +`document.provider ?? document.providers`, así que la raíz singular gana siempre que existe. Por lo tanto, la integración lee primero el archivo de destino y escribe en el raíz que el archivo ya utiliza: un documento que ya lleva una `providers` mapa mantiene y sus otros proveedores se mantienen legibles. Un archivo fresco obtiene el singular `provider` +raíz. Ambas raíces se declaran como rutas administradas, por lo que Deshabilitar elimina el bloque de Cualquiera que sea el texto en el que fue escrito. + +**La forma de credencial.** El proveedor está escrito con `apiKey: false`, la forma documentada para un punto final que no necesita clave. Command Code rechaza una cadena sin procesar, y esta integración no lee, hace referencia ni exporta ningún archivo de token de servicio. + +**Resolución Home.** No hay ninguna `COMMANDCODE_HOME` Anular aquí. El publicado El cliente resuelve `HOME ?? USERPROFILE` y luego añade `/.commandcode/providers.json`; no consulta esa variable. Una anulación de esta integración honrada, pero la cliente ignorado haría Aplicar éxito del informe en una ruta Command Code nunca se abre, por lo que El camino es siempre `~/.commandcode/providers.json`. En Windows con el hogar predeterminado, la integración utiliza `HOME ?? USERPROFILE` +solo cuando el valor seleccionado no está en blanco y Windows-absolute; de lo contrario, usa +`homedir()`. Se conserva una casa suministrada por separado. A `HOME` establecido por Git para Por lo tanto, Windows o MSYS2 solo se respetan cuando pasan esas comprobaciones. + +Pegue la clave usted mismo si luego mueve el proveedor fuera del bucle de retroceso: Command Code almacena las claves en `~/.commandcode/auth.json` (a través de `/connect`), no en `providers.json`. + +```bash +ocx integration client enable --client commandcode +ocx export --client commandcode --out ./providers.json +``` + +`ocx commandcode restore --op ` acepta solo Command Code operaciones, incluyendo `--preview` y `--plan-fingerprint` solicitudes. Rechaza las anulaciones de cliente/perfil. El proxy en ejecución debe admitir la restauración con alcance de cliente; los proxies más antiguos devuelven un error sin volver al extremo de restauración genérico. Utilice `ocx integration client restore` para la revista genérica y los comandos de perfil explícitos de Aside anteriores para las operaciones de Aside. + +## Factory Droid + +Ejecute Droid una vez para crear `~/.factory`, luego habilite explícitamente esta integración con `ocx integration client enable --client droid`. OpenCodex agrega solo `customModels` entradas documentadas a su `settings.json` personal, utilizando un punto final Chat Completions local sin llave. Elija una fila de Droid 's `/model` selector. Deshabilitar elimina las filas administradas; Deshacer restaura el archivo guardado exacto. Otros ajustes y modelos personalizados siguen siendo suyos. Si Droid normaliza una fila `customModels` agregando `id` o `index`, OpenCodex ignora esos dos campos de cliente al verificar la propiedad, por lo que los valores predeterminados de razonamiento guardados permanecen disponibles. + +Abra **Conectar → Factory Droid** (`/#integrations/droid`) para establecer un razonamiento predeterminado para cada modelo conectado. Elija entre los esfuerzos compatibles del modelo, revise los cambios y luego confirme. **Sin valores predeterminados** borra la configuración de borrador de ese modelo; use **Guardar / revisar cambios** y confirme para aplicar la eliminación. Los modelos sin una lista de esfuerzo declarada muestran que no hay ningún valor predeterminado disponible. + +El CLI admite los mismos valores predeterminados en Droid apply/overwrite. Por ejemplo, reemplace el modelo ficticio de abajo con un ID conectado exacto y esfuerzo soportado: + +```bash +ocx integration client preview --client droid --operation apply --reasoning-default example/model-a=high --json > droid-preview.json +``` + +Después de revisar el plan aplicable y elegir la escritura: + +```bash +DROID_FINGERPRINT="$(jq -er 'select(.canApply == true) | .fingerprint' droid-preview.json)" +ocx integration client enable --client droid --reasoning-default example/model-a=high --plan-fingerprint "$DROID_FINGERPRINT" --json +ocx integration client status --client droid --json +``` + +Repita `--reasoning-default MODEL=EFFORT` para enviar el mapa de reemplazo completo. El último signo igual separa el modelo y el esfuerzo; se conservan los identificadores de caso y exactos. Las claves de modelo duplicadas se rechazan. Las banderas omitidas preservan los valores predeterminados; `--clear-reasoning-defaults` explícitamente envía un mapa vacío. Para borrar, previsualizar con ese indicador y repetirlo en el comando de habilitación de coincidencia. Borrar y las entradas no se pueden combinar. Estos indicadores son Droid -only y no se aplican para deshabilitar/restaurar. Repita el mismo mapa en la vista previa y confirmación; el servidor valida los esfuerzos específicos del modelo y rechaza la vinculación obsoleta en lugar de aceptar silenciosamente un mapa cambiado. + +Para una clara intención completa, previsualizar esa acción separada: + +```bash +ocx integration client preview --client droid --operation apply --clear-reasoning-defaults --json > droid-clear-preview.json +``` + +Después de revisarlo y elegirlo: + +```bash +DROID_CLEAR_FINGERPRINT="$(jq -er 'select(.canApply == true) | .fingerprint' droid-clear-preview.json)" +ocx integration client enable --client droid --clear-reasoning-defaults --plan-fingerprint "$DROID_CLEAR_FINGERPRINT" --json +``` + +El valor predeterminado se aplica solo cuando Droid omite un esfuerzo de su solicitud. Un esfuerzo explícito de solicitud tiene prioridad sobre este valor predeterminado; los pines y tapas existentes de OpenCodex aún se aplican. Droid puede continuar visualizando **Dinámico** incluso cuando OpenCodex aplica el valor predeterminado configurado. Las solicitudes sin el encabezado predeterminado Droid no se ven afectadas; el encabezado es una preferencia de solicitud, no una prueba de identidad del cliente. Para combos y políticas de enrutamiento, cada destino concreto comprueba la preferencia en contra de su propia lista de esfuerzo, por lo que un primer objetivo incompatible no lo elimina de una reserva compatible. + +Un valor predeterminado guardado que el modelo enrutado ya no admite se ignora para las solicitudes. Si la lista de esfuerzo declarada del modelo conectado ya no incluye el valor guardado, se omite de los valores predeterminados del panel y se elimina de la fila administrada al actualizar. La revisión sin edición permite que OpenCodex conserve los valores predeterminados compatibles restantes. + +Actualizar conserva los valores predeterminados mientras el selector exacto `provider/model` permanece conectado y declara el esfuerzo guardado. Renombrar un proveedor, modelo o alias combinado reemplaza esa fila administrada y borra su valor predeterminado; elija un valor predeterminado para la fila renombrada nuevamente. Deshabilitar elimina los valores predeterminados con las filas del modelo administrado y Deshacer restaura las filas guardadas y sus valores predeterminados juntos. + +Los modelos cuyos ID o nombres de visualización contienen `,` o `]` se omiten porque el selector administrado no puede abordarlos de forma segura; la configuración de exportación y administrada muestra las mismas filas. Se rechaza un catálogo no vacío sin modelos direccionables. + +Droid también lee el legado `config.json` y el local `settings.local.json`. Resolver filas heredadas que usan el punto final OpenCodex, un ID de modelo generado o un nombre de visualización `OpenCodex:` y cualquier anulación local `customModels`, antes de habilitar; OpenCodex rechaza esos ajustes ambiguos. También rechaza un objetivo inseguro o una fila editada desde que se aplica. La integración es solo loopback y nunca copia las credenciales del proveedor. La fábrica documenta el [Esquema BYOK](https://docs.factory.ai/model-independence/byok) y [configuración personal](https://docs.factory.ai/droid-cli/settings). diff --git a/docs-site/src/content/docs/es/guides/local-plugins.md b/docs-site/src/content/docs/es/guides/local-plugins.md new file mode 100644 index 00000000000..39fd6207392 --- /dev/null +++ b/docs-site/src/content/docs/es/guides/local-plugins.md @@ -0,0 +1,75 @@ +--- +title: "Plugins locales" +description: "Cargue su propio código en el proxy al inicio para reescribir los envíos del proveedor, por ejemplo, para poner un proxy de compresión local frente a los proveedores." +--- + +Un plugin local es un archivo JavaScript que `ocx start` carga antes de que el proxy empiece a atender solicitudes. Puede inspeccionar cada envío al proveedor justo antes de que salga del proceso, redirigirlo o añadir encabezados. Esto permite colocar un sidecar local, como un proxy de compresión o una grabadora, delante del proveedor sin modificar opencodex. + +Los plugins son locales para una instalación. opencodex no los descarga, actualiza ni firma. + + + +## Donde viven los plugins + +Ponga los archivos del plugin en `plugins/` dentro del hogar opencodex (`~/.opencodex/plugins/` o `$OPENCODEX_HOME/plugins/` cuando esa variable esté establecida): + +```text +~/.opencodex/plugins/ + my-sidecar.ts +``` + +- Los archivos que terminan en `.ts`, `.js` o `.mjs` se cargan en orden de nombre. +- Los nombres que comienzan con `.` o `_`, y `*.d.ts`, se ignoran: cambie el nombre de un complemento a `_my-sidecar.ts` para apagarlo. +- El directorio es opcional. Sin ella no hay nada cargado. +- Un plugin se ejecuta dentro del proxy con sus credenciales, por lo que opencodex rechaza un archivo plugin o un directorio `plugins/` que es propiedad de otro usuario o escribible por grupo u otros, y rechaza enlaces simbólicos. Cada directorio por encima de `plugins/`, hasta `/`, también debe ser propiedad de usted o root y no escribirse por grupo u otros, a menos que sea pegajoso como `/tmp`. Arreglar permisos con `chmod go-w ~/.opencodex/plugins ~/.opencodex/plugins/*`; en sistemas cuya máscara predeterminada es `002`, compruebe los directorios padre también. En macOS, una concesión de ACL a otro usuario o grupo que puede escribir, eliminar, cambiar permisos o agregar / quitar bloques de entradas de ruta de carga, incluso si el modo es `0600`; inspeccionar la ruta en sí con `/bin/ls -lebd -- `. Solo lectura, denegación, solo herencia y concesiones solo al propietario de la ruta o al usuario en ejecución no bloquean la carga. Los nombres de visualización ACL como `root` o `0` no se tratan como prueba UID numérica. En Linux, se comprueban las ACL extendidas cuando `getfacl` está instalado. Sin ella, solo se verifican los bits de propietario y modo. +- En Windows, la carga automática del complemento está desactivada hasta que esté disponible una verificación de confianza ACL. + +Reinicie el proxy después de agregar, cambiar o eliminar un plugin (`ocx service restart`, o detener e iniciar `ocx start` ). Cada plugin cargado imprime una línea `Plugin loaded: ` al inicio; un plugin omitido imprime una categoría de razón limitada. El texto de excepción del complemento RAW nunca se imprime automáticamente. + +Para empezar una vez sin plugins, establece `OCX_PLUGINS=0`. + + + +## Escribir un plugin + +El módulo debe exportar por defecto un objeto con una propiedad opcional `name` de tipo cadena y una función `setup`, que recibe el contexto. Un `setup` asíncrono dispone de cinco segundos para terminar. Los plugins se ejecutan en el mismo hilo que el proxy: si `setup` bloquea de forma síncrona, no se puede interrumpir y retrasa el inicio hasta que termine. Agotar el plazo tampoco detiene sus servidores o temporizadores ya iniciados. Inicia los recursos de larga duración únicamente después del trabajo que pueda fallar: + +```ts +interface UpstreamTarget { + url: string; // absolute upstream URL; assign a new one to redirect + headers: Headers; // outbound headers, including credentials — never log them + readonly transport: "http" | "websocket"; +} + +export default { + name: "my-sidecar", + setup(ctx: { + log(message: string): void; + registerUpstreamRewriter(rewrite: (target: UpstreamTarget) => void): void; + onShutdown(teardown: () => void): void; + }) { + ctx.registerUpstreamRewriter(target => { + const upstream = new URL(target.url); + if (!upstream.pathname.endsWith("/chat/completions")) return; + target.url = `http://127.0.0.1:9000${upstream.pathname}${upstream.search}`; + target.headers.set("x-original-origin", upstream.origin); + }); + }, +}; +``` + +El contexto también incluye `name`, `configDir` (el directorio de configuración de opencodex) y `pluginDir`. + +Los plugins no pueden importar módulos opencodex - en el binario empaquetado no están en disco. Declare las interfaces pequeñas que necesita localmente, como anteriormente. + + + +## Cómo se comportan las reescrituras + +- El rewriter se ejecuta de forma síncrona en cada envío HTTP al proveedor y en la conexión WebSocket de Codex, después de que opencodex haya elegido el transporte. Debe ser rápido: realiza las comprobaciones de red en segundo plano y consulta un resultado en caché desde el rewriter. +- Un envío redirigido a una dirección de loopback (`127.0.0.1`, `::1`, `localhost`) se conecta directamente tanto por HTTP como por WebSocket de Codex, sin usar los proxies del proveedor ni `HTTP_PROXY`: un proxy en otra máquina no puede acceder al loopback local. Los demás destinos siguen la configuración habitual de salida, incluido `NO_PROXY`, evaluada con la URL reescrita en ambos transportes. +- El rewriter de WebSocket de Codex se ejecuta en cada turno, antes de reutilizar un socket inactivo del pool. Solo se reutiliza si coinciden el destino y los encabezados reescritos, excepto `x-codex-turn-state` y `x-codex-turn-metadata`. Estos dos encabezados viajan dentro de cada trama de solicitud y pueden variar entre turnos en un mismo socket; se descartan las modificaciones que el rewriter haga a esos dos encabezados. Si un plugin empieza o deja de redirigir, el cambio se aplica en el siguiente turno. +- La reescritura ocurre después de elegir el proveedor, la cuenta y la ruta; no cambia el enrutamiento, la selección de cuentas, los reintentos ni los registros de solicitudes. +- El envío llega al host elegido, que recibe la solicitud tal como la recibiría el proveedor, incluidas las credenciales. +- Si un rewriter lanza una excepción, opencodex revierte únicamente sus cambios en ese envío y lo deshabilita durante el resto del proceso. Los cambios de los rewriters anteriores se conservan; si era el único, la solicitud queda sin modificar. Si `setup` lanza una excepción o agota su plazo, se omite el plugin, se eliminan sus registros de handlers y se ignoran sus intentos posteriores de registro. Los demás plugins y el proxy se inician normalmente. +- Si el directorio de plugins existe pero no se puede leer, por ejemplo por sus permisos, se informa al iniciar en lugar de tratarlo como vacío. \ No newline at end of file diff --git a/docs-site/src/content/docs/es/guides/macos-menu-bar.md b/docs-site/src/content/docs/es/guides/macos-menu-bar.md new file mode 100644 index 00000000000..80d6797293a --- /dev/null +++ b/docs-site/src/content/docs/es/guides/macos-menu-bar.md @@ -0,0 +1,70 @@ +--- +title: "Barra de menús de macOS" +description: "Usa la bandeja, el panel nativo de uso y el widget de OpenCodex Desktop en macOS." +--- + +El elemento de la barra de menús forma parte de OpenCodex Desktop. Muestra el uso del proxy local y abre un panel nativo de uso. La aplicación también incluye el dashboard y una extensión de WidgetKit. Consulta la [guía de escritorio](/es/guides/desktop-app/) para instalarla en otras plataformas. + + + +## Instalar + +Descarga `OpenCodex--macos.dmg` de la [última versión](https://github.com/lidge-jun/opencodex/releases), abre el DMG y arrastra `OpenCodex.app` a Aplicaciones. La aplicación requiere macOS 13 o posterior; el widget, macOS 14 o posterior. + + + +## Primer inicio + +Las versiones publicadas de `OpenCodex.app` llevan firma de Developer ID, usan el entorno de ejecución reforzado y están notarizadas por Apple, con el comprobante adjunto. En el primer inicio, macOS normalmente solo pide la confirmación habitual para una aplicación descargada. Si sigue bloqueándola, abre **Configuración del Sistema → Privacidad y seguridad → Abrir de todos modos**. Las compilaciones propias llevan firma ad hoc; consulta [Compilar desde el código fuente](#build-from-source). + +Al abrirse, la aplicación muestra el progreso de inicio en una ventana. En el primer inicio activa una vez **Iniciar al iniciar sesión (Start at Login)**; puedes desactivarlo desde la bandeja. Esa opción solo aparece marcada cuando esta copia está registrada y macOS no ha desactivado el elemento de inicio. En otro caso, la etiqueta explica el motivo; consulta [Aplicación de escritorio](/es/guides/desktop-app/). Los inicios posteriores mediante ese elemento ocultan la ventana y mantienen la bandeja disponible. + + + +## Barra de menús y panel de uso + +La barra muestra de forma predeterminada los tokens totales de hoy. En el dashboard, abre **Uso → Barra de menús y widget** o `#usage/companion` para elegir solicitudes, tokens, costo estimado, cuota o solo el icono. + +Usa **Show Usage (Mostrar uso)** en la bandeja para abrir el panel nativo. Incluye totales de hoy y de 30 días, un gráfico de uso, la lista de modelos y los límites de proveedores y cuentas según tus preferencias de visualización. Los totales incluyen tokens y solicitudes, además del costo estimado si está activado. Las filas de cuota muestran ventana, porcentaje y restablecimiento. Las mediciones ausentes aparecen como `—` y los datos parciales se marcan como incompletos. + +Los controles nativos son **Refresh**, **Dashboard** y **Settings**. **Dashboard** abre Uso en la ventana de escritorio y **Settings**, la pestaña Barra de menús y widget de Uso. La bandeja también ofrece **Open Dashboard**, **Open in Browser**, **Start at Login** (iniciar al iniciar sesión), **Stop proxy**, **Check for Updates…**, **Install update** cuando hay una actualización y **Quit**. **Stop proxy** siempre aparece, pero solo está disponible si la aplicación inició el proxy; uno iniciado por separado sigue funcionando. Cerrar la ventana o pulsar Command-Q oculta la aplicación cuando hay bandeja; usa **Quit** para salir por completo. + +El botón de actualización del dashboard abre la página de actualizaciones de la aplicación y usa la misma actualización firmada que la bandeja. + +El texto de la bandeja se actualiza cada 60 segundos. Mientras está abierto, el panel nativo también se actualiza cada 60 segundos; **Refresh** solicita una actualización inmediata. + +## Widget + +En macOS 14 o posterior, abre OpenCodex.app una vez y haz Control-clic en un área vacía del escritorio. Elige **Editar widgets**, busca **OpenCodex** y añade el tamaño deseado. Los tamaños combinan estado del proxy, tokens y solicitudes de hoy, costo estimado, cuotas y gráfico de uso. La extensión lee una instantánea local escrita por la aplicación: contiene datos de visualización, no claves API ni datos originales de cuentas. La aplicación la actualiza cada cinco ciclos de bandeja de 60 segundos, aproximadamente cada cinco minutos mientras el proxy está conectado. WidgetKit también solicita una nueva línea temporal después de cinco minutos. + + + +## Conectar con el proxy + +La aplicación pide a su CLI incluida ejecutar `ocx resolve --json`. Se conecta a un proxy local accesible existente o inicia su entorno incluido solo si la CLI confirma que no hay ninguno escuchando. Si la detección es incierta, informa el problema en lugar de crear un segundo proxy. Usa el puerto resuelto en `127.0.0.1`. + +Para las solicitudes de administración prueba primero sin token. Si recibe HTTP 401, reintenta con `OPENCODEX_ADMIN_AUTH_TOKEN` del entorno de la aplicación o con el archivo `admin-api-token` del directorio de configuración resuelto. No usa el Llavero de macOS para ese token. La aplicación no puede conectarse a un proxy que solo escuche en una dirección inaccesible mediante loopback. + + + +## Compilar desde el código fuente + +En macOS 13 o posterior, con Bun, Rust y las herramientas Swift/Xcode disponibles, compila el dashboard desde la raíz y después ejecuta los comandos de escritorio desde `desktop/`: + +```bash +bun install +bun run build:gui +cd desktop +bun install +bun run prepare-sidecar +bun run prepare-widget +bun run build:local +``` + +`build:local` genera la aplicación y el DMG sin requerir una clave de firma del actualizador de Tauri. Ejecutar `bunx tauri build` directamente sí requiere `TAURI_SIGNING_PRIVATE_KEY`, porque también genera el artefacto de actualización. El widget usa firma ad hoc salvo que se configure `MACOS_SIGN_IDENTITY`; los paquetes locales de escritorio también llevan firma ad hoc. La aplicación funciona, pero macOS no registra una extensión de widget con esa firma y normalmente no aparece el widget. `build:local` siempre firma la aplicación de forma ad hoc: configurar solo `MACOS_SIGN_IDENTITY` no basta. Para registrar el widget, tanto la aplicación como la extensión deben estar firmadas por el mismo equipo de Developer ID, como ocurre en las versiones publicadas. Usa una versión publicada si necesitas el widget. + + + +## Desinstalar + +Desactiva **Iniciar al iniciar sesión (Start at Login)** en la bandeja si estaba activado y mueve `OpenCodex.app` de Aplicaciones a la Papelera. Esto elimina la CLI incluida y la extensión del widget, pero conserva el estado de `$OPENCODEX_HOME` y cualquier servicio `ocx` instalado por separado. La aplicación también guarda un identificador de instalación y marcadores de inicio en su directorio de configuración, además de una instantánea del widget en `~/Library/Containers/com.opencodex.desktop.widget/Data/Library/Application Support/OpenCodex/snapshot.json`; moverla a la Papelera no borra esos archivos. diff --git a/docs-site/src/content/docs/es/guides/minimax.md b/docs-site/src/content/docs/es/guides/minimax.md new file mode 100644 index 00000000000..b95d43f2a5f --- /dev/null +++ b/docs-site/src/content/docs/es/guides/minimax.md @@ -0,0 +1,91 @@ +--- +title: "Clientes MiniMax" +description: "Enrutar código MiniMax y comandos de texto MiniMax CLI a través de OpenCodex sin exponer las credenciales MiniMax." +--- + +MiniMax publica dos productos de línea de comandos diferentes. OpenCodex integra cada uno en el límite del protocolo que realmente expone: + +- **MiniMax Code** (`mcode`) es un agente de codificación con proveedores personalizados Anthropic Messages. +- **MiniMax CLI** (`mmx`) es una plataforma multimodal CLI. Solo su recurso `text` habla del Anthropic -compatible API que OpenCodex puede encaminar. + + + +## MiniMax Code + +En la página de Modelos OpenCodex, ambas regiones del Plan de Codificación MiniMax anuncian la entrada de imagen para `MiniMax-M3` y `MiniMax-M3.1-Flash-Preview`. El conmutador **Imagen / multimodal** de Combo solo está disponible cuando cada modelo seleccionado admite la entrada de imágenes. El interruptor controla los archivos adjuntos de la imagen; no permite la carga de vídeos. + +Instale e inicie sesión en MiniMax Code utilizando primero las instrucciones de MiniMax. Luego inicie OpenCodex y conecte la integración de archivos reversibles: + +```bash +ocx start +ocx integration client enable --client mcode +ocx mcode +``` + +![Integración de MiniMax Code con datos de ejemplo aislados](/screenshots/minimax-code-integration.png) + +La integración fusiona un bloque en `~/.minimax/config.yaml`: + +```yaml +custom_provider: + opencodex: + name: OpenCodex + kind: custom + enabled: true + api: anthropic-messages + options: + apiKey: opencodex-loopback + baseURL: http://127.0.0.1:10100 + authMode: api-key + models: + anthropic/claude-opus-5: + limit: + context: 1000000 +``` + +La lista de modelos generados, las ventanas de contexto y las escaleras de esfuerzo de razonamiento provienen del catálogo OpenCodex en ejecución. Las ventanas de contexto pueden incluir [Estimaciones de proveedores personalizados](/es/reference/configuration/providers/#context-windows-on-custom-providers); si el catálogo no tiene ventana o escala de esfuerzo, se omite el campo correspondiente. MCode mantiene el esfuerzo seleccionado actualmente en la sesión, por lo que OpenCodex exporta `effortOptions` sin sobrescribir esa selección. El bloque no escribe una clave real, no reemplaza `defaultModel` y no cambia su inicio de sesión MiniMax. En MCode, elija un modelo bajo `custom_provider:opencodex/...`. + +`ocx mcode` verifica que este proveedor apunta al proxy que se está ejecutando actualmente antes de lanzar el cliente. Después de la habilitación de una sola vez, `ocx sync` actualiza el bloque propietario cuando cambian las capacidades del puerto o catálogo. La sincronización automática nunca crea un bloque sin dueño, recrea uno que eliminó o sobrescribe un archivo que cambió después de que lo escribió OpenCodex; use el comando enable cuando desee volver a conectarse intencionalmente. Deshabilitar o restaurar a través del mismo sistema de integración auditado: + +```bash +ocx integration client disable --client mcode +ocx integration client history --client mcode +ocx integration client restore --op [--confirm-drift] +``` + +`MINIMAX_DATA_DIR` y el legado `MAVIS_DATA_DIR` son honrados. Se rechazan las anulaciones relativas porque OpenCodex y MCode pueden iniciarse en diferentes directorios de trabajo. + +## MiniMax CLI (`mmx`) + +Instale el CLI oficial por separado: + +```bash +npm install -g mmx-cli +mmx --version +``` + +Enrutar un comando de texto a través de OpenCodex mediante el wrapper y un identificador de modelo OpenCodex: + +```bash +ocx mmx text chat \ + --model anthropic/claude-opus-5 \ + --message "Explain this function" + +ocx mmx --output json text chat \ + --model openai/gpt-5.6-sol \ + --message "Return a JSON summary" +``` + +Códigos duros MMX `/anthropic/v1/messages` debajo de su base API URL. El envoltorio comienza a puente temporal de loopback durante toda la vida del proceso hijo. Solo acepta POST solicitudes a esa ruta Messages y `/anthropic/v1/messages/count_tokens`, cartografiarlos a OpenCodex existente `/v1/messages` y `/v1/messages/count_tokens` Plano de datos mientras preservar los cuerpos de solicitud y los datos de consulta. Canonical OpenCodex solicitud de traducción, la contabilidad de uso y la autenticación configurada del proveedor descendente permanecen en efecto; Los proveedores reciben `x-api-key` o transporte de portador según su configuración. La transmisión conserva los eventos de mensajes y contenido Anthropic. Antes de salir, el puente elimina los encabezados de credenciales de admisión entrantes y fija el público +`opencodex-loopback` marcador de posición. Los recursos arbitrarios de Anthropic no se representan, y El puente nunca se expone más allá del bucle. + +La envoltura también crea un `MMX_CONFIG_DIR` temporal que contiene solo ese marcador de posición, luego lo elimina después de las salidas `mmx`. Sus tokens `~/.mmx/config.json`, OAuth y MiniMax API nunca se cargan ni copian. + +Los siguientes límites son intencionales: + +- Sólo `text chat` y `text repl` se encaminan a través de OpenCodex. +- `--api-key`, `--base-url` y `--region` son rechazadas por la envoltura para que las credenciales de llamada o los selectores de destino no puedan entrar en conflicto con el puente aislado. +- La envoltura es solo bucle porque MMX no puede enviar el encabezado de admisión dedicado `x-opencodex-api-key` de OpenCodex para un enlace remoto. +- Ejecutar el plan `mmx` para `image`, `video`, `speech`, `music`, `vision`, `search`, `quota`, `auth`, `config`, `file` y `update`; los llaman MiniMax - APIs específicas que OpenCodex no emula. + +`mmx` por defecto su modelo de texto a `MiniMax-M3`. Pase `--model ` cuando desee una ruta específica de OpenCodex; de lo contrario, las reglas de enrutamiento del modelo OpenCodex normales decidirán si el id predeterminado está disponible. diff --git a/docs-site/src/content/docs/es/guides/model-ordering.md b/docs-site/src/content/docs/es/guides/model-ordering.md new file mode 100644 index 00000000000..2a120a12267 --- /dev/null +++ b/docs-site/src/content/docs/es/guides/model-ordering.md @@ -0,0 +1,155 @@ +--- +title: "Orden de modelos" +description: "Cómo determina opencodex el orden del modelo en el selector Codex y el modelo spawn_agent anula." +--- + +El selector de modelos Codex no conserva el orden de las declaraciones del proveedor o las matrices de modelos en la configuración opencodex. Su orden final proviene de las prioridades del catálogo, con un orden alfabético determinista para los modelos enrutados que comparten la misma prioridad. + + + +## La regla Codex se aplica + +Codex 's models-manager ordena las entradas de catálogo visible por `priority` en orden ascendente. Descarta el orden de la matriz de catálogo, por lo que mover una entrada anterior en una matriz JSON generada no la mueve anterior en el selector. La implementación registra esta restricción directamente en `src/codex/catalog/sync.ts`. + +Por lo tanto, opencodex controla la ubicación de las funciones asignando prioridades más bajas, no confiando en la posición de la matriz. A menos que se indique lo contrario, las prioridades fijas y el ejemplo trabajado a continuación describen un catálogo sin selectores de cuenta Codex elegibles. Con `N` selectores elegibles, las prioridades presentadas usan `N` como un paso: una elección nativa desnuda en el rango configurado `i` se expande a filas de selectores en las prioridades `i * N + j`, donde `j` es la posición basada en cero del selector; una elección encaminada usa `i * N`; y una elección calificada por selector exacta usa `i * N + j` para su selector. Las filas enrutadas no seleccionadas se mueven fuera de esos grupos selectores. Codex todavía anuncia sólo las primeras cinco filas visibles. + +Sin el pedido completo del seleccionador, las prioridades relevantes de no selector son: + +| Entrada de catálogo | Prioridad | Fuente | +| --- | ---: | --- | +| `subagentModels[i]` | `i` (`0` a través de `4`) | El mapa de rango destacado en `src/codex/catalog/sync.ts` | +| Otros modelos ruteados | `5` | Creación de la entrada encaminada en `src/codex/catalog/sync.ts` | +| Modelos ruteados no destacados listados en `modelPickerOrder` | `1000 + i` | Rango de selector de solo visualización en `src/codex/catalog/sync.ts` | +| Por defecto, las identificadores GPT nativas | `9` | Creación de entradas nativas en `src/codex/catalog/sync.ts` | +| Modelos nativos no seleccionados mientras existe una lista destacada | Al menos `featured.length + 100` | Catálogo nativo fusionar en `src/codex/catalog/sync.ts` | + +La gestión API limita `subagentModels` a cinco entradas con `slice(0, 5)` en `src/server/management/agent-settings-routes.ts`. Esto coincide con la superficie Codex `spawn_agent`, que anuncia solo los primeros cinco modelos anulados. Los modelos fuera de esos cinco todavía pueden permanecer visibles en el selector principal y llamarse por su id exacto. + + + +## Cómo se ordenan los lazos + +Todos los modelos ruteados ordinarios tienen prioridad `5`, por lo que necesitan un desempate. Antes de que se construyan las entradas del catálogo, `gatherRoutedModels()` ordena la lista de modelos enrutados por nombre del proveedor y luego por la identificación del modelo, ambos alfabéticamente (`src/codex/catalog/provider-fetch.ts`). + +Esto significa que ninguno de estos detalles de configuración cambia el orden final: + +- el orden de las claves de declaración en el objeto `providers`; +- el orden de los id en la matriz `models` de un proveedor. + +`orderForSubagents()` luego usa una ordenación estable para mover las selecciones destacadas configuradas al frente en el mismo orden que `subagentModels`. Los modelos no destacados mantienen el orden relativo alfabético proveedor/identificador establecido anteriormente (`src/codex/catalog/sync.ts`). El rango destacado también se convierte en prioridades `0` a `4` cuando se construyen las entradas, por lo que el orden de prioridad de Codex conserva esa secuencia principal. + + + +## La visibilidad está separada del orden + +`selectedModels` y `disabledModels` deciden qué modelos enrutados están expuestos; no están ordenando controles. `filterCatalogVisibleModels()` convierte ambas selecciones en `Set` búsquedas y filtra la lista recopilada sin usar las matrices como rangos (`src/codex/catalog/provider-fetch.ts`). + +Como resultado, reordenar `selectedModels` o `disabledModels` no tiene ningún efecto sobre la posición del selector. Solo puede cambiar si se incluye un modelo. + + + +## Patrón de selector efectivo + +Sin selectores de cuenta elegibles y una lista de características no vacía, el pedido resultante es: + +1. Modelos en el orden exacto configurado `subagentModels`, con prioridades `0` a `4`. +2. Todos los modelos enrutados restantes, ordenados alfabéticamente por proveedor y luego por ID de modelo, con prioridad `5`. +3. Modelos nativos no seleccionados, empujados por debajo del bloque destacado durante la fusión del catálogo. + +Sin `subagentModels`, los modelos enrutados permanecen en la prioridad `5`, las entradas GPT nativas usan su prioridad normal (normalmente `9` para las entradas construidas por opencodex), y el grupo enrutado permanece alfabético como proveedor/identificador. + + + +## Ejemplo + +Supongamos que `subagentModels` contiene estos cinco id en este orden exacto: + +```toml +subagentModels = [ + "gpt-5.5", + "opencode-go/glm-5.2", + "anthropic/claude-opus-4-6", + "gpt-5.6-sol", + "gpt-5.6-terra", +] +``` + +El selector comienza de la siguiente manera: + +| Posición del selector | Modelo | Prioridad | Por qué aparece allí | +| ---: | --- | ---: | --- | +| 1 | `gpt-5.5` | `0` | Primera selección `subagentModels` | +| 2 | `opencode-go/glm-5.2` | `1` | Segunda selección, a pesar de que su proveedor clasifica después de `anthropic` | +| 3 | `anthropic/claude-opus-4-6` | `2` | Tercera selección | +| 4 | `gpt-5.6-sol` | `3` | Cuarta selección | +| 5 | `gpt-5.6-terra` | `4` | Quinta selección | +| 6 | `anthropic/claude-fable-5` | `5` | Primer id enrutado restante en orden alfabético proveedor/id | +| 7 en adelante | Los modelos enrutados restantes | `5` | Proveedor alfabéticamente, luego modelar id alfabéticamente | +| Después de modelos enrutados | Los modelos nativos | `featured.length + 100` o superior | Los nativos no seleccionados se mueven por debajo del bloque destacado | + +Las primeras cinco entradas son las anulaciones anunciadas a `spawn_agent`; el resto continúa en el orden normal del selector. Con los selectores de cuenta, el límite de cinco entradas se aplica después de que las opciones nativas desnudas se hayan expandido a grupos calificados por el selector. + + + +## Cambiar el orden + +Utilice `subagentModels` para elegir y ordenar los modelos líderes que Codex también anuncia a `spawn_agent`. La página **Subagentes** del panel de control puede reordenar los ID nativos y enrutados. Utilice `ocx agent subagents set` o edite la configuración opencodex para las opciones exactas `/`; el panel de control conserva esas identificaciones una vez guardadas, incluidas las opciones actualmente no disponibles. Utilice como máximo cinco ID configurados. Con los selectores de cuenta, una opción nativa puede expandirse a múltiples filas de catálogo calificadas por el selector, por lo que las opciones configuradas y las filas anunciadas no son necesariamente individuales. + +Si ninguna cuenta configurada admite un modelo nativo con apertura de cuenta, la solicitud falla como una opción de modelo no válida. Si las cuentas de soporte existen pero están temporalmente agotadas o no están disponibles, falla como un límite de tasa reintentable. Estos estados nunca se informan como una clave API no válida; elija otro modelo disponible o espere a que se vuelva a abrir la ventana de cuota de la cuenta capaz. + +Utilice `modelPickerOrder` para ordenar solo en pantalla las filas enrutadas `/` más allá del bloque destacado: + +```json +{ + "modelPickerOrder": [ + "tyler/deepseek-v4-flash", + "jd-chat/kimi-k3", + "jd-chat/glm-5.2" + ] +} +``` + +Las filas enrutadas aparecen en el orden configurado. Una fila enrutada omitida de la matriz mantiene su prioridad normal, por lo que permanece por delante de la banda de visualización `modelPickerOrder`; enumere cada fila enrutada cuya posición relativa desea controlar. Una fila también presente en `subagentModels` mantiene su prioridad destacada. Con una lista solo encaminada, las filas nativas mantienen sus posiciones normales. + +Para pedir el selector completo, incluya un identificador nativo desnudo: + +```json +{ + "modelPickerOrder": ["gpt-5.6-sol", "opencode-go/glm-5.3"] +} +``` + +Las filas listadas aparecen primero en orden de array, seguidas de las filas no listadas en orden de prioridad natural. La coincidencia utiliza ID de catálogo exactos: `gpt-5.6-sol` y `openai/gpt-5.6-sol` son filas separadas. También se aceptan ortografías crudas y codificadas del mismo id enrutado, teniendo prioridad las coincidencias exactas. Las entradas vacías son ignoradas. Las filas calificadas para la cuenta necesitan su id calificado para el selector en la lista. + + + +### Nota de migración: ID nativos en pedidos existentes + +Anteriormente, los identificadores nativos en `modelPickerOrder` fueron ignorados. Una lista existente que contiene un id nativo desnudo ahora activa el pedido de un selector completo, incluidas las filas destacadas. Retire los id nativos desnudos para mantener el comportamiento anterior solo enrutado. Las listas sin configurar, vacías y solo enrutadas conservan su comportamiento; El cálculo de los candidatos a orientación de prioridad natural de OpenCodex no ha cambiado. + +`modelPickerOrder` conserva el cálculo de prioridad natural de OpenCodex de hasta cinco candidatos preferidos para la orientación de subagentes. Cada fila movida conserva su prioridad natural por separado de su `priority` nativo; el cambio de orden del selector por sí solo no debe cambiar ese cálculo de OpenCodex. No restringe la elegibilidad para una anulación de modelo de nombre exacto: la lista nativa anunciada no es una lista de permisos, y aún se aplican las restricciones de autenticación, modelo/esfuerzo y backend existentes. + +Native Codex utiliza Native `priority` para seleccionar los primeros cinco modelos elegibles visibles para el selector anunciados por `spawn_agent` en V1 y en V2 cuando se exponen las anulaciones del modelo. Por lo tanto, los cinco anunciados pueden cambiar con la orden del seleccionador, incluso cuando los candidatos preferidos de OpenCodex permanecen sin cambios. V1 no recibe inyección de cartucho preferido OpenCodex. V2 también puede recibir orientación de prioridad natural de OpenCodex cuando el estado del catálogo del cliente lo permita; esa orientación no reordena la lista anunciada de la herramienta nativa. + +`disabledModels` y los `selectedModels` de cada proveedor siguen siendo campos de visibilidad, no controles de pedido. No hay configuración separada de `modelOrder`, `providerOrder` o mapa de prioridad. + + + +## Configuración preestablecidos del selector de panel + +En marcha **Modelos**, elige **Predeterminado**, **A–Z por modelo**, **Grupo por proveedor**, o **Instantánea más utilizada**Entonces, **Aplicar orden**. Esto guarda los identificadores de ruta actualmente visibles y `modelPickerOrderMode` (`alphabetical`, `provider`, o `most-used`) La mayoría de las lecturas usadas retienen el uso una vez cuando se aplican; las recargas restauran la instantánea sin recuperar el uso nuevamente. Los modelos nuevos o eliminados no lo vuelven a calcular automáticamente. Un pedido guardado manualmente, incluyendo un pedido completo/nativo, permanece intacto hasta que aplique explícitamente un reemplazo. El valor predeterminado borra ambos campos de selección, incluso cuando no hay modelos enrutados disponibles. + +Los controles usan `GET/PUT /api/subagent-models`: `chosen` y `available` retienen las opciones guardadas de la lista, incluidos los modelos desactivados o desaparecidos; `pickerAvailable` contiene solo identificadores de catálogo enrutados elegibles. La página Modelos envía `pickerOrder` y `pickerOrderMode`, nunca `models`. La lista solo guarda la configuración del selector de conservación. Las actualizaciones combinadas no válidas y la persistencia fallida dejan intacto el estado anterior del selector/roster. + +Los ajustes preestablecidos de solo ruta mantienen las bandas de prioridad existentes destacadas/nativas. Afectan al catálogo Codex y a los grupos dirigidos del descubrimiento Claude; El prefijo nativo de Claude y la propiedad explícita de perfil/alias de escritorio permanecen sin cambios. Se conservan los rangos de guía OpenCodex y los ajustes de reserva configurados, pero los cinco anuncios de Codex nativos y el valor predeterminado recomendado pueden cambiar con la prioridad de visualización. Guardar no reinicia clientes; puede que una actualización de catálogo permanezca pendiente, y los clientes que tengan un catálogo antiguo pueden necesitar volver a abrir. + + + + +### Orden enrutada personalizada + +Elija **Orden de encargo** en Modelos para cargar una nueva instantánea enrutada. Arrastre una fila móvil antes de otra fila, o utilice sus botones Arriba/Abajo, luego **Guardar borrador**. Las filas enrutadas destacadas permanecen en la parte delantera en su rango configurado y no pueden moverse. No se muestran las filas nativas; esto no es una vista previa del selector nativo completo. Las filas guardadas supervivientes mantienen su orden relativo y los nuevos candidatos siguen la lista de candidatos actual. Cada guardado envía la lista completa, sin cambiar la lista destacada. + +Una orden que contiene ids nativos desnudos permanece protegida hasta que aplique explícitamente un preset o Predeterminado enrutado. Seleccionar una opción diferente por sí sola no la reemplaza. Desconocido destacados bloques de estado de edición. Antes de guardar, el editor comprueba una nueva instantánea; los cambios preservan el borrador y bloquean el ahorro hasta que **Recargar y descartar borrador** cargue la configuración actual. Solicitar que los fallos retengan el borrador. Los archivos guardados aceptados aún pueden tener una actualización de catálogo pendiente; vuelva a cargar antes de volver a editar. + +El editor también requiere una identidad de modelo inequívoca para cada candidato enrutado. Si el catálogo de modelos está incompleto, actualice la página Modelos antes de editar; la recarga de la configuración del selector por sí sola no puede restaurar las identidades de catálogo que faltan. Las opciones destacadas se combinan exactamente sin recortar; las opciones duplicadas usan su última posición configurada, y los id canónicos tienen prioridad sobre los id sin procesar. diff --git a/docs-site/src/content/docs/es/guides/model-routing.md b/docs-site/src/content/docs/es/guides/model-routing.md new file mode 100644 index 00000000000..a9d28d57135 --- /dev/null +++ b/docs-site/src/content/docs/es/guides/model-routing.md @@ -0,0 +1,97 @@ +--- +title: "Enrutamiento de modelos" +description: "Cómo decide opencodex qué proveedor sirve un ID de modelo determinado." +--- + +Cuando Codex solicita un modelo, `router.ts` lo resuelve exactamente a un proveedor configurado. Las reglas se comprueban **por orden**; el primer partido gana. + +Para OpenAI, se considera una identificación `/gpt-*` configurada a través de `codexAccountNamespaces` a exactamente una cuenta Codex almacenada antes de combo o espacios de nombres de proveedor. Bare `gpt-*` ids selecciona el proveedor canónico `openai` en su lugar. Su `codexAccountMode` elige Pool (por defecto, cuentas principales más agregadas) o Direct (portadora actual de llamadas / principal) sin cambiar el ID del modelo. `openai-apikey/` explícitamente selecciona API -clave de transporte. Estas rutas de credenciales no se cruzan entre sí. + + + +Antes de estas reglas, un `policy/` explícito o un alias de perfil de enrutamiento configurado evalúa la política y enruta a su candidato concreto. Un selector de política reservado desconocido se rechaza sin continuar por las rutas de proveedores ni por la predeterminada. + +## Precedencia + +1. **Selector de cuenta Exact Codex** - si el id es `/` y el selector está configurado en `codexAccountNamespaces`, la solicitud usa solo la cuenta almacenada asignada y envía el modelo nativo desnudo aguas arriba. Si el destino exacto no está disponible, la solicitud se rechaza sin recurrir a Pool, Direct ni al enrutamiento del proveedor. + + ```text + side/gpt-5.6-sol → provider "openai", model "gpt-5.6-sol", account selector "side" + ``` + +2. **Identificación combinada o alias** - mientras se configura al menos un combo, un alias canónico `combo/` o combo configurado selecciona su objetivo concreto antes de que se comprueben los espacios de nombres del proveedor. Sin combos configurados, un proveedor físico heredado llamado literalmente `combo` sigue siendo un espacio de nombres de proveedor normal. Véase [Combos](/es/guides/combos/) para la selección de destino y el comportamiento de conmutación por error. + +3. **`provider/model` explícito** - si el id contiene `/` y la parte anterior es el nombre de un proveedor configurado, ese proveedor se utiliza y el id se quita a la parte después de la barra. + + ```text + anthropic/claude-opus-5 → provider "anthropic", model "claude-opus-5" + ollama-cloud/glm-5.2 → provider "ollama-cloud", model "glm-5.2" + openrouter/openai/gpt-5.6-sol → provider "openrouter", model "openai/gpt-5.6-sol" + ``` + + Esta es la forma explícita del proveedor de rutas, y el selector de modelos de Codex utiliza para los modelos enrutados. Si el mismo id público es un alias combinado configurado, gana la regla 2. Si el proveedor nombrado está deshabilitado, esta forma explícita lanza en lugar de enrutamiento. + +4. **Desnudo nativo OpenAI - familia id** - un id tal como `gpt-*`, `o1-*`, `o3-*`, o `o4-*` utiliza el canónico habilitado `openai` proveedor y su configurado Pool o Direct modo de cuenta. + +5. **`defaultModel` de un proveedor** - si el `defaultModel` de cualquier proveedor es igual al id, ese proveedor se usa (id pasó sin cambios). + +6. **Patrones de prefijo incorporado** - el id se compara con prefijos de familia de modelos conocidos, y luego se enruta a un proveedor configurado con ese nombre (o prefijo de nombre): + + | Prefijos | Proveedor | + | --- | --- | + | `claude-`, `claude-sonnet-`, `claude-opus-`, `claude-haiku-` | `anthropic` | + | `llama-`, `mixtral-`, `gemma-` | `groq` | + + Este emparejador se basa en el nombre y, a diferencia de las exploraciones `defaultModel` / `models[]`, actualmente no filtra un proveedor coincidente cuya bandera `disabled` es verdadera. + +7. **`models[]` de un proveedor** - si no se ganó ninguna regla de prefijo y un proveedor activo muestra el id en su `models[]`, se usa ese proveedor. La regla 4 ya envía una identificación desnuda `gpt-*` al proveedor canónico habilitado `openai` antes de que la reclamación `models[]` de otro proveedor pueda coincidir. + +8. **Proveedor predeterminado** - si nada coincide, el id se envía a `config.defaultProvider` sin cambios. (Si no hay ningún proveedor predeterminado configurado, o está deshabilitado, el enrutamiento se lanza.) + + + +## API claves y variables de entorno + +Cualquiera que sea la ruta elegida, el `apiKey` del proveedor se resuelve a través de `resolveEnvValue()`: un valor de `${OPENAI_API_KEY}` o `$OPENAI_API_KEY` se expande desde el entorno en el momento de la solicitud, por lo que los secretos nunca necesitan vivir en `config.json`. + + + +## Visibilidad del catálogo y tapas de contexto + +El enrutamiento y la visibilidad del catálogo son controles separados: + +- `disabledModels` esconde identificadores de rutas de nombres del catálogo Codex y `/v1/models`; una identificador GPT nativa desnuda se mantiene en el catálogo con `visibility: "hide"`. El **no** rechaza una solicitud directa para ese modelo. +- El `selectedModels` no vacío de un proveedor es otra lista de permisos de catálogo. El descubrimiento en vivo y el enrutamiento directo aún funcionan; solo se reducen el catálogo y las emisiones de `/v1/models`. +- Conjunto de instalaciones frescas `modelDiscovery.newModelPolicy` a `"off"`. Después de que el primer live fetch exitoso establece una línea de base, las llegadas posteriores se agregan a `disabledModels` y llevan una insignia de tablero **NUEVO** hasta que se habilita o se reconoce. Las instalaciones existentes permanecen en `"on"` hasta que se opta. La política se aplica antes de publicar modelos recién descubiertos a través de `/v1/models`, el panel de control, las exportaciones de configuración del cliente o una sincronización de catálogo Codex (incluido el inicio del servicio). Habilitar una llegada manualmente la mantiene habilitada en actualizaciones y exportaciones posteriores. Si la configuración del proveedor en ejecución difiere del disco, las listas de modelos siguen aplicando la directiva mediante una proyección temporal; dejan intacta la configuración en ejecución y las opciones guardadas. Utilice `ocx models new-policy off` a nivel mundial, agregue `--provider ` para una anulación e inspeccione `ocx models new-arrivals [--json]`. Los resultados fallidos/degradados nunca cambian la línea base. Los proveedores con un `selectedModels` no vacío (incluido el modo preestablecido) ya están curados, por lo que esta política es deliberadamente inerte para ellos. +- `provider.disabled: true` elimina ese proveedor del descubrimiento de catálogo. Las solicitudes explícitas `provider/model` fallan y las exploraciones `defaultModel` / `models[]` las omiten. +- Las filas de catálogo enrutadas se clonan a partir de la plantilla nativa Codex, por lo que los indicadores de entrega solo nativos se eliminan durante la normalización: `supports_websockets`, `supports_reasoning_summaries` y `supports_experimental_context`. Un proveedor enrutado nunca hereda el contrato de contexto experimental; heredando el Codex compacto después de casi cada paso en hilos enrutados largos. +- `providerContextCaps` se aplica por proveedor Codex -caps contexto visible. `contextCapValue` es el tablero predeterminado (350,000 por defecto), pero no hace nada por sí mismo hasta que un proveedor está presente en `providerContextCaps`. Cambiar el valor del panel de control actualiza cada límite habilitado solo cuando se activa "aplicar a cada proveedor enrutado"; de lo contrario, cada proveedor mantiene su propio límite. Las ventanas ordinarias conocidas solo se pueden bajar; los modelos nativos que admiten una ventana más larga pueden expandirse hasta su propio techo soportado. Las tapas nunca cambian el límite real del modelo ascendente. Apagar una tapa conserva su selección en `providerContextCapValues`, incluso después de la recarga; encenderla restaura esa selección. Una selección recordada nunca aplica un límite mientras está deshabilitada. El envío de `{ "setAll": true }` sin `value` habilita a todos los proveedores configurados al valor global actual y reemplaza sus selecciones recordadas. +- Un modelo GitHub Copilot que admite el nivel de contexto largo ascendente puede optar por `providers.github-copilot.modelContextTiers. = "long_context"` o `ocx provider edit github-copilot --model-context-tier =long_context`. El nivel envía `contextTier: "long_context"` en el Chat del Copiloto y Responses solicitudes. Se eleva la ventana anunciada sólo cuando ese modelo exacto tiene una ventana conocida por modelo en `modelContextWindows` (por ejemplo, `1000000`); un modelo desconocido mantiene su ventana en vivo. Gana una ventana explícita por modelo, luego se aplica el límite de proveedor existente. Las ventanas guardadas y las selecciones de nivel sobreviven al inicio y al reinicie OAuth. OAuth presets llenan los valores predeterminados por modelo que faltan mientras mantiene sus entradas configuradas, incluso en xAI. El nivel `"default"` conserva metadatos de contexto en vivo normales. El control del panel se planifica por separado. + +```json +{ + "contextCapValue": 350000, + "providerContextCaps": { + "anthropic": 350000, + "cursor": 350000 + } +} +``` + + + +## Propinas + +- **Dirigir una cuenta Codex explícitamente** con `/` (regla 1). Esa ruta es exacta y falla cerrada; nunca cambia silenciosamente a otra cuenta. +- **Sea explícito para los modelos enrutados.** Prefiera `provider/model` (regla 3) cuando esa identificación pública exacta no es un alias combinado. Nombra directamente al proveedor y coincide con lo que Codex muestra en su selector después de una sincronización de catálogo. +- **Semilla `models[]` o `defaultModel`** en un proveedor tan corto ids (reglas 5/7) resolver sin el prefijo `provider/`. +- **Los patrones de prefijo son una conveniencia**, no es una garantía: solo se resuelven si un proveedor con ese nombre (p. ej. `anthropic` o `groq`) está configurado realmente. + +Consulte [Configuración](/es/reference/configuration/) para los campos de proveedor que leen estas reglas. + + + + +## Salida estructurada en rutas Cursor + +Cursor rutas traducen Responses `text.format` (`json_object` o `json_schema`) en instrucciones explícitas de respuesta final en el contexto del sistema y solicitud activa, incluyendo continuación de resultados de herramientas. Esta es una reserva rápida: Cursor no proporciona una decodificación JSON restringida nativa en este transporte, y los modelos aún pueden devolver una respuesta no válida. El adaptador no convierte la prosa en una decisión de aprobación. Las personas que llaman deben validar el JSON devuelto y usar una ruta con capacidad de salida estructurada cuando se requiere una aplicación estricta. Las solicitudes de texto ordinarias y las llamadas de herramientas intermedias mantienen su comportamiento existente. diff --git a/docs-site/src/content/docs/es/guides/native-main-profiles.md b/docs-site/src/content/docs/es/guides/native-main-profiles.md new file mode 100644 index 00000000000..b794723a800 --- /dev/null +++ b/docs-site/src/content/docs/es/guides/native-main-profiles.md @@ -0,0 +1,138 @@ +--- +title: "Perfiles del inicio de sesión nativo principal" +description: "Administre los perfiles guardados del inicio de sesión nativo de Codex por separado del enrutamiento Pool de OpenCodex." +--- + + + +## El inicio de sesión nativo es independiente de la selección Pool + +En Multi-auth, dentro de los ajustes de Codex, abra +**Administrar el inicio de sesión principal** en el panel independiente +**Inicio de sesión nativo principal**, situado debajo de la tarjeta de la cuenta +principal. El mismo panel aparece junto a esa tarjeta en el espacio de cuentas +de Proveedores. Administra el inicio de sesión real de Codex, no la cuenta que +atenderá la siguiente solicitud Pool. No añade una pestaña de Integraciones ni +reemplaza los controles existentes de Pool. + +El **CODEX_HOME efectivo** mostrado pertenece al servidor de OpenCodex. +Si usa un panel remoto, puede estar en un equipo distinto del navegador. +**Perfil activo registrado** identifica al propietario registrado en el almacén +de perfiles cifrados. El servidor verifica el inicio de sesión real antes de +cambiarlo: un inicio de sesión modificado fuera de OpenCodex puede provocar +un error de propiedad en lugar de sobrescribirse silenciosamente. + + + +## Guardar y cambiar + +Use **Guardar el inicio de sesión actual como perfil** para registrar el inicio +de sesión de la aplicación. Si el inicio de sesión activo ya está registrado, +esta acción actualiza su nombre y no añade otra cuenta. Cambiar de perfil +requiere el almacén de credenciales en archivos compatible y un almacén de +claves del sistema operativo disponible. Los códigos de diagnóstico explican +por qué no están disponibles los controles. No eluda errores del almacén de +claves o de propiedad copiando credenciales de Pool al archivo de inicio +de sesión nativo. El panel permanece desactivado mientras la tarjeta principal +está realizando su operación de reautenticación nativa mediante dispositivo. + +Seleccione **Cambiar** junto a un perfil guardado que esté inactivo. +Revise su nombre y el **CODEX_HOME** mostrado; cierre Codex nativo en el equipo +servidor que usa ese **CODEX_HOME**. Marque la casilla bajo los pasos para +confirmar que Codex está cerrado y, después, confirme el cambio. +No se envía ninguna modificación de credenciales antes de la confirmación. +Justo antes de enviar la operación, el panel vuelve a leer el directorio actual, +el propietario activo y el estado de recuperación. Si cambiaron, revise el +nuevo estado y vuelva a confirmar. El backend sigue siendo la autoridad para +los bloqueos, las comprobaciones de procesos, el drenaje de solicitudes +en curso, la activación y la reversión. + +La confirmación muestra tres pasos: cerrar Codex en el equipo servidor para +el **CODEX_HOME** indicado; marcar la casilla que confirma que está cerrado +y confirmar el cambio; esperar el resultado y el perfil activo actualizado +antes de seguir las instrucciones para volver a abrir Codex. +Mantenga Codex cerrado hasta comprobar el resultado. Las instrucciones de +reapertura esperan a que terminen la lectura de verificación y la actualización +de cuentas. Si falla la actualización, se le pide actualizar antes de continuar. + +Si `CODEX_BUSY` bloquea el cambio, cierre Codex en el servidor para el +**CODEX_HOME** indicado, seleccione **Actualizar estado** y revise el perfil +activo. Seleccione **Cambiar** de nuevo y marque la casilla que confirma que +Codex está cerrado antes de confirmar. Actualizar solo lee el estado: +no reintenta el cambio. + +Un error de comprobación de procesos pide verificar que Codex esté cerrado +e inspeccionar los diagnósticos del servidor. Los errores por solicitudes +activas u operaciones ocupadas piden esperar a que termine el trabajo existente. +Un error de almacenamiento indica que el servidor no puede acceder de forma +segura al directorio de inicio de sesión o al almacén de perfiles; revise los +diagnósticos antes de otro cambio. Los demás errores permitidos identifican +problemas de perfil, almacén de claves, almacenamiento o recuperación, +sin mostrar mensajes sin filtrar del servidor. + +Una respuesta perdida deja el resultado sin confirmar, incluso si el perfil +activo actualizado ha cambiado. La ausencia de respuesta no significa que +se haya restaurado el inicio de sesión original. Nada se reintenta +automáticamente. Para reintentar un cambio, seleccione de nuevo la acción +y confirme que Codex está cerrado. + +Los resultados se muestran como **Último resultado confirmado**. +Una actualización manual borra el error visible, pero no confirma una +transacción anterior cuya respuesta se perdió. Puede seguir apareciendo +un requisito de reinicio de un cambio confirmado previamente. + +Después de un éxito, compruebe el perfil activo actualizado y vuelva a abrir +Codex nativo en el servidor con el **CODEX_HOME** indicado. Siga cualquier +requisito de reinicio mostrado. El panel vuelve a leer el estado de los perfiles +y actualiza el controlador de cuentas existente. No llama a las operaciones +de selección o configuración de Pool ni modifica claves de proveedores, tareas +o historial. El backend sigue conciliando la identidad nativa `__main__` +igual que en el flujo de la CLI. + + + +## Recuperación y perfiles anteriores + +Son operaciones diferentes: + +- **Recuperar el cambio interrumpido** concilia una transacción del backend + que quedó incompleta. **Restaurar la transacción pendiente** solicita + revertir esa transacción. Ambas requieren marcar la casilla que confirma + que Codex está cerrado antes de confirmar el cambio. Estos controles siguen + disponibles si no se puede leer una lista de perfiles dañada, pero los + diagnósticos indican que hay una recuperación pendiente. +- **Volver al perfil mostrado anteriormente**, después de un cambio correcto, + selecciona el perfil mostrado antes del cambio mediante el flujo normal + con confirmación. Este acceso directo solo se conserva en la memoria de + la página, vinculado al directorio y al propietario activo esperado. + Desaparece al recargar la página o al cambiar el proxy o el propietario. + La API no devuelve el origen de la transacción: no es un historial de + deshacer verificado por el servidor. Otro operador pudo cambiar el inicio + de sesión entre la lectura previa y su cambio. Después de recargar, + seleccione directamente el perfil guardado que desee. + +Un error de red no demuestra que una escritura haya fallado o se haya revertido. +Después de enviar una modificación, incluso si se pierde la respuesta, el panel +vuelve a leer el estado del servidor y nunca reintenta automáticamente. +Si falla la actualización, un cambio correcto no se presenta como deshecho. +Actualice e inspeccione los diagnósticos antes de otra operación. +El comando `ocx account main doctor` ofrece diagnósticos del servidor. + + + +## Alcance de esta fase + +El panel enumera, registra, cambia y recupera perfiles existentes mediante +`/api/native-main-profiles`. No inicia procesos de inicio de sesión ni expone +tokens de escritura para la preparación. Añadir otro inicio de sesión nativo +sigue siendo parte del flujo de CLI `ocx account main add`; el registro desde +el navegador queda para un seguimiento separado de la incidencia #3417. +La reautenticación mediante dispositivo de la cuenta principal actual es +otro flujo y no se reemplaza con este panel. + +Los datos de los perfiles no se escriben en el almacenamiento del navegador. +El cliente solo expone campos públicos, muestra códigos de error permitidos +en lugar de mensajes sin filtrar del servidor y utiliza el mecanismo +autenticado de solicitudes existente en la aplicación. +Se mantienen las comprobaciones del backend para la autenticación de +administración, las sesiones GUI/CSRF y la admisión de rutas. diff --git a/docs-site/src/content/docs/es/guides/opencode.md b/docs-site/src/content/docs/es/guides/opencode.md new file mode 100644 index 00000000000..c5cd17a91e1 --- /dev/null +++ b/docs-site/src/content/docs/es/guides/opencode.md @@ -0,0 +1,167 @@ +--- +title: "OpenCode" +description: "Usa modelos enrutados desde OpenCode: opencodex inyecta el proveedor durante el lanzamiento y conserva tus archivos de configuración." +--- + +OpenCode combina varias capas de configuración JSON para leer sus proveedores. No ofrece una variable equivalente a `ANTHROPIC_BASE_URL`. `ocx opencode` resuelve esa integración: comprueba que el proxy esté en ejecución, construye un bloque de proveedor a partir del catálogo visible y lo inyecta mediante la configuración en línea de OpenCode (`OPENCODE_CONFIG_CONTENT`). + + + +## Inicio rápido + +```bash +ocx opencode +``` + +El comando comprueba que el proxy esté en ejecución y abre OpenCode con los bloques generados `provider.opencodex` y `providers.opencodex`, solo para ese proceso. El primero usa la estructura heredada de V1 y el segundo la estructura nativa de V2. Ambos incluyen las variantes de esfuerzo de razonamiento en el formato de su cliente. Los argumentos adicionales se transmiten al cliente: `ocx opencode run "hello"`. + +Los modelos enrutados aparecen en el selector bajo el proveedor `opencodex`: + +```text +opencodex/kiro/glm-5 +opencodex/gpt-5.6-sol # native slugs stay unprefixed +``` + + + +## Esfuerzo de razonamiento + +OpenCode ofrece el esfuerzo de razonamiento mediante *variantes* del modelo. opencodex genera una variante por cada esfuerzo declarado, incluido `none` cuando el modelo admite explícitamente desactivar el razonamiento. La selección llega al proxy como esfuerzo de razonamiento, además de mostrarse en el selector. Las asignaciones de esfuerzo al proveedor de origen que existan en opencodex siguen aplicándose. + +Se generan dos bloques de proveedor: + +| Bloque | Cliente que lo lee | Formato de variantes | +|---|---|---| +| `provider.opencodex` | OpenCode V1 (`npm` + `options`) | Mapa de opciones heredado | +| `providers.opencodex` | OpenCode V2 (`package` + `settings`) | Array de configuración nativo | + +V2 usa su array nativo de variantes en lugar del mapa heredado. Ambos bloques identifican los mismos proveedores y modelos y se combinan en una sola entrada; ningún modelo aparece duplicado. V2 siempre escribe el array de variantes, vacío cuando no se declara ninguna, para impedir que el cliente invente opciones de esfuerzo bajo, medio y alto. En el bloque heredado, los modelos conocidos de razonamiento fijo desactivan por el mismo motivo todos los niveles generados automáticamente; esas entradas desactivadas no son esfuerzos seleccionables. + +Si se conoce el esfuerzo predeterminado del modelo, se exporta; elegir una variante sustituye ese valor en el cliente. Si el catálogo no declara un predeterminado, no se inventa ninguno. El lanzador regenera estos ajustes en cada inicio. Después de cambiar el predeterminado en opencodex, actualiza la integración administrada o vuelve a exportar la instantánea manual. + + + +## Imágenes y archivos adjuntos + +OpenCode decide si un modelo admite imágenes a partir de su entrada de catálogo. No puede consultar models.dev sobre `opencodex`, porque ese proveedor no está registrado allí. Por eso, los bloques generados incluyen las capacidades por modelo que el proxy informa en `GET /api/models`. Por ejemplo, el bloque heredado contiene `attachment` y `modalities`: + +```json +"gpt-5.6-luna": { + "name": "gpt-5.6-luna (native)", + "limit": { "context": 272000, "output": 128000 }, + "attachment": true, + "modalities": { "input": ["text", "image"], "output": ["text"] } +} +``` + +V2 recibe los campos nativos `capabilities.input` y `capabilities.output`. Cuando se conoce la compatibilidad con herramientas, también recibe `capabilities.tools`. Los clientes heredados leen los campos del ejemplo anterior. Si el catálogo anuncia entrada de imágenes para un modelo cubierto por el sidecar de visión, OpenCode permite enviar el adjunto para que el sidecar lo describa antes de la solicitud al proveedor de origen. + +V2 exige un booleano `tools` cuando existe el objeto nativo de capacidades. Si se desconoce la compatibilidad con herramientas, se omite ese objeto. Las modalidades de entrada conocidas siguen llegando a V2 mediante la migración del bloque heredado. Así se evita inventar capacidades o generar una configuración de proveedor inválida. + +Cuando una capacidad es desconocida, se conservan las suposiciones predeterminadas de OpenCode; esas suposiciones no prueban lo que admite el proveedor. Los metadatos que declaran explícitamente un modelo de solo texto impiden enviarle imágenes desde el cliente. + +Los modelos personalizados heredan los metadatos conocidos del catálogo, salvo que se guarde una anulación explícita. Una entrada personalizada que declara solo texto se mantiene así. Las capacidades desconocidas se omiten y una lista explícitamente vacía de esfuerzos no afirma que el modelo sea incapaz de razonar. + + + +## Tus archivos de configuración se conservan + +El lanzador no copia ni reescribe `~/.config/opencode/opencode.json`, los archivos de proyecto `opencode.json` / `opencode.jsonc` ni ninguna otra capa de configuración en disco. Puede leer la configuración global o del proyecto para detectar una definición del proveedor en `provider.opencodex` o `providers.opencodex`. Tus proveedores, agentes, atajos de teclado, entradas MCP y referencias relativas `{file:…}` siguen resolviéndose desde sus archivos originales. + +Solo para ese inicio, opencodex añade los dos bloques generados, `provider.opencodex` y `providers.opencodex`, mediante la configuración en línea de OpenCode. Esta capa se combina después de las capas global, personalizada y del proyecto, y sustituye únicamente las claves en conflicto para el proceso hijo. + +| Capa | Comportamiento con `ocx opencode` | +| --- | --- | +| Configuración global, personalizada o del proyecto | Permanece en disco tal como la escribiste | +| Configuración en línea (`OPENCODE_CONFIG_CONTENT`) | Recibe los bloques generados `provider.opencodex` y `providers.opencodex`, combinados con la configuración en línea heredada | +| Rutas relativas `{file:…}` | Se resuelven respecto del archivo de configuración que las definió | + +Si la configuración global o del proyecto ya define `provider.opencodex` o `providers.opencodex`, el lanzador muestra una nota informativa: la capa de `ocx opencode` tiene prioridad durante ese inicio. + + + +## Añadir el bloque a tu configuración + +`ocx opencode` inyecta el proveedor solo para un inicio. Ejecutar `opencode` directamente no configura el proxy. Para usar los modelos enrutados desde ese comando o desde una extensión del editor que no pase por el lanzador, `ocx export` muestra los mismos bloques para que los combines con tu configuración: + +```bash +ocx export --client opencode +``` + +El proxy debe estar en ejecución. El comando muestra la configuración, el destino canónico (`~/.config/opencode/opencode.json`, o bajo `XDG_CONFIG_HOME` si está definido), la advertencia para combinarla y la línea de exportación de la variable de entorno. Nunca modifica ese archivo: añadir los bloques a tu configuración es una acción explícita tuya. + +:::caution[Combina la configuración; no la reemplaces] +Combina ambos bloques, `provider.opencodex` y `providers.opencodex`, con el contenido existente. Reemplazar el archivo completo elimina tus otros proveedores, agentes, atajos y entradas MCP. Por ese motivo, `ocx export --out` rechaza sobrescribir un archivo existente. Dirige `--out` a una ruta temporal y copia los bloques: + +```bash +ocx export --client opencode --out ~/opencodex-opencode.json +``` +::: + +El bloque añadido manualmente es una instantánea estática: no sigue los cambios del catálogo como el bloque del lanzador. Vuelve a ejecutar `ocx export` después de añadir un proveedor o cambiar la visibilidad o los metadatos de un modelo. También puedes [activar la integración administrada](/es/guides/integrations/): `ocx sync` actualiza los bloques que ya administra, conservando los editados o eliminados manualmente. + +Después de combinar los bloques, exporta la clave de acceso antes de abrir OpenCode si el listener de inferencia exige autenticación. Un listener vinculado únicamente a loopback no la requiere: + +```bash +export OPENCODEX_OPENCODE_API_KEY= +``` + + + +## La clave de acceso no se escribe en disco + +Cuando el proxy requiere una clave API, la configuración en línea usa la referencia `{env:…}` de OpenCode en lugar del secreto. Los listeners vinculados a loopback la usan como `apiKey`; los demás la envían solo mediante `x-opencodex-api-key`, manteniendo separadas la autenticación del proxy y la cabecera `Authorization` del proveedor de origen. + +Ejemplo de loopback: + +```json +"options": { + "baseURL": "http://127.0.0.1:10100/v1", + "apiKey": "{env:OPENCODEX_OPENCODE_API_KEY}" +} +``` + +Ejemplo fuera de loopback: + +```json +"options": { + "baseURL": "http://192.168.1.10:10100/v1", + "headers": { + "x-opencodex-api-key": "{env:OPENCODEX_OPENCODE_API_KEY}" + } +} +``` + +El valor real solo se transmite mediante el entorno del proceso hijo. `OPENCODEX_API_AUTH_TOKEN` tiene prioridad, seguido del archivo protegido de token del servicio y de una clave API configurada. Un listener vinculado fuera de loopback exige una credencial aceptada. + +Un listener vinculado a loopback (`127.0.0.1`, el valor predeterminado) no exige una clave del plano de datos, aunque haya claves de cliente configuradas. Para ese listener puedes dejar sin establecer la variable de la referencia `{env:…}`. La URL local por sí sola no basta: un listener público vinculado a `0.0.0.0` sigue exigiendo una clave aceptada aunque se acceda por `127.0.0.1`. Exporta la clave cuando `hostname` esté configurado fuera de loopback; consulta [Acceso remoto](/es/reference/configuration/server/#remote-access). Esta clave pertenece a opencodex y es distinta de las claves de los [proveedores de origen](/es/guides/providers/). + + + +## Revertir + +El lanzador no escribe ningún archivo de configuración generado en `~/.opencodex`. Ejecuta `opencode` directamente para que lea tu configuración como antes. + + + +## Límites de modelos + +`limit.context` solo se escribe cuando el catálogo informa una ventana de contexto confirmada. Si no la conoce, se omite todo el bloque `limit` y OpenCode conserva sus valores predeterminados. + +El límite de salida usa el máximo conocido del modelo en el catálogo o los metadatos generados. Solo si se desconoce se usa `32000`. Siempre se limita a la ventana de contexto, incluso cuando el máximo conocido es inferior a `32000`. + +Los límites de entrada conocidos también se incluyen y se limitan al contexto; los desconocidos se omiten. La exportación de la CLI y del dashboard, la actualización administrada y el lanzador comparten los mismos metadatos efectivos. + +El bloque del proveedor `opencodex` se regenera en cada inicio, por lo que los ajustes manuales por modelo dentro de ese bloque no se conservan. Guarda tus entradas personalizadas bajo una clave de proveedor propia. + + + +## Requisitos + +OpenCode debe estar instalado y disponible en `PATH`: + +```bash +npm install -g opencode-ai +``` + +El lanzador lee el catálogo con el token de administración local obtenido del entorno o del directorio del proxy en ejecución. Se conecta directamente a un listener de administración de loopback y rechaza redirecciones. Un hub vinculado solo a una dirección no local necesita activar `hub.managementIngress`. El token de administración no se pasa al proceso hijo de OpenCode: la inferencia sigue usando su clave de datos independiente. Si falta el token de administración local, el lanzador informa del problema; no vuelve a intentarlo con una clave de datos. diff --git a/docs-site/src/content/docs/es/guides/pi.md b/docs-site/src/content/docs/es/guides/pi.md new file mode 100644 index 00000000000..ee5170a743d --- /dev/null +++ b/docs-site/src/content/docs/es/guides/pi.md @@ -0,0 +1,124 @@ +--- +title: "Pi" +description: "Usa modelos enrutados desde Pi: ocx export genera un proveedor personalizado para models.json conectado al proxy." +--- + +Pi lee sus proveedores de un archivo JSON global, por lo que opencodex no lo inicia. `ocx export` genera el bloque del proveedor `opencodex`, con la URL base, la lista de modelos y un marcador de clave local que no es secreto. Debes combinarlo con tu propia configuración. + + + +## Inicio rápido + +Inicia el proxy y muestra la configuración: + +```bash +ocx start +``` + +Mantén ese proceso en ejecución. En una segunda terminal, muestra la configuración: + +```bash +ocx export --client pi +``` + +La salida comienza con el JSON e indica después la ruta de destino, la advertencia para combinar la configuración, la indicación de uso local y cuántos modelos tienen límites de contexto confirmados. Esta exportación solo admite un proxy de loopback sin autenticación; no configura el acceso remoto. + +```json +{ + "providers": { + "opencodex": { + "baseUrl": "http://127.0.0.1:10100/v1", + "api": "openai-completions", + "apiKey": "opencodex-loopback", + "compat": { + "sendSessionAffinityHeaders": true, + "supportsDeveloperRole": false + }, + "models": [ + { + "id": "anthropic/claude-opus-5", + "name": "Claude Opus 5 (anthropic)", + "input": ["text"], + "contextWindow": 200000, + "maxTokens": 128000 + } + ] + } + } +} +``` + +Los proveedores generados para Pi activan `compat.sendSessionAffinityHeaders`. Conserva esta opción al combinar o editar el proveedor: Pi aporta una identidad estable de sesión y OpenCodex deriva de ella la afinidad canónica de OpenCode Go. Pi puede omitir esa identidad cuando `cacheRetention` es `none`. + +También establecen `compat.supportsDeveloperRole` en `false`, para que Pi envíe su prompt de sistema como `system` en lugar de `developer`. OpenCodex reenvía los roles de Chat Completions tal como llegan; varios proveedores compatibles con OpenAI rechazan `developer` con HTTP 400, mientras que todos aceptan `system`. + +Los identificadores son los selectores canónicos del proxy. Los modelos enrutados aparecen como `provider/model` (`anthropic/claude-opus-5`), y los modelos nativos de OpenAI conservan su identificador sin prefijo (`gpt-5.6-sol`). El sufijo de `name` —`(anthropic)`, `(native)` o `(routed)`— permite distinguir modelos con el mismo nombre de distintos proveedores en el selector de Pi. + + + +## Dónde se guarda + +El archivo global de modelos de Pi es: + +```text +~/.pi/agent/models.json +``` + +:::caution[Combina la configuración; no la reemplaces] +`ocx export` nunca escribe ese archivo. Combina el bloque `providers.opencodex` con el contenido existente: reemplazar todo el archivo destruye los demás proveedores configurados. `--out` sirve para una ruta temporal y no sobrescribe archivos existentes salvo que se indique `--force`: + +```bash +ocx export --client pi --out ~/opencodex-pi-models.json +ocx export --client pi --json > ~/opencodex-pi-models.json # or redirect the byte-exact JSON +``` +::: + +El bloque exportado es una instantánea estática. Vuelve a ejecutar `ocx export` después de añadir un proveedor o cambiar la visibilidad de modelos y combina el bloque nuevo con el anterior. + + + +## La clave de acceso + +El `apiKey` exportado es el marcador no secreto `opencodex-loopback`. No se genera ni se requiere una variable `OPENCODEX_API_KEY`. El exportador solo admite un proxy local de loopback sin autenticación y rechaza servidores remotos o protegidos con token. Las credenciales de los proveedores permanecen en la configuración de opencodex, como explica [Proveedores](/es/guides/providers/); nunca pongas una clave del proveedor de origen en este bloque de Pi. Para acceso remoto, usa una integración que admita credenciales de acceso al proxy. Cambiar el marcador no habilita la exportación remota de Pi. + + + +## Metadatos de modelos + +`contextWindow` y `maxTokens` solo se incluyen cuando el catálogo informa una ventana de contexto confirmada. Si no hay una, se omiten ambos y Pi aplica sus valores predeterminados; `ocx export` indica cuántas entradas están en ese caso. + +Los límites de salida usan el máximo conocido del modelo en el catálogo o los metadatos generados. Solo si ese límite se desconoce se usa `32000`. La salida siempre se limita a la ventana de contexto, incluso cuando los límites conocidos son inferiores a `32000`. + +El campo `cost` se omite porque requiere cuatro precios y opencodex no tiene esos datos para los modelos enrutados; emitir ceros afirmaría que todos son gratuitos. + +`reasoning`, que antes se omitía, ahora se deriva de los niveles de esfuerzo del catálogo. Pi guarda un booleano: una lista **no vacía** genera `"reasoning": true`; sin lista, o con una explícitamente vacía, no se anuncia razonamiento. Así Pi ofrece el control solo para modelos cuyo catálogo declara que aceptan parámetros de razonamiento (`reasoning_effort`). La exportación también genera `thinkingLevelMap`, que oculta con `null` los niveles de Pi sin un destino declarado, para que no se ofrezca ni envíe un esfuerzo ajeno a la lista. Si se declara `ultra` sin `max`, el nivel `max` de Pi se asigna a `ultra`, que sí pertenece a la lista. Si necesitas otra asignación, edita `thinkingLevelMap` según la documentación de Pi. + +Trata `reasoning` como un metadato de interfaz de Pi, no como prueba de compatibilidad nativa del proveedor. Lo que el proxy envía para un valor `reasoning_effort` depende del adaptador y el modelo: puede reenviarlo, convertirlo a otro nombre del protocolo, limitarlo a los niveles configurados, emularlo u omitirlo (por ejemplo, con `noReasoningModels`). El booleano solo decide si Pi ofrece el control. + + + +## Compatibilidad de adjuntos y solicitudes + +:::note[Comportamiento pendiente de publicación] +Los cambios de paridad de proveedores descritos aquí están en la cadena de PR de desarrollo; una versión instalada anterior puede conservar la conversión previa. +::: + +OpenCodex normaliza las imágenes de usuario con formato Pi/MCP o Anthropic antes de elegir una ruta Chat nativa o traducida. Las imágenes devueltas por herramientas pasan a un mensaje de usuario traducido después de los resultados de herramientas emparejados; las imágenes normales de usuario y los resultados de texto pueden conservar la ruta nativa. Usa `tool_calls` y `role: "tool"` con `tool_call_id`: se rechaza la traducción de imágenes en resultados antiguos `function`, en lugar de descartar el resultado silenciosamente. + +Un esfuerzo explícito `none` se conserva al convertir a Chat. Los límites de salida y controles de muestreo se conservan para destinos Responses genéricos con clave API; el destino canónico de ChatGPT sigue aplicando sus restricciones. Esto no hace equivalentes los controles de todos los proveedores. + +El audio WAV/MP3 incluido en un mensaje de usuario o resultado de herramienta se conserva al convertir a OpenAI Chat como contenido `input_audio`. El audio de herramientas pasa a un mensaje de usuario posterior a los resultados emparejados, porque los mensajes de herramienta de Chat solo admiten texto. Un documento con sus propios bytes base64 en un mensaje de usuario también se conserva: llega a Anthropic, OpenAI Chat y Google como documento nativo, parte de archivo y datos en línea, respectivamente. Los demás casos devuelven un error explícito: audio remoto o incompatible, referencias remotas o identificadores de archivo que el proxy no pueda resolver, adjuntos en mensajes de sistema, documentos en resultados de herramientas y documentos enviados a un protocolo sin soporte para bytes. Las imágenes con solo identificador de archivo tienen la misma limitación. Convierte el adjunto a texto o usa un protocolo nativo y un modelo que lo admitan. Chat nativo y Responses sin conversión (incluido Azure) conservan su comportamiento; esto no promete compatibilidad multimedia de todos los modelos. Los límites de conversión de video dependen del adaptador. + + + +## Estado del esquema + +:::note[Sin verificar en una instalación real] +La estructura anterior sigue la documentación pública de proveedores personalizados de Pi. **No se ha verificado** con un archivo `~/.pi/agent/models.json` real de una instalación de Pi. Si Pi rechaza el bloque exportado, el error está de nuestro lado: [abre una issue](https://github.com/lidge-jun/opencodex/issues) con el mensaje que muestra Pi. +::: + + + +## Requisitos + +Un proxy opencodex en ejecución (`ocx start`) y Pi instalado. `ocx export` lee el catálogo activo mediante la API de administración del proxy, por lo que no genera una configuración con la lista de modelos vacía. diff --git a/docs-site/src/content/docs/es/guides/protocol-paths.md b/docs-site/src/content/docs/es/guides/protocol-paths.md new file mode 100644 index 00000000000..ce93515fc38 --- /dev/null +++ b/docs-site/src/content/docs/es/guides/protocol-paths.md @@ -0,0 +1,125 @@ +--- +title: "Rutas de protocolo" +description: "Cómo una solicitud en el Responses, Chat Completions o Messages API llega a un proveedor, cómo obtener una vista previa y rastrear esa ruta, y los switches por etapas que la cambian." +--- + +opencodex sirve a tres API de cliente: **Responses** (`/v1/responses`), **Chat Completions** (`/v1/chat/completions`) y **Messages** (`/v1/messages`). Cada proveedor recibe un cable ascendente, decidido por su adaptador. Cuando el cliente API y el cable ascendente difieren, la solicitud se convierte en el camino de entrada y la respuesta se convierte en el camino de regreso. Esta página explica cómo se nombra esa ruta, cómo verla antes y después de una solicitud y qué ajustes la cambian. + +Los ajustes de esta página están desactivados de forma predeterminada, salvo `antigravityDirect`, que está activado. Esta excepción permite la ruta directa de Antigravity cuando corresponde; las demás opciones requieren activación explícita. + + + +## Modos de entrega + +Una ruta es una lista de saltos desde el cliente API al cable ascendente. Los saltos son los tres API nombres, `ir` (petición de adaptador-neutral de opencodex y formulario de evento), y `responses-internal` (Responses JSON o SSE producido sólo como un puente interno, nunca visto por un cliente). + +| Modo | Descripción | Ruta de solicitud de ejemplo | +| --- | --- | --- | +| `native` | Mismo API en ambos extremos; el cuerpo del cliente es lo que recibe el proveedor | `chat > chat` | +| `translated` | Convertido una vez, a través del códec del cable de destino o el IR | `chat > responses`, `responses > ir > messages` | +| `legacy-bridge` | Convertido a través de la forma interna Responses primero | `chat > responses-internal > ir > messages` | +| `blocked` | Rechazado antes de que nada fuera enviado | Ninguno | + +`native` describe cómo viaja una solicitud. No es un veredicto de compatibilidad: una ruta nativa todavía puede cumplir con un proveedor que rechaza un campo, y los resultados verificados de Compatibility Lab son una cosa separada. + +Con cada apagado, una ruta de proveedor único elegible toma estos caminos: + +| Cliente API → aguas arriba | Ruta | +| --- | --- | +| Responses → Responses | Nativo | +| Responses → Chat o Messages | Traducido a través de IR | +| Chat → Chat | nativo (JSON cuando el cliente envía `stream: false`) | +| Chat → Responses, Messages → Responses | traducido a través del codec Responses | +| Chat → Messages, Messages → Chat | Puente legado | +| Messages → Messages | nativo solo cuando el llamante reenvía su propia credencial Anthropic; el puente heredado para una clave opencodex administra | + +Los combos, las políticas de enrutamiento y el esfuerzo sintético o las filas de modelos rápidos toman el puente heredado de Chat y Messages a menos que un interruptor a continuación indique lo contrario. + + + +## Efectos de función + +Algunas características de solicitud no pueden sobrevivir a cada conversión. Por ejemplo, los campos de Chat `n`, `logprobs`, `logit_bias`, `seed`, `audio` y `prediction` no tienen lugar en un cuerpo Responses, y el campo Messages `top_k` se deja caer en el camino hacia Responses. opencodex registra cada efecto como `passthrough`, `translated`, `degraded` o `unsupported` (mostrado como *Caído* en el tablero de instrumentos). Estos se declaran desde el código de los convertidores; no son resultados medidos. + + + +## Previsualizar una ruta + +Una vista previa se calcula solo a partir de su configuración. No envía nada a ningún proveedor, no avanza la rotación combinada y no se registra. + +- Panel de control: **API** página, **Solicitar vista previa de ruta**. +- CLI: + + ```bash + ocx api explain --model combo/main --inbound chat --feature request.seed + ocx api explain --model claude-sonnet-4-5 --inbound messages --json + ``` + +La vista previa enumera cada ruta candidata con su ruta de solicitud, modo de entrega, efectos de características y si la política `reject` (abajo) la rechazaría. `ocx api protocols --json` enumera los nombres de las características que acepta. Una solicitud Messages que reenvía la propia credencial Anthropic del llamante se muestra con `caller-credential-required` en lugar de suponerse, porque una vista previa no tiene llamante. + + + +## Rastrear una solicitud + +Cada solicitud que llegó a un proveedor, o fue rechazada antes de enviar, registra la ruta que realmente tomó en su fila de registro: el modo final y las rutas, las razones, los efectos de las características y una ruta por intento físico. En el panel de control, **Troncos** muestra una insignia de ruta, un filtro **Ruta de protocolo** y una sección **Ruta de protocolo** en el detalle de la solicitud. Las filas más antiguas no tienen datos de trayectoria y lo dicen; nada se adivina. + + + +## Características irrepresentables + +`protocols.unrepresentable` decide lo que sucede cuando una solicitud lleva una característica que su trayectoria caería: + +- `legacy` (predeterminado): la solicitud se envía como antes, y la pérdida solo aparece en los efectos de la característica de seguimiento. +- `reject`: la solicitud se rechaza con HTTP 400 antes de que se envíe nada, nombrando solo las claves de características. Chat respuestas `invalid_request_error` con código `unsupported_feature`; Messages respuestas `invalid_request_error`. El trazo es `blocked`. + +Bajo `reject`, una ruta directa se juzga en el ingreso una vez que su proveedor y el alambre se establecen. Los combos y las políticas no se juzgan en el ingreso; con `nativeChatCombos` encendido, un combo de Chat juzga a cada candidato y omite uno que no puede llevar la solicitud. + + + +## Interruptores de despliegue + +Estos interruptores preparan los nuevos caminos. Cada uno por defecto está apagado excepto `antigravityDirect`, y un interruptor que está apagado no cambia nada. + +| Interruptor | Cuando esté | +| --- | --- | +| `nativeChatCombos` | Un candidato de chat elegible dentro de un combo se envía de forma nativa desde su propia copia del cuerpo del cliente; los otros candidatos mantienen el puente. | +| `managedMessagesNative` | Una solicitud Messages cuya ruta es un proveedor de Anthropic autenticado por clave directa se envía como Messages en lugar de a través del puente. Las rutas que necesitan un comportamiento de solo puente (un esfuerzo anclado, elisión de habilidades bloqueadas, el sidecar de búsqueda web, preprocesamiento de visión, filas sintéticas) permanecen en el puente. | +| `managedMessagesNativeOAuth` | Nativo Messages para el proveedor sin agrupar `anthropic` OAuth en `api.anthropic.com`. Efectivo solo junto con `managedMessagesNative`; un conjunto de cuentas Anthropic OAuth agrupado permanece en el puente. | +| `directEncoders` | Para un flujo ascendente no Responses, la respuesta a un cliente Chat o Messages se codifica directamente a partir de los eventos del adaptador en lugar de a través del flujo interno Responses. El lado de la solicitud no cambia. | +| `antigravityDirect` | **Activado por defecto**; establecerlo en `false` para apagarlo. Una solicitud de Chat o Messages cuya ruta es un proveedor Google Antigravity salta el cuerpo interno Responses en ambas direcciones: la conversación se decodifica desde el cuerpo del cliente directamente en lo que compila el adaptador Google, y la respuesta se codifica directamente como con `directEncoders`. El camino lee `chat -> ir -> other` o `messages -> ir -> other`. Las configuraciones de solicitud (modelo, esfuerzo, límites, elección de herramientas) aún pasan por las políticas habituales, por lo que la rotación de la cuenta, las reglas de esfuerzo y el uso no cambian. Combos, políticas, una herramienta de búsqueda web alojada, imágenes para un modelo marcado solo texto, un modelo que la intercepción de llamada de sombra podría reescribir y texto que el proxy reescribe (un catálogo de habilidades, un enlace de imagen generada) permanecen en el puente y la fila de registro nombra la razón. | +| `shadowPlan` | Al final de cada Chat o solicitud Messages, el plan que una vista previa habría predicho se compara con la ruta que tomó la solicitud; un desacuerdo agrega `planMismatch: true` al registro de ruta de la fila de registro. No se envía ninguna segunda solicitud. | + +Cámbialos con el CLI o editando `protocols` en `config.json` ([referencia](/es/reference/configuration/server/#protocol-paths-protocols)): + +```bash +ocx api policy # show the current policy; changes nothing +ocx api policy --rollout shadowPlan=on # change one switch +ocx api policy --unrepresentable reject +``` + +`ocx api policy` escribe solo cuando pasa una bandera de configuración, y solo cuando la ejecuta. + + + +### Plano de sombra + +`shadowPlan` es el primer paso seguro: no cambia ninguna solicitud. Comprueba si la vista previa está de acuerdo con la realidad para el tráfico que realmente envías. La comparación utiliza la ruta en la que se estableció la solicitud (para un combo, el objetivo que respondió), y compara el modo de entrega, el cable ascendente y la ruta de la solicitud. La ruta de respuesta no se compara, porque `directEncoders` lo cambia y la vista previa no modela ese cambio. No se comparan una solicitud de Messages enviada por el llamante y un rechazo de compatibilidad de Claude. Responses solicitudes no se comparan. + +`planMismatch` aparece en el `protocolTrace` de una fila devuelta por `GET /api/logs`. El panel de control aún no lo muestra. + + + +## Lo que aún no se ha movido + +Estos caminos todavía utilizan el puente interno Responses o no están cubiertos: + +- El chat y las solicitudes Messages todavía se decodifican en un cuerpo con forma de Responses antes de la IR, incluso en una ruta traducida. La excepción es una solicitud de Chat o Messages a una única ruta Google Antigravity, a menos que `antigravityDirect` se establezca en `false`. +- Los candidatos de la política de enrutamiento, combos alcanzados a través de una fila de esfuerzo, combos candidatos mientras `nativeChatCombos` está apagado y Messages combos. +- Direct (`directEncoders`) cubre solo una ruta concreta, no Responses en la entrega de transmisión. Los hijos combinados y de políticas, la compactación enrutada, los adaptadores de ejecución-giro (Cursor, Devin, los CLI de agentes de codificación, CodeBuddy) y los giros laterales mantienen el puente. +- Un candidato combinado nativo de Chat que falla en la banda antes de cualquier salida no pasa al siguiente candidato; uno puenteado lo haría. +- Los sidecares de búsqueda, visión y generación de imágenes web solo funcionan en la tubería Responses. +- `previous_response_id`, `store`, `background`, y características de la suspensión de compactación Responses. +- Los adaptadores cuyo cable no es ninguna de las tres API (Gemini, Kiro, Cursor y otros) se traducen a través del IR sin reivindicaciones de características. +- Messages nativo administrado a Anthropic de primera parte preservar un coherente observado Claude Code CLI agente de usuario, UUID de sesión y encabezados SDK permitidos en la actualización y selección de cuenta de token. La colocación de credenciales sigue siendo propiedad de un proxy y la lista de permisos beta aún se aplica. Desaparecidos o no válidos usa los encabezados de compatibilidad existentes; los hosts compatibles y Responses generados retienen su comportamiento actual. Los encabezados por sí solos no autorizan solicitudes ni establecen soporte oficial. El agente de TypeScript SDK `sdk-ts` punto de entrada usuario-agente se reconoce con el mismo requerido encabezados de identidad, preservando sus betas de características nativas permitidas en las solicitudes Anthropic de origen. +- El chat nativo de más de OAuth no está planeado. Nativo Messages sobre Anthropic OAuth cubre solo una cuenta no agrupada; un conjunto de cuentas agrupadas permanece en el puente. +- La ruta nativa gestionada Messages reenvía los valores de `anthropic-beta` del llamante solo desde una lista de permisos corta y solo a `api.anthropic.com`, deja caer los campos de nivel superior fuera de su lista de permisos sin un efecto de característica, y no aplica `claudeCode.stabilizePromptCache`. Un cliente reconocido Claude Code mantiene `context-management-2025-06-27` junto con su campo de cuerpo `context_management`. Para la clave Anthropic de origen y las solicitudes OAuth, cualquier cliente nativo Messages puede enviar `thinking-binding-controls-2026-08-01` con `thinking.block_binding` en pensamiento adaptativo o habilitado. Las tiras proxy que anidaban en el campo cuando la beta está ausente o el destino no lo soporta, preservando el resto de la configuración pensante. Los puntos finales de proveedores en la nube y los proveedores compatibles con terceros no heredan el soporte beta de terceros. El emparejamiento utiliza el encabezado final, incluidas las betas configuradas por el operador; solo una beta es válida para [Diagnósticos de transformación del pensamiento](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking). Los nombres beta caídos aparecen una vez en el registro proxy como `anthropic-beta-dropped=`. diff --git a/docs-site/src/content/docs/es/guides/providers.md b/docs-site/src/content/docs/es/guides/providers.md new file mode 100644 index 00000000000..a7e6e77b4b8 --- /dev/null +++ b/docs-site/src/content/docs/es/guides/providers.md @@ -0,0 +1,929 @@ +--- +title: "Proveedores" +description: "En todos los sentidos opencodex autentica y habla con un proveedor de LLM — OAuth, API clave, ChatGPT hacia adelante y local." +--- + +Un **proveedor** es un punto final de LLM ascendente más cómo llegar a él: un adaptador, una URL base, un modo de autenticación y una lista de modelos opcional. Los proveedores viven bajo `providers` en `~/.opencodex/config.json`. + +La vista general del proveedor del panel separa los detalles de conexión, el uso de la cuenta y las notas editables. Las notas aparecen una vez, debajo de las secciones de conexión y autenticación. Los ajustes preestablecidos de patrocinador compatibles también muestran una breve introducción, una etiqueta de patrocinador y enlaces al sitio o consola del proveedor. Estos enlaces conservan los parámetros de referencia del preset. La información del patrocinador se muestra solo cuando el nombre del proveedor configurado, el adaptador y el punto final coinciden con el ajuste preestablecido; nunca cambia el enrutamiento, la selección de la cuenta o los valores predeterminados. + + + +## Modos de cuenta OpenAI + +| Id de proveedor | Uso | Regla de credenciales/cuenta | +| --- | --- | --- | +| `openai` | Codex inicio de sesión | Pool (predeterminado) selecciona las cuentas principales más las cuentas agregadas; Direct utiliza el inicio de sesión actual de la persona que llama/principal solamente. | +| `openai-apikey` | OpenAI API | Configurado API clave/grupo de claves solamente; nunca lee Codex cuentas. | + +Utilice `gpt-5.6-sol` desnudo con la opción Pool / Direct en la página de proveedores, o `openai-apikey/gpt-5.6-sol` para API. Las rutas de credenciales nunca se cruzan entre sí. La ruta API publica 1,050,000 metadatos de entrada de contexto / 922,000 máximos. Sus identificadores virtuales `sol-pro`, `terra-pro` y `luna-pro` mantienen su identidad pública seleccionada, mientras que el cable utiliza el modelo base más `reasoning.mode: "pro"`. + +Si el proveedor `openai` integrado no está disponible o está desactivado, el selector de cuentas del panel de control y la página Codex Auth pueden restaurarlo: las filas ausentes se crean a partir del preajuste canónico, las filas canónicas deshabilitadas se vuelven a habilitar sin reemplazar la configuración del modelo o modo guardado, y no canónicas a las filas `openai` no se les ofrece esa ruta de recuperación. + +La compatibilidad con Luna Reserve es una capacidad de cuenta ChatGPT en la ruta de avance canónica OpenAI, no un derecho de clave OpenAI API. Su selector manual de almacenamiento principal requiere un modo de escritorio local efectivo y un permiso de flujo ascendente actual vinculado a credenciales; una entrada de catálogo por sí sola no autoriza una solicitud. Consulte [Luna Reserve junto a modelos enrutados](/es/reference/cli/providers-accounts/#luna-reserve-alongside-routed-models) para ver la configuración, el orden de reinicio, los requisitos de autorización y los ayudantes no compatibles. + +Para añadir una cuenta con cuota agotada y finalizar su validación diferida, véase [Codex calentamiento de la cuenta](/es/guides/codex-integration/#codex-account-warmup). + + + +### Capacidad del grupo + +Para el inicio de sesión Codex en el modo Pool, la descripción general de proveedores muestra una estimación del peso configurado de la capacidad utilizada del grupo en lugar de presentar una cuenta arbitraria como el total del proveedor. La misma fila también muestra el porcentaje de cuota en bruto de la cuenta efectiva actual, para que pueda distinguir la estimación del grupo de la cuenta que usaría una nueva solicitud. + +Cuando la información de restablecimiento está disponible, la visión general muestra el siguiente tiempo de restablecimiento y la capacidad que se espera que se recupere como `+N% pool capacity`. **Cobertura incompleta** significa que una o más cuentas del grupo no podrían contribuir de manera segura a la estimación, por ejemplo, porque su plan o cuota es desconocido, su lectura es obsoleta o la cuenta está pausada o necesita reautenticación. + +Una advertencia de **Cobertura de ventana parcial** significa que algunas cuentas incluidas informaron una ventana de cuota pero no otra. La descripción general mantiene esas ventanas separadas y marca cada ventana afectada incompleta en lugar de tratar la lectura faltante como uso para esa ventana. + +Esta estimación es solo de visualización. No cambia la selección de cuenta, afinidad de sesión, conmutación automática, tiempos de reutilización o cualquier otra decisión de enrutamiento. Utilice el [Codex Fondo de cuenta de Auth](/es/guides/web-dashboard/#codex-auth-and-account-pools) para los controles de estado y enrutamiento de la cuenta individual. + +Las configuraciones v1 enviadas migran automáticamente al marcador 2 y a una fila consciente de las opciones. La configuración original se conserva una vez en `~/.opencodex/config.json.pre-openai-tiers-v2.bak`; restaurarlo con `cp ~/.opencodex/config.json.pre-openai-tiers-v2.bak ~/.opencodex/config.json`. + + + +## Claude Opus 5.5 actualizaciones de progreso + +Cuando el adaptador `anthropic` envía Claude Opus 5.5 a `api.anthropic.com` (clave OAuth o API), OpenCodex solicita Anthropic s [Modo de visualización de actualización de progreso](https://platform.claude.com/docs/en/build-with-claude/thinking#progress-updates). Las actualizaciones de progreso y los reconocimientos a mitad de giro aparecen como comentarios asistentes visibles en Codex, incluso cuando los resúmenes de pensamiento están ocultos. Los resúmenes de razonamiento se omiten en este modo porque Anthropic no puede distinguir las actualizaciones de progreso del razonamiento bajo `display: "summarized"`. Los bloques de pensamiento firmados originales se conservan para la continuación de la herramienta; ninguna firma se decodifica o se reescribe. Las actualizaciones aparecen una vez que se completa su bloque firmado. Otros modelos y puntos finales de terceros compatibles conservan su comportamiento de visualización de pensamiento existente. + + + +## Entrada de imagen Anthropic + +Las semillas modelo Claude incorporadas anuncian la entrada de texto e imagen para `anthropic` (OAuth) y `anthropic-apikey`, consistente con [Anthropic 's visión general del modelo](https://platform.claude.com/docs/en/models/overview). Las anulaciones explícitas de la modalidad de entrada por modelo siguen siendo autorizadas; los modelos desconocidos no se asumen con capacidad de imagen. Esto se aplica a todas las integraciones donde la configuración del cliente admite metadatos de capacidad de imagen: OpenClaw exporta una matriz `input` declarada, y Kimi Code exporta `capabilities: ["image_in"]` solo para modelos con capacidad de imagen. OpenClaw omite `input` cuando no se declaran modalidades compatibles; Kimi omite `capabilities` para modelos desconocidos o de solo texto. Los clientes sin un campo de capacidad compatible mantienen su forma de configuración existente. Después de actualizar opencodex, regenerar o actualizar la configuración del cliente gestionada por opencodex para recibir los metadatos actualizados. + + + +## Firmas de pensamiento Anthropic reproducidas + +En el punto final Responses, un flujo ascendente compatible con Anthropic puede rechazar una firma de pensamiento reproducida porque pertenece a un prefijo de conversación diferente. Cuando el error identifica explícitamente este problema de firma vinculante, opencodex puede eliminar el pensamiento firmado/redactado reproducido y volver a intentarlo una vez dentro del presupuesto de envío de la solicitud. Esto cubre HTTP 400 rechazos y errores de flujo iniciales antes de la salida o la actividad de la herramienta. La búsqueda web alojada y los puentes de imagen/vídeo comparten un límite de recuperación a través de sus iteraciones de modelo: solo se reenvía la inferencia rechazada, mientras que se conservan las llamadas de sidecar completadas y los resultados de la herramienta. Un reintento de finalización vacía comparte la asignación de su solicitud; las continuaciones ordinarias después de la salida no pueden usarla. Un reemplazo fallido se devuelve sin otro reintento de firma. Otros errores mantienen su manejo existente. + +La recuperación de Sidecar se desactiva cuando la contabilidad de gastos forzada no puede establecer recibos para envíos anteriores de sidecar ordinarios. Nunca aumenta la asignación de envío de llamadas o combo. + +Solo una finalización exitosa y no vacía recuerda el rechazo de esa conversación y la identidad de servicio durante cinco minutos. Solo las cargas útiles opacas rechazadas se suprimen cuando pueden ser identificadas; el pensamiento recién emitido sigue siendo reproducible. El historial de texto sin formato permanece disponible; un reintento fallido o cancelado no inhabilita la repetición de pensamiento en solicitudes posteriores. + + + +## Modos de autenticación + +Las configuraciones de proveedor aceptan tres valores `authMode` (`key` es el valor predeterminado). El registro incorporado también etiqueta los preajustes locales por separado; los que normalmente omiten tanto `authMode` como `apiKey`. + +| `authMode` | Cómo se autentica | Utilizado por | +| --- | --- | --- | +| `key` | Envía su llave API (`Authorization: Bearer …`, o `x-api-key` / `api-key` por adaptador). La clave puede ser una referencia literal o una referencia `${ENV_VAR}`. | La mayoría de los proveedores. | +| `forward` | Relés **tus encabezados de autenticación entrantes Codex** verbatim al proveedor - sin clave almacenada. Este es el passthrough de inicio de sesión ChatGPT. | OpenAI (adaptador `openai-responses`). | +| `oauth` | Resuelve un token de acceso OAuth almacenado (actualizado automáticamente antes de la expiración) y lo usa como la clave portadora. | xAI, Anthropic, Kimi, Kiro, Google Antigravity, Cursor, Zed Hosted AI, Command Code, GitHub Copilot, Nous Portal. | + +La repetición de un error 429 con la misma clave mediante [`retryOn429`](/es/reference/configuration/) solo se aplica a proveedores con clave API (`authMode: "key"`). OAuth, el reenvío de credenciales y los preajustes locales quedan excluidos: sus credenciales no deben repetirse en el mismo token y los entornos locales no tienen una clave remota que conservar. La opción debe habilitarse expresamente, salvo los valores predeterminados documentados para destinos concretos. Mistral Chat oficial usa una política de espera con seis repeticiones e intervalo alternativo de diez segundos, dentro del límite de envíos de la solicitud. Las opciones explícitas de `retryOn429`, incluido `enabled: false`, tienen prioridad. El preajuste de Mistral también reenvía por defecto las claves de caché de instrucciones que recibe; `promptCacheKey: false` lo desactiva. La afinidad de caché mejora la posibilidad de reutilizarla, pero no garantiza un acierto ni elimina los límites de tokens por unidad de tiempo. + +Mistral usa un único proveedor con clave API tanto para las claves de Studio como para las de Vibe. Su [documentación de claves API](https://docs.mistral.ai/admin/identity-access/api-keys) describe los tipos de claves y los límites de los planes; el proxy no deduce el nivel de suscripción a partir de la clave. Para cada modelo, los plazos explícitos de `Retry-After` se comparten entre llamadas que usan la misma credencial y el mismo modelo. Un 429 sin plazo puede activar una espera conservadora de recuperación de 60 segundos si los contadores válidos por minuto indican capacidad agotada o si el costo medido de la consulta rechazada supera los tokens restantes, pero cabe en el límite total anunciado. Es una política local de recuperación, no una predicción exacta del restablecimiento del servidor. El tráfico correcto nunca predice el costo ni la caché de la siguiente consulta. Tras la espera se envía una sola consulta de prueba; si funciona, se restablece el tráfico normal. La evidencia ausente, malformada, sin derechos de uso, con cuota mensual agotada o por encima del límite total no inventa un restablecimiento ni compacta el historial. `requestPacing: { "enabled": false }` o `retryOn429: { "respectRetryAfter": false }` desactivan la espera compartida. Si el plazo de Mistral supera `retryOn429.maxIntervalMs`, el proxy devuelve el 429 y su indicación de espera en lugar de reintentar antes de tiempo. Las ventanas de contexto y las preferencias de compactación por modelo siguen siendo independientes. + +Cuando se habilita la selección de clave de round-robin, las solicitudes en cola vuelven a verificar los tiempos de reutilización de la clave antes de enviar y adquieren capacidad de estimulación para cualquier clave de reemplazo. Esto se aplica a Chat nativo, Messages, Responses y compacto. Esperar la capacidad de la clave de reemplazo no consume el tiempo de espera del encabezado de respuesta ascendente. El ritmo por tecla y el uso de round-robin están protegidos HTTP / SSE incluso cuando se habilitan WebSockets aguas arriba; WebSocket -sólo la dirección y la inyección requieren una ruta sin esas políticas clave. Esto no cambia la clave activa guardada. Un giro ascendente establecido mantiene su credencial; los envíos posteriores se rechazan si esa clave se enfría. El rechazo de clave de pre-salida puede recuperar una clave sana dentro del límite de solicitud existente. Direct Las imágenes y las solicitudes compactas registran los tiempos de reutilización genuinos 401/429 sin reproducir ese POST pagado. + + + +### Anthropic API-agotamiento de crédito clave + +Anthropic API -grupos de claves con al menos dos claves intentan automáticamente una clave hermana cuando un error completo HTTP `400` o `402` indica que el saldo de crédito es demasiado bajo para acceder al Anthropic API. Esto se aplica a `invalid_request_error`, `billing_error` y `permission_error` antes de cualquier salida de texto o herramienta. Las estrategias de rotación y agrupación de claves omiten la clave fallida durante una hora, porque un saldo vacío solo se borra cuando se agregan créditos; cuando cada clave está fuera de crédito, las solicitudes aún usan la clave activa y devuelven el error original de Anthropic; elegir la clave como activa en el panel de control o reiniciar el proxy borra esa retención después de una recarga. El reemplazo envía compartir el límite de envío de la solicitud. Los errores ordinarios `400` permanecen en el terminal, y esto no permite reintentos de la misma clave ni cambiar el enrutamiento de la cuenta OAuth. Una anulación de encabezado que envía una credencial diferente no puede enfriar o rotar la clave de grupo seleccionada. + + + +### Que cuenta gasta una solicitud + +La pregunta que la gente hace antes de conectar una cuenta es si opencodex se basará en la suscripción que el inicio de sesión ya paga, o facturará una cuenta separada API. La respuesta sigue el nivel de marketing anterior `authMode` en lugar del nivel de marketing del proveedor. + +- `forward` - el inicio de sesión ChatGPT. La solicitud lleva su credencial Codex, por lo que gasta el plan ChatGPT detrás de ese inicio de sesión e informa las ventanas de cuota Codex de ese plan. Qué ventanas existen depende del plan: no todos los planes tienen una ventana de cinco horas. Nunca se lee una clave API. +- `oauth` - un inicio de sesión de suscripción. La solicitud lleva un token de acceso almacenado, por lo que gasta cualquier cuenta que haya iniciado sesión como, y opencodex informa cualquier ventana de uso que el proveedor expone. +- `key` - la solicitud lleva la clave que usted proporcionó, por lo que el uso aterriza en la cuenta que posee esa clave, en los propios términos de esa clave. Eso es uso medido para una cuenta de pago por uso API, pero una asignación de plan cuando la clave *es* una suscripción: Z.AI GLM Coding Plan, Kimi Code, el plan de codificación BigModel, Command Code y CodeBuddy todos venden uno de esa manera. + +Una solicitud utiliza exactamente uno de estos, y el opencodex no se devuelve de uno a otro. Cuando no se puede resolver una credencial OAuth, la solicitud falla con un error de autenticación en lugar de alcanzar una clave almacenada, y la conmutación por error de grupo de claves que responde a un 429 o un 401 se rechaza completamente para OAuth y los proveedores de reenvío. + +Dos excepciones vale la pena conocerlas porque puedes golpearlas: + +- `xai` y `github-copilot` aceptan `authMode: "key"` en el mismo ID de proveedor, y si ese proveedor ya tenía una clave almacenada, ejecutar `ocx login` puede dejarlo en modo clave en lugar de cambiarlo a la suscripción. Lo que eso cambia es: una clave `xai` reorienta al proveedor a `https://api.x.ai/v1`, por lo que una cuenta diferente paga, mientras que una clave `github-copilot` sigue siendo una credencial de Copiloto contra `api.githubcopilot.com`, por lo que la suscripción de Copiloto paga de cualquier manera. +- `orcarouter-oauth` es un flujo de consentimiento que acuña una clave de usuario `sk-orca-…` API. Una vez que lo ha hecho, la solicitud lleva una clave, por lo que sigue la regla `key` anterior. + + + +#### Proveedores que aceptan tanto un inicio de sesión como una clave + +| Proveedor | Inicio de sesión de suscripción | API clave | +| --- | --- | --- | +| OpenAI / ChatGPT | `openai` - Codex inicio de sesión; gasta el plan ChatGPT detrás de él | `openai-apikey` - un proveedor separado; el uso aterriza en la cuenta de la plataforma OpenAI que posee la clave | +| Anthropic | `ocx login anthropic` - inicia sesión como su cuenta Claude. opencodex lee sus ventanas de uso de cinco horas y siete días; ese punto final no informa ningún nivel de suscripción | `anthropic-apikey` - facturación directa Anthropic API, no Claude suscripción | +| xAI | `ocx login xai` - la pasarela de suscripción Grok CLI. opencodex lee los créditos semanales de SuperGrok, o el grupo mensual | el mismo proveedor `xai` con `authMode: "key"`, que apunta `https://api.x.ai/v1`, por lo que el uso aterriza en esa cuenta API | +| Kimi | `ocx login kimi` - inicie sesión con su cuenta Kimi. `kimi-responses` es el mismo inicio de sesión de la cuenta Kimi enrutado a través del cable OpenAI Responses (creyendo que el contenido permanece cifrado en el lado del servidor, las llamadas a herramientas permanecen visibles; el ajuste preestablecido predeterminado de Chat mantiene el razonamiento de texto plano) | `kimi-code` - la forma de la llave API del mismo plan de código Kimi transporte | +| Command Code | `ocx login command-code` - opencodex lee ventanas de cinco horas y semanales más un saldo de crédito | `commandcode` - el mismo servicio en `/provider/v1` con una llave | +| GitHub Copilot | `ocx login github-copilot` - requiere una suscripción activa a Copilot | el mismo proveedor `github-copilot` con `authMode: "key"`. El flujo de dispositivos anterior es la ruta de acceso admitida, y cualquiera de las credenciales es una Copilot, por lo que la suscripción aún paga | +| OrcaRouter | `ocx login orcarouter-oauth` - consentimiento acuña una clave de `sk-orca-…` de larga duración, propiedad del usuario, y la solicitud lleva una clave | `orcarouter` - la misma llave pegada a mano | +| Meta Muse | `ocx login meta-muse` puede importar una clave local de código Muse CLI o iniciar el inicio de sesión del dispositivo. Meta alcances de esa credencial a su propio CLI, por lo que este es un uso no compatible: cómo se liquidan las llamadas no es observable desde el API, y debe tratar cada llamada como facturable en su cuenta | `meta-model` es la ruta admitida: cada llamada se mide por token, y una suscripción Muse Code no funciona allí. | + +Cursor, Kiro, Zed Hosted AI y Nous Portal son solo de inicio de sesión y no tienen el equivalente de clave API. Google Antigravity también es solo para iniciar sesión: `ocx login google-antigravity` inicia sesión con su cuenta Google a través del cable de Cloud Code Assist, y el ajuste preestablecido `google` al lado es el AI Studio Gemini API, un producto diferente al que se llega con su propia clave, no un modo de clave para el mismo inicio de sesión. La pestaña Cuentas Antigravity muestra un nivel de membresía observado como una insignia junto a la etiqueta de la cuenta, utilizando el ID de nivel ascendente (por ejemplo, `free-tier` o `gemini-pro`). No aparece ninguna insignia cuando el plan es desconocido; no afecta el enrutamiento ni la cuota. + +Gemini 4 Argon (`gemini-4-argon`) aparece en el preajuste `google` con niveles de pensamiento bajos, medios (el predeterminado) y altos. Google lo ofrece solo en el nivel pagado Gemini API, no en el nivel gratuito. El `google-antigravity`, Argon aparece con los mismos tres niveles, que se asignan a los modelos de alambre `gemini-4-argon-low`, `-medium` y `-high`. Google lo limita a las cuentas AI Ultra y Enterprise elegibles. Cloud Code Assist sirve Argon solo al cliente Antigravity CLI, por lo que OpenCodex envía solicitudes de Argon y descubrimiento de modelo con el CLI User-Agent (`antigravity/cli/1.3.4` ) y mantiene el IDE User-Agent para cualquier otro modelo. + +En Vertex AI, `gemini-4-argon` recibe imágenes devueltas por herramientas, como capturas de pantalla, dentro de la respuesta de función coincidente. Esto evita el error 400 aguas arriba "Las solicitudes que terminan con un giro de modelo no son compatibles" después de una llamada de herramienta de producción de imágenes mientras se conservan las imágenes. Las imágenes de resultados duplicados o resultados sin una llamada coincidente se conservan en un mensaje separado después de las respuestas de la herramienta, con un marcador que explica que no se pudieron emparejar. No se necesita ningún cambio de configuración; este manejo es específico para Vertex Argon. + +Para Gemini en Antigravity, incluyendo Argon, los resúmenes de pensamiento marcados por el proveedor se mantienen separados de la respuesta: Responses usa elementos de resumen de razonamiento, Chat Completions usa `reasoning_content` y Messages usa `thinking` bloques. Los clientes deciden cómo mostrar esos campos. Un cliente Responses puede solicitar `reasoning.summary: "none"` para suprimir resúmenes; esto no desactiva el razonamiento interno del modelo. Una firma de pensamiento es metadatos de continuación y puede acompañar al texto ordinario, por lo que su presencia por sí sola no oculta ese texto. OpenCodex conserva texto de respuesta sin marcar incluso cuando su redacción suena como planificación o análisis. + +Los modelos Gemini, Argon en particular, a veces se saltan el pensar en un turno de llamada de herramientas y escriben su planificación en el texto de progreso visible, por ejemplo, una línea de progreso seguida de "Leamos google.ts a continuación". Una vez que el texto se envía de vuelta como historia, el modelo tiende a repetir el patrón en cada turno posterior. Para evitar que se extienda, OpenCodex envía Gemini solo la primera oración del texto que llegó antes de una llamada de herramienta en giros anteriores. Las respuestas finales se devuelven por completo y lo que muestra su cliente no se cambia. + +La lista integrada de `google-antigravity` incluye Gemini 3.8 Flash (`gemini-3.8-flash`), Gemini 4 Argon (`gemini-4-argon`), Claude Opus 5.5 (`claude-opus-5-5`) y Claude Sonnet 5.5 (`claude-sonnet-5-5`), con esfuerzo bajo, medio y alto. La lista que ves procede del descubrimiento de tu cuenta: Google habilita modelos por cuenta. Algunas ofrecen Claude Sonnet 4.6 y Claude Opus 4.6 (Thinking); otras, solo Claude Opus y Sonnet 5.5 en planes Pro o Ultra de facturación directa y sin prueba; Gemini 4 Argon requiere Ultra o Enterprise. Ambas generaciones de Claude se pueden mapear: 4.6 recibe un nivel de pensamiento; 5.5, una variante de modelo `-low`, `-medium` o `-high`. + +Las solicitudes de Antigravity solo se envían a cuentas que puedan atender el modelo solicitado. OpenCodex conserva en memoria durante seis horas la lista obtenida del descubrimiento de cada cuenta. Prefiere una cuenta que incluya el modelo. Si una cuenta no tiene una lista vigente —porque aún no se consultó, caducó o se perdió al reiniciar— todavía puede usarse, ya que no hay evidencia de que carezca del modelo. Una cuenta cuya lista vigente lo omita nunca recibe la solicitud, tampoco durante la recuperación ante errores 429 o de autenticación. Si la cuenta seleccionada lo omite y `oauthAccountFailover.enabled` está activado, se intenta otra cuenta que no esté en pausa ni requiera reautenticación. En caso contrario, OpenCodex rechaza localmente la solicitud con HTTP 403 `permission_denied` sin enviar nada al proveedor: + +- `The selected Google Antigravity account does not list the model "" in its model discovery. Select an account that lists it, or enable oauthAccountFailover so OpenCodex can choose one.` Otra cuenta utilizable podría atender el modelo, pero la conmutación está desactivada. +- `The selected Google Antigravity account does not list the model "" in its model discovery, and no account that may serve it could be used for this request. Retry the request.` La conmutación eligió otra cuenta, pero no se pudo usar para esta solicitud. +- `No usable Google Antigravity account lists the model "" in its model discovery. Choose a model your accounts list, or add an account that has access to it.` Todas las cuentas utilizables omiten el modelo en sus listas vigentes. + +Una selección guardada de un modelo que ya no aparezca en la lista sigue las mismas reglas. + +Para comprobar qué modo está utilizando realmente un proveedor, ábralo en la página Proveedores: la fila **Autenticación** del bloque **Conexión** lee `OAuth`, `API key`, `ChatGPT passthrough`, `Local` o `No key needed`. Es una configuración a nivel de proveedor, por lo que las filas de la cuenta debajo de ella no la repiten. + + + +## 1. Inicio de sesión ChatGPT (adelante / paso) + +El proveedor de `openai` necesita **no API clave**. Direct reenvía las credenciales de su `codex login` existente; Pool resuelve una cuenta principal o agregada Codex antes de usar el mismo backend: + +```json +{ + "openai": { + "adapter": "openai-responses", + "baseUrl": "https://chatgpt.com/backend-api/codex", + "authMode": "forward" + } +} +``` + +Solo se reenvía un conjunto curado de encabezados (`FORWARD_HEADERS`: autorización, ChatGPT cuenta id, OpenAI beta/originador/sesión - ver [Adaptadores](/es/reference/adapters/)). Este camino es también el que alimenta el [web-search y sidecars de visión](/es/guides/sidecars/). + +El catálogo ChatGPT passthrough también se superpone en las identificadores GPT-5.6 Sol / Terra / Luna (`gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-5.6-luna` ) para las cuentas que pueden usarlas. + + + +## 2. Inicio de sesión de la cuenta (OAuth) + +Los ajustes preestablecidos del proveedor pueden usar el inicio de sesión de la cuenta, incluido el GitHub Copilot, a través de un puente experimental no oficial de flujo de dispositivos. opencodex almacena sus credenciales en `~/.opencodex/auth.json`; los tokens actualizables se actualizan automáticamente, mientras que las claves duraderas se reutilizan hasta que el proveedor las revoca. `ocx login codex` también es aceptado, pero no es uno de estos proveedores: se dirige al grupo de cuentas Codex, el mismo flujo que `ocx account login codex`, que mantiene su propio libro de cuentas y necesita un proxy en ejecución. `chatgpt` y `openai` son alias de esa ruta. + +```bash +ocx login xai # xAI Grok +ocx login anthropic # Anthropic Claude (Pro/Max) +ocx login kimi # Moonshot Kimi +ocx login nous # Nous Portal (device grant; free + paid models) +ocx login kiro # import kiro-cli credentials (or token fallback) +ocx login google-antigravity +ocx login cursor # standalone Cursor PKCE login +ocx login zed # Zed native-app callback login (experimental) +ocx login command-code # Command Code browser OAuth (or import ~/.commandcode/auth.json) +ocx login orcarouter-oauth # OrcaRouter browser consent + PKCE +ocx login devin # Cognition/Devin: import Devin CLI credential, else Auth0 browser sign-in +ocx login dsh-account # DeepSeek Harness Desktop (import ~/.dsh/.credentials.yaml grant) +ocx login github-copilot # GitHub device flow → Copilot token (Copilot account) +ocx login codex # Codex account pool (aliases: chatgpt, openai; needs a running proxy) +ocx logout +``` + +| Proveedor | Adaptador | URL base | Notas | +| --- | --- | --- | --- | +| `xai` | `openai-chat` | `https://cli-chat-proxy.grok.com/v1` | OAuth utiliza la pasarela de suscripción separada Grok CLI. La anulación de la clave API utiliza `https://api.x.ai/v1` y puede inyectar Procesamiento Prioritario. En vivo primero Grok catálogo; `grok-4.5` es el valor predeterminado. | +| `anthropic` | `anthropic` | `https://api.anthropic.com` | Claude modelos; lista de modelos en vivo desde `/v1/models`. | +| `kimi` | `openai-chat` | `https://api.kimi.com/coding/v1` | Kimi Modelos de codificación de Plan de Código. Predeterminado para el alias estable `kimi-for-coding` (actualmente K2.8 Preview): ventana de contexto de token 1M, pensamiento ajustable `low` / `high` / `max` (predeterminado `max`), texto + entrada de imagen. Las selecciones `kimi-k2.x` retiradas se migran al alias en la actualización. | +| `kimi-responses` | `openai-responses` | `https://api.kimi.com/coding/v1` | El mismo inicio de sesión de la cuenta Kimi (reutiliza la credencial `kimi` OAuth) sobre el cable OpenAI Responses. Misma lista de modelos y capacidades que `kimi`; pensando que el contenido permanece encriptado en el lado del servidor, las llamadas a herramientas y los resultados permanecen visibles. | +| `nous` | `openai-chat` | `https://inference-api.nousresearch.com/v1` | Nous Research pasarela de suscripción (el mismo backend que usa Hermes Agent). El inicio de sesión de concesión de dispositivo contra `portal.nousresearch.com`; el token de acceso es la inferencia por solicitud JWT. Pago mixto + catálogo de modelos `:free` (`tencent/hy3:free`, `stepfun/step-3.7-flash:free`,...) descubierto en vivo desde la cuenta iniciada. Los tokens de actualización son de un solo uso y se rotan en cada actualización. | +| `kiro` | `kiro` | `https://runtime.us-east-1.kiro.dev` | Los botones de inicio de sesión y agregar cuenta del panel de control ofrecen Builder ID, Google, GitHub inicio de sesión del dispositivo o Kiro CLI. El inicio de sesión nativo del dispositivo agrega una cuenta sin cerrar sesión `kiro-cli`. La opción Kiro CLI importa o inicia una sesión CLI; su flujo de trabajo Agregar cuenta cambia temporalmente la cuenta CLI y la restaura en caso de cancelación o falla. | +| `google-antigravity` | `google` | `https://daily-cloudcode-pa.googleapis.com` | Google OAuth sobre el cable de Cloud Code Assist. Live discovery utiliza el punto final autenticado `v1internal:fetchAvailableModels` de CCA y publica los modelos de agente disponibles para la cuenta iniciada; el catálogo mantenido sigue siendo la reserva. | +| `cursor` | `cursor` | `https://api2.cursor.sh` | Inicio de sesión PKCE experimental, transporte HTTP/2 en vivo con una ruta de compatibilidad opt-in HTTP/1.1 y descubrimiento de modelo filtrado por cuenta. | +| `zed` | `zed` | `https://cloud.zed.dev` | Experimental puente Zed AI alojado. Utiliza la devolución de llamada RSA de Zed, intercambia el token de cuenta por un token de inferencia alojada de corta duración y descubre la lista en vivo de la cuenta. | +| `orcarouter-oauth` | `openai-chat` | `https://api.orcarouter.ai/v1` | El consentimiento del navegador y el intercambio de claves usan `https://www.orcarouter.ai` con S256 PKCE. La clave `sk-orca-…` API de propiedad del usuario devuelta se almacena en el almacén de credenciales existente y se reutiliza hasta que se revoca. | +| `devin` | `devin` | `https://server.codeium.com` | Experimental no oficial Cognición/Puente Devin. Login primero importa la credencial que ya tiene el Devin CLI instalado (`devin auth login` escribe un `devin-session-token` a su propio `credentials.toml`); cuando no está presente, abre el inicio de sesión del navegador Auth0 e intercambia el token pegado a través del `RegisterUser` de Cognition por una clave API de larga duración. `ocx login devin-cli` sigue siendo un alias obsoleto. Los modelos se descubren por cuenta con `GetCascadeModelConfigs`. La cuota de la cuenta viene de `GetUserStatus` bajo una solicitud de ocho segundos y la fecha límite del cuerpo: ventanas con fecha diaria y semanal, más el fondo de crédito rápido y flexible mensual para un plan de crédito facturado o una estrategia desconocida con ambas fechas de reinicio ausentes cuando un campo de saldo está presente. Los créditos usados negativos omiten la ventana mensual; los créditos válidos disponibles cero la marcan agotada. Una sonda de tiempo de espera mantiene la última cuota buena. No se muestra en el panel de control predeterminado. Los informes de chat y uso se verifican con una cuenta real en tres modelos. | +| `dsh-account` | `dsh-account` | `https://api.deepseek.com/anthropic` | Proveedor experimental de cuentas de importación primero que reutiliza una cuenta de escritorio DeepSeek Harness (DSH) instalada y registrada. Lee las credenciales estrictamente de solo lectura desde `~/.dsh/.credentials.yaml` después de la importación explícita. Independiente de la facturación de claves DeepSeek API. | +| `github-copilot` | `openai-chat` | `https://api.githubcopilot.com` | Experimental. GitHub flujo de dispositivos + intercambio `copilot_internal` (cliente VS Code OAuth). Requiere una suscripción activa de Copiloto; no un tercero oficial API. | + +Google Antigravity agrupa las variantes completas `low` / `medium` / `high` de un modelo en una entrada con un selector de esfuerzo. Esto incluye Claude Opus y Sonnet 5.5 y futuras versiones descubiertas durante la actualización automática. Los conjuntos parciales permanecen separados. Las opciones existentes activadas/deshabilitadas se incluyen en la entrada agrupada; los modelos genuinamente nuevos aún siguen su política de Nuevo modelo. Los ID de sufijo guardados continúan solicitando su nivel original. El enrutamiento de esfuerzo agrupado sobrevive a un reinicio proxy cuando el descubrimiento del modelo no está disponible temporalmente. Una sesión Codex en ejecución puede necesitar volver a cargar su lista de modelos después de actualizar el catálogo. Grupos de uso conocidos como Claude Sonnet y Opus 5.5 bajo su modelo base, incluyendo registros históricos de nivel. Sus costos mostrados se derivan de Anthropic estimaciones de referencia, no Antigravity cargos de suscripción. + +Google Antigravity Las sondas de cuotas de cuenta y proveedor utilizan Google puntos finales de contabilidad fijos, incluidos los modelos alternativos. Soportan DNS de IP falsa transparente para esos destinos al tiempo que retienen la verificación TLS, el rechazo de redireccionamiento y las verificaciones de direcciones privadas. Un URL base de proveedor personalizado cambia las solicitudes de modelo, no los destinos de cuota; `NO_PROXY` continúa seleccionando la política de ruta directa. + + + +### Google diagnósticos de pérdida de herramientas-esquema + +Las declaraciones de herramientas Google se compilan con la clase de punto final seleccionada. Cuando el debug del proveedor está activado - `ocx debug provider on`, el conmutador Logs del panel de control, o `OCX_DEBUG=1` - pérdida de esquema durante la conversión de compatibilidad en la ruta de directiva omitida o `compatible` emite un registro `[ocx:google:google-tool-schema-loss]` (cola con `ocx debug provider logs -f` ) que lleva solo la versión del informe, clase de punto final, un indicador `lossy`, un recuento de incertidumbre limitado, categorías de pérdida fija con recuentos limitados y un indicador de truncamiento. Los nombres de herramientas y propiedades, rutas, valores y texto de esquema nunca se incluyen. Con una política omitida o `compatible`, este diagnóstico observa la conversión existente sin rechazarla. Bajo `reject-lossy`, una compilación inicialmente con pérdidas o indeterminada por comparación se rechaza antes del envío; no se emite un registro de pérdidas separado para la solicitud rechazada. Bajo `reject-lossy`, una reparación de Vertex o Cloud Code Assist que borraría las restricciones emite un registro `google-tool-schema-repair` sin contenido similar y devuelve el original 400 sin un envío modificado; con una política omitida o `compatible`, la solicitud reparada se reproduce como antes. Direct AI Studio nunca realiza esta reparación. Los esquemas de salida nativos están fuera de ambas rutas de política. Ver el [referencia de comando debug](/es/reference/cli/agents/). + + +Después de un fallo de actualización de terminal Nous, ejecute `ocx login nous` para volver a autenticar. + +### Zed Hosted AI (experimental) + +:::caution[No oficial: úsalo bajo tu responsabilidad] +Zed no proporciona ni respalda este puente. Reutiliza el modelo alojado de tu cuenta de Zed derecho fuera del editor de Zed, que puede estar fuera de los términos de servicio de Zed. Zed puede calificar Limitar, restringir o suspender la cuenta. Revise los términos actuales de Zed antes de iniciar sesión; el proveedor se queda fuera hasta que lo agregues y ejecutes `ocx login zed` y el dashboard pregunta Usted debe reconocer este riesgo antes de que comience el inicio de sesión. +::: + +Ejecute `ocx login zed` y complete el inicio de sesión de la aplicación nativa de Zed en el navegador. OpenCodex inicia una devolución de llamada de bucle, le da a Zed una clave pública RSA y mantiene la clave privada local coincidente mientras la devolución de llamada devuelve la identidad de la cuenta y el token de acceso cifrado. El identificador de cuenta y el token almacenados se emparejan en cada solicitud; OpenCodex intercambia esa credencial por el token LLM de corta duración de Zed antes de llamar al `https://cloud.zed.dev/completions`. + +La lista de modelos en vivo de Zed es de metadatos de visualización con alcance de cuenta. El id del modelo seleccionado se reenvía como se proporciona, y el puente infiere la familia de backend alojado desde la fila en vivo o el nombre del modelo; el descubrimiento del modelo no es una lista de permisos. El token de acceso de Zed no tiene punto final de actualización, por lo que cuando Zed lo revoque, ejecute `ocx login zed` nuevamente. + +Para los modelos OpenAI alojados en Zed, OpenCodex traduce `developer` instrucciones a `system` mensajes y elimina OpenAI campos privados y herramientas integradas no compatibles como `web_search`. La función y las herramientas personalizadas permanecen disponibles a través del delegado; una opción de herramienta sin herramientas compatibles se convierte en `none`. + +Para los preajustes canónicos del Plan de Codificación Kimi (inicio de sesión de cuenta `kimi` y clave `kimi-code` API), opencodex reenvía solo un establo `prompt_cache_key` suministrado por el llamante a la solicitud Chat Completions (el cable Responses acepta el mismo campo, pero opencodex no lo envía allí hoy); nunca genera uno. Kimi documenta una clave de sesión/tarea estable según sea necesario para mejorar las tasas de aciertos de la caché del Plan de código, mientras que las solicitudes sin una clave permanecen sin clave. Si un opt-in aguas arriba rechaza el campo, opencodex no lo elimina y vuelve a intentar o mutar la configuración guardada. Otros proveedores siguen negando por defecto. + +Kimi La ruta nativa Responses de Code omite los mensajes del historial del asistente vacíos de contenido explícito para evitar su rechazo `assistant must not be empty`. Texto no vacío, espacios en blanco, rechazos, razonamiento y llamadas/resultados de herramientas son retenidos; el historial del cliente almacenado no es reescrito. Un mensaje vacío referenciado por un `item_reference` en la misma entrada se retiene en lugar de dejar una referencia colgante. + +Kimi Codificación precios de uso para `k3`, `k3[1m]`, y `k3-256k` son **API-estimaciones de referencia** a través +`kimi`, `kimi-code`, y `kimi-responses`, usando la tasa de escritura en caché de 5 minutos predeterminada publicada. No reproducen la facturación o cuota del Plan de Código: la variante 1M de K3 consume aproximadamente el doble de la cuota de `k3-256k`. `kimi-for-coding` ahora apunta a K2.8 Preview, por lo que su antiguo precio K2.7 ya no es utilizado; su estimación permanece indisponible a menos que el operador suministre `modelCosts`. Precio desconocido Por lo tanto, las políticas de enrutamiento y los límites de costos que excluyen estimaciones desconocidas pueden excluir este alias. Véase [Configuración del modelo de Kimi](https://www.kimi.com/code/docs/en/kimi-code/models.html) y +[Precios de API](https://platform.kimi.ai/docs/pricing/chat). + +Un proveedor personalizado de `openai-chat` puede optar por cuando sus documentos ascendentes sean compatibles con `prompt_cache_key`: + +```json +{ + "providers": { + "example-compatible-provider": { + "adapter": "openai-chat", + "baseUrl": "https://api.example.com/v1", + "apiKey": "${EXAMPLE_API_KEY}", + "promptCacheKey": true + } + } +} +``` + +El adaptador reenvía la llave que se le da y nunca inventa una. Todavía puede recibir una clave que la persona que llama no envió: Claude Messages traducción deriva uno de `metadata.user_id`, o de un modelo / sistema / herramientas cohorte cuando el cliente no envía metadatos, porque el OpenAI backends informe `cached_tokens: 0` para cada vuelta sin clave. Por lo tanto, "reenviado, no fabricado" describe este adaptador, no toda la ruta de solicitud. + +Preservar el resto de la configuración del proveedor al agregar la opción, a continuación, volver a cargar o reiniciar opencodex. Para validar el almacenamiento en caché, compare la solicitud inicial en frío con solicitudes posteriores que lleven la misma clave estable. Deje la opción omitida o configúrela a `false` para secuencias ascendentes incompatibles, y deshabilite o elimine si una puerta de enlace estricta devuelve un error de campo desconocido de HTTP 400. + +También puede comenzar OAuth desde el [panel web](/es/guides/web-dashboard/). + + + +### Iniciar sesión desde otro perfil de navegador u otra máquina + +Cuando se inicia un inicio de sesión, el proxy abre la URL de autorización en la máquina **Su propio**, utilizando el navegador predeterminado del sistema operativo y, por lo tanto, el perfil predeterminado. Ese es el comportamiento correcto para un escritorio local y el incorrecto en dos casos comunes: necesita un perfil de navegador diferente (una identidad de trabajo, una segunda cuenta) o el panel de control está abierto contra un proxy que se ejecuta en otro lugar. + +Cada superficie de inicio de sesión muestra la URL de autorización con un botón de copia, el código del dispositivo cuando el proveedor emite uno y las instrucciones actuales. Los flujos de devolución de llamada del navegador también muestran un campo para pegar la URL de redirección o el código de autorización. Durante la aprobación del dispositivo, ese campo está oculto: introduzca el código mostrado en la página de verificación del proveedor. Si el proveedor cambia a la entrada manual, el panel de control reemplaza el código antiguo y las instrucciones en su próxima encuesta de estado. + +Si el proxy intenta abrir un navegador y no puede, el inicio de sesión lo dice por encima de la URL y continúa: abra la página de inicio de sesión desde el enlace o cópiela. Un inicio de sesión del dispositivo nunca abre un navegador por sí mismo; **Copiar código & abrir** copia el código y abre la página de verificación con un solo clic, y el panel de control sigue esperando mientras el código del proveedor siga siendo válido. En la aplicación de escritorio, estos enlaces se abren en su navegador predeterminado. + +Para evitar que el proxy abra un navegador, marque **No abra un navegador en la máquina proxy** junto al botón de inicio de sesión o configúrelo permanentemente: + +```json +{ "oauthOpenBrowser": false } +``` + +Ausente y `true` abiertos, por lo que nada cambia para una instalación existente; solo una disminución explícita de `false`. `POST /api/oauth/login` y `POST /api/codex-auth/login` también aceptan un booleano por solicitud `openBrowser` que anula la configuración almacenada para ese inicio de sesión. + +Dos casos se comportan de manera diferente, y vale la pena saber en cuál se encuentra: + +- **Un perfil de navegador diferente en la misma máquina** funciona solo con el enlace copiado. El bucle de retorno de llamada en `127.0.0.1` todavía completa el flujo. +- **Un flujo de devolución de llamada del navegador en una máquina diferente** también necesita el retroceso de pegado, porque el URI de redirección sigue siendo `http://127.0.0.1:/callback` en el host del proxy. Termina el inicio de sesión allí, luego pega la URL de redirección (o solo el código) nuevamente en el tablero o `ocx account code`. + +Los proveedores de código de dispositivo nunca abren un navegador desde el proxy en ningún caso: muestran un código y una URL de verificación para abrir donde sea que haya iniciado sesión. + + + +### Inicio de sesión Claude sin cabeza (modo de visualización de código) + +Para Anthropic hay un camino más limpio que pegar una redirección muerta: el inicio de sesión **code-display**. Anthropic redirige a su propia página y muestra una cadena `code#state` en lugar de llamar al proxy, por lo que nada necesita llegar a `127.0.0.1` en el host del proxy. + +```bash +ocx login anthropic --headless +``` + +A lo largo de la gestión API, comience con `POST /api/oauth/login` y `{"provider":"anthropic","mode":"code"}`; la respuesta lleva un `flowId` y un `expiresAt` (10 minutos). Envíe la cadena pegada al `POST /api/oauth/login/code` con ese `flowId`. La respuesta es el resultado del intercambio de tokens, `{"ok":true,"account":…}` o `{"ok":false,"error":…}`, por lo que una persona que llama alojada con un solo cuadro de pegado sabe si el inicio de sesión realmente funcionó. Una pasta con el estado incorrecto, o sin código, se rechaza antes de cualquier solicitud de token y deja el flujo abierto para otro intento; una pasta que llega al intercambio de tokens usa el flujo hacia arriba, así que inicie un nuevo inicio de sesión si ese intercambio falla. + +Solo `anthropic` y `anthropic2` admiten este modo; otros proveedores responden `code_mode_unsupported`. Varios inicios de sesión de código pueden estar en vuelo a la vez, cada uno anclado a su `flowId`, pero todos escriben la misma tienda de cuentas: la más reciente se convierte en la cuenta activa Claude. Esto está destinado a un operador en un host sin cabeza, no para aislar usuarios no relacionados en una instancia compartida. + + + +### Múltiples cuentas OAuth + +OAuth proveedores cuyas credenciales incluyen un ID de cuenta estable o correo electrónico pueden mantener más de un inicio de sesión. La página Proveedores muestra esas cuentas en un menú desplegable, le permite agregar otra y cambia la cuenta activa sin cerrar la sesión de las otras. Un inicio de sesión normal con una credencial sin identidad Kimi reemplaza la ranura activa, mientras que un **Añadir cuenta** explícito conserva esa ranura y activa una nueva y distinta. Kiro cuentas están clavedas por el perfil ARN. `chatgpt` siempre es de una sola ranura porque las cuentas de grupo Codex tienen un libro mayor separado. Los tokens permanecen en `~/.opencodex/auth.json`; `/api/oauth/accounts` devuelve solo metadatos enmascarados. + + + +### Importación de Antigravity desde Cockpit Tools + +En v1, OpenCodex solo importa archivos JSON de **Antigravity exportados desde Cockpit Tools**, para el proveedor `google-antigravity`. En el dashboard, selecciona el archivo local desde la pestaña Cuentas de ese proveedor. El dashboard no muestra el contenido del archivo ni las credenciales; solo informa cuántas cuentas se importaron, se actualizaron, fallaron o no son compatibles. En v1 se rechazan las exportaciones de otros proveedores de Cockpit Tools. + +El CLI solo acepta la exportación desde un archivo o entrada estándar, nunca lo pegue en un argumento de comando: + +```bash +ocx account import google-antigravity --format cockpit-tools --file [--json] +cat accounts.json | ocx account import google-antigravity --format cockpit-tools --stdin [--json] +``` + +En línea JSON y argumentos posicionales adicionales son rechazados. Mantenga los archivos exportados privados y elimínelos o guárdelos de forma segura después de importarlos. + +Cada registro puede incluir `project_id` para una cuenta cuyo proyecto de Cloud Code Assist no se descubra automáticamente. Debe ser un identificador de proyecto de Google Cloud de 6 a 30 letras minúsculas, dígitos o guiones. OpenCodex solo lo usa si el descubrimiento no encuentra un proyecto y una consulta de cuota con el token de esa misma cuenta lo valida; de lo contrario, el registro falla con `missing_project` y no se guarda nada. El proyecto descubierto siempre tiene prioridad. + + + +### OAuth fiabilidad + +opencodex coordina la actualización de tokens y el enrutamiento de grupo Codex para que las solicitudes concurrentes no aceleren el almacén de credenciales. Esto es trabajo de confiabilidad y diagnóstico: **no** garantiza protección contra la aplicación del proveedor, los límites de solicitudes o las acciones de la cuenta. + +**Refrescar la coordinación.** Antes de una llamada enrutada, un token de acceso vencido se actualiza una vez cada `(provider, account)`: + +1. En proceso de un solo vuelo - llamantes concurrentes comparten una promesa de actualización. +2. Bloqueo de archivos por cuenta: los escritores de procesos cruzados se serializan en la misma cuenta. +3. Generación CAS: persiste solo cuando la generación de credenciales almacenada aún coincide; un escritor más nuevo gana y un resultado de actualización más antiguo no puede sobrescribirlo. + +Los fallos de actualización de terminal marcan la cuenta como que necesita una nueva autenticación en lugar de volver a intentarlo para siempre. + +Para la credencial principal nativa Codex en `CODEX_HOME/auth.json`, cancelar una solicitud detiene una actualización en espera antes de que comience el intercambio de tokens. Un intercambio que ya comenzó termina dentro de su propio tiempo de espera de 30 segundos y guarda el acceso exitoso y actualiza los tokens antes de informar la cancelación de la solicitud. Esto conserva el token de actualización rotado para solicitudes posteriores; un reemplazo de credenciales externo concurrente aún tiene prioridad. + +**Enfriamientos (Codex pool).** Upstream `429` / las respuestas de cuota establecen un tiempo de reutilización duro de `Retry-After`, una cuota de `reset` encabezados (cap) o un retroceso predeterminado corto. Las cuentas en un tiempo de reutilización explícito de `Retry-After` no se exploran temprano; los tiempos de reutilización derivados del restablecimiento pueden recibir un arrendamiento de sonda con ritmo para que la recuperación pueda detectarse sin inundar al proveedor. Los tiempos de reutilización de modelos nativos derivados de restablecimiento mantienen la cuota nativa compartida (incluido GPT-5.6 Terra/Luna) separada de `gpt-reserve`. Los modelos en el grupo compartido todavía se protegen unos a otros; un éxito ordinario no puede borrar un tiempo de reutilización de la Reserva. `Retry-After` explícito y los tiempos de reutilización predeterminados siempre permanecen en toda la cuenta. + +**Afinidad de sesión.** Codex hilo → cuenta afinidad es proceso-local (en memoria solamente; no persistió a través de reinicios proxy). En caso de fallos de credenciales (`401` / `403`), la cuenta se pone en cuarentena para determinar la autenticidad y se borran las afinidades de esa cuenta. En `429`, la cuenta entra en tiempo de reutilización, las afinidades se borran y la selección del grupo puede girar: los hilos no se fijan a través de una respuesta de límite de velocidad. + +**Volver a una cuenta recuperada.** Para reanudar el uso de la cuenta de máxima prioridad durante una tarea en curso, active `ocx config set codexAccountPriorityFailback true` y mantenga la estrategia Pool en `quota` con la conmutación automática habilitada. Por ejemplo, una tarea puede pasar de Plus a otra cuenta cuando se llena su ventana de cinco horas y luego volver a Plus después de que la actualización de la cuota confirme la recuperación. Mientras fluyen las solicitudes, los intentos de actualización en segundo plano se ejecutan como máximo una vez cada cinco minutos. La solicitud que desencadena una actualización puede seguir utilizando la cuenta anterior; la siguiente solicitud después de que se complete la actualización puede retroceder. Las solicitudes que ya se están ejecutando terminan en su cuenta capturada. Los pines de cuenta manuales y las restricciones de acceso al modelo aún se aplican. Esta función está desactivada por defecto; use `ocx config set codexAccountPriorityFailback false` para restaurar enlaces estables. + +El umbral efectivo de la cuenta de origen vinculada controla esta preferencia: la anulación `0` la deshabilita, y una anulación positiva funciona incluso cuando el umbral global es `0`. Un candidato debe tener un uso conocido y no agotado por debajo de su propio umbral efectivo positivo. El candidato `0` elimina solo esa preferencia de umbral; aún se aplican la elegibilidad, el tiempo de reutilización y los bloqueos duros. Cada ventana que contribuye a su puntuación necesita una observación reciente en vivo en este proceso. Las actualizaciones solo de créditos, las ventanas retenidas y las barras de visualización hidratadas no prueban por sí mismas la recuperación. + +**Metadatos del cliente Codex.** La ruta de avance ChatGPT pasa a través de la `FORWARD_HEADERS` +allowlist (autorización, `chatgpt-account-id`, originador, ID de sesión/hilo y Codex relacionados cabeceras — ver [Adaptadores](/es/reference/adapters/)) El modo Pool sobrescribe solo la autenticación y +`chatgpt-account-id` para que coincida con la credencial seleccionada. opencodex hace **no** Fabricar oficial identidad del cliente (por ejemplo, `originator`, encabezados de sesión o hilo) cuando la persona que llama no envió A ellos. + +Para el diagnóstico de compatibilidad de cuenta-interruptor, habilitar la depuración del proveedor (`ocx debug provider on`) agrega una línea `[ocx:codex:affinity]` por respuesta directa canónica ChatGPT. La línea contiene presencia de encabezado, cubos de tamaño aproximado, etiquetas de igualdad HMAC locales de proceso, resúmenes seguros de campos de giro de nivel superior conocidos y un recuento de campos de giro desconocidos. Nunca incluye credenciales sin procesar, identificadores de cuenta, valores de certificación, identificadores de subproceso/sesión, metadatos de turno o cuerpos de solicitud; las etiquetas cambian intencionalmente después de cada reinicio del proxy. Use `ocx debug provider logs -f` mientras reproduce las dos solicitudes, luego ejecute `ocx debug provider off`. Esta captura es solo de observación y no elimina metadatos, reintenta una solicitud, cambia de cuentas, restablece un subproceso o afecta el enrutamiento. + +**Diagnóstico y reauth.** Human `ocx status` imprime un bloque de salud OAuth (identificadores de cuenta redactados, sin tokens). `ocx doctor` agrega una sección de confiabilidad OAuth con comprobaciones de almacenamiento grabable / de un solo vuelo y filas WARN que incluyen una acción de recuperación. Cuando una cuenta de proveedor OAuth necesita reautenticación, ejecute `ocx login ` (o utilice Reautenticar en el panel de control). Codex cuentas de grupo no son uno de esos proveedores, pero `ocx login codex --reauth` rutas a su cuenta de grupo de reautenticación, que el tablero Codex cuenta de grupo también realiza. Véase [`ocx status` / `ocx doctor`](/es/reference/cli/) en la referencia CLI. + + + +### Créditos de solicitud Kiro + +En los giros habilitados para herramientas, opencodex mantiene el texto ordinario de Kiro hasta que se valide la finalización. Si Kiro termina con texto sin formato en lugar de su herramienta privada de respuesta final, todavía se ejecuta un reintento limitado y solo se muestra la respuesta final resultante. El progreso que acompaña a una llamada de herramienta real sigue siendo visible. Una respuesta final privada normal no necesita reintento de finalización. + +Cuando Kiro emite la medición de crédito, los registros de solicitudes conservan el gasto reportado como `usage.providerCredits`, incluso en el libro mayor de uso persistente. Estos son Kiro créditos; los recuentos de tokens aún pueden estimarse y el valor del crédito no reemplaza las estimaciones de costos de USD. Las solicitudes de reserva de finalización agregan sus créditos reportados. Un valor ausente significa que Kiro no reportó el uso del crédito; un cero explícito significa que no reportó ningún gasto. + + + +### Kiro actualizar la atención + +Si una actualización de AWS SSO devuelve `400 invalid_request` y la recuperación Kiro CLI no se realiza correctamente, el panel de control muestra que la cuenta afectada necesita volver a autenticarse una vez que expire su token de acceso. El proveedor activo informa entonces de `loggedIn: false` desde `/api/oauth/status`. Un token de acceso todavía válido permanece conectado. Puede iniciar sesión de nuevo a través del panel de control; una actualización automática exitosa posterior también borra el estado de atención. Este estado no clasifica la concesión de actualización como revocada ni desactiva futuros intentos de actualización. Los errores de red y servidor no activan este estado. + +Para las cuentas de escritorio, un HTTP 401 con exactamente `Bad credentials` requiere un nuevo inicio de sesión e inmediatamente marca la generación de credenciales rechazadas como que necesita una nueva autenticación. Otros mensajes, estados y respuestas de AWS SSO no activan esta regla específica del escritorio. + + + +### Importación de credenciales Kiro + +El panel de control ofrece inicio de sesión nativo del dispositivo Builder ID, Google y GitHub sin Kiro CLI. La opción Kiro CLI y la ruta de importación `ocx login kiro` usan el CLI: en Unix, instálelo con `curl -fsSL https://cli.kiro.dev/install | bash`; en Windows PowerShell, use `irm 'https://cli.kiro.dev/install.ps1' | iex`; luego inicie sesión con `kiro-cli login`. Sin una sesión `kiro-cli`, `ocx login kiro` vuelve a un token de acceso pegado o la variable de entorno `KIRO_ACCESS_TOKEN`. + +La ruta de importación `ocx login kiro` busca en la plataforma Kiro CLI almacena y abre SQLite bases de datos de solo lectura. Dos variables de entorno hacen explícita la selección de la fila de origen y token: + +- `KIROCLI_DB_PATH` selecciona una base de datos no estándar Kiro CLI SQLite. La ruta de acceso ya debe existir; durante esta ruta de acceso de importación, opencodex no crea ni modifica los archivos de base de datos, WAL o SHM. +- `KIROCLI_TOKEN_KEY` selecciona la clave de token exacta `auth_kv` cuando una base de datos contiene múltiples filas de tokens ambiguas. Una selección faltante falla el inicio de sesión en lugar de adivinar. + +En Windows, la importación busca `%LOCALAPPDATA%\Kiro-Cli\data.sqlite3`. El inicio de sesión forzado/agregar cuenta también necesita el binario local CLI: opencodex primero usa `PATH`, luego vuelve a `%LOCALAPPDATA%\Kiro-Cli\kiro-cli.exe` y `C:\Program Files\Kiro-Cli\kiro-cli.exe`. Si ninguna de las carpetas tiene `kiro-cli.exe`, se utiliza un `kiro.exe` dentro de esas mismas dos carpetas `Kiro-Cli`. opencodex nunca ejecuta un `kiro` corto o `kiro.exe` que se encuentra en `PATH` o en directorios compartidos macOS / Linux bin, por lo que instalar o vincular el CLI como `kiro-cli` allí. + +Después de una importación exitosa, opencodex persiste la credencial importada a `~/.opencodex/auth.json`. Mantenga estas variables y la base de datos seleccionada privada. No adjunte archivos de base de datos o diagnósticos de inicio de sesión sin procesar a los informes de errores. + +Para la opción **Kiro CLI**, **Añadir cuenta** es un flujo de trabajo de escritura separado: captura la sesión actual, inicia sesión en `kiro-cli` e importa el inicio de sesión del navegador nuevo. Si el inicio de sesión se cancela o falla, incluso mientras OpenCodex persiste la credencial, el retroceso reemplaza la base de datos Kiro CLI y elimina sus sidecars WAL, SHM y diario actuales antes de publicar la instantánea de sesión anterior. + +Debido a que la reversión solo es posible a partir de una instantánea, la opción Kiro CLI **Añadir cuenta** se niega a firmar `kiro-cli` cuando un almacén de sesión está presente pero no se puede capturar (archivo ilegible, esquema no coincidente o una selección ambigua de token), cuando la importación de redireccionamiento `KIROCLI_DB_PATH` / `KIRO_CLI_DB_FILE` se lee desde el almacén CLI en vivo, o cuando una base de datos CLI primaria existente no tiene una fila de token reconocida. Repare o elimine la base de datos ilegible bajo la ruta de datos normal `kiro-cli`, desactive los selectores de importación y vuelva a intentarlo. No se afecta el inicio de sesión desde una máquina sin sesión `kiro-cli` existente. Las opciones del panel de control nativo son solo para agregar y no cerrar sesión en `kiro-cli`. Un diálogo de dispositivo muestra el código y el destino de la verificación. Solo los hosts Kiro o Builder ID reconocidos se abren como enlaces; un destino inesperado se muestra como texto copiable para su revisión. Cerrar el cuadro de diálogo envía la cancelación y deja una verificación de estado de fondo limitada para conciliar una confirmación que ya está en curso. Se vuelve a intentar una respuesta de estado estancada; agotar la fecha límite de flujo produce el resultado final neutral en lugar de reclamar el éxito. La aprobación Google y GitHub se completa cuando Kiro informa `authorized` (o el estado `approved` heredado) con tokens válidos y un ARN de perfil. La lista de cuentas marca Kiro cuentas excluidas de la selección automática con un motivo, cuando está disponible. + + + +### DeepSeek Cuenta (DSH) + +`dsh-account` es un proveedor experimental de cuentas de importación diseñado para reutilizar las credenciales de cuenta autenticadas de una aplicación de escritorio DeepSeek Harness (DSH) instalada. + +- **Independiente de DeepSeek API Llave:** `dsh-account` se ejecuta en la cuenta DeepSeek iniciada con DeepSeek Harness, mientras que el proveedor `deepseek` factura contra su saldo de claves API de plataforma. Los dos dominios y rutas de credenciales están estrictamente separados y nunca se cruzan. +- **Importación explícita solamente:** opencodex lee `~/.dsh/.credentials.yaml` (o `$DSH_HOME/.credentials.yaml`) solo cuando ejecuta `ocx login dsh-account` o selecciona **Iniciar sesión** en la fila DeepSeek Account (DSH) del selector **Añadir proveedor** del tablero de instrumentos. Nunca copia, importa o usa el token por sí mismo. +- **Tienda de credenciales DSH de solo lectura:** OpenCodeX trata a `~/.dsh/.credentials.yaml` como estrictamente de solo lectura. OpenCodeX nunca escribe, modifica, elimina o altera los permisos de los archivos pertenecientes a DeepSeek Harness. +- **Copia de credenciales aislada & cierre de sesión:** Al importar, OpenCodeX valida el token contra el punto final de identidad autorizado de DeepSeek (`/auth-api/v0/users/current`) y guarda su propia copia en el almacén de autenticación de OpenCodeX. Cerrar la sesión o eliminar la cuenta en OpenCodeX solo elimina la copia local de OpenCodeX; nunca activa el cierre de sesión remota ascendente y no cerrará la sesión en DeepSeek Harness Desktop. +- **Sin rotación de token de fondo y reimportación 401:** Las concesiones de sesión DSH no cuentan con un punto final de actualización de fondo automático. Si el flujo ascendente devuelve HTTP 401 (`ACCOUNT_TOKEN_INVALID`), OpenCodeX marca la cuenta `needsReauth` y detiene el enrutamiento. Para restaurar el acceso, el usuario debe volver a importar explícitamente a través de `ocx login dsh-account`. +- **Descargo de responsabilidad de terceros:** OpenCodeX no hace ninguna reclamación de respaldo oficial o autorización por DeepSeek para clientes de terceros que reutilizan subvenciones de sesión. + + + +## 3. Catálogo de proveedores con clave API + +opencodex incluye 105 preajustes integrados: 84 con clave, 17 OAuth, tres locales y uno predeterminado de reenvío a ChatGPT. El selector **Añadir proveedor** abre el formulario del proveedor con clave, valida la credencial y la guarda; cada proveedor tiene su propia validación. Entre ellos: + +**ClinePass** utiliza una llave Cline API con los [catálogo de suscripción oficial](https://docs.cline.bot/getting-started/clinepass) y [Chat Completions punto final](https://docs.cline.bot/api/chat-completions), operados por Cline Bot Inc. bajo [Los términos de Cline](https://cline.bot/tos). Un id encaminado tal como `cline-pass/cline-pass/kimi-k3` es intencional: el primer segmento selecciona el proveedor opencodex, mientras que `cline-pass/kimi-k3` es la identificador modelo completa enviada aguas arriba. La cuota de ClinePass es compartida por la cuenta a través de límites mensuales, semanales y de 5 horas. Una sonda activa 2026-08-13 verificó que cada modelo estático de ClinePass acepta `low`, `medium`, `high`, `xhigh` y `max` en el límite de entrada de pasarela. opencodex conserva los niveles solicitados; cualquier normalización específica del backend sigue siendo responsabilidad de ClinePass. + +**Cline** es la misma clave y punto final API en la facturación de uso de pago por uso en más de 100 modelos (ID de estilo OpenRouter como `anthropic/claude-sonnet-4-6`). Los modelos promocionales gratuitos de Cline solo están disponibles en el IDE de Cline/ CLI, no a través del API; `minimax/minimax-m2.5` es el modelo documentado de experimentación libre API. + +**OrcaRouter** ([patrocinador](https://github.com/lidge-jun/opencodex/blob/main/SPONSORS.md)) es una puerta de enlace compatible con OpenAI en `https://api.orcarouter.ai/v1` con identificadores de modelo separados por el nombre del proveedor (`openai/gpt-5.5`, `anthropic/claude-opus-4.8`, `deepseek/deepseek-v4-flash`,...) y un enrutador adaptativo, `orcarouter/auto`, que califica cada solicitud y selecciona el modelo. Cree una clave en el [Consola OrcaRouter](https://www.orcarouter.ai/console); el preajuste fija la fila cerca de la parte superior del selector de proveedores Agregar y la marca como patrocinador, y nada más sobre el enrutamiento o los cambios predeterminados. + +**PackyCode** es un relé API para Claude Code, Codex, Gemini y más. Los objetivos preestablecidos apuntan a su punto final OpenAI -compatible con Chat Completions, `https://cf.api.fan/v1`, con el descubrimiento del modelo en vivo reducido a lo que su grupo de tokens permite (`gpt-5.5` y `gpt-5.1-codex` se siembran). Regístrese en [packyapi.com](https://www.packyapi.com) y cree un token de grupo Codex. + +**Opper** es la puerta de enlace AI alojada en la UE de Opper AI (Estocolmo): una clave (creada en [plataforma.opper.ai](https://platform.opper.ai)) y un punto final compatible con OpenAI frente a más de 700 modelos de más de 30 proveedores. Los identificadores de modelos desnudos como `claude-sonnet-4-6` o `gpt-5.5` son *grupos*: Opper selecciona el proveedor y la región por solicitud, por lo que los identificadores sembrados permanecen válidos a medida que las rutas van y vienen. Un id `vendor/model` (`anthropic/claude-sonnet-4-6`, `aws/claude-sonnet-4-6-eu`) fija una ruta en su lugar. El catálogo se descubre en vivo desde `/v3/compat/models` con su clave; la lista pública, incluidas las rutas de la UE por regiones, está en [opper.ai/modelos](https://opper.ai/models). Opper también es un proveedor [modelos.dev](https://models.dev) (`opper`), que utiliza los mismos identificadores de grupo desnuda. + +| Proveedor | URL base | +| --- | --- | +| **OpenAI (clave API)** | `https://api.openai.com/v1` | +| **Anthropic (clave API)** | `https://api.anthropic.com` | +| **OpenRouter** | `https://openrouter.ai/api/v1` | +| **Cline** | `https://api.cline.bot/api/v1` | +| **ClinePass** | `https://api.cline.bot/api/v1` | +| **Ollama Cloud** | `https://ollama.com/v1` | +| Google Gemini · Google Vertex AI | `https://generativelanguage.googleapis.com` · `https://aiplatform.googleapis.com` | +| Azure OpenAI | `https://{resource}.openai.azure.com/openai` | +| Umans AI · Neuralwatt | `https://api.code.umans.ai` · `https://api.neuralwatt.com/v1` | +| Mistral | `https://api.mistral.ai/v1` | +| MiniMax · MiniMax (CN) | `https://api.minimax.io/v1` · `https://api.minimaxi.com/v1` | +| DeepSeek | `https://api.deepseek.com` | +| Cerebras | `https://api.cerebras.ai/v1` | +| Chutes | `https://llm.chutes.ai/v1` | +| DeepInfra | `https://api.deepinfra.com/v1/openai` | +| Hyperbolic | `https://api.hyperbolic.xyz/v1` | +| Nscale Serverless Inference | `https://inference.api.nscale.com/v1` | +| Vultr Serverless Inference | `https://api.vultrinference.com/v1` | +| Baseten Model APIs | `https://inference.baseten.co/v1` | +| Command Code | `https://api.commandcode.ai/provider/v1` | +| OrcaRouter | `https://api.orcarouter.ai/v1` | +| PackyCode | `https://cf.api.fan/v1` | +| Meta Model API | `https://api.meta.ai/v1` | +| Meta Muse Code (credencial CLI) | `https://api.meta.ai/v1` | +| SambaNova Cloud | `https://api.sambanova.ai/v1` | +| Nebius Token Factory | `https://api.tokenfactory.nebius.com/v1` | +| Crusoe | `https://api.inference.crusoecloud.com/v1` | +| DigitalOcean Serverless Inference | `https://inference.do-ai.run/v1` | +| Scaleway Generative APIs | `https://api.scaleway.ai/v1` | +| Featherless AI | `https://api.featherless.ai/v1` | +| Novita AI | `https://api.novita.ai/openai/v1` | +| Together | `https://api.together.xyz/v1` | +| Fireworks | `https://api.fireworks.ai/inference/v1` | +| Moonshot (Kimi API) · Kimi (coding) | `https://api.moonshot.ai/v1` · `https://api.kimi.com/coding/v1` | +| Hugging Face | `https://router.huggingface.co/v1` | +| NVIDIA NIM | `https://integrate.api.nvidia.com/v1` | +| Z.AI (GLM Coding) | `https://api.z.ai` — Responses en `/api/v1/responses` de forma predeterminada; Chat Completions en `/api/coding/paas/v4/chat/completions` por modelo mediante `modelAdapters` | +| Zhipu AI (BigModel) | `https://open.bigmodel.cn/api/paas/v4` | +| BigModel Coding Plan (Responses, lista estática) | `https://open.bigmodel.cn/api/v1` | +| Qwen Cloud | Plan de tokens (predeterminado): `https://token-plan.maas.qwencloudapi.com/compatible-mode/v1` · Pago por uso: `https://dashscope.aliyuncs.com/compatible-mode/v1` · o personalizado | +| Tencent Cloud Coding Plan | `https://api.lkeap.cloud.tencent.com/coding/v3` | +| SiliconFlow | `https://api.siliconflow.cn/v1` | +| Volcengine Ark · Coding Plan · Agent Plan | `https://ark.cn-beijing.volces.com/api/v3` · `https://ark.cn-beijing.volces.com/api/coding/v3` · `https://ark.cn-beijing.volces.com/api/plan/v3` | +| Xiaomi MiMo | `https://api.xiaomimimo.com/anthropic` | +| Xiaomi MiMo (OpenAI Chat) | `https://api.xiaomimimo.com/v1` | +| Kilo | `https://api.kilo.ai/api/gateway` | +| Opper | `https://api.opper.ai/v3/compat` | +| TokenLab | `https://api.tokenlab.sh/v1` | +| Modelflare | `https://modelflare.dev/v1` | +| OpenGateway | `https://apis.opengateway.ai/v1` | +| GitLab Duo | `https://cloud.gitlab.com/ai/v1/proxy/openai/v1` | +| Cloudflare AI Gateway | `https://gateway.ai.cloudflare.com/v1/{account-id}/{gateway}/anthropic` | +| …y otros | opencode zen, Vercel AI Gateway, Venice, NanoGPT, Synthetic, Qianfan, Alibaba, Parallel, ZenMux, LiteLLM | + +**Alibaba Token Plan** ofrece los presets Personal Edition de Beijing y Team Edition internacional. Ambas regiones ofrecen los dos niveles de suscripción. Las listas de modelos de chat son estáticas porque el descubrimiento del proveedor también incluye modelos que no son de chat. Se conservan las selecciones existentes y los endpoints internacionales configurados explícitamente. + +Ambos presets incluyen `deepseek-v4.1-flash-1017`, con entrada de texto e imágenes, salida de texto, contexto de 1.000.000 de tokens y razonamiento `low`, `high` y `max` (`high` por defecto). Su límite de salida de 393.216 sigue la normalización del presupuesto publicado; no es un límite medido. El Lab informa 384.000. Los esquemas estrictos son rechazados y `json_object` no está verificado para este identificador exacto, por lo que las solicitudes Chat omiten `response_format`: la salida es texto de mejor esfuerzo, sin garantía de JSON. La degradación JSON verificada del modelo sin sufijo y las asignaciones existentes a Responses no cambian. Beijing también incluye `deepseek-v4-pro-0813`, ahora publicado. La región internacional omite los retirados `deepseek-v3.2` y `deepseek-v4-flash` sin sufijo, pero conserva `deepseek-v4-flash-0731`. Los presets mantienen los hosts de sus guías oficiales: Beijing usa `https://token-plan.cn-beijing.maas.aliyuncs.com/compatible-mode/v1` y la región internacional `https://token-plan.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1`. El preset Qwen Cloud usa el host Token Plan independiente documentado arriba. Consulta la [ficha del modelo 1017](https://www.qianwenai.com/models/deepseek-v4.1-flash-1017), la [referencia Chat](https://docs.qwencloud.com/api-reference/chat/openai-chat) y la [guía Personal](https://help.aliyun.com/en/model-studio/token-plan-personal-overview). + +**OpenGateway** es una puerta de enlace compatible con OpenAI operada por Sionic AI en +`https://apis.opengateway.ai/v1`. Su catálogo público contiene alrededor de 80 modelos activos. (como se verificó en 2026-10-02); el ajuste preestablecido actualiza automáticamente la lista de modelos en vivo desde público `GET /v1/models` y mantiene activos los modelos Chat Completions (además de la Responses-only `openai/o3-pro`, que está anclado a Responses). Servido con ión +`deepseek/deepseek-v4.1-flash-ultrafast` y `z-ai/glm-5.3-flash-ultrafast` Se enumeran primero. Crear una clave en el [Panel de OpenGateway](https://opengateway.ai/api-keys), luego corre +`ocx provider add opengateway` o seleccione **OpenGateway** en el panel. Solicitudes de chat use la clave Bearer configurada; la lista de modelos públicos no valida esa clave. En el cable Responses, OpenGateway rechaza las llamadas a herramientas personalizadas nativas reproducidas, por lo que el ajuste preestablecido reduce las herramientas personalizadas Codex, como el modo de código `exec` para que funcionen antes de enviarlas. + +Los resultados de herramientas que contienen arrays se envían como texto; las imágenes se conservan después del grupo de resultados emparejados. Las partes incompatibles, incluidos rechazos y contenido opaco, se rechazan expresamente con un error de entrada del cliente antes del envío. El nivel de detalle de imagen `original` se convierte a `high`, que la pasarela admite, sin cambiar sus bytes. La ruta nativa de Responses también comprueba las respuestas vacías de solo texto antes de mostrarlas como correctas. Agotar el presupuesto de salida produce `incomplete` con `max_output_tokens`; el proxy no aumenta el presupuesto solicitado. Una respuesta vacía que admita repetición segura y conserve presupuesto puede reintentarse una vez, dentro del límite existente de envíos. `emptyCompletionRetry: false` u `OCX_EMPTY_COMPLETION_RETRY=0` lo desactivan. El texto, los rechazos, la actividad de herramientas y los eventos de streaming desconocidos impiden repetir la solicitud y conservan la transmisión original. Esta protección no cambia otros proveedores ni sus valores de reintento. Para repetir se requiere `store: false` explícito, entrada completa y solo herramientas ejecutadas por el cliente; una herramienta alojada como `web_search` impide la repetición automática aunque no se haya observado un evento de herramienta. + +**TokenLab** ([patrocinador](https://github.com/lidge-jun/opencodex/blob/main/SPONSORS.md)) es un OpenAI -compatible API puerta de enlace en [tokenlab.sh](https://tokenlab.sh/r/OPENCODEX), operado por TOKENLAB AI INC. Cree un espacio de trabajo [API clave](https://tokenlab.sh/dashboard/api?tab=keys), luego ejecute `ocx provider add tokenlab` o seleccione **TokenLab** en el selector **Añadir proveedor** del panel de control. TokenLab mantiene un paso a paso [Guía de integración OpenCodex](https://tokenlab.sh/docs/en/integrations/opencodex) ([한국어](https://tokenlab.sh/docs/ko/integrations/opencodex)) que cubre la configuración y el enrutamiento por modelo. El preajuste utiliza [Chat Completions](https://tokenlab.sh/docs/en/quickstart) y descubre modelos en `GET /v1/models?category=chat`, manteniendo solo las entradas que declaran la capacidad de `tool-use`. Los modelos de imagen, video, audio, incrustación y decisión están excluidos de este preajuste de chat. + +Cada modelo utiliza el formato de solicitud TokenLab declara para ello ( `tokenlab.accepted_request_formats` en `GET /v1/models/{model}` ): + +| Modelos | Codex (Responses clientes) | Clientes de chat | Claude Code (Anthropic clientes) | +| --- | --- | --- | --- | +| `gpt-6-astra`, `gpt-6.1-sol`, `gpt-6-sol`, `gpt-6-luna`, `grok-4.7`, `deepseek-v4.1-flash`, `deepseek-v4-pro`, `kimi-k3`, `glm-5.3` | [Responses](https://tokenlab.sh/docs/en/api-reference/responses/create-response) | Chat Completions | Chat Completions | +| `claude-*` | [Messages](https://tokenlab.sh/docs/en/api-reference/messages/create-message) | Messages | Messages | +| Cualquier otro modelo, incluyendo `gemini-3.8-flash` | Chat Completions | Chat Completions | Chat Completions | + +Para mantener un modelo en Chat Completions, añádalo al `modelAdapters` del proveedor, por ejemplo `"modelAdapters": { "gpt-6.1-sol": "openai-chat" }`. El enrutamiento Claude se aplica solo mientras el proveedor apunta a `https://api.tokenlab.sh/v1`. OpenCodex no envía ningún encabezado de política de entrega, por lo que la política de entrega de su clave API decide cómo TokenLab sirve cada solicitud. + +El [catálogo de modelos](https://tokenlab.sh/docs/en/api-reference/models/list-models) es público sin una clave, pero se valida una clave suministrada y los resultados de alcances a sus permisos de modelo y política de entrega. Utilice una clave válida con un espacio de trabajo financiado para la inferencia. `gpt-5.6-terra` es el valor predeterminado; elija otro modelo descubierto si su clave no lo permite. Los prefijos de proveedor y modelo permanecen separados: `tokenlab/gpt-5.6-terra` envía `gpt-5.6-terra` aguas arriba. Las referencias [términos](https://tokenlab.sh/tos) y [Política de privacidad](https://tokenlab.sh/privacy-policy) de TokenLab se aplican a las solicitudes enviadas a este servicio. El preset fija la fila cerca de la parte superior del selector Añadir proveedor y la marca como patrocinador, y nada más sobre el enrutamiento o los cambios predeterminados. + +**Modelflare** es un relé compatible con OpenAI en `https://modelflare.dev/v1`. Seleccione **Modelflare** en `ocx init` o el selector **Añadir proveedor** del tablero de instrumentos, o ejecute `ocx provider add modelflare`, y déle su clave directamente o como referencia `${MODELFLARE_API_KEY}` para que la clave permanezca en su entorno. El preset utiliza Chat Completions y siembra cuatro modelos que fueron verificados con chat, streaming y llamadas de herramientas: `glm-5.3-flash` (el predeterminado), `claude-sonnet-5-5`, `gpt-6.1-sol` y `deepseek-v4-flash`. Puede agregar otros modelos Modelflare compatibles con Chat como modelos personalizados. Los modelos de imagen y vídeo utilizan puntos finales de Modelflare independientes y no funcionan con este ajuste preestablecido de Chat. Una clave Modelflare ordinaria está vinculada a un grupo de enrutamiento y puede llamar solo a los modelos de ese grupo, así que use una clave inteligente para el conjunto inicial completo o pase `--default-model` con un modelo que sirva el grupo de su clave. `deepseek-v4.1-flash` se muestra aguas arriba, pero actualmente responde 503, por lo que el preajuste lo deja fuera. La latencia ascendente varía de unos pocos segundos a aproximadamente 30 segundos, con transitorios ocasionales 503. + +Las tarjetas de proveedor MiniMax y MiniMax (CN) también pueden mostrar la cuota del Plan de codificación cuando la clave configurada tiene un plan activo. El panel de control lee la ventana de 5 horas del plan y, cuando está presente, la ventana semanal; estas son observaciones de visualización y no cambian el enrutamiento del modelo. + +Ollama Las tarjetas de proveedores de la nube leen la cuota de `/api/balance` primero, con `/api/usage` como alternativa para implementaciones anteriores. Un informe de reserva analizado reemplaza a un fallo anterior; de lo contrario, las respuestas 4xx duras (excepto 404/408/429) borran la última cuota válida incluso si falla otro intento, mientras que los fallos transitorios la mantienen. Un cuerpo ilegible o sobredimensionado detiene los intentos adicionales. Los créditos en dólares muestran solo la asignación incluida, excluyendo los créditos comprados, por lo que una asignación agotada deja de enviarse a Ollama Cloud solo cuando no queda ningún crédito comprado. + +`MiniMax-M3.1-Flash-Preview` (contexto de 1M) aparece en ambos preajustes MiniMax. MiniMax solo sirve para claves de suscripción de Token Plan y código MiniMax por ahora, por lo que una clave de pago por uso API recibe un error por ello. Pensar siempre está en marcha: el selector de esfuerzo ofrece `low` a `max` y por defecto a `max`, y no hay forma de desactivar el pensamiento. MiniMax no ha publicado un precio por token para la vista previa; el uso se extrae de su [Cuota del Plan Token](https://platform.minimax.io/docs/guides/pricing-token-plan), por lo que OpenCodex no muestra un costo estimado para él. El punto final `/models` de MiniMax aún no enumera la vista previa, por lo que OpenCodex lo mantiene en el catálogo desde el preajuste. Una instalación cuya lista de modelos MiniMax guardada sigue siendo la predeterminada anterior la recibe en el siguiente inicio; una lista que ha editado se deja tal como está; registre la vista previa a mano con `ocx models add minimax MiniMax-M3.1-Flash-Preview --context-window 1000000`. + +**OpenCode Ir** rutas `gemini-4-argon-contributor` a través de su Gemini API, incluyendo streaming y continuación de resultados de herramientas. El preajuste `opencode-go` existente mantiene su URL histórica fija: las URL personalizadas guardadas, incluida `https://opencode.ai/inference/go/v1`, se enrutan a través del punto final canónico `https://opencode.ai/zen/go/v1` y heredan los valores predeterminados de Go. Gemini luego usa el punto final del modelo nativo de Go con autenticación de clave. Un proveedor personalizado con nombre diferente mantiene su URL configurada y no recibe este pin Gemini. Go selecciona protocolos por ID de modelo exacto: GPT 6 Luna, GPT 5.6 Luna, Grok 4.6/4.7 y Muse Spark Contributor usa Responses; Claude Haiku 5.5, MiniMax M2.7/M3 y Qwen3.7 Plus/3.8 Max/3.8 Uso del flash Anthropic Messages. Legacy MiniMax M2.5 y Union Alpha también retienen Messages. Los modelos sin un cable listado retienen el chat. Los nuevos pines nativos se aplican al destino Go anclado con autenticación de clave. Los modelos Responses aún aceptan una anulación explícita de `modelAdapters`. Al leer una configuración guardada anterior, OpenCodex ignora las anulaciones obsoletas de Chat/ Responses para los modelos Gemini y Qwen recién anclados, junto con sus preferencias de herramientas alojadas solo Responses válidas anteriormente. Otros proveedores, cuentas y enrutamiento permanecen disponibles. Las lecturas dejan el archivo sin cambios; una edición de configuración explícita posterior guarda los valores actualizados. Nuevas anulaciones para estos modelos nativos siguen siendo rechazadas. Gemini utiliza `low`, `medium` y `high` niveles de pensamiento; esfuerzos más altos se fijan a `high`. + +OpenCode Go requiere un identificador de sesión estable para el enrutamiento. OpenCodex envía `claude-haiku-5-5`, al igual que los modelos MiniMax, sobre el alambre Anthropic Messages, que coincide con [Tabla de puntos finales de OpenCode Go](https://opencode.ai/docs/go/#endpoints). OpenCodex deriva su encabezado de sesión Go de encabezados de hilo/sesión Codex, o de un encabezado `x-opencode-session` de un cliente cuando los encabezados Codex están ausentes. Esto se aplica a las solicitudes Chat Completions directas y las solicitudes puenteadas a Responses. Incluso un valor entrante `ocx_`-prefijo se trata como entrada del cliente y se hashed en afinidad Go; el puente interno lleva el valor original, por lo que Chat nativo, Chat puenteado y Responses obtienen el mismo resultado. Los encabezados de sesión explícitos provider-config son anulaciones del operador y se envían sin cambios. Los clientes deben mantener el identificador estable dentro de una conversación y distinto en todas las conversaciones. Una solicitud sin ningún identificador de sesión no recibe una identidad de solicitud cruzada inferida; en cambio, se envía bajo una sesión asignada solo para esa solicitud, aislada de cualquier otra solicitud (consulte la referencia del proveedor sobre cómo se transmite ese valor). Para Claude Messages, los encabezados de sesión de OpenCode Go configurados siguen siendo autorizados. De lo contrario, los encabezados de sesión o hilo explícitos válidos tienen prioridad, y la identidad de conversación válida en `metadata.user_id` proporciona la reserva. Esta reserva se aplica al destino final de Go, incluidas las selecciones aleatorias combinadas y los intentos de reserva, en lugar de la ruta preliminar. Las claves compartidas de la caché del símbolo del sistema no identifican las conversaciones y la identidad específica de Go no se envía a los objetivos que no son Go. Las configuraciones del proveedor Pi generado habilitan `compat.sendSessionAffinityHeaders` para que Pi envíe su identidad por sesión al proxy. Las configuraciones de Pi administradas manualmente existentes también pueden establecer esta opción en su proveedor `opencodex`. Pi puede omitir la afinidad de sesión cuando `cacheRetention` es `none`; habilitar la retención de caché cuando se requiere una sesión ascendente estable. + +**Ecos de llamadas a herramientas de MiMo.** En OpenCode Go y otras rutas de Chat Completions, se oculta un bloque `` cuando duplica una llamada estructurada a la misma herramienta con la misma entrada efectiva. Esto incluye envoltorios de MiMo como `` con identificadores de cierre coincidentes, incluso cuando el eco sigue a un texto normal. Los ejemplos de código siguen visibles. Si la entrada es distinta o varias llamadas pueden explicar el bloque, el marcado se conserva. Para `mimo-v2` y los identificadores MiMo V2 con puntos, como `mimo-v2.6-pro`, si la pasarela envía exactamente una llamada vacía `{}` a una herramienta freeform declarada y coloca su entrada en un bloque independiente, sin identificador o con él, opencodex recupera la entrada en la llamada y oculta el bloque. Los identificadores con guiones, como `mimo-v2-pro` y `mimo-v2-omni`, no participan en esta recuperación. El texto normal, los ejemplos entre comillas, las funciones ordinarias y las respuestas ambiguas no cambian. También se admite el inicio incorrecto ` **Tres rutas de facturación Volcengine:** `volcengine` es el pago por uso de Ark API, `volcengine-coding-plan` consume la cuota del Plan de codificación, y `volcengine-agent-plan` consume la cuota del Plan de agente. Utilice la clave y el punto final emitidos para el mismo producto; el punto final ordinario `/api/v3` puede incurrir en cargos de pago por uso incluso cuando existe una suscripción a Plan. Los preajustes usan catálogos de modelos estáticos seleccionados porque la respuesta `/models` de Ark también incluye recursos de incrustación, imagen, video y 3D, la puerta de enlace de codificación devuelve el mismo catálogo amplio y la puerta de enlace de plan de agente no tiene ningún recurso `/models`. Pay-as-you-go predeterminado a `doubao-seed-2-1-pro-260628`; su catálogo curado también incluye modelos de texto DeepSeek y GLM actuales. El plan de codificación se establece por defecto en `ark-code-latest`, mientras que el plan de agente se establece por defecto en `deepseek-v4-flash`. + +> **Restricción de uso del plan Volcengine:** Volcengine documenta la cuota de Plan de codificación y Plan de agente como válida solo dentro de las herramientas de codificación de IA compatibles, y advierte que el uso de una clave de plan para las llamadas generales API puede suspender la suscripción o prohibir la cuenta. La ruta Codex o Claude Code a opencodex es el uso documentado; señalar otra automatización en una clave de plan no lo es. La ruta `volcengine` de pago por uso no conlleva tal restricción. + +**Chutes descubrimiento.** Los `chutes` preset usa el contenido compartido fijo de Chutes OpenAI-compatible LLM Se lee el público. `/v1/models` catálogo, mantiene solo filas cuya `supported_features` anunciar +`tools`, conserva los identificadores de modelos que contienen barras y los metadatos en vivo seguros, y limita el descubrimiento a 256 KiB y 128 filas brutas. Debido a que ese catálogo es público, no puede probar que una clave suministrada sea válida; chat Las solicitudes siguen utilizando la clave Bearer configurada. Los hosts Chute personalizados desplegados por el usuario y los Chutes que no son LLM Las API siguen siendo territorio de proveedor personalizado. Crea una clave desde el [Panel de chutes](https://chutes.ai/auth/start). + +**DeepInfra descubrimiento.** El proveedor basado en claves `deepinfra` OpenAI Chat Completions utiliza el adaptador `openai-chat` con una clave Bearer API. Su URL de lista de modelos propiedad del registro mantiene solo las filas etiquetadas con `chat`, conserva los identificadores de modelos nativos que contienen barras y limita el descubrimiento en vivo a 512 KiB y 512 filas sin procesar. Crear claves en [Panel de DeepInfra](https://deepinfra.com/dash/api_keys). + +**descubrimiento hiperbólico.** El preajuste lee `/v1/models` con la clave de portador configurada, conserva los identificadores de modelo nativos que contienen barras y limita el descubrimiento en vivo a 256 KiB y 256 filas sin procesar. Cubre solo el chat de texto y visión-idioma sin servidor; Los puntos finales separados de imagen, audio y GPU de Hyperbolic están fuera de alcance. Crear claves en [Hiperbólico](https://app.hyperbolic.ai). + +**Nscale y descubrimiento de Vultr.** Ambos preajustes leen el catálogo autenticado del proveedor `/v1/models`, preservan los identificadores nativos y limitan el descubrimiento a 256 KiB y 256 filas sin procesar. El catálogo de Nscale mezcla modelos de chat, imagen e incrustación sin un campo de modalidad, por lo que el preajuste admite solo `meta-llama/Llama-3.1-8B-Instruct`, el modelo utilizado por la herramienta oficial de Nscale que llama al ejemplo API. Vultr actualmente documenta la herramienta que llama solo por `kimi-k2-instruct`, por lo que su preajuste expone solo ese modelo. Otras filas permanecen ocultas hasta que el proveedor publica evidencia equivalente de agente-herramienta. Cree un token de servicio Nscale en el [Consola Nscale](https://console.nscale.com); copie la clave de inferencia de Vultr de la descripción general de suscripción en el [Consola Vultr](https://my.vultr.com). + +**Detección de Command Code.** El preajuste lee el Command Code `/provider/v1/models` Lista del host fijo Provider API, conserva los identificadores nativos del proveedor y limita el descubrimiento a 256 KiB y 256 raw filas. `ocx login command-code` admite OAuth a través del inicio de sesión en el navegador (con credenciales locales opcionales CLI Importación de `~/.commandcode/auth.json` para los usuarios existentes de Command Code CLI); el catálogo del modelo es cuenta-scoped y viene del punto final de descubrimiento autenticado después de iniciar sesión. El proveedor-API preset (`commandcode`) envía la clave de configuración activa: la mayoría de los identificadores de modelo usan Chat Completions con un Bearer encabezado, mientras `claude-*` ids use Anthropic Messages con `x-api-key`porque el Command Code les sirve sólo en `/provider/v1/messages`. Un proveedor que reutiliza el `commandcode` nombre para un diferente punto final mantiene su propio cable. El ajuste preestablecido de OAuth (`command-code`) utiliza el portador de la cuenta almacenada para descubrimiento autenticado y generación de flujos desde `/alpha/generate` como NDJSON. MiMo tool-call markup repetido por la puerta de enlace como texto se elimina cuando duplica una llamada real. En los modelos MiMo, a Completar la llamada de herramienta declarada sin contraparte nativa se restaura solo después de un acabado limpio; Los giros interrumpidos o filtrados dejan el marcado como texto. Crear claves de proveedor-API en +[Command Code Studio](https://commandcode.ai/studio/). + +Para un proveedor que utiliza el adaptador nativo `command-code`, `projectContext: "on"` opta por enviar archivos de proyecto locales en los campos `/alpha/generate`, `memory`, `taste` y `skills`. Con `projectContext` sin configurar o `"off"`, no se leen ni envían archivos de proyecto (`AGENTS.md`, gusto o habilidades); la carga útil de metadatos `config` existente no cambia. Las raíces se resuelven desde el **Directorio de trabajo del proceso proxy opencodex**, no desde el espacio de trabajo remoto de una persona que llama. El cargador lee `AGENTS.md`, `.commandcode/taste/taste.md` y `SKILL.md` archivos en directorios secundarios inmediatos de `.commandcode/skills`, `.agents/skills` y `.pi/skills` bajo ese directorio de trabajo. Al habilitar la opción, se envía el contenido recopilado aguas arriba al punto final Command Code configurado. Se rechaza para otros adaptadores. Las comprobaciones de ruta asíncrona mantienen las lecturas dentro del directorio de trabajo resuelto, incluso cuando ese directorio es una raíz del sistema de archivos; solo se lee el contenido del archivo regular. Los enlaces simbólicos de directorio de habilidad que se resuelven dentro de ese directorio están permitidos; aquellos que se resuelven fuera son rechazados. Cada entrada visitada cuenta para el presupuesto de escaneo; como máximo se seleccionan 16 habilidades. Los bytes de archivo, los bytes de habilidad total y el tiempo de carga están limitados; los archivos ilegibles o faltantes producen campos vacíos. Los resultados estables se almacenan en caché durante 30 segundos; los tiempos de espera y los rechazos de admisión al sistema de archivos no se almacenan en caché, por lo que una solicitud posterior puede volver a intentarlo. + +**Autenticación y descubrimiento de OrcaRouter.** Elija `ocx login orcarouter-oauth` para la autorización del navegador con un solo clic o `ocx login orcarouter` para pegar una clave API existente. El flujo PKCE inicia primero un oyente de bucle de retorno, envía un nuevo desafío S256 y se indica a `https://www.orcarouter.ai/auth`, intercambia el código de un solo uso en `https://www.orcarouter.ai/api/v1/auth/keys` y almacena la clave de propiedad del usuario devuelta en `~/.opencodex/auth.json`. El preajuste de teclas manuales continúa utilizando el almacén de claves de proveedor normal. Ambos modos se encaminan a `https://api.orcarouter.ai/v1` y descubren el catálogo público en vivo con `capability=chat`; se excluyen las filas de medios/reordenados que no son de chat, y las modalidades de entrada informadas controlan si Codex ofrece adjuntos de imagen. Debido a que el catálogo en sí es público, la configuración manual de la clave informa que la validación es desconocida en lugar de aceptar esa respuesta como prueba de que la clave funciona. + +Durante el inicio de sesión del navegador OrcaRouter (`ocx login orcarouter-oauth`), un cuerpo de respuesta de intercambio de claves exitoso debe ser válido UTF-8 JSON no más grande de 64 KiB. El presupuesto de 30 segundos de la solicitud cubre tanto los encabezados de respuesta como el cuerpo completo; los cuerpos sobredimensionados o malformados son rechazados antes de guardar la clave. Estos límites se aplican solo al intercambio de claves de inicio de sesión, no a las cargas útiles de solicitud de inferencia. La validación del alcance no cambia: se permite un `scope` omitido, mientras que se rechaza un `scope` explícitamente inválido. + +Para una implementación autoalojada de un origen, establezca el origen compartido antes del primer inicio de sesión de PKCE; la URL de inferencia guardada se deriva del mismo origen: + +```bash +ORCAROUTER_BASE_URL=https://router.example ocx login orcarouter-oauth +``` + +Para una implementación auto-alojada dividida, establezca `ORCAROUTER_API_BASE_URL` y `ORCAROUTER_AUTH_BASE_URL` por separado. + +El valor debe ser un origen HTTPS (o loopback HTTP para el desarrollo local) sin credenciales, consulta o fragmento. Antes del primer inicio de sesión en un punto final autoalojado privado/loopback, permita explícitamente ese destino en la fila de proveedores `~/.opencodex/config.json`. Por ejemplo, fusione esta entrada en el objeto `providers` existente para un servidor de desarrollo local: + +```json +{ + "orcarouter-oauth": { + "adapter": "openai-chat", + "baseUrl": "http://127.0.0.1:9999/v1", + "authMode": "oauth", + "allowPrivateNetwork": true + } +} +``` + +Luego ejecuta `ORCAROUTER_BASE_URL=http://127.0.0.1:9999 ocx login orcarouter-oauth`. El inicio de sesión conserva este consentimiento explícito; establecer la URL por sí sola nunca permite el acceso a la red privada. Sin la aceptación, la validación de destino rechaza la inferencia y el descubrimiento de modelo para ese punto final. Este requisito se refiere al punto final del proveedor; el oyente de devolución de llamada del navegador no necesita dicha aceptación. Volver a ejecutar el inicio de sesión después de un relé `401`; Las llaves OrcaRouter son duraderas y no tienen una subvención de actualización de token. + +**Meta Modelo API (`meta-model`).** Muse Spark en el propio punto final compatible con OpenAI de Meta, servido por más de `/v1/responses`. Crear una clave en [la consola de desarrolladores de Meta](https://dev.meta.ai/docs/authentication) - Meta llama a esta variable `MODEL_API_KEY`, pero opencodex deriva la var env del ID del proveedor, por lo que exportarlo como **`META_MODEL_API_KEY`** (o pegarlo durante `ocx init`). La cuenta necesita un método de pago antes de atender las solicitudes, y cada llamada se mide por token. Tres modelos están sembrados, cada uno con una ventana de contexto de 1M: `meta-model/muse-spark-1.3` y `meta-model/muse-spark-1.3-contributor` con `minimal` / `low` / `medium` / `high` / `xhigh` escalera, y `meta-model/muse-wonder-1.0` (Muse Wonder, vista previa) con `minimal` a través `max`. Muse Wonder es el modo estándar solo en el Modelo API: no tiene nivel de colaborador y cuesta $ 4 por entrada de 1 millón y $ 20 por tokens de salida de 1 millón. Muse Wonder Full solo está disponible dentro de las suscripciones Muse Code, por lo que no se siembra. Discovery se queda fuera hasta que se verifica una lista autenticada, porque Meta sirve modelos de imagen y voz en el mismo host. + +Dos cosas que vale la pena saber antes de elegirlo. **Una suscripción Muse Code no se aplica aquí:** Meta alcances que acreditan al Muse Code CLI y factura cualquier otra clave de pago por uso. Y el nivel Contributor es barato porque Meta entrena en sus mensajes: aproximadamente 92% de descuento en la entrada, 96% de descuento en la salida y 99% de descuento en la entrada en caché, así que mantenga el material confidencial fuera de él. Muse Spark también es accesible a través de revendedores, con una lista más estrecha: `command-code` lleva ambos niveles, mientras que `opencode-go` sirve solo `muse-spark-1.3-contributor`. + +**Código Meta Muse (`meta-muse`).** Un inicio de sesión macOS simple ya prueba la clave API Almacenado por `muse login`. Sin credenciales locales, o en otra plataforma, se inicia el flujo de aprobación del dispositivo del navegador. Agregar cuenta y reautenticación omite la importación local para evitar Reutilizar la cuenta que se está reemplazando. OpenCodex nunca lanza el Muse CLI. Si el dispositivo inicia sesión falla sin cancelación, una superficie de entrada manual disponible puede aceptar una clave pegada; que la clave se enfrenta al mismo formato y validación del modelo API como una clave importada. En macOS, Aprobar el aviso de llavero en el host proxy en 120 segundos. Denegaciones de importación mostrar la razón de falla y ofrecer un campo de pegado de clave existente sin iniciar otro inicio de sesión. Agregar cuenta en un proveedor ya configurado omite la importación local. Véase +[Soporte de plataforma](/es/reference/platform-support/) para la imagen completa por plataforma. + +Para iniciar cualquier inicio de sesión de Meta Muse a través de la administración, API requiere una sesión de panel. incluyendo add-account y reautenticación. Un encabezado token de administración en bruto o GUI falsificado recibe +`403 oauth_consent_required` antes de que se lea una credencial o comience una subvención. Esta puerta utiliza el principal de sesión resuelto por el servidor, no un recibo de casilla de advertencia registrado por separado. Direct `ocx login meta-muse` y otros proveedores de OAuth mantienen sus políticas de inicio de sesión existentes. Por lo tanto, la lista de proveedores de administración OAuth omite Meta Muse para los paneles raw-admin-token; abra un panel de control autenticado por sesión para usar ese flujo de inicio de sesión. Esto sólo cambia el descubrimiento, no las verificaciones de admisión en el inicio de sesión o la continuación manual. + +Los tres sembrados `meta-muse` modelos (Muse Spark 1.3, su nivel de colaborador y Muse Wonder) exponer `minimal`/`low`/`medium`/`high`/`xhigh`/`max` a clientes enrutados, incluido el selector de esfuerzo de Grok. Solicitudes de uso +`User-Agent: muse-build/1.3.0 (opencodex compatibility)` Así que Meta acepta el código Muse Contrato de esfuerzo. Un proveedor explícito User-Agent anula este valor predeterminado y puede causar +`max` ser rechazado. En marcha `meta-model` Solo Muse Wonder acepta `max`sus filas de chispa y OpenCode Ir a mantener el `xhigh` techo. Publicidad `max` es el contrato del modelo y no prueba tu plan de código Muse cubre Muse Wonder. + +**Lee esto antes de habilitarlo.** Meta scopes esa credencial a la Muse Code CLI, por lo que su uso aquí es una ruta *sin soporte*. Meta no autoriza la cobertura de suscripción fuera de su propio cliente, cómo se liquidan estas llamadas no es observable desde el API, y debe tratar cada llamada como facturable en su cuenta. La clave, importada o pegada, se copia en el almacén de autenticación de OpenCodex (`~/.opencodex/auth.json`, modo 0600) como cualquier otra credencial OAuth. El panel de control muestra una advertencia de Términos de servicio antes del primer inicio de sesión y antes de cualquier reautenticación: el mismo tratamiento que obtienen Anthropic y Google Antigravity. + +Meta informa el uso de la ventana de suscripción dentro de las respuestas de transmisión, y OpenCodex lo lee desde allí. La fila de la cuenta muestra las últimas ventanas semanales y de 5 horas observadas con la antigedad de esa lectura: Meta no publica ningún punto final para consultarlas a pedido, por lo que un valor solo se actualiza con otro turno de transmisión a través de este proveedor, y un turno que pasa por la traducción de solicitudes en lugar de passthrough informa ninguno. Una cuenta que aún no ha servido un turno de transmisión simplemente no muestra cuota, lo cual no es un error. Se aplican límites de solicitudes por equipo, no por clave. + +Para una configuración compatible, use `meta-model` anterior con su propia clave. + +**Cuota Command Code.** El tablero de instrumentos y la sonda `ocx account refresh` Command Code `/alpha/billing/credits` ventanas (5 horas y semanales) en el canónico `https://api.commandcode.ai` host. El preajuste OAuth (`command-code`) utiliza el portador de cuenta almacenado; el preajuste de tecla Proveedor-API (`commandcode`) utiliza la tecla configurada activa. Una URL de base similar editada por el usuario nunca se sondea. Los créditos mensuales restantes, comprados y gratuitos se muestran como una ventana de USD cuando Command Code también informa sobre el período de gasto. + +**SambaNova Cloud descubrimiento.** El preajuste lee la lista pública `/v1/models` de SambaNova Cloud desdel host API fijo, conserva los identificadores nativos del proveedor y limita el descubrimiento a 128 KiB y 128 filas sin procesar. Debido a que el catálogo no está autenticado, el flujo de inicio de sesión CLI informa que la clave no es verificable en lugar de tratar la respuesta pública como prueba. Las solicitudes de chat siguen utilizando la clave Bearer configurada y desactivan las llamadas a funciones paralelas, que SambaNova aún no admite. Los puntos finales de implementación privados de SambaStudio están fuera del alcance. Crear claves en [Nube SambaNova](https://cloud.sambanova.ai/apis). + +**Descubrimiento de la fábrica de tokens Nebius.** El preajuste solicita el catálogo de modelos detallado autenticado y mantiene solo filas cuya arquitectura produce texto, excluyendo modelos de incrustación y generación de imágenes. Conserva los identificadores nativos que contienen barras, además de los metadatos de contexto y de modalidad de entrada informados, y limita el descubrimiento a 512 KiB y 512 filas sin procesar. Los hosts de implementación dedicados están fuera del alcance. Crear claves en [Fábrica de tokens Nebius](https://tokenfactory.nebius.com). + +**Crusoe descubrimiento.** El preajuste basado en claves utiliza el adaptador `openai-chat` y envía su clave de portador solo al host de inferencia sin servidor fijo de Crusoe. `/v1/models` rechaza solicitudes no autenticadas con 401, por lo que una respuesta de lista exitosa cuenta como validación de clave. Discovery conserva los identificadores nativos delimitados por barras, como `zai-org/GLM-5.3` y `moonshotai/Kimi-K2.6`, exactamente como Crusoe los devuelve y tiene un límite de 256 KiB y 256 filas sin procesar. Las filas se mantienen solo cuando informan `is_public: true` y un texto o un multimodal `architecture.modality`, que excluye las implementaciones privadas de cuenta y cualquier incorporación o filas de medios. Los modelos de razonamiento devuelven su pensamiento en el campo Chat Completions `reasoning`, que lee el adaptador. Solo `openai/gpt-oss-120b` acepta una escalera `reasoning_effort` (`low`, `medium`, `high`); los otros modelos de razonamiento tratan el campo como una palanca de encendido / apagado, por lo que el preajuste declara que no hay escalera de esfuerzo en todo el proveedor y no hay llamadas de herramienta paralelas en todo el proveedor. Se aplican límites de solicitudes por proyecto y por modelo (429 cuando se excede, 503 cuando se escala una implementación compartida), y las nuevas cuentas comienzan con $ 5 de créditos gratuitos. Crea una clave en el [Consola de Crusoe Cloud](https://console.crusoecloud.com) bajo Fundición de Inteligencia, Inferencia. + +**DigitalOcean descubrimiento.** El preajuste utiliza una clave de acceso de modelo contra el host de Inferencia sin servidor compartido fijo e interseca la respuesta autenticada `/v1/models` con la lista de permisos Chat Completions respaldada por documentos de DigitalOcean. Unknown, Responses -sólo, incrustación, y los identificadores de generación de medios fallan. Discovery tiene un límite de 256 KiB y 256 filas sin procesar; los hosts dedicados y específicos del agente están fuera de alcance. Cree una clave en el [Panel de Control de Seguridad](https://cloud.digitalocean.com/model-studio/manage-keys). + +**Scaleway descubrimiento.** El ajuste preestablecido cruza la lista de modelos autenticados con la lista de permisos de Scaleway Chat Completions sin servidor documentada. Desconocido, solo Responses, la incrustación, la transcripción y otros identificadores de modelos de medios fallan; el descubrimiento está limitado a 128 KiB y 128 filas en bruto. Utiliza el punto final compartido del proyecto predeterminado; las URL calificadas para el proyecto y las implementaciones dedicadas requieren un proveedor personalizado. Cree una clave API en el [Consola Scaleway](https://console.scaleway.com/generative-api). + +**Descubrimiento de Featherless.** El preajuste consulta el host fijo compatible con OpenAI y pide solo los primeros 100 modelos populares filtrados por el servicio para chat y el plan actual. Las reglas del registro rechazan cada fila salvo que declare disponibilidad en el plan, ausencia de restricciones de acceso de Hugging Face y `features.tool_use: true`. El descubrimiento se limita a 128 KiB y 100 filas originales; nunca se descarga ni almacena completo el catálogo de decenas de miles de modelos. Como `/v1/models` admite consultas con o sin autenticación, esa respuesta no demuestra que la clave proporcionada sea válida; las solicitudes de chat sí usan la clave Bearer configurada. Featherless reserva sus planes individuales para uso interactivo y prototipos; las aplicaciones generales necesitan un plan Scale. Crea una clave en el [panel de Featherless](https://featherless.ai/account/api-keys). + +**Novita descubrimiento.** El preajuste basado en claves utiliza el adaptador `openai-chat` y envía su clave de portador solo al host compatible OpenAI de Novita. Su lista de modelos públicos se filtra a filas que informan tanto `model_type: chat` como el punto final `chat/completions`, con el descubrimiento limitado a 512 KiB y 256 filas sin procesar. Los identificadores de modelo deben conservarse exactamente como Novita los devuelve, incluidos los identificadores delimitados por barra diagonal, y no deben normalizarse ni reescribirse antes del enrutamiento. Debido a que el catálogo es público, el inicio de sesión informa la clave como no verificable en lugar de tratar una respuesta de lista exitosa como prueba. Las capacidades del modelo varían, por lo que el ajuste preestablecido no anuncia llamadas de herramientas paralelas a todo el proveedor o OpenAI `reasoning_effort`. Crear una clave en [Gerente clave de Novita](https://novita.ai/settings/key-management). + +> **Alcance Baseten:** El preajuste cubre solo el [API de modelo](https://docs.baseten.co/inference/model-apis/overview) compartido de Baseten. Use un [API clave](https://docs.baseten.co/organization/api-keys) personal para uso local o una clave de equipo con acceso **API de modelo de llamada** para uso compartido/de producción. Los endpoints dedicados de Truss `predict` usan diferentes hosts y esquemas y no son enrutados por este preajuste. El descubrimiento en vivo para este preajuste se limita a una respuesta de 1 MiB y 256 filas de modelos sin procesar. + + + + + +### Suscripción WorkBuddy AI + +`workbuddy-ai` conecta tu suscripción internacional de WorkBuddy AI como proveedor de modelos. Elige **WorkBuddy AI** en Proveedores e inicia sesión, o ejecuta: + +```bash +ocx login workbuddy-ai +``` + +Completa el inicio de sesión en el navegador. OpenCodex consulta la autorización durante un máximo de cinco minutos, guarda los tokens y los renueva cuando hace falta. Puedes añadir cuentas mediante la lista OAuth existente; la identidad del equipo permanece asociada a su propio token. No necesitas instalar WorkBuddy Desktop ni importar archivos de credenciales. + +Los modelos y capacidades proceden del catálogo de productos de tu cuenta. Después de iniciar sesión, elige un modelo `workbuddy-ai/`; si el descubrimiento no está disponible, se ofrece `workbuddy-ai/default-model` como selector de respaldo. El streaming, las herramientas y las respuestas almacenadas usan el endpoint Chat de WorkBuddy. Las pestañas Resumen y Cuentas muestran créditos restantes, usados y totales, saldos base y de regalo y los próximos créditos no diarios que caducan, cuando esa información está disponible. Actualizar consulta el resumen de facturación de la cuenta; una lectura fallida no significa saldo cero. Los créditos son informativos: agotarlos no desactiva los modelos gratuitos. + +Se utiliza un protocolo de suscripción no oficial basado en el [plugin WorkBuddy de Magpie](https://github.com/magpie-community/plugins/tree/e7f65641df820dfd715c0d2241f99f2092e4efb1/packages/workbuddy). Las restricciones del canal del cliente o de la cuenta se devuelven al solicitante. OpenCodex no reescribe instrucciones de identidad del agente para evitarlas. La disponibilidad depende de tu cuenta, región, permisos de modelo y la API vigente de WorkBuddy. Es independiente de los proveedores CodeBuddy CLI con clave API y no conecta el cliente WorkBuddy Desktop a OpenCodex. + +### CodeBuddy Code CLI oficial (Global y CN) + +OpenCodex proporciona soporte oficial para adaptadores para el código CodeBuddy Code CLI de Tencent Cloud a través de los presets `codebuddy` (Global) y `codebuddy-cn` (China). + +```json +{ + "providers": { + "codebuddy": { + "adapter": "codebuddy", + "baseUrl": "https://www.codebuddy.ai", + "apiKey": "${CODEBUDDY_API_KEY}" + }, + "codebuddy-cn": { + "adapter": "codebuddy", + "baseUrl": "https://www.codebuddy.cn", + "apiKey": "${CODEBUDDY_CN_API_KEY}" + } + } +} +``` + +- **Prerrequisitos:** Instale el CodeBuddy CLI oficial a nivel mundial: + ```bash + npm install -g @tencent-ai/codebuddy-code + ``` +- **Autenticación:** Obtenga su clave oficial API desde la consola del proveedor: + - Global: [Llaves CodeBuddy Global API](https://www.codebuddy.ai/profile/keys) + - CN: [Llaves CodeBuddy CN API](https://copilot.tencent.com/profile/keys) +- **Aislamiento de la región:** `codebuddy` y `codebuddy-cn` utilizan puntos finales canónicos separados (`https://www.codebuddy.ai` y `https://www.codebuddy.cn`) y entornos infantiles aislados (`CODEBUDDY_INTERNET_ENVIRONMENT=public` vs `internal`). Las credenciales son estrictamente regionales y nunca se intercambian entre entornos. La anulación de la URL base canónica falla cerrada. +- **Modelo Discovery:** el proxy solicita la configuración del producto CodeBuddy (`GET {baseUrl}/v3/config`) con la clave configurada como el encabezado `X-API-Key`, y la lista en esa respuesta es la lista autorizada de modelos descubiertos: es la configuración de la cuenta propia de la clave, por lo que se demuestra que pertenece a la clave: una clave diferente o incorrecta responde al sobre anónimo sin lista en lugar de los modelos de otra cuenta. La lista autenticada es la misma lista de las impresiones CLI para `--model` (la línea "Actualmente compatible" de un inicio de sesión CLI), puede diferir del manifiesto estático incluido con el CLI, y los selectores predeterminados del proveedor (`default` para CN, `default-model` para Global) nunca aparecen en él, pero permanecen llamables: el catálogo los retiene durante el descubrimiento en vivo y en cada ruta alternativa. Al iniciar/sincronizar, el proxy vincula la lista almacenada en caché a una huella digital irreversible de la clave configurada, por lo que un conmutador de clave nunca observa una lista almacenada en caché para la clave anterior, y se degrada a la caché obsoleta de proveedor/huella digital, luego a la semilla estática en `src/providers/codebuddy-models.ts`, cuando la clave no se autentica o la solicitud falla. Los registros de fallos de detección contienen solo una categoría y un estado HTTP, sin el mensaje de la puerta de enlace o una excepción de transporte sin procesar. La solicitud de descubrimiento con credenciales no sigue a las redirecciones; una respuesta 3xx degrada la lista sin reenviar la clave a otro origen. +- **Propiedad de la herramienta y el puente de herramientas:** El CLI siempre se genera con `--tools ""` y `--strict-mcp-config`, por lo que no tiene herramientas incorporadas o configuradas por el usuario. Cuando una solicitud lleva un catálogo de herramientas Codex, el proveedor arma un puente MCP de captura solamente: el catálogo validado y la configuración MCP se escriben en un dir temp privado, el CLI se lanza con `--mcp-config` y una lista `--allowedTools` exacta, y el marco `system/init` debe informar exactamente ese servidor de puente como conectado o el giro falla cerrado. El puente anuncia las herramientas Codex y captura las llamadas propuestas, pero nunca ejecuta nada: un lote de llamadas a herramientas completado se devuelve como `function_call` elementos (nombres asignados a los nombres de cable de la solicitud, como máximo 16 llamadas por mensaje de asistente), el árbol de procesos se termina en `message_stop`, y el cliente externo Codex solo realiza aprobación, sandboxing y ejecución. Los bloques de uso de herramientas paralelos se almacenan en memoria intermedia y se devuelven como llamadas completas incluso cuando sus fragmentos se entrelazan o CodeBuddy reutiliza un índice de bloque de contenido. Un bloque que se deja abierto en el extremo de giro, un reemplazo del mismo índice antes de completar JSON argumentos, o un fragmento de argumento que no se puede atribuir a un bloque abierto falla el giro en lugar de reenviar una llamada parcial o vacía. Los resultados de la herramienta vuelven como entrada de la siguiente solicitud, y la conversación continúa. Las solicitudes sin herramientas mantienen la forma de texto y razonamiento sin formato. Si el CLI escribe una línea de control DSML `calls` no citada seguida de una línea de control `functions.*` invocada en texto o razonamiento, el OpenCodex rechaza el turno en lugar de reenviar el andamio o interpretarlo como una llamada ejecutable. DSML discutido o citado en prosa, código en línea, código cercado o ejemplos de fuente sigue siendo texto de respuesta ordinario. +- **Aplicación de elección de herramienta:** Cuando una solicitud especifica `tool_choice: "required"` o selecciona una herramienta con nombre específico, el puente espera una llamada de herramienta del modelo. Si el CLI completa el turno con texto sin formato en lugar de capturar una llamada de herramienta, el OpenCodex falla al cerrarse con un error 502 `tool_call_required` en lugar de devolver una finalización de texto no válida. +- **Estado de gobierno:** Si el enrutamiento de esta superficie de automatización del proveedor detrás de un proxy para un agente de terceros satisface los términos de uso aceptable de CodeBuddy es una pregunta abierta marcada para la revisión de seguridad del mantenedor (consulte la nota de gobierno en la entrada del registro del proveedor). Trate a este proveedor como pendiente de esa revisión, y tenga en cuenta el límite de propiedad del puente de herramientas: el CLI anidado anuncia herramientas pero nunca las ejecuta, y la aprobación, el sandboxing y la ejecución permanecen con el cliente externo Codex. +- **Derechos y facturación:** El proveedor utiliza la misma cuenta CodeBuddy/superficie de autenticación CLI documentada por el proveedor. La disponibilidad y la facturación de los créditos gratuitos, promocionales, de prueba o de suscripción siguen estando determinadas por el derecho de cuenta de CodeBuddy del usuario. + + + +### Oficial Qoder CLI (Global y CN) + +OpenCodex proporciona soporte de adaptador oficial para Qoder a través de los preajustes `qoder` (Global) y `qoder-cn` (China). Ambos usan un Token de Acceso Personal suministrado por el usuario y el CLI sin cabeza del proveedor; OpenCodex nunca lee sesiones de escritorio de Qoder, cookies de navegador, tokens de actualización o API de consolas privadas. + +```json +{ + "providers": { + "qoder": { + "adapter": "qoder", + "baseUrl": "https://qoder.com", + "apiKey": "${QODER_PERSONAL_ACCESS_TOKEN}" + }, + "qoder-cn": { + "adapter": "qoder", + "baseUrl": "https://qoder.cn", + "apiKey": "${QODERCN_PERSONAL_ACCESS_TOKEN}" + } + } +} +``` + +- **Prerrequisitos:** Instale el CLI oficial para la región que utiliza: + ```bash + npm install -g @qoder-ai/qodercli # Global: qoder / qodercli + npm install -g @qodercn-ai/qoderclicn # CN: qodercn / qoderclicn + ``` +- **Autenticación:** Cree una PAT en la página de integraciones de cuenta ([Mundial](https://qoder.com/account/integrations), [NC](https://qoder.cn/account/integrations)) y péguela como clave API del proveedor. La clave almacenada alcanza el CLI solo como `QODER_PERSONAL_ACCESS_TOKEN` (Global) o `QODERCN_PERSONAL_ACCESS_TOKEN` (CN) en un entorno secundario con alcance. +- **Aislamiento de la región:** Cada preajuste acepta solo su destino canónico (`https://qoder.com` o `https://qoder.cn`) y resuelve su propio ejecutable. Las credenciales, el caché del modelo, el uso y la salud son independientes; ninguna región vuelve a la otra. Un proveedor personalizado más antiguo llamado `qoder` con un destino diferente mantiene su adaptador y URL existentes. +- **Ejecutables de Windows:** Cada preset usa el ejecutable nativo de su CLI cuando está en PATH: `qoder.exe` o `qodercli.exe` para Global; `qodercn.exe` o `qoderclicn.exe` para CN. Dentro de una misma carpeta, `.exe` tiene prioridad sobre `.cmd` con el mismo nombre. Un nombre alternativo posterior, como `qoderclicn.exe`, encontrado en cualquier carpeta de PATH tiene prioridad sobre `qodercn.cmd`; sin embargo, una carpeta anterior que solo contenga `qodercn.cmd` oculta `qodercn.exe` del mismo nombre base en una carpeta posterior. Qoder recibe valores vacíos para `--tools` y `--setting-sources`, para excluir sus herramientas y ajustes locales. Un lanzador que pasa por PowerShell descarta esos argumentos vacíos. Si es el único disponible, se rechaza el turno antes de iniciar la CLI con `cli_dispatcher_drops_empty_args`. Añade a PATH la carpeta del ejecutable nativo —el instalador CN oficial usa `%USERPROFILE%\.qoder-cn\bin\qoderclicn`— y reintenta. Un lanzador que pasa los argumentos directamente, como una shim de npm, sigue funcionando. +- **Modelo Discovery:** `qoder --list-models` es la lista autorizada de derechos para el PAT actual. La caché está vinculada a una huella digital irreversible del token, por lo que cambiar de cuenta nunca reutiliza la lista de otra cuenta. Si el descubrimiento falla, el proveedor se degrada a una caché obsoleta y luego a la semilla estática documentada. +- **Uso del token:** Qoder CLI reporta cero recuentos de tokens a menos que su interruptor de uso esté activado, por lo que cada preajuste lo enciende en su entorno hijo de alcance CLI: `QODER_EXPOSE_TOKEN_USAGE=true` para Global y `QODERCN_EXPOSE_TOKEN_USAGE=true` para CN, que lee solo su propio prefijo. +- **Propiedad de la herramienta:** El CLI ejecuta un solo giro `stream-json` con `--tools ""`, `--strict-mcp-config`, deshabilitando las fuentes y la persistencia de la sesión, por lo que Codex mantiene la propiedad exclusiva de la herramienta. Las herramientas declaradas por el cliente se exponen a través de un servidor MCP aislado. +- **Entrada de imagen:** Qoder Global acepta la entrada de imágenes a través del Qoder CLI. OpenCodex reenvía las entradas de imagen compatibles que llegan al adaptador Global a la CLI sin mantener una lista de permisos de capacidad de visión por modelo allí. La compatibilidad de imágenes y cualquier preprocesamiento o enrutamiento específico del modelo son manejados por Qoder. OpenCodex no utiliza la lista de reserva de descubrimiento estático para clasificar la capacidad de visión por modelo. Qoder CN mantiene su clasificación de sidecar existente, y cualquier solicitud de imagen bruta residual que llegue al adaptador CN se rechaza como `unsupported_input_modality`. OpenCodex serializa el historial antes del turno actual, pero Qoder no persiste las sesiones, por lo que las imágenes anteriores se reproducen en turnos posteriores. En las conversaciones de imágenes observadas de varios giros, las imágenes reproducidas pueden asociarse de manera poco confiable u ordenarse efectivamente en relación con el texto histórico que acompañaron originalmente. +- **Recuperación de PAT:** Para ambos ajustes preestablecidos de Qoder, un grupo de claves de múltiples claves API puede cambiar a otra PAT en un rechazo de autenticación compatible o agotamiento de cuota a nivel de cuenta, pero solo antes del contenido de respuesta o un evento que hace que la reproducción sea insegura. La recuperación requiere una clasificación específica de Qoder y respeta los presupuestos de credenciales y envío; un mensaje de cuota o de HTTP 401/429 por sí solo no es permiso para reproducir. Las configuraciones de una sola tecla no giran. Compartir el corredor CLI no habilita esta recuperación de clave API para CodeBuddy o Claude CLI autoautenticado. +- **Contingente:** No se utiliza la cuota pública API, por lo que los totales y los tiempos de reinicio no están disponibles. Los códigos 110 (límite diario de cuenta) y 118 (agotamiento de créditos personales) informan `insufficient_quota` y permiten la consideración de la recuperación de PAT. Otros códigos de cuota soportados también reportan `insufficient_quota` pero no lo autorizan. Los códigos de error numéricos tienen prioridad: un código numérico no reconocido no vuelve a la cuota o al texto de autenticación. Sin un código numérico, solo el mensaje diario de la cuenta compatible que comienza con "Ha alcanzado su límite de uso diario para Chat", sin equipo/modelo/calificador compartido, otorga recuperación de cuota; el texto genérico de límite de crédito no lo hace. Solo los fallos de cuota elegibles para la recuperación de PAT ingresan al manejo de enfriamiento de claves. Cuando un fallo de este tipo no tiene tiempo de reinicio, la clave fallida utiliza el tiempo de reutilización predeterminado existente; las clasificaciones de cuotas no recuperables no crean un tiempo de reutilización a través de esta ruta, y no se infiere ningún reinicio del día siguiente. +- **Operadores:** Qoder Global es operado por BRIGHT ZENITH PRIVATE LIMITED bajo el [términos de servicio del producto](https://qoder.com/product-service); Qoder CN by?(?)? con Alibaba Cloud. Verifique `ocx provider test qoder` (o `qoder-cn` ) después de configurar. + + + +### Claude Code CLI (suscripción) + +OpenCodex puede gastar una suscripción de Claude a través del propio arnés de Anthropic en lugar de reproducir una identidad de Claude Code contra el Messages API. El preajuste `claude-cli` ejecuta el oficial Claude Code CLI sin cabeza (`claude -p`, `stream-json`) una vez por turno: + +```json +{ + "providers": { + "claude-cli": { + "adapter": "claude-cli", + "baseUrl": "https://api.anthropic.com" + } + } +} +``` + +- **Prerrequisitos:** `npm install -g @anthropic-ai/claude-code`, luego inicie sesión una vez con `claude` (o `claude setup-token` ). El CLI usa el propio inicio de sesión Claude Code de la máquina (la entrada macOS Keychain, o `~/.claude/.credentials.json` en otros lugares). +- **Ninguna credencial almacenada:** esta fila no tiene clave API, y OpenCodex nunca lee, copia o reenvía un token Claude. El CLI posee el inicio de sesión y factura la cuenta en sí. Un CLI que no está conectado falla el turno con un error de inicio de sesión que nombra el comando, en lugar de un `401` genérico. La clasificación sigue el mismo hecho: el preajuste es una fila de teclas sin llave (`keyOptional`), por lo que no necesita ninguna tecla API y no se ofrece ningún campo de clave para ello. Una tecla API guardada en esta fila por otros medios nunca se entrega al arnés - la facturación de la tecla pertenece al preajuste `anthropic-apikey`. +- **En el panel de control:** el selector de proveedor de Añadir enumera este preajuste bajo **Pagado**, con las filas API, y lo marca con una insignia **Suscripción CLI** en lugar de **Libre** - sin llave aquí significa que el CLI posee la cuenta, no que el tráfico es libre. Seleccionarlo muestra una advertencia en lugar del campo de clave: esta no es una ruta de acceso de clave API, activa el inicio de sesión CLI (`claude -p`) y las facturas de esa suscripción, y nunca se usa una clave ingresada. El espacio de trabajo de los proveedores cuenta y lo filtra como pagado y muestra **Suscripción CLI** como su modo de autenticación. Cualquier proveedor con `"adapter": "claude-cli"` es tratado de la misma manera, incluyendo una fila renombrada o escrita a mano: el panel de control lo enumera como listo sin una clave y nunca solicita una. +- **Un inicio de sesión sirve a todo el proxy:** el arnés lee el inicio de sesión Claude Code del usuario OpenCodex se ejecuta como, por lo que cada solicitud enrutada a través de esta fila, desde cualquier cliente del proxy, gasta esa cuenta Claude. No hay una cuenta por cliente, ni agrupación ni multiplexación; dar a varias personas su propio uso Claude necesita un usuario proxy por inicio de sesión. +- **Medios de entrada:** la fila publica sus modelos como texto-sólo para v1. El CLI acepta un marco de imagen en su entrada de flujo json, pero no se ha mostrado ningún giro sin cabeza para entregar esos bytes al modelo, por lo que se rechaza una imagen enviada directamente a este proveedor (`unsupported_input_modality`) en lugar de caerse silenciosamente y responder ciegamente. Con el sidecar de visión en la ruta de la solicitud, las imágenes se subtitulan en texto antes de llegar a la fila. +- **Aislamiento:** cada turno se ejecuta en un entorno hijo con alcance sin variable heredada `ANTHROPIC_*` (un `claude` ya apuntado a este proxy por lo tanto no puede volver a él), telemetría, retroalimentación y el auto-actualizador desactivado, y `--tools ""`, `--strict-mcp-config` más `--setting-sources ""`. El arnés no carga ningún servidor CLAUDE.md, skill, hook, plugin o MCP desde la máquina y no puede leer, escribir, ejecutar ni navegar. No se mantiene ninguna sesión entre turnos. El oficial CLI se encuentra en `PATH`, o en la ubicación de instalación nativa (`~/.local/bin/claude`) cuando un servicio inicia OpenCodex con un `PATH` más antiguo. +- **Indicación del sistema:** el sistema de la persona que llama y las indicaciones del desarrollador reemplazan el preajuste Claude Code (`--system-prompt-file`), por lo que el turno responde al contrato del cliente en lugar del personaje del arnés. El indicador plegado se organiza en un archivo privado por turno (modo `0600`) y se pasa por ruta, porque los argumentos de proceso son legibles en todo el mundo a través de la lista de procesos; una solicitud que no lleva ni un sistema ni un indicador de desarrollador obtiene solo las instrucciones de repetición de conversación fijas. +- **Almacenamiento en caché de conversación:** cada mensaje se reproduce como un bloque de texto estable separado, con el mensaje actual formateado de manera idéntica a su representación histórica posterior. La larga historia se corta solo en los puntos de control de mensajes completos. Los catálogos de herramientas se serializan de manera determinista. Claude Code controla los puntos de interrupción de caché, por lo que esto hace posible la reutilización de caché rápida sin garantizarlo. +- **Propiedad de la herramienta:** cuando la solicitud lleva herramientas, un catálogo aislado de solo captura MCP expone solo las herramientas seleccionadas del cliente (el mismo puente que CodeBuddy usa). El CLI captura la llamada y el turn termina allí; aprobación, sandboxing, ejecución y el resultado devuelto se queda con Codex, Pi, u otro cliente. Las herramientas integradas y todos los demás servidores MCP permanecen desactivados. +- **Límites de suscripción:** antes de cada lanzamiento OpenCodex pide el punto final de uso de Anthropic, con el propio inicio de sesión del CLI leído en la memoria, si la ventana de 5 horas, semanal o específica del modelo del plan está llena. Un plan agotado es rechazado localmente con HTTP 429 `claude_subscription_cooldown` y un `Retry-After` para el reinicio, en lugar de comenzar un CLI que fallaría. La respuesta se almacena en caché durante un minuto en `claude-usage-admission.json` bajo el OpenCodex home (solo porcentajes, tiempos de reinicio y una clave de cuenta hash). Si el cheque no puede ejecutarse, el turno continúa. +- **Destino:** la fila canónica nombra `https://api.anthropic.com` porque ahí es donde aterriza el tráfico de la suscripción. OpenCodex nunca envía esa solicitud en sí, y anular la URL base falla en cerrarse en lugar de entregar el turno a otro entorno. + +> **Términos:** este preajuste gasta su suscripción Claude a través de Anthropic 's propio CLI. Si conducir ese arnés sin cabeza desde un proxy se ajusta a los términos de su plan es una pregunta entre usted y Anthropic. OpenCodex no convierte el inicio de sesión en una clave API y no reproduce la identidad CLI de HTTP. + + + +### Cuota de crédito A6API + +Un proveedor `openai-chat` personalizado que usa `authMode: "key"` y la URL base canónica `https://api.a6api.com` o `https://api.a6api.com/v1` recibe un medidor de crédito A6API en el panel de control y desde `ocx account refresh `. El nombre del proveedor es arbitrario; la detección utiliza el extremo canónico HTTPS. El medidor convierte las unidades de token A6API en USD utilizando el límite de crédito duro de la cuenta y muestra el porcentaje consumido más el crédito restante. El vencimiento del token no se muestra como un restablecimiento de la cuota porque el vencimiento no implica que el crédito se reponga. + +```json +{ + "providers": { + "my-a6": { + "adapter": "openai-chat", + "authMode": "key", + "baseUrl": "https://api.a6api.com/v1", + "apiKey": "${A6API_API_KEY}" + } + } +} +``` + +Las sondas de cuota envían solo la clave activa al host canónico A6API y rechazan las redirecciones. Los totales de facturación mal formados, negativos o internamente inconsistentes no producen ningún informe en lugar de una barra engañosa. + +> **Restricción de uso de Tencent Cloud Coding Plan:** Tencent documenta esta suscripción solo para herramientas de codificación interactivas. La automatización general API, los backends de aplicaciones personalizados y el uso por lotes no interactivo están prohibidos y pueden hacer que se suspenda la clave del plan. + +> **Rutas de facturación GLM:** `zai` es la suscripción internacional de planes de codificación de Z.AI; `zhipu-bigmodel` es el punto final nacional de pago por uso de Zhipu. Diferentes hosts, diferentes claves, diferente facturación: una clave emitida para uno no se autenticará contra el otro. + + + +### Plan de codificación BigModel sobre Responses + +Seleccione **Zhipu AI - Plan de codificación BigModel ( Responses)** (`zhipu-bigmodel-responses`) para el punto final `openai-responses` `https://open.bigmodel.cn/api/v1`. Esto está separado de `zhipu-bigmodel-coding`, que usa Chat Completions en `/api/coding/paas/v4`. + +El preajuste utiliza un **Lista estática** (`liveModels: false`) tomado del [Documentación del plan de codificación GLM](https://docs.bigmodel.cn/cn/coding-plan/tool/codex.md) publicado: + +| Modelo | Tokens de contexto | Esfuerzo seleccionable ascendente | Esfuerzo predeterminado | Resúmenes de razonamiento | +| --- | ---: | --- | --- | --- | +| `glm-5.3` | 1,048,576 | `low`, `high`, `max` | `max` | Apoyado | +| `glm-5.3-flash` | 1,048,576 | `low`, `high`, `max` | `max` | Apoyado | +| `glm-5-turbo` | 204,800 | Ninguno (lista vacía) | `max` | Apoyado | + +`glm-5.3` y `glm-5-turbo` declaran entrada de solo texto aguas arriba. El catálogo Codex anuncia texto e imagen para ellos porque el sidecar de visión existente opencodex puede describir imágenes para modelos solo de texto; esa ruta requiere un sidecar de visión disponible y habilitado y no reclama soporte de imagen BigModel nativo. + +`glm-5.3-flash` es la excepción: declara la entrada nativa `text` y `image`, porque upstream lo documenta como un modelo multimodal nativo. Por lo tanto, lee imágenes directamente en lugar de ser enrutado a través del desvío del primer sidecar descrito. + +El modelo predeterminado es `glm-5.3`; Responses El contenido de razonamiento se conserva en la repetición. La exportación Codex existente agrega su nivel de compatibilidad `ultra` a GLM-5.3 y omite el campo de esfuerzo predeterminado de Turbo porque Turbo no tiene una escalera seleccionable; los metadatos del proveedor aún registran `max` para ambos modelos. Para Turbo, las solicitudes salientes Responses omiten `reasoning.effort`, incluyendo `max` o `ultra` de la persona que llama, mientras se conservan los resúmenes de razonamiento solicitados. Esto deja la selección de esfuerzo en el valor por defecto ascendente; opencodex no inyecta un alambre seleccionable o `max`. + +El `models.json` del ejemplo es un archivo de catálogo local, no una respuesta documentada de la lista de modelos HTTP, y no el conjunto de modelos que sirve el punto final: las páginas del Plan de codificación indican que cada nivel del plan alcanza GLM-5.3 y GLM-5.3-Flash, y que las llamadas GLM-5-Turbo se cambian automáticamente a Flash, por lo que este punto final ya estaba sirviendo Flash bajo el Turbo id. Este preajuste aún no realiza el descubrimiento de modelos en vivo. Un proveedor personalizado existente con el mismo nombre mantiene su destino y metadatos configurados. El inicio de sesión de clave CLI también omite la sonda indocumentada `/models` e informa la validación como desconocida; la autenticación de clave exitosa se establece mediante una solicitud de inferencia posterior. + + + +### Múltiples claves API + +Los proveedores basados en claves también pueden mantener múltiples claves. La adición de una clave a través de la página de proveedores la almacena en `provider.apiKeyPool`, la hace activa y la refleja en `provider.apiKey` para que el enrutamiento y los adaptadores continúen leyendo el mismo campo que antes. El mismo menú desplegable puede conmutar o eliminar teclas; la gestión API es `/api/providers/keys` y devuelve solo teclas enmascaradas. + + + +### Cambio de cuentas desde la terminal + +Utilice `ocx account list`, `ocx account current` y `ocx account use` para inspeccionar o cambiar los mismos grupos de teclas Codex, OAuth y API sin abrir el tablero de instrumentos. Consulte [CLI referencia](/es/reference/cli/providers-accounts/#ocx-account-subcommand) para ver los comandos, la salida JSON y el comportamiento de la sesión nueva. + + + +#### Nivel de suscripción en los listados de cuentas + +`ocx account list --json` y `GET /api/oauth/accounts` reportan un campo `plan` en cada cuenta OAuth, usando el mismo nombre y ubicación que el proveedor OpenAI / Codex para que un consumidor pueda leer una forma en todos los proveedores. + +El campo siempre está presente. Es `null` cuando se desconoce el nivel, lo cual es deliberado: una clave **ausente** significa que el proxy es anterior a este campo, mientras que `null` significa que esta versión se veía y el proveedor no informó un nivel. Colapsar los dos permitiría a un consumidor asumir silenciosamente un nivel. + +Para Anthropic cuentas (ambos grupos) el valor proviene del perfil de cuenta autenticado que OpenCodex ya lee: el nivel de límite de solicitudes de la organización, informado como etiquetas como `max_20x`, `max_5x` o `pro`. Se registra en el inicio de sesión, importación local Claude Code y actualización de token. Para Google Antigravity el valor es el nivel pagado de `loadCodeAssist` (por ejemplo `g1-pro-tier`), volviendo al nivel actual. Una lectura fallida mantiene la última etiqueta grabada; una lectura que responde sin un nivel de informes `null`. El nivel nunca se deriva de los porcentajes de cuota, ya que estos se normalizan por cuenta: un asiento máximo × 5 al 50% es indistinguible de un asiento máximo × 20 al 50%. + + + +### GPT-5.6 rutas de vista previa + +GPT-5.6 Sol / Terra / Luna se siembran en las listas de reserva del proveedor para que `ocx sync` pueda mantener los modelos visibles incluso cuando los catálogos en vivo se retrasan: + +| Ruta Codex | IDs de modelos de semillas | Codex - contexto visible | +| --- | --- | --- | +| Codex inicio de sesión ( Pool o Direct) | `gpt-5.6-*` | 922,000 | +| OpenAI (clave API) | `openai-apikey/gpt-5.6-*` más `*-pro` | 922.000 (922.000 entradas máximas) | +| OpenRouter | `openrouter/openai/gpt-5.6-sol`, `openrouter/openai/gpt-5.6-terra`, `openrouter/openai/gpt-5.6-luna` | 922,000 | +| Cursor | `cursor/gpt-5.6-sol`, `cursor/gpt-5.6-terra`, `cursor/gpt-5.6-luna` | 1,000,000 | + +Las entradas nativas de GPT-5.6 preservan las escalas de razonamiento aguas arriba ancladas (por ejemplo, Luna tiene `max` pero no `ultra`). Las entradas enrutadas usan sus metadatos de proveedor y mapeos de razonamiento. Las cuatro rutas permanecen abiertas aguas arriba; El descubrimiento en vivo de Cursor filtra adicionalmente su semilla estática a los modelos que puede usar la cuenta iniciada. + +:::note[Pasarelas y proxies de suscripciones] +Se incluye un proveedor cuando opencodex tiene un adaptador de cable correspondiente, **no** basado en si es un producto "agente". Los identificadores de adaptador actuales son `openai-chat`, `openai-responses`, `anthropic`, `google` +(modos AI Studio, Vertex y Antigravity / Cloud Code Assist), `azure` / `azure-openai`, `kiro`, y +`cursor`. Un propietario API sin una de estas implementaciones, como Amazon Bedrock nativo, No se apoya directamente. + +La configuración del proveedor selecciona el adaptador; la selección de transporte aguas arriba es independiente. El tráfico Responses elegible puede usar WSS con [Enrutamiento proxy explícito](/es/reference/proxy-formats/#json-and-sse-output). Los ajustes del proxy WebSocket no válidos o no compatibles vuelven a HTTP / SSE, que utiliza el [servidor configurado outbound fetch](/es/reference/configuration/server/). Un servidor proxy SOCKS5 de `config.proxy` o un SOCKS5 `ALL_PROXY` heredado utiliza el túnel incorporado cuando `NO_PROXY` no exime al objetivo. Las variables proxy HTTP (S) específicas del esquema conservan su manejo nativo separado; no SOCKS `ALL_PROXY` no es una ruta de extracción HTTP nativa. + +**GitHub Copilot** es un proveedor de OAuth (`ocx login github-copilot`) que intercambia un inicio de sesión de flujo de dispositivos GitHub por un token Copilot API de corta duración, no una clave API pegada. **Dúo GitLab** sigue siendo una puerta de enlace clave/token de suscripción en su punto final compatible con OpenAI. **Puerta de enlace de Cloudflare AI** necesita su cuenta + identificadores de puerta de enlace rellenados en la URL. + +Copilot automáticamente usa Auto cuando cada fila válida en un catálogo de cuenta no vacía informa explícitamente que la selección manual no está disponible. Los permisos faltantes o mal formados retienen rutas con nombre; el selector elimina solo filas explícitamente denegadas. La detección automática solo suministra `github-copilot/auto`, y GitHub selecciona el modelo real por solicitud. Esto no cambia los permisos de suscripción. Las listas de permisos de modelos ordinarios, el estado pendiente/deshabilitado y la política de nuevo modelo también se aplican a la visibilidad automática. Si las selecciones guardadas o la directiva ocultan Auto, seleccione o habilite la fila Auto antes de usarla. Las preferencias manuales existentes permanecen guardadas. Un modelo llamado `auto` solo no anula la evidencia de la cuenta. + +Auto sigue el protocolo de sesión e intención en el público [VS Copilot Aplicación de chat](https://github.com/microsoft/vscode-copilot-chat/blob/7b70532a4cbdfa61c2b30fe4ccffda3d89336a4d/src/platform/endpoint/node/automodeService.ts). Se trata de una integración experimental de clientes, no de un contrato de terceros documentado API; GitHub puede cambiar los permisos del protocolo o de la cuenta. Auto utiliza el punto final anunciado del modelo seleccionado para cada solicitud. El enrutamiento intencional envía solo el último texto de usuario, limitado localmente a 32,768 unidades de código UTF-16; la inferencia real mantiene la entrada completa. La negociación tiene presupuestos defensivos locales de 512 entradas de catálogo / grupo / candidato, 1 MiB por respuesta exitosa y ocho segundos por llamada, incluyendo ritmo y lecturas de cuerpo. Estos son OpenCodex salvaguardas, no documentado GitHub límites; catálogos de gran tamaño, negociación lenta o un extracto de intención truncada pueden afectar la compatibilidad. + +Para las selecciones con nombre, Copilot presenta un catálogo de cables mixtos: los siguientes modelos (`gpt-5.3-codex`, `gpt-5.4`, +`gpt-5.4-mini`, `gpt-5.5`, `gpt-5.6-luna`, `gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-6-astra`, `grok-4.5`, `grok-4.6`, `mai-code-1.1-flash`, `mai-code-1-flash-picker`) Rechazar +`/chat/completions` para el tráfico de agentes, por lo que opencodex enruta esos modelos Responses API por defecto incorporado, mientras que cualquier otro modelo Copilot permanece en el chat Finalizaciones. La precedencia es: pin de alambre duro → su explícito +[`modelAdapters`](/es/reference/configuration/providers/) entrada Registro → predeterminado → adaptador de todo el proveedor. Para optar por un modelo sin un valor predeterminado incorporado (por ejemplo +`gpt-5.4-nano`) en Responses, conjunto `"modelAdapters": { "gpt-5.4-nano": "openai-responses" }`. + +Cursor se rastrea por separado como un adaptador experimental. `adapter: "cursor"` aparece en `ocx init` +y el selector Add Provider del panel como una entrada de configuración local experimental con Cursor's metadatos estáticos del catálogo de modelos de reserva. Cursor acceso token está configurado, opencodex usos Cursor's vivo HTTP/2 transporte. Conjunto `upstreamHttpVersion: "http1.1"` cuando un proxy requiere Cursor de HTTP/1.1 ruta de compatibilidad; la configuración cubre tanto la inferencia como el descubrimiento del modelo en vivo y se expone en +**Proveedores → Cursor → Configuración → Cursor transporte**. Su semilla de reserva incluye `gpt-5.6-sol` / `terra` / `luna` (1M contexto), filas regulares/rápidas para Grok 4.5, 4.6 y 4.7 (500K), y `kimi-k3` (262K); el descubrimiento en vivo decide cuál permanecer visible para la cuenta. Grok 4.6 y 4.7 exponer `low` / `medium` / `high` / `xhigh` En ambas formas, mientras que 4.5 se detiene en `high`. Las solicitudes rápidas Grok 4.5 y 4.6 envían el modelo base correspondiente con una configuración separada +`effort` y `fast=true` `requested_model` parámetros; sus aplanados +`cursor-grok-{version}-{effort}-fast` ids son solo identidades de descubrimiento y selector. Grok 4.7 aparece sin el `cursor-` Prefijo y envía `grok-4.7-{effort}-fast` directamente. Cursor sirve Kimi K3 solo como ids de alambre con sufijo de esfuerzo, así que +`cursor/kimi-k3` expone a `low` / `high` / `max` Escalera y valores predeterminados `max`, igualando el modelo documentado API por defecto. Cursor lectura/escritura/eliminación nativa impulsada por servidor/ls/grep/shell/ejecución de fetch está deshabilitado de forma predeterminada porque omite la aprobación de Codex y la ruta sandbox; establecer +`unsafeAllowNativeLocalExec: true` en el `providers.cursor` objeto en `~/.opencodex/config.json` +solo para experimentos locales de confianza (o a través de **Proveedores → Cursor → Editar JSON** en el panel). Solicitudes de shell nativo en primer plano (`shellArgs` y `shellStreamArgs`) permanecen no disponibles en Windows, macOS y Linux incluso con esta opción: opencodex los rechaza antes de comenzar un proceso hasta que tenga un propietario descendiente respaldado por el kernel. Utilice la herramienta de shell del cliente en su lugar. Sin comando se recopila la salida; los shells de fondo y los ejecutores MCP/desktop configurados por separado no cambian. Ver la [Referencia de configuración](/es/reference/configuration/providers/#cursor-provider-adapter-cursor) +Para un ejemplo completo. MCP, grabación de pantalla y uso del ordenador están disponibles como ganchos ejecutor; sin un configurado el ejecutor local, opencodex devuelve los resultados sin ejecutor escritos en lugar del bloqueo de directivas la solicitud. Cursor OAuth y el descubrimiento de modelos en vivo están habilitados para este adaptador experimental; Cursor todavía no se muestra en las listas de inicio de sesión clave. +::: + + + +### Ollama Cloud + +Ollama Cloud es un servidor (no local) Ollama. Configure en `https://ollama.com/v1` con una clave de [ollama.com/settings/keys](https://ollama.com/settings/keys). opencodex lo alcanza sobre el propio Ollama REST API ( `POST /api/chat` ) en lugar de la superficie compatible con OpenAI, y descubre la lista de modelos en vivo del proveedor, por lo que los nuevos modelos Ollama Cloud aparecen sin un cambio de configuración. opencodex clasifica su línea de nubes por capacidad de visión, por lo que el [visión sidecar](/es/guides/sidecars/) solo se activa para modelos de solo texto. Los modelos solo de texto (p. `glm-5.2`, `deepseek-v4-flash`, `gpt-oss`, `qwen3-coder`, `minimax-m2.x`, `nemotron-3-*` ) se enumeran en `noVisionModels`; modelos nativos de la visión (por ejemplo. `kimi-k2.6`, `minimax-m3`, `gemma4`, `qwen3.5`, `gemini-3-flash-preview`). El emparejamiento es tolerante a las etiquetas `:size` de Ollama, por lo que `gpt-oss` cubre `gpt-oss:120b` y `gpt-oss:20b`. + +Ollama actualmente documenta salidas estructuradas como no compatibles en Ollama Cloud. Para canónica `ollama-cloud`, opencodex por lo tanto rechaza las solicitudes de salida estructuradas (`text.format`) con un error claro en lugar de devolver silenciosamente prosa sin restricciones; local y costumbre `ollama-native` puntos finales mantener Ollama 's nativo `format` comportamiento. + + + +## 4. Proveedores locales + +Punto opencodex en un servidor compatible local OpenAI - por lo general con una llave en blanco: + +| Proveedor | URL base | +| --- | --- | +| Ollama (local) | `http://localhost:11434/v1` | +| vLLM | `http://localhost:8000/v1` | +| LM Studio | `http://localhost:1234/v1` | + + + +## Cualquier punto final compatible con OpenAI + +Si un proveedor habla Chat Completions, el adaptador `openai-chat` lo maneja: elija **Personalizado** en el tablero de instrumentos o `custom` en `ocx init` e ingrese la URL base. Ver el [Referencia de configuración](/es/reference/configuration/) para cada campo de proveedor (`headers`, `noReasoningModels`, `noVisionModels`, `models`,...). + + + +## Revisor de aprobación por proveedor + +Codex le pide a un segundo modelo que revise las solicitudes de aprobación, y toma ese revisor de `auto_review_model_override` en la fila de catálogo del modelo de turno actual. La raíz `auto_review_model` en `$CODEX_HOME/config.toml` es el retroceso de Codex. El panel de control global **Anulación de revisión automática** en la configuración del modelo aplica un revisor a todas las filas del catálogo que no tienen un revisor con alcance de proveedor. Almacena `autoReviewOverride` en `~/.opencodex/config.json`; la configuración debe estar habilitada y nombrar un modelo. Una configuración habilitada sin modelo permanece sin aplicar y deja el retroceso Codex en efecto. Una actualización de catálogo es un estado separado: después de guardarlo puede permanecer pendiente, y la página Modelos lo informa para que pueda volver a intentarlo con `ocx sync`. Desde el CLI, lea la configuración con `ocx models auto-review status` o cámbiela con `ocx models auto-review set [--enabled ]`; use `-` para borrar el modelo. La salida CLI recomienda `ocx sync` cuando se puede volver a intentar una actualización. Si falla una actualización, la configuración permanece guardada y el comando sale 1. Resolver el fallo antes de la sincronización. Para dar a un proveedor enrutado su propio revisor, generalmente más barato, configure el selector en esa fila de proveedores en `~/.opencodex/config.json`: + +```json +{ + "providers": { + "blsc": { + "autoReviewModel": "opencode-go/deepseek-v4-flash", + "autoReviewModelOverrides": { "kimi-k3": "gpt-5.6-terra" } + } + } +} +``` + +`autoReviewModel` cubre todas las filas enrutadas del proveedor. `autoReviewModelOverrides` apunta a un único id de modelo ascendente y gana sobre él. Un valor es un id de modelo desnudo de ese mismo proveedor o un slug de catálogo público como `opencode-go/deepseek-v4-flash`, y un sello de proveedor gana sobre el selector de raíz en sus propias filas mientras que el selector de raíz mantiene la reserva en otro lugar. + +Un valor desnudo se resuelve contra las propias filas del proveedor primero y luego contra una fila de catálogo desnuda, que es cómo se nombra un modelo nativo como `gpt-5.6-terra`; un valor que no coincide con ninguno se deja sin resolver, y un valor desnudo que aterriza fuera del proveedor imprime una nota que nombra la fila que suministra el revisor. Dar la identificador completa evita la pregunta por completo cuando el revisor es el modelo enrutado de otro proveedor. + +Los selectores se resuelven contra el catálogo final en la siguiente sincronización, cada uno por su cuenta, y cada uno falla cerrado por sí mismo: un `autoReviewModel` no resuelto imprime un diagnóstico y no estampa filas de todo el proveedor, una entrada `autoReviewModelOverrides` no resuelta imprime un diagnóstico y no estampa una anulación por modelo, dejando un objetivo válido de todo el proveedor como reserva. Lo que sea que resuelva se sigue aplicando. Las filas sin un sello de proveedor mantienen el selector raíz o el comportamiento ascendente cuando no se establece. La eliminación del selector raíz deja solos los sellos del proveedor y la eliminación de un selector de proveedor solo borra los sellos de ese proveedor. + +Los campos de proveedor están disponibles a través de la configuración, `PATCH /api/providers?name=`, y el editor de proveedor raw JSON del panel de control; los controles de formulario de proveedor dedicado no están presentes. La anulación global está disponible en la configuración del modelo. El proveedor canónico `openai` rechaza los campos de revisor del proveedor. Las reglas de campo por campo viven en el [referencia de configuración del proveedor](/es/reference/configuration/providers/#auto-review-approval-model-selection). + + + +## Límites de solicitudes en la descripción general de los proveedores + +La sección **Límites de solicitudes** de la descripción general de proveedores muestra las barras de utilización en vivo actualizadas desde el punto final de uso/facturación de cada proveedor cuando existe uno. Las barras muestran la cantidad de una ventana (5 horas, semanal, mensual o específica del proveedor) que ya se consume. + +Proveedores con una consulta activa: OpenAI/Codex, Anthropic, xAI, Cursor, Kimi, Google Antigravity, OpenCode Go, OpenRouter, DeepSeek, ClinePass, Z.AI, MiniMax, Moonshot, Venice, Synthetic, DeepInfra, Neuralwatt, Command Code y proveedores personalizados basados en a6api o Abliteration. + +**Créditos de Abliteration.** Un proveedor de cualquier nombre cuyo `baseUrl` sea `https://api.abliteration.ai` o `https://api.abliteration.ai/v1` consulta `GET https://api.abliteration.ai/v1/credits` con la clave activa como token bearer, sin seguir redirecciones. El saldo restante en USD es `total_credits` menos `total_usage`; la barra muestra el gasto consumido. Una cuenta sin créditos no muestra barra. Una clave rechazada elimina la fila; `503 credit_balance_unavailable`, 408 y 429 conservan la última lectura. + +**Cuota de OpenCode Go.** El preajuste canónico `opencode-go` lee `GET https://opencode.ai/zen/go/v1/usage` con la clave configurada como token de portador y no sigue redirecciones. Los valores de la respuesta rodando, semanal y mensual `percent` ya están consumidos: rodando mapas a la barra de 5 horas, mientras que semanal y mensualmente mantienen sus barras coincidentes. OpenCodex no reconstruye los límites de dólares de los registros de uso local, y a un proveedor que usa un `baseUrl` no canónico nunca se le envía la clave para esta sonda. + +**Cuota del plan de codificación Z.AI GLM.** Los preajustes `zai`, `glm`, `glm-cn` y `zhipu-bigmodel-coding` leen `GET /api/monitor/usage/quota/limit` y no siguen redireccionamientos. La sonda corre contra la región que el proveedor señala en: `api.z.ai` (desnudo o `/api/coding/paas/v4`) o `open.bigmodel.cn` (desnudo, `/api/coding/paas/v4` o el punto final OpenAI Responses `/api/v1`). + +La autenticación difiere según la región: `api.z.ai` toma la clave como Bearer token, mientras +`open.bigmodel.cn` espera la clave directamente en `Authorization` Sin prefijos y rechaza un encabezado Bearer. La respuesta es `limits` Rellene las filas de la barra de utilización: +`TOKENS_LIMIT` / `CREDIT_LIMIT` filas con `unit` 3 / `number` 5 Llene la barra de 5 horas y +`unit` 6 / `number` 1 El bar semanal. + +`TIME_LIMIT` filas son **no** cuota de modelo y se ignoran. Son la asignación de llamada mensual compartida MCP para Web Search, Web Reader y Zread, por lo que tratarlos como una ventana de modelo permitiría que un presupuesto de búsqueda web gastado se lea como capacidad de modelo agotada en la clasificación de la cuenta consciente de cuotas. Por lo tanto, un plan que reporta solo `TIME_LIMIT` filas no muestra barras de cuotas en lugar de una fabricada, y las ventanas del plan no informan que permanezca ausente en lugar de mostrarse como 0%. + +Nunca se envía la clave para esta sonda a un proveedor que utilice un `baseUrl` no canónico. + + + +### Diagnosticar una actualización de cuota Antigravity + +La vista de cuota de cuenta y `ocx account list google-antigravity --quota --refresh` distinguen entre denegación de acceso, limitación de velocidad, destinos bloqueados o redirecciones, DNS/conexión/tiempos de espera y datos de cuota inutilizables. Las últimas barras conocidas permanecen visibles con su tiempo de observación cuando falla una actualización. La reautenticación retira los diagnósticos de la credencial anterior; una actualización exitosa borra el fallo. + +Un resultado denegado por acceso no prueba por sí mismo un inicio de sesión vencido o un plan no elegible. Un destino bloqueado es una decisión de política de red, no una prueba de un defecto de IP falsa. Los destinos de la cuota Canonical Google retienen las restricciones de verificación y redirección/dirección privada de TLS. El comportamiento de TUN autenticado debe comprobarse en el entorno afectado; los accesorios de transporte inyectados solos no establecen ese resultado de campo. + + + +## Grandes imágenes en línea en proveedores de chat + +Las solicitudes de chat compatibles con la traducción OpenAI reducen las imágenes en línea cuando sus datos base64 combinados superan los 3,5 MiB. Las imágenes más antiguas pierden detalle primero. Este es un presupuesto de imagen de mejor esfuerzo, por lo que el texto grande, los esquemas o las imágenes que no se pueden procesar aún pueden exceder un límite de solicitud ascendente. Las URL de imágenes remotas no se descargan y las imágenes que no se pueden reducir permanecen adjuntas. El passthrough de Native Chat mantiene sus bytes de imagen originales. diff --git a/docs-site/src/content/docs/es/guides/remote-hub.md b/docs-site/src/content/docs/es/guides/remote-hub.md new file mode 100644 index 00000000000..76ec0176f6e --- /dev/null +++ b/docs-site/src/content/docs/es/guides/remote-hub.md @@ -0,0 +1,529 @@ +--- +title: "Despliegue de Remote Hub" +description: "Ejecute un concentrador opencodex de un puerto en Linux, macOS o Docker con un loopback acompañante, un token de datos autoaprovisionado, ocx hub invite, una entrada de administración solo loopback, Tailscale Serve y OAuth sin cabeza." +--- + +Para enlaces de máquinas SSH, véase [Enlace remoto](/es/guides/remote-link/). + +Un concentrador opencodex mantiene las credenciales del proveedor y el estado de uso en un host mientras los clientes autenticados usan su plano de datos de forma remota. El plano de gestión orientado al navegador es independiente: un oyente opcional vincula solo `127.0.0.1`, sirve el tablero de instrumentos y `/api/*`, y está destinado a sentarse detrás de Tailscale Serve u otro frontend HTTPS propiedad del operador. + +El plano de datos es **Un puerto**. Las máquinas remotas marcan `hostname:port` con su propia clave por cliente; los propios procesos del concentrador marcan `127.0.0.1:` sin credenciales, a través del loopback compañero de escucha. Comience desde [La receta abajo](#linux-systemd-or-macos-launchd), luego entregue a una segunda máquina un comando listo para usar con [`ocx hub invite`](#inviting-another-machine). + +La entrada de gestión nunca sirve `/v1/*`, `/healthz` o `/readyz`. Cuando se habilita explícitamente, el espacio de trabajo remoto admite solo su agente WebSocket autenticado por portador emparejado y su intercambio de emparejamiento único; véase [Espacio de trabajo remoto](/es/guides/remote-workspace/). No publique su puerto directamente, no agregue una regla de firewall en la nube para él y no use Tailscale Funnel. Funnel es una superficie de Internet pública y está fuera de este modelo de despliegue. + +Con la entrada de administración habilitada, el comando del panel local abre `http://127.0.0.1:` para que la dirección coincida con el oyente solo IPv4 sin resolver `localhost`. + +Las configuraciones del cliente exportadas o aplicadas a través de ese panel de control siguen apuntando al oyente de inferencia, no al puerto de administración. Los clientes locales usan el puerto complementario de bucle de retorno configurado (o el puerto del oyente público real cuando el compañero no tiene un puerto explícito). + + + +## Límites de confianza y consentimiento + +- El proveedor y las credenciales OAuth permanecen en el concentrador. Nunca los copie en un cliente, capa de imagen, definición de servicio, paquete de soporte, captura de pantalla o línea de comandos. +- El token de admisión de datos se entrega a través del archivo `service-api-token` o `OCX_API_TOKEN_FILE`. No es una credencial de gestión. +- El `allowedModels` de un cliente configurado debe incluir tanto el ejecutor como cualquier modelo de Asesor facturado por separado utilizado por el Anthropic Messages nativo administrado. Se aceptan los ID de modelo desnudo y los `provider/model` nombres configurados del concentrador. Un destino de Asesor no permitido o sin nombre devuelve HTTP 403 antes del envío del proveedor; las claves solo de proveedor y sin restricciones conservan su alcance existente. +- GitHub Copilot Auto vuelve a comprobar el modelo concreto seleccionado durante la negociación y la renovación. Un modelo fuera del alcance permitido del cliente finaliza la solicitud con `model_not_allowed_for_key` (HTTP 403 antes de la transmisión, o un error de terminal en un flujo ya iniciado). La rotación de credenciales o un objetivo alternativo no pueden anular ese rechazo. +- Un token de administrador de administración en bruto puede realizar una administración ordinaria, pero no puede acuñar una sesión de navegador ni autorizar acciones con consentimiento, como protagonizar el repositorio. Esas acciones requieren un `gui-session` emitido por el servidor, un origen de navegador coincidente y un token CSRF. +- `Tailscale-User-Login` se confía solo en la entrada de administración por separado. Se ignora el mismo encabezado en el oyente público. `remoteGui.allowedTailscaleUsers` controla la emisión de la sesión; no crea un nuevo principal de propósito general. + + + +## Roles y flujo directo de datos + +`standalone` mantiene los datos y la administración en una sola máquina. Un `hub` posee las credenciales del proveedor, el catálogo y los registros de uso. Un `client` almacena solo sus metadatos de conexión y una clave de datos por cliente. Codex y Claude el tráfico va directamente desde el cliente al centro de escucha de datos; no se tuneliza a través del tablero de instrumentos o el relé de gestión de loopback. + +Conéctese con exactamente una fuente de autoridad transitoria. La autoridad se lee desde stdin y nunca se escribe en config o en el archivo token: + +```bash +ocx connect https://hub-name.tailnet-name.ts.net --pairing-code-stdin +ocx connect status +ocx sync +``` + +Los diagnósticos de preparación legibles por humanos muestran caracteres de control en valores de catálogo como escapes hexadecimales visibles, tanto cuando se conecta por primera vez como cuando `ocx sync` rechaza un catálogo de concentrador actualizado. El estado estructurado JSON conserva el valor de diagnóstico original. + +No tienes que armar esa línea a mano. `ocx hub invite`, se ejecuta en el concentrador, acuña el código e imprime el comando exacto, incluidos ambos orígenes, para la máquina que se está uniendo. Véase [Invitar a otra máquina](#inviting-another-machine). + +El concentrador emite automáticamente una clave por cliente. El cliente lo escribe en el archivo `service-api-token` existente solo para el propietario, nunca en `config.json`. Mientras está conectado, el uso proviene del almacén de uso del concentrador filtrado al establo `apiKeyId` de ese cliente. Después de la desconexión, el uso proviene de la tienda local. OpenCodex no refleja el uso entre las dos tiendas. `ocx service uninstall` elimina el servicio local pero conserva una clave existente cuando el cliente está conectado, sus metadatos de conexión no son válidos o no coinciden, o un marcador de conexión pendiente coincide con la clave actual. Un marcador válido para una clave anterior no retiene una clave de servicio no relacionada. Si un marcador no es seguro, está mal formado o es ilegible, no se puede verificar la limpieza del token; el comando advierte en lugar de afirmar que se mantuvo la clave. Utilice `ocx disconnect` para eliminar la clave local y el estado de un cliente conectado. + +Si un cliente guardó una URL de concentrador remota `http://` antes de la regla de transporte seguro, sus operaciones de concentrador ahora devuelven `insecure_http_refused`. Ejecute el `ocx disconnect` localmente, luego vuelva a conectar al Hub con el `https://` (o use el bucle de retroceso HTTP cuando ambos lados estén en la misma máquina). + +Rotar un cliente conectado con una nueva autoridad transitoria: + +```bash +ocx connect rotate --pairing-code-stdin +# or, only over HTTPS: +ocx connect rotate --admin-token-stdin +``` + +La rotación mantiene las claves de datos antiguas y nuevas válidas durante un máximo de diez minutos bajo el mismo `apiKeyId`. El cliente realiza una copia de seguridad del token antiguo como `service-api-token.prev`, instala atómicamente y sondea la nueva clave, luego confirma. Si una respuesta de confirmación es incierta, vuelva a ejecutar el comando rotar con autoridad transitoria; la recuperación prueba ambos archivos antes de confirmar o restaurar. Nunca elimine ninguno de los archivos cuando se informe de recuperación de que ambos candidatos fueron rechazados. + +`ocx disconnect` es local y funciona mientras el concentrador está fuera de línea. Restaura el estado del cliente local y no revoca la clave de concentrador. Después de desconectar, revoque esa clave de **Conecte las llaves → API** en el concentrador. `ocx connect revoke --admin-token-stdin` solo está disponible mientras está conectado y utiliza el persistente `apiKeyId`; no acepta la anulación de id. La sesión de cierre de sesión/caducidad del navegador está separada de la rotación, revocación y desconexión de la clave de datos. + + + +### Lo que muestra un cliente conectado + +`ocx connect` y `ocx connect status` comprueban la disponibilidad del catálogo contra el primer entorno de ejecución local válido de Codex en orden de selección. Los candidatos preferidos fallidos pueden retroceder, pero las alternativas de menor prioridad no se prueban después de que se selecciona un entorno de ejecución válido. Esta comprobación deja la selección de entorno de ejecución guardada sin cambios. General `ocx status` todavía descubre alternativas para el diagnóstico en entorno de ejecución. + +Un cliente no almacena credenciales de proveedor y ningún catálogo propio, por lo que su tienda de configuración y credenciales locales están vacías por diseño, y leerlas como la verdad produce una respuesta segura y errónea sobre lo que el concentrador puede servir. En un cliente conectado `ocx status` por lo tanto conduce con `State from hub ` y fuentes las líneas de OAuth - inicios de sesión, proveedores y modelos delegables desde el concentrador sobre el plano de datos, etiquetando las líneas que realmente describen esta máquina `(local)`: el proxy, el servicio, el binario Codex y la shim, y los puertos locales. `ocx status --json` lleva la misma respuesta que `runtimeRole` más un bloque `remoteHub` cuyo `stateSource` es `hub`, `cache` o `unavailable`, nunca el propio estado del cliente. Un concentrador más antiguo que no sirve `/v1/hub-state` informa `unavailable` con una instrucción para actualizar el concentrador en lugar de volver silenciosamente al estado de inicio de sesión local, y `ocx config show` en un cliente imprime una nota `_remoteHub` que indica las credenciales y la disponibilidad del modelo en vivo en el concentrador. La lectura de concentrador utiliza solo la clave de datos por cliente; ningún token de administrador y ningún secreto de proveedor llegan a un cliente. + +`ocx status` realiza una solicitud de estado de concentrador en vivo solo cuando la conexión guardada aún coincide con la instantánea de estado y el archivo de token de datos coincide con esa conexión. Si falla la comprobación, se salta la solicitud y muestra el estado del concentrador en caché coincidente, o `unavailable` si no existe caché coincidente. + + + +## Lanzamiento de Linux systemd o macOS + +Vincule el oyente de datos a la dirección de Tailscale del concentrador, habilite el compañero de bucle de retorno para que los propios procesos del concentrador lleguen a ese mismo puerto sin una credencial y publique la administración por separado. Los valores siguientes son ejemplos: + +:::danger[Usa un servidor dedicado para un solo usuario] +El compañero de loopback no está autenticado: cada proceso y usuario del sistema operativo en esta máquina puede usar el credenciales del proveedor del concentrador y la cuota de cuenta, y puede agotar la capacidad de giro compartida que clientes remotos autenticados dependen de. No lo habilite en un host compartido o multi-tenant. Si el host es compartido, deja el `unauthenticatedLoopbackListener` configuración deshabilitada y no ejecute el local del concentrador integraciones. + +Vinculación a `127.0.0.1` significa que el kernel rechaza conexiones remotas, pero no detiene un navegador: una página que visita puede hacer que su navegador se conecte a `127.0.0.1`. Por lo tanto, el oyente misma `Host` y `Origin` como un enlace de bucle de retorno ordinario. +::: + +```bash +ocx config set runtimeRole hub +ocx config set hostname 100.64.0.10 +ocx config set corsAllowOrigins '["http://localhost:10100"]' + +# A fresh standalone config has no `hub` or `remoteGui` object, and `ocx config set` does not +# create a missing parent: a nested set fails with `config parent path not found: hub`. Setting +# `runtimeRole` does not create it either. Create each object first, then set its fields. +ocx config set hub '{}' +ocx config set remoteGui '{}' +ocx config set hub.managementPublicOrigin '"https://hub-name.tailnet-name.ts.net"' +ocx config set hub.dataPublicOrigin '"https://hub-name.tailnet-name.ts.net:8443"' +ocx config set hub.managementIngress '{"enabled":true,"port":10101}' +ocx config set remoteGui.allowedTailscaleUsers '["operator@example.com"]' + +# One port. Remote machines dial 100.64.0.10:10100 with their own key; the hub's own local +# processes dial 127.0.0.1:10100 with no credential, on that same port. +ocx config set unauthenticatedLoopbackListener '{"enabled":true}' + +# No token to export: install provisions the hub's own data-plane token. See below. +ocx service install +ocx service status +ocx status # the "Hub:" block summarizes every line above +``` + +En una configuración genuinamente vacía, puede establecer cada objeto en una llamada en su lugar: + +```bash +ocx config set hub '{"managementPublicOrigin":"https://hub-name.tailnet-name.ts.net","dataPublicOrigin":"https://hub-name.tailnet-name.ts.net:8443","managementIngress":{"enabled":true,"port":10101}}' +ocx config set remoteGui '{"allowedTailscaleUsers":["operator@example.com"]}' +``` + +Utilice esa forma solo cuando el objeto no existe todavía. Un conjunto de objetos enteros **sustituye** el objeto en lugar de fusionarse en él, por lo que ejecutar la línea de arriba contra una configuración que ya tenía `hub.managementIngress` silenciosamente deja caer la entrada. Cuando esté adaptando una configuración existente, establezca un campo a la vez: el padre ya está allí, por lo que la forma anidada funciona y no toca nada más. + +Dos detalles que deciden si se acepta una línea. El valor se analiza primero como JSON y vuelve a la cadena sin procesar, por lo que una URL se escribe como `'"https://…"'`: objetos, matrices, booleanos y números deben ser válidos JSON. Y `hub` y `remoteGui` son estrictos, por lo que una clave mal escrita se rechaza en el momento de la escritura como `schema_invalid: hub.` en lugar de convertirse en una configuración que nunca tiene efecto. `managementPublicOrigin` y `dataPublicOrigin` deben ser cada uno un origen desnudo sin ruta, consulta o fragmento. + + + +### Aprovisionamiento automático del token de datos + +No hace falta ejecutar `export OPENCODEX_API_AUTH_TOKEN=…` antes de `ocx service install`. Cuando el servicio escucha fuera de loopback, el instalador resuelve el token de admisión de datos con esta precedencia y lo guarda en `service-api-token`, accesible solo por su propietario y con modo `0600`: + +1. **`OPENCODEX_API_AUTH_TOKEN`**, si está exportado en la terminal que ejecuta la instalación. Así se conserva el valor elegido por el operador. +2. **El archivo existente `service-api-token`.** Reutilizarlo hace que `ocx service install`, `ocx service repair` y los reinicios sean idempotentes: generar otro valor invalidaría las claves por cliente ya intercambiadas con el anterior. El archivo se vuelve a comprobar antes de reutilizarlo; no se confía en él sin validarlo. Véase la comprobación de colisiones con el token de administración más abajo. +3. **Un token nuevo de 32 bytes aleatorios codificados en hexadecimal.** Esta opción elimina la necesidad de crear el token manualmente. + +El comando imprime la **ruta**, nunca el valor. Tanto el plist de launchd como la unidad de usuario de systemd leen ese archivo protegido al iniciar el proceso; ninguno contiene el token literal. No pegues su valor en `ocx config show`, en la salida de la unidad o del plist, en capturas ni en paquetes de soporte. `ocx start` en primer plano también lee ese archivo: puede escuchar fuera de loopback sin que exportes el token. + +Se rechaza cualquier token de datos que **coincida con el de administración**, tanto en la variable como en el archivo. El mensaje indica cómo corregir cada origen. Si la colisión está en `OPENCODEX_API_AUTH_TOKEN`, ejecuta `unset OPENCODEX_API_AUTH_TOKEN` y vuelve a iniciar. Si está en el archivo reutilizado `service-api-token`, elimina ese archivo y después ejecuta `ocx service repair`; quitar una variable no corrige el archivo. Ambas comprobaciones se ejecutan antes de omitir los requisitos de admisión por tratarse de loopback, de modo que también protegen una instalación local. El wrapper de arranque exporta el archivo como `OPENCODEX_API_AUTH_TOKEN` independientemente del hostname; una colisión impediría iniciar la API de administración. + +Los dos planos usan credenciales diferentes. El token de datos admite llamadas a `/v1/*` y no permite administrar el proxy. Como el servicio aprovisiona su propio token, no hace falta exportar ninguno de los dos. Una vez que existe el archivo, `ocx service repair` no vuelve a exigir la variable de entorno. + +`ocx status` muestra el estado del token sin revelar su valor: `present (file)`, `unsafe (file)` si los permisos no son exclusivos del propietario, `admin-collision (file)` si coincide con el token de administración, o `missing`. En caso de colisión también explica la consecuencia y la corrección. Este estado describe siempre el **archivo**, porque el wrapper sobrescribe el entorno antes de ejecutar el proceso. Una línea aparte indica si la terminal tiene `OPENCODEX_API_AUTH_TOKEN` establecido, que es el valor que usaría un `ocx start` en primer plano desde esa terminal. + + + +### Un puerto, y la alternativa porteada + +`unauthenticatedLoopbackListener: {"enabled": true}` con **no** `port` es la forma *compañero*: un segundo zócalo en `127.0.0.1:` - el mismo número de puerto que el oyente público utiliza en la dirección tailnet. Esa es la dirección que ya escribe cada integración local, por lo que no se debe enseñar nada en el concentrador a un nuevo puerto, y un puerto mantiene toda la superficie de datos remota. + +El formulario complementario se acepta solo cuando `hostname` es una dirección específica no loopback, no comodín. En `127.0.0.1`, `localhost`, `0.0.0.0` o `::` el oyente público ya tiene esa dirección de bucle, por lo que opencodex rechaza el par en el momento de la escritura y nuevamente en el inicio, nombrando la colisión, en lugar de dejar que el segundo enlace falle. En esos enlaces no necesitas al oyente en absoluto: un enlace de bucle de retorno ya admite llamadas locales. + +La forma más antigua *ported* todavía funciona y es la alternativa cuando desea que las dos superficies en puertos separados: + +```bash +ocx config set unauthenticatedLoopbackListener '{"enabled":true,"port":10104}' +``` + +La forma portada es la misma superficie no autenticada: la advertencia de host dedicado anterior también se aplica a este comando. + +Con un conjunto `port`, las integraciones locales siguen al oyente y escriben `http://127.0.0.1:10104` en su lugar. El puerto debe diferir del puerto proxy y nunca está asignado al sistema operativo: un puerto efímero cambiaría en los reinicios mientras que los servidores de aplicaciones que ya se ejecutan conservarían el anterior `base_url`. + +**Reinicie el proxy después de cambiar este campo.** Los sockets se unen una vez al iniciarse y los archivos de cliente local se escriben a partir del valor resuelto, de modo que un concentrador en ejecución mantiene su respuesta antigua. En un concentrador portado que es la diferencia entre `ocx claude` llegar al oyente y obtener un `404` de él. En un servicio de fondo el verbo es `ocx service restart`, que siempre se reinicia - ver [macOS operaciones de servicio](#macos-service-operations). `ocx restart` es un verbo diferente: rebota el proceso proxy que usted mismo comenzó, no el servicio que supervisa el gerente. + + + +### Los propios clientes locales del hub + +Un concentrador solía ser la única máquina que no podía usarse a sí misma: `ocx claude`, Claude Desktop, Cursor, la inyección `system-env` y el asistente de visión enrutado, todos marcan `http://127.0.0.1:`, que no existe cuando el oyente está vinculado a una dirección de red Tailscale. Con el oyente de loopback habilitado, trabajan en el concentrador: + +```bash +ocx sync # the hub now writes its own Codex/Grok blocks +ocx claude # Claude Code wired to the hub's own loopback address +``` + +El oyente solo lleva cables de inferencia: `POST /v1/responses` y su actualización WebSocket, `POST /v1/responses/compact`, `POST /v1/messages`, `POST /v1/chat/completions`, `POST /v1/alpha/search`, `GET /v1/models` y la superficie de voz en tiempo real. `POST /v1/messages/count_tokens` se admite deliberadamente **no**, por lo que Claude Code vuelve a la estimación de token local: una pérdida cosmética, no un lanzamiento roto. `/api/*`, `/healthz`, `/readyz` y el tablero de instrumentos todos devuelven `404` allí: lecturas de administración local como la llamada de descubrimiento de `ocx claude` van a la superficie de administración autenticada con una credencial de administración, nunca a un socket no autenticado. Es por eso que la entrada de la gerencia y este oyente siguen siendo dos cosas diferentes. + +Con el oyente **apagado**, un concentrador deliberadamente no reescribe sus propias configuraciones de cliente, y cada salto nombra la puerta que lo detuvo: + +```text +This machine is a hub; it does not rewrite its own Codex/Grok/Claude configs unless +unauthenticatedLoopbackListener is enabled. +``` + +Esa frase significa la puerta del concentrador, no su conmutador `clientIntegrations`. `ocx ensure` deja un bloque gestionado existente Grok en su lugar cuando está cerrado en lugar de despojarlo, y `ocx restore back` informa de la puerta en lugar de culpar a un escritor competidor. + + + +### Aceptación en el plano de datos + +Demostrar vivacidad y disposición en el oyente de datos públicos: + +```bash +curl --fail --silent http://100.64.0.10:10100/healthz +curl --fail --silent http://100.64.0.10:10100/readyz +``` + +Un `200` de `/healthz` solo demuestra que el proceso está vivo. La aceptación de implementación también requiere `/readyz`, una autenticación `GET /v1/catalog` y una respuesta real enrutada. + + + +## Escala de cola Servir + +Primero prueba que el socket de administración es solo loopback, luego publícalo a través de Serve: + +```bash +ss -ltnp | grep 10101 # Linux: expected 127.0.0.1:10101 only +lsof -nP -iTCP:10101 -sTCP:LISTEN # macOS: expected 127.0.0.1 only + +tailscale serve --bg --https=443 http://127.0.0.1:10101 +tailscale serve status +``` + +Establecer `hub.managementPublicOrigin` al origen exacto HTTPS mostrado por Serve. Agregue el inicio de sesión de Tailscale exacto del operador a `remoteGui.allowedTailscaleUsers`; una lista vacía significa que ninguna identidad remota puede acuñar una sesión. Verifique ambas direcciones: + +```bash +# Negative: the loopback-only port must not be reachable through the node's tailnet address. +curl --fail --connect-timeout 3 http://100.64.0.10:10101/ && echo "unexpected exposure" + +# Positive: the HTTPS dashboard loads through Serve from an allowed tailnet user. +curl --fail --silent --show-error https://hub-name.tailnet-name.ts.net/ >/dev/null +``` + +La prueba de navegador positiva debe usar una sesión Tailscale con inicio de sesión real; un `curl` desnudo puede no llevar los encabezados de identidad necesarios para la emisión automática de la sesión. El emparejamiento sigue siendo la alternativa cuando el frontend HTTPS no puede proporcionar una identidad de Tailscale confiable. + + + +### Dar al oyente de datos TLS + +El mapa Serve de arriba publica solo la entrada **gestión**. Ese ingreso nunca sirve `/v1/*`, `/healthz` o `/readyz`, por lo que por sí solo no le da a un cliente remoto un plano de datos utilizable. opencodex también termina no TLS de su propio: el oyente es llano HTTP y HTTPS es siempre un frontend poseído por el operador. + +Servir puede ser ese frontend para el plano de datos también, en un segundo puerto HTTPS. En macOS necesita un salto extra, porque Tailscale Servir proxies solo a `127.0.0.1` - no puede apuntar al oyente que enlaza a la propia dirección tailnet del nodo, y la compilación de App Store del cliente macOS rechaza un destino remoto por completo. Ejecutar un reenviador de bucle en el concentrador y apuntar Servir en eso: + +```bash +# Any loopback TCP forwarder works; socat is one. Pick a port the hub is not already using: +# with the loopback companion enabled, 127.0.0.1:10100 belongs to opencodex itself. +socat TCP-LISTEN:10110,bind=127.0.0.1,fork,reuseaddr TCP:100.64.0.10:10100 & + +tailscale serve --bg --https=8443 http://127.0.0.1:10110 +tailscale serve status # expect both mappings: 443 -> 10101, 8443 -> 10110 +``` + +**No apuntes Servir al oyente acompañante del loopback.** Es un socket real en `127.0.0.1:10100`, por lo que se crearía la asignación y luego fallaría de la misma manera que describe la trampa a continuación: el compañero ejecuta la política de admisión de loopback, que requiere un encabezado de loopback `Host`, y sirve hacia adelante `Host: hub-name.tailnet-name.ts.net`. El compañero existe para los procesos *on* el concentrador, que envían un loopback `Host` propio. El promotor lleva el oyente tailnet, cuya admisión de credenciales y manejo `Host` es lo que necesita un frontend TLS. + +Servir acepta un conjunto limitado de puertos HTTPS; confirmar que el mapeo fue creado con `tailscale serve status` en lugar de asumir que el puerto estaba permitido. + +Dar al promotor la misma vida útil que el hub. Un trabajo de shell en segundo plano muere en el reinicio mientras que el El servicio vuelve a aparecer, lo que deja un concentrador que se ejecuta e inalcanzable sobre TLS; ejecútelo desde lanzamiento o systemd junto `ocx service install`. + +Luego conéctese con los dos orígenes establecidos por separado. El URL posicional es el origen **datos** - es donde `/readyz` y `/v1/catalog` son buscados - y `--management-url` es el origen del tablero de instrumentos utilizado para el emparejamiento y la emisión de claves. No tienen que compartir un puerto: + +```bash +# This is exactly the line `ocx hub invite` prints, with the code filled in. +echo '' | ocx connect https://hub-name.tailnet-name.ts.net:8443 \ + --management-url https://hub-name.tailnet-name.ts.net \ + --pairing-code-stdin +``` + +Registre esos dos orígenes en el centro como `hub.dataPublicOrigin` y `hub.managementPublicOrigin`, y `ocx hub invite` los imprimirá para usted en lugar de pedirle que los recuerde. + +Cuando se omite `--management-url`, se toma de la respuesta `/readyz`, que informa `hub.managementPublicOrigin`. Establecerlo explícitamente es más claro cuando los dos orígenes difieren. + +**No corte esto vinculando el receptor de datos a `127.0.0.1`.** Un enlace de loopback es cómo opencodex reconoce una implementación puramente local: deja de requerir una credencial de datos y comienza a requerir que el encabezado `Host` de la solicitud también sea loopback. Un frontend TLS avanza `Host: hub-name.tailnet-name.ts.net`, por lo que `/v1/catalog` responde `403 origin_rejected` - mientras que `/readyz`, que no ejecuta esa comprobación, todavía devuelve `200`. El despliegue se ve saludable y no puede servir a un modelo. Nada en la ruta de solicitud lee `X-Forwarded-Host`, por lo que el frontend no puede repararlo. Mantenga al oyente en la dirección de la red Tailscale, donde se mantiene la admisión de credenciales y no se aplica el cheque `Host`. + +Esa trampa es sobre el **enlace**, y sigue siendo cierto. Obtener un conector `127.0.0.1` en un concentrador para los propios procesos del concentrador es un problema diferente, y [`unauthenticatedLoopbackListener`](#one-port-and-the-ported-alternative) es la respuesta sancionada: el enlace público permanece en la dirección de la red Tailscale con la admisión activada, y un segundo conector sirve a las personas que llaman locales. No es un objetivo TLS, por la razón dada anteriormente. + +La vinculación `0.0.0.0` también funciona y elimina la necesidad de un promotor, ya que el oyente es entonces accesible en loopback también. Publica el puerto de datos en cada interfaz, por lo que lo prefiere solo dondel host no tiene otra red que le importe, y tenga en cuenta que la forma complementaria de `unauthenticatedLoopbackListener` se rechaza en un enlace comodín, porque el oyente público ya tiene `127.0.0.1:` allí. + +Vuelva a ejecutar las comprobaciones de aceptación contra el origen de datos HTTPS una vez que Serve esté activo: `/readyz`, un `GET /v1/catalog` autenticado y una respuesta enrutada real. + + + +### Proxy de certificado ts.net propiedad del operador + +Si opera su propio proxy TLS, obtenga un certificado solo para el FQDN completo de ts.net: + +```bash +tailscale cert hub-name.tailnet-name.ts.net +``` + +Proteja la clave privada, renuévela a través del mecanismo compatible de Tailscale y provide solo a `127.0.0.1:10101`. Un proxy genérico TLS no proporciona una identidad fiable de Tailscale. No fabrique encabezados `Tailscale-User-*`; use el flujo de emparejamiento de un solo uso vinculado al origen. + + + +## Invitar a otra máquina + +Ejecute esto en el concentrador en lugar de escribir una línea `ocx connect` a mano: + +```bash +ocx hub invite +``` + +Acuña un código de emparejamiento de un solo uso y de corta duración e imprime el comando para ejecutarse en la otra máquina: + +```text +# Run on the other machine: +echo '' | ocx connect https://hub-name.tailnet-name.ts.net:8443 --management-url https://hub-name.tailnet-name.ts.net --pairing-code-stdin +``` + +El origen de los datos proviene de `--data-url`, luego `hub.dataPublicOrigin`, luego la dirección de enlace. Ese último recurso solo funciona cuando el enlace **es** una dirección que otra máquina puede marcar: en un enlace de loopback o comodín se resolvería con `http://localhost:`, que le dice a la otra máquina que se marque a sí misma y gasta el código de un solo uso por nada, por lo que `invite` se niega e imprime la línea `ocx config set hub.dataPublicOrigin` (más el formulario `--data-url` por invitación). Un `--data-url` o `hub.dataPublicOrigin` explícito nunca se cuestiona en segundo lugar: un origen de datos de bucle de retorno es legítimo sobre un túnel SSH. + +El origen de gestión es `hub.managementPublicOrigin`, y en `invite` el indicador `--management-url` es un **confirmación, no una anulación**: la concesión está vinculada al origen configurado y el intercambio se compara con él, por lo que se rechaza un valor que difiere con ambos orígenes nombrados en lugar de imprimir un código que el concentrador rechazaría. + +Cada invitación exitosa también imprime el **origen del navegador vinculado** en stderr. Una concesión está vinculada a un origen, y un remoto `ocx connect` presenta `Origin: http://localhost:`, por lo que si el origen vinculado no es el predeterminado `http://localhost:10100`, la otra máquina ya tiene que estar funcionando en ese puerto antes de que ejecute la línea, de lo contrario el concentrador rechaza el intercambio y el código se gasta. La nota dice qué puerto, y ofrece admitir el origen predeterminado en su lugar. + +`invite` rechaza *antes* acuñando cualquier cosa cuando la configuración no puede funcionar: un `runtimeRole` que no es `hub`, un `hub.managementPublicOrigin` faltante, un origen de gestión sin bucle de retorno de texto plano, un `--data-url` mal formado, un origen de datos que sería el propio bucle de retorno de esta máquina, o ningún proxy certificado en ejecución. Una condición previa merece su propio párrafo. + +**`corsAllowOrigins` tiene que nombrar el origen del navegador local de la máquina de unión.** `ocx connect` envía `Origin: http://localhost:` cuando intercambia la concesión, y las concesiones están vinculadas al origen, por lo que solo el propio `hub.managementPublicOrigin` o una entrada de bucle de `corsAllowOrigins` pueden coincidir. Sin ninguno presente, `invite` sale no cero, no acuña nada y nombra el comando exacto: + +```bash +ocx config set corsAllowOrigins '["http://localhost:10100"]' +``` + +Utilice el puerto en el que escucha el proxy de la máquina **afiliarse**; `10100` es el valor predeterminado. El bloque de configuración anterior ya lo establece. Un conjunto de matrices completas reemplaza la matriz, por lo que cuando el concentrador ya tiene entradas, ejecuta la línea `invite` impresiones, lleva las existentes más el nuevo origen. `ocx config get +corsAllowOrigins` muestra lo que hay ahora. + +`ocx hub invite --json` emite `{ code, expiresAt, dataUrl, managementUrl, command }` con `expiresAt` como ISO 8601. El código es un secreto: de un solo uso, cinco minutos de vida útil, tasa limitada en el concentrador, y no debe ser persistente, registrado o pegado en un problema. `--clients codex,claude` elige qué cliente configura el comando impreso apuntará al concentrador. + +`invite` es una conveniencia sobre el flujo de emparejamiento existente, no un segundo mecanismo. Conduce la misma ruta local certificada que usa `ocx gui pair`, por lo que no necesita un token de administración y no tiene que exportarse a su shell. Todo en [Roles y flujo directo de datos](#roles-and-direct-data-flow) sobre rotación, revocación y desconexión se aplica sin cambios a una máquina que se unió de esta manera. + + + +## Operaciones de servicio macOS + +`ocx service install` y `ocx service repair` se pueden volver a ejecutar en un hub activo. La reparación genera primero el plist y lo compara con el guardado. Si ambos son idénticos, el archivo de token no ha cambiado y `launchctl print` confirma que el job está cargado desde ese plist, se restablecen los permisos `0600`, se actualiza el estado de instalación y se muestra `service is already loaded from the current plist; nothing to do.`. En ese caso no se modifica launchd. Las versiones anteriores descargaban incondicionalmente un job sano, convirtiendo un comando de diagnóstico en una interrupción del servicio. + +**`ocx service restart` siempre solicita un reinicio.** Ya no es un alias de `repair`. Ejecuta la misma actualización y, si no hubo que recargar nada porque el job está sano y sin cambios, lo reinicia con `launchctl kickstart -k`. Después vuelve a consultar `launchctl print` para confirmar que el job sigue cargado y muestra: + +```bash +ocx service restart +# ℹ️ service restarted (launchctl kickstart -k gui/501/com.opencodex.proxy). +``` + +Usa ese comando después de cambiar `unauthenticatedLoopbackListener`, `hostname` o `port`. El reinicio con kickstart no descarga previamente el job, por lo que evita la ventana sin registro que provocaba la reparación incondicional antigua. + +`ocx service`, sin subcomando, sigue eligiendo `repair`, no `restart`: actualiza la instalación de forma idempotente y no solicita reiniciar un hub sano. Usa `ocx service repair` para corregir un job cargado desde un plist anterior o que ya no está cargado. Si está sano, no lo reiniciará. + +También siguen funcionando `launchctl kickstart -k gui/$(id -u)/com.opencodex.proxy` y la secuencia `ocx service stop` seguida de `ocx service start`. El mensaje de error ofrece el primero como alternativa, pero la vía recomendada es `ocx service restart`. + +En Linux y Windows no existía esta diferencia: `ocx service restart` usa respectivamente `systemctl --user restart` y la detención seguida del inicio de la tarea programada, según lo solicitado. + +`ocx service status` distingue cuatro launchd estados, y el último es el que la gente malinterpretó: + +| Resumen | Descripción | +| --- | --- | +| `installed and loaded` | Un dominio responde y ejecuta el comando definido en el plist actual. Estado normal. | +| `installed and loaded from an OLDER plist` | El job se ejecuta con una definición anterior. `ocx service repair` la actualiza. | +| `installed, not loaded` | Todos los dominios respondieron que el job está ausente. La reparación vuelve a registrarlo. | +| `installed; launchd state could not be verified` | No se pudo consultar `launchctl`, por ejemplo por falta de acceso al dominio `gui/`. Esto **no demuestra** que el hub esté caído: no se recomienda reparar por ese motivo ni se marca como muerto un proxy que sigue activo. | + +Antes, una consulta que no se podía ejecutar se presentaba como «no cargado». Eso podía llevar a reparar un servicio sano y hacer que el actualizador iniciara otro proxy en el puerto que ya utilizaba el servicio. + + + +## Sin cabeza OAuth + +Deshabilitar el inicio del navegador en el concentrador: + +```bash +ocx config set oauthOpenBrowser false +``` + +1. Desde el panel de control remoto autenticado o el cliente de administración, inicie `POST /api/oauth/login` para el proveedor. El concentrador devuelve la URL de autorización y las instrucciones sin abrir un navegador. +2. Abra la URL en la máquina del operador y autorice allí. +3. Si la devolución de llamada no puede llegar al concentrador, pegue la URL o el código de redirección final en el panel de control/ CLI. Envía `POST /api/oauth/login/code` con `{provider,input}`. +4. Sondear el punto final de estado existente hasta que se complete y, a continuación, realizar una solicitud de modelo enrutado. + +Nunca ponga el código OAuth en argv de shell, registros, texto de emisión, capturas de pantalla o evidencia de implementación. La ruta de código manual mantiene sus comprobaciones de entrada existentes de proveedor desconocido, flujo no activo, código no válido y 4096 bytes. + +## Docker Compose + +opencodex no publica una imagen de contenedor oficial. El repositorio mantiene un código fuente-construido [`Dockerfile`](https://github.com/lidge-jun/opencodex/blob/main/Dockerfile), [`compose.yaml`](https://github.com/lidge-jun/opencodex/blob/main/compose.yaml), y un estrecho `.dockerignore`. La compilación fija el índice de imagen multiplataforma Bun 1.4.4 por compendio, ejecuta el proxy como el usuario no raíz `bun`, mantiene el sistema de archivos raíz de solo lectura, elimina las capacidades Linux y publica solo el oyente de datos en el `127.0.0.1:10100` del host de forma predeterminada. El proceso en primer plano utiliza `OCX_SERVICE=1`, por lo que detener o recrear el contenedor conserva el estado Codex enrutado en lugar de restaurar una configuración de escritorio nativa. Docker proporciona supervisión; no hay ningún administrador de servicios del sistema operativo instalado en la imagen. Use Compose para reiniciar/recrear el contenedor; esto no extiende el soporte a todas las rutas de reinicio del panel. + +La imagen siembra una configuración `hub` de primera ejecución que une el oyente de contenedor a `0.0.0.0`. Antes del primer inicio normal, transmita un token de plano de datos recién generado al ayudante de arranque. El ayudante acepta como máximo una línea de 4096 bytes, nunca imprime el token, se niega a reemplazar un token existente y lo persiste como el propietario canónico `service-api-token` en el volumen `ocx-state`. + +El despliegue persiste dos hogares separados: `ocx-state` en `/home/bun/.opencodex` para la configuración OpenCodex, las credenciales del proveedor y el uso, y `codex-state` en `/home/bun/.codex` para el estado Codex y `opencodex-catalog.json`. La imagen y Compose establecen explícitamente `CODEX_HOME=/home/bun/.codex`, por lo que esta ruta del catálogo sigue siendo escribible con `read_only: true` y sobrevive a la recreación de contenedores. La imagen crea ambos directorios para el usuario no raíz `bun` con el modo `0700`; la propiedad del volumen existente y los permisos no se migran automáticamente. + +No combine `CODEX_HOME` y `OPENCODEX_HOME`: ambos productos utilizan un nombre de archivo `auth.json` con diferentes formatos. Este cambio de empaque agrega persistencia, no un generador de catálogo. Materialice o importe un catálogo válido en `/home/bun/.codex/opencodex-catalog.json` antes de la verificación de aceptación del catálogo a continuación; sin uno, `catalog_not_found` sigue siendo la respuesta esperada. + +La actualización conserva el volumen `ocx-state` existente y agrega `codex-state`; no se migran archivos automáticamente. Si una solución anterior colocó un catálogo directamente debajo de `/home/bun/.opencodex`, respalde y copie deliberadamente solo el catálogo a la nueva casa Codex, preservando el acceso solo para el propietario. No copie el `auth.json` de ninguno de los productos sobre el otro. Las implementaciones con un `CODEX_HOME` personalizado deben conservar su entorno explícito y la asignación de volumen grabable hasta que se complete la migración. Al anular `CODEX_HOME`, monte ese directorio exacto y persista el catálogo predeterminado en `${CODEX_HOME}/opencodex-catalog.json`. Si `model_catalog_json` selecciona explícitamente otro archivo, esa ruta de acceso resuelta también debe persistir. + +Mantenga estable el nombre del proyecto de redacción durante las actualizaciones para que se reutilicen los mismos volúmenes con nombre. Los montajes con propiedad externa existente, montajes de solo lectura y montajes con `volume-nocopy` no se reparan mediante la configuración del directorio de la imagen. Persistir catálogo seleccionado por separado o SQLite rutas por separado; un almacén de credenciales del sistema operativo no está respaldado por estos dos volúmenes. + +Cuando se ejecute sin Compose, proporcione explícitamente ambos montajes con nombre. Solo las declaraciones Dockerfile `VOLUME` crean volúmenes anónimos que un `docker run` posterior no reutiliza automáticamente. Estas opciones de montaje utilizan nombres de ejemplo independientes; para reutilizar los datos de Compose, sustituya los nombres de volumen predefinidos para el proyecto: + +```sh +--mount type=volume,src=ocx-state,dst=/home/bun/.opencodex \ +--mount type=volume,src=codex-state,dst=/home/bun/.codex +``` + +El host necesita Git y Docker Compose para un clon local, o solo Docker Compose para un contexto Git remoto. Bun y no se requiere una etapa de preparación manual. La etapa de manifiesto de solo compilación deriva el inventario canónico de la instantánea Git seleccionada, escribe el `src/generated/compatibility-version.json` sin seguimiento y verifica cada SHA-256 registrado contra el contexto de compilación de solo lectura antes de que las instrucciones de origen `COPY` puedan desreferenciar un enlace simbólico. Los archivos de entorno de ejecución copiados se verifican nuevamente dentro de la imagen. Los metadatos de Git se admiten solo para ese montaje de enlace; no `COPY` coloca `.git` en una capa de imagen, y el ejecutable de Git permanece confinado a la etapa de manifiesto. + +"Git metadata" aquí significa dos archivos. El inventario canónico proviene de `git ls-files`, que lee el índice y nunca abre un objeto o una referencia, por lo que el contexto de compilación admite solo `.git/index` y `.git/HEAD`, aproximadamente 1 MB, en lugar del almacén de objetos completo del repositorio. La etapa de manifiesto los copia en un directorio Git de cero que posee y suministra los directorios vacíos `objects/` y `refs/` que requiere la verificación del repositorio de Git. Un contexto sin un manifiesto ni un índice Git falla la compilación con un mensaje que nombra ambas entradas compatibles; nunca vuelve a un marcador de posición. + +Un manifiesto generado por el host existente sigue siendo compatible: la compilación lo verifica y lo usa en lugar de reemplazarlo silenciosamente. Los archivos que faltan o no coinciden, los archivos de origen adicionales ausentes del manifiesto y los enlaces simbólicos (incluidos los directorios principales) fallan la compilación. El inventario requiere `package.json`, `bun.lock` y `scripts/model-metadata.source.json`; el propio manifiesto generado es el único archivo fuente exento del inventario. No lo cometas ni lo edites a mano. + +```bash +git clone https://github.com/lidge-jun/opencodex.git +cd opencodex +docker compose build +openssl rand -hex 32 | docker compose run --rm -T hub bun run docker/bootstrap-token.ts +docker compose up -d +``` + +Para un contexto Git remoto, establezca el argumento integrado BuildKit que conserva los metadatos de Git. Por ejemplo, reemplace el bloque de compilación del servicio con: + +```yaml +services: + hub: + pull_policy: build + build: + context: https://github.com/lidge-jun/opencodex.git#main + dockerfile: Dockerfile + target: runtime + args: + BUILDKIT_CONTEXT_KEEP_GIT_DIR: "1" +``` + +Establezca un puerto host alternativo sin cambiar el oyente `10100` fijo del contenedor: + +```bash +OPENCODEX_PORT=10190 docker compose up -d +``` + +El acceso remoto es una opción explícita. Configure `OPENCODEX_BIND_ADDRESS` en la LAN o la IP de Tailscale del host, o use `0.0.0.0` para publicar en las interfaces de host **todos**: + +```bash +OPENCODEX_BIND_ADDRESS=0.0.0.0 docker compose up -d +``` + +Utilice un firewall y un frontend TLS /tailnet autenticado antes de exponer el puerto. La anulación de enlace cambia solo la publicación del host; el oyente del contenedor sigue siendo `0.0.0.0:10100`. Mantenga la misma anulación de enlace en invocaciones de composición posteriores que recrean el concentrador. Para actualizar una implementación existente, ejecute `docker compose build` y vuelva a crear el concentrador con `docker compose up -d`; no repita la inicialización de token de una sola vez. + +Configure los proveedores con el panel de control a través de un frontend de administración propiedad del operador o con comandos CLI de un solo disparo que comparten el volumen de estado. Los siguientes comandos muestran la configuración de Remote Hub existente; reemplace el origen y la identidad del ejemplo antes de habilitarlos: + +```bash +docker compose run --rm hub bun run src/cli/index.ts config set hub.managementPublicOrigin '"https://hub-name.tailnet-name.ts.net"' +docker compose run --rm hub bun run src/cli/index.ts config set hub.managementIngress '{"enabled":true,"port":10101}' +docker compose run --rm hub bun run src/cli/index.ts config set remoteGui.allowedTailscaleUsers '["operator@example.com"]' +docker compose restart hub +``` + +Estos conjuntos anidados funcionan porque la imagen siembra una configuración `hub` de primera ejecución, por lo que el objeto ya existe. En una nueva instalación independiente no lo hace, y las mismas líneas fallan hasta que se crea - ver [Linux systemd o macOS launchd](#linux-systemd-or-macos-launchd) arriba. + +El oyente del contenedor se une a `0.0.0.0`, por lo que ya es accesible en la propia dirección de bucle del contenedor y la forma complementaria de `unauthenticatedLoopbackListener` no se aplica allí, se rechaza en un enlace comodín. El token bootstrap a continuación es el contenedor equivalente al propio paso de aprovisionamiento del servicio, y también se ejecuta una vez. + +No ponga un token en `ARG`, `ENV`, `COPY`, Compose YAML, historial de imágenes o argumentos de comando. No monte el socket Docker, la casa del host o Codex casa, agente SSH o proveedores de archivos clave. Una entrada de administración vinculada a `127.0.0.1:10101` dentro del contenedor solo se puede alcanzar mediante un frontend TLS /tailnet en el mismo espacio de nombres de red; nunca publique `10101` como acceso directo. + +Después de que el recipiente esté sano, ejecute una prueba de promoción de preparación por separado: + +```bash +docker compose exec hub bun -e \ + "const r=await fetch('http://127.0.0.1:10100/readyz');console.log(r.status,await r.text());if(!r.ok)process.exit(1)" + +docker compose exec hub bun -e \ + "const t=(await Bun.file('/home/bun/.opencodex/service-api-token').text()).trim();const r=await fetch('http://127.0.0.1:10100/v1/catalog',{headers:{'x-opencodex-api-key':t}});console.log(r.status);if(!r.ok)process.exit(1)" +``` + +A continuación, envíe una respuesta enrutada autenticada real con un modelo configurado. Si el secreto está ausente o es ilegible, no debe aceptarse como listo un concentrador de no retorno de bucle. Nunca trates a la vida sola como prueba. + +`docker compose down` elimina el contenedor y la red, pero conserva ambos volúmenes con nombre. Tratar `docker compose down --volumes` como destructivo: elimina la configuración, OAuth credenciales, historial de uso, el token de plano de datos, y persistió Codex estado juntos. + +CI multiplataforma construye la imagen de origen y comprueba el inicio, la admisión de tokens de plano de datos y la recreación de contenedores utilizando un proyecto de Compose aislado con credenciales desechables. Verifica que tanto los volúmenes con nombre como un catálogo sintético sobrevivan al reemplazo. Esta comprobación no valida una cuenta de proveedor real, devolución de llamada OAuth, migración de montaje personalizada o cada arquitectura de CPU; realice la comprobación de respuesta enrutada autenticada anterior para su implementación. + + + +## Reversión + +Inspeccione las asignaciones de servicio existentes antes de cambiarlas. `tailscale serve reset` elimina todas las asignaciones en el nodo; use un comando de eliminación compatible más estrecho cuando existan asignaciones no relacionadas. + +```bash +tailscale serve status +tailscale serve reset +ocx config set hub.managementIngress '{"enabled":false}' +ocx service restart +``` + +Para una reversión de contenedor, conserve tanto los volúmenes de estado con nombre como sus asignaciones. Una imagen anterior todavía puede usar `CODEX_HOME=/home/bun/.codex` cuando ese directorio permanece montado; no vuelva a un archivo de composición anterior que elimine el montaje Codex. No fusione las casas ni vuelva a ejecutar el token bootstrap. Para una reversión del servicio, detenga el servicio de la sucursal y repare la versión anterior contra el mismo `OPENCODEX_HOME`. Deshabilitar la entrada de administración o Servir no requiere cambiar el oyente de datos. + + + +## Solución de problemas + +- **Hub abajo:** `ocx connect status` todavía muestra la conexión guardada. `ocx disconnect` puede restaurar el estado local sin conexión; no puede revocar la clave remota. +- **Catálogo Stale:** `ocx sync` mantiene un último catálogo válido solo para fallos transitorios del concentrador. Las fallas de autenticación, esquema, tamaño y protocolo son errores difíciles y nunca vuelven a los proveedores locales. +- **Token giratorio o recuperación `.prev`:** vuelve a ejecutar `ocx connect rotate` con un código de emparejamiento o token de administración. No edite ni elimine ninguno de los candidatos de token antes de que finalice la sonda de recuperación. +- **Desajuste de protocolo:** actualizar el lado más antiguo nombrado por el mensaje `hub-too-new` o `hub-too-old`. La negociación falla antes de que el token, el catálogo, el diario o el estado del cliente escriban. +- **Código de emparejamiento perdido o quemado:** ejecutar `ocx hub invite` de nuevo. Las concesiones son de un solo uso y los fallos repetidos son de velocidad limitada sin revelar si existe un código. +- **`ocx hub invite` dice `No loopback browser origin is admitted for pairing`:** el concentrador no admite el origen del navegador de bucle de retroceso, por lo que una concesión vinculada al origen nunca podría igualar. Nada fue acuñado. Ejecute la línea `ocx config set corsAllowOrigins` las impresiones de error, con el puerto proxy de la máquina de unión. Véase [Invitar a otra máquina](#inviting-another-machine). +- **`ocx hub invite` dice que el origen de los datos anunciados sería el propio bucle de retorno de esta máquina:** el bind es solo loopback o un comodín y `hub.dataPublicOrigin` está desactivado, por lo que no hay dirección para anunciar y nada adivina una red Tailscale o LAN. Nada fue acuñado. Establecer `hub.dataPublicOrigin`, o pase `--data-url` para esta invitación solamente. +- **Se rechaza el intercambio de la máquina de unión y se gasta el código:** la subvención estaba vinculada a un origen que la máquina no presenta. Vuelva a leer la línea `Bound browser origin:` de la invitación: nombra el puerto en el que debe ejecutarse la otra máquina u ofrece la admisión `http://localhost:10100` en el concentrador. +- **`ocx hub invite` rechaza un `--management-url`:** en un concentrador ese indicador confirma `hub.managementPublicOrigin` en lugar de anularlo, porque la concesión está vinculada al valor configurado. Cambie la configuración o suelte la bandera. +- **`ocx claude` en el concentrador se inicia de forma nativa Codex / Claude, o el concentrador se niega a escribir sus propias configuraciones de cliente:** `unauthenticatedLoopbackListener` está apagado. El mensaje de omisión nombra la puerta. Habilite el oyente y reinicie el proxy (`ocx service restart` en una instalación de servicio). +- **`ocx claude` en el concentrador obtiene `404` del oyente:** el proxy sigue siendo el proceso que comenzó antes de que existieran los cables del oyente, o antes de que el puerto cambiara. Reinicie con `ocx service restart` - ver [macOS operaciones de servicio](#macos-service-operations). +- **`ocx service repair` impreso `nothing to do` y el proceso no rebotó (macOS):** esperados. Una reparación de un trabajo saludable es deliberadamente una opción prohibida. Cuando desee un nuevo proceso, ejecute `ocx service restart`, que inicia el trabajo cargado en su lugar y reporta `service restarted (launchctl kickstart -k …)`. Solo si eso falla es `launchctl kickstart -k gui/$(id -u)/com.opencodex.proxy` el retroceso manual - el mensaje de falla lo nombra. +- **`ocx service install` rechaza `OPENCODEX_API_AUTH_TOKEN`:** ese valor es un token de administrador de administración. `unset OPENCODEX_API_AUTH_TOKEN` y reejecutar; el servicio proporciona su propio token de plano de datos. Véase [El propio token del plano de datos](#the-data-plane-token-provisions-itself). +- **El buje se bloquea en el arranque y `ocx status` muestra `admin-collision (file)`:** el archivo `service-api-token` contiene el token de gestión, por lo que el concentrador cerca su gestión API cerrada. Elimine el archivo y ejecute `ocx service repair` para proporcionar un token de plano de datos. Desactivar la variable de entorno no ayuda aquí - el archivo es la fuente. +- El emparejamiento de **Plain HTTP se negó:** sobre HTTP no loopback se rechaza completamente, y no hay ninguna bandera que opte por salirse de él. Ponga el origen de la administración detrás de HTTPS o pare sobre loopback. Los tokens de administrador nunca se envían por encima de HTTP. +- **`403 origin_rejected` de `/v1/catalog` mientras que `/readyz` devuelve `200`:** el oyente de datos está obligado a retroceder detrás de un frontend TLS. Véase [Dar al oyente de datos TLS](#giving-the-data-listener-tls). +- **Finalizó la sesión remota:** Iniciar sesión o emparejar de nuevo. El cierre de sesión y la expiración invalidan solo la sesión del navegador, no una clave de datos del cliente. +- **Revocación excepcional después de la desconexión:** usa la página **Conecte las llaves → API** del panel de control central. Es el único camino de revocación posterior a la desconexión. + + + +### Uso desde un cliente conectado + +`ocx usage` lee el concentrador conectado con la clave de datos registrada de este cliente. La salida humana identifica la fuente del concentrador y el alcance de la clave del cliente; `--json` devuelve los mismos datos de alcance. Los filtros de rango, superficie, proveedor / modelo y los límites personalizados `--since` / `--until` permanecen disponibles. Los desgloses de cuentas y los registros de otros clientes no se comparten. Un concentrador antiguo o no disponible produce un error explícito en lugar de sustituir el uso local; actualice el concentrador si no admite esta lectura. + +El punto final del plano de datos de solo lectura es `GET /v1/usage`, usando `x-opencodex-api-key` con una clave de cliente configurada. En todo el entorno y las claves de administración son rechazadas. Acepta `range`, `surface`, `provider`, `model`, `since` y `until`; se rechazan las opciones desconocidas / repetidas y los identificadores de clave seleccionados por el llamante. Las filas sobredimensionadas omitidas retienen la advertencia explícita de historial incompleto. + +Las credenciales de uso del cliente se envían solo por HTTPS o loopback HTTP. Tanto la solicitud como la respuesta deshabilitan el almacenamiento en caché. + + + +### Emparejar este navegador con un hub + +La inscripción de la máquina y la autenticación del navegador son independientes. El panel de emparejamiento nombra el concentrador y muestra un comando `ocx gui pair --origin` para el origen exacto abierto actualmente en su navegador. Ejecute ese comando en el concentrador o envíelo al operador del concentrador y solicite un código de emparejamiento único. Pegue ese código en el panel; una clave de datos API o un token de administración no es un código de emparejamiento. + +Mientras la autenticación del navegador está pendiente, el panel de control no recomienda reiniciar un cliente conectado saludable. Completar el emparejamiento actualiza los datos del panel de control de inmediato, incluido un error de autenticación previamente almacenado en caché. La expiración de la sesión vuelve al emparejamiento; la denegación de permiso mantiene su propia guía de configuración de acceso. Otras actualizaciones fallidas pueden mostrar los últimos datos recibidos con un aviso de datos obsoletos y una acción de reintento. + +Si se ha intercambiado el código pero la validación de Remote Link no está disponible temporalmente, mantenga la página abierta y use **Reintentar validación**. Esto comprueba la sesión pendiente del navegador sin gastar otro código de emparejamiento. Las respuestas a los desafíos de Cloudflare también mantienen la sesión pendiente para reintentar. Emparejar solicitudes de intercambio y validación cada vez después de 10 segundos, incluida la lectura del cuerpo de la respuesta, para que el formulario vuelva a ser utilizable. Un tiempo de espera de validación mantiene la sesión instalada pendiente para **Reintentar validación**; una respuesta de intercambio que llega después de su tiempo de espera no puede instalar credenciales. Si el concentrador rechaza definitivamente la sesión con HTTP 401 o 403, el panel de control restaura la sesión del navegador anterior solo mientras el traspaso aún posee el estado de sesión actual y no se ha reemplazado por un inicio de sesión, cierre de sesión o cambio de destino más reciente; solicite al operador del concentrador un código nuevo para este origen del navegador. Un intercambio de emparejamiento captura la revisión actual de la sesión y el objetivo antes de enviar el código; las respuestas retrasadas no pueden reemplazar una sesión después de que cambie la revisión. El arranque automático de descubrimiento y la recuperación de fondo siguen la misma regla, incluyendo cambiar los objetivos de ida y vuelta; ninguno anula el cierre de sesión. El cierre de sesión pendiente y completado suprime la recuperación automática hasta que cambie un nuevo inicio de sesión explícito o un nuevo objetivo. Un tiempo de espera de recuperación informa de una sesión no disponible solo si su solicitud sigue siendo actual, no cancelada y sin credenciales; los resultados de arranque tardío se descartan. + +Si un oyente auxiliar no puede enlazar, los nombres de inicio `unauthenticatedLoopbackListener` o `hub.managementIngress` y la dirección real. Corregir ese oyente o liberar su dirección; cambiar solo el puerto proxy público no repara un puerto auxiliar fijo. Los bloques de escucha mal formados editados a mano advierten y permanecen desactivados mientras se conservan las configuraciones no relacionadas. + + + +## Devolver un concentrador a autónomo + +Ejecuta `ocx hub disable [--json]` en el concentrador para eliminar `hub`, `unauthenticatedLoopbackListener`, `runtimeRole` y `hostname` juntos en una escritura validada. La configuración del proveedor, el puerto y las claves API guardadas se conservan. Se rechaza una configuración de cliente o independiente sin cambios. + +Las claves no llevan un origen de inscripción verificado y los nombres son editables. Para revocar las claves de cliente, primero inspeccione los ID con `ocx access key list --json` y, a continuación, seleccione explícitamente cada ID: + +```sh +ocx hub disable --revoke-clients --client-key --json +``` + +Repita `--client-key` para varios clientes. Con las claves guardadas presentes, `--revoke-clients` sin ID seleccionados se niega antes de cambiar la configuración. Las identificaciones desconocidas también se niegan. Solo se eliminan las teclas seleccionadas y sus rotaciones pendientes; la salida contiene metadatos seguros en lugar de secretos. El comando imprime el paso de reinicio para el supervisor detectado; no reinicia el proxy. Revisión `tailscale serve status` y otros frontends externos para asignaciones a puertos hub antiguos. La configuración y revocación persistentes se aplican al proxy en ejecución después del reinicio; Los registros de enlace remoto y los túneles permanecen sin cambios. diff --git a/docs-site/src/content/docs/es/guides/remote-link.md b/docs-site/src/content/docs/es/guides/remote-link.md new file mode 100644 index 00000000000..543406ccd9f --- /dev/null +++ b/docs-site/src/content/docs/es/guides/remote-link.md @@ -0,0 +1,222 @@ +--- +title: "Enlace remoto" +description: "Conecte una computadora OpenCodex Home a una computadora Child a través de SSH." +--- + +Un enlace de máquina conecta un ordenador **Home** OpenCodex a un ordenador **Child** a través de SSH. El Home sirve al Child a través del túnel SSH, mientras que ambos ordenadores mantienen su servicio local OpenCodex en el puerto `10100`. El panel de control transfiere la clave de enlace por hijo a través de SSH, por lo que no escribe un token. + + + +## Necesidades + +- El ordenador Home puede iniciar sesión en el Child con una clave OpenSSH. +- Para un enlace iniciado en Child, el Child puede iniciar sesión en Home con una clave OpenSSH (no se admite el inicio de sesión con contraseña). +- OpenCodex 2.66.0 o posterior está instalado en el ordenador Child, y en Home para un enlace iniciado Child. +- Ambos equipos ejecutan macOS o Linux. +- El panel de control que agrega un Child de Home se abre en el propio Home o a través de una sesión Hub emparejada. Convertir el equipo actual en un Child requiere una sesión de panel de control emparejada con el operador; una sesión de panel de control local sin credenciales no puede confirmar ese cambio de enrutamiento. + +La contraseña SSH y Windows están fuera del flujo actual. Se puede iniciar un enlace desde cualquier lado: desde el Home, como se describe a continuación, o desde el Child, como se describe en el [Conecte este equipo como un Child](#connect-this-computer-as-a-child). + + + +## Añadir un Child de `#remote` + +1. Abra el panel de control en `#remote` y activar el enlace remoto. +2. Elija **Home**, luego **Continuar**. Se abre la lista de hosts SSH. +3. Elija un host de los candidatos SSH o introduzca un alias de configuración SSH. +4. Ejecute la prueba de conexión y compare la huella dactilar del host ofrecida con la huella dactilar de la máquina que desea utilizar. Compararlo ayuda a detectar un host incorrecto o una clave de host cambiada antes de que SSH confíe en el host. +5. Confirme la huella digital y luego conecte el Child. + +El panel de control no te pide que ingreses un token. Primero sondea el host y no puede aplicar el enlace hasta que confirme explícitamente la huella digital. + +La hoja Add Child explica que el Child utiliza este Home 's proveedores sobre SSH y enumera los requisitos previos anteriores. Los alias de host provienen de `~/.ssh/config` en el Home que ejecuta OpenCodex, no necesariamente el ordenador que muestra el navegador. Si el descubrimiento tiene éxito sin hosts, agregue una entrada `Host` como esta, luego elija **Rescan hosts**. También puede introducir un alias existente manualmente; seleccionar o introducir un alias habilita **Conexión de prueba**. La hoja enlaza con esta guía. + +```sshconfig +Host devbox + HostName devbox.example.com + User you + IdentityFile ~/.ssh/id_ed25519 +``` + +Si falla el descubrimiento, la hoja muestra **No se pudo cargar los hosts SSH**, la razón de la solicitud disponible y **Reintentar**, en lugar de reclamar que la lista de host está vacía. Un fallo en la prueba de conexión mantiene su razón específica y la pista SSH desinfectada en la hoja activa, no duplicada detrás de ella. Compruebe la razón, utilice el diagnóstico SSH en Solución de problemas a continuación cuando sea relevante, y vuelva a intentarlo. El rescanning mantiene el alias ingresado pero requiere una nueva revisión de huellas dactilares antes de conectarse. + + + +## Conecte este equipo como un Child + +En el equipo que debe utilizar los proveedores de Home: + +1. Abra el panel de control en `#remote` y activar el enlace remoto. +2. Elija **Child**. Se abre la lista de hosts SSH. +3. Elija el host SSH del Home, ejecute la prueba de conexión, luego compare y confirme su huella digital del host. +4. Lea el aviso y elija **Conectar como Child**. + +La conexión se reinicia OpenCodex en este equipo. Codex turnos que ya se están ejecutando terminan primero, y las nuevas solicitudes pueden fallar hasta por un minuto mientras se reinicia. El tablero de instrumentos se recarga por sí mismo y muestra el enlace Child. Codex sigue usando `http://127.0.0.1:/v1` en este equipo, sin token y sin variable de entorno para establecer: el local OpenCodex retransmite cada solicitud al Home, que le sirve con sus propios proveedores y cuentas. + +El Child espera su puerto configurado mientras el proceso anterior lo libera. Si aún falla un reinicio administrado CLI, ejecute `ocx start` en el Child y verifique `~/.opencodex/restart-handoff.log`. En la aplicación de escritorio, la aplicación inicia y supervisa el reemplazo automáticamente. + +Si el **Child** dice emparejar esta máquina primero, abra el panel de control HTTP de loopback literal configurado de este equipo, por ejemplo, `http://127.0.0.1:`. El formulario de emparejamiento local aparece solo cuando falta el emparejamiento y el panel de control y el API usan el mismo origen de bucle invertido. Copie el comando `ocx gui pair --origin "http://127.0.0.1:"` del formulario, ejecútelo en un terminal en este equipo y pegue el código de un solo uso en el formulario. Use el origen exacto que se muestra en el formulario; una clave o token de administrador API del proveedor no es un código de emparejamiento. El emparejamiento faltante es independiente de un desajuste de puerto configurado. + +En un panel de Hub abierto a través de una dirección que no sea de loopback, es posible que el navegador no tenga sesión de loopback o que tenga una sesión compartida que no pueda administrar los enlaces de la máquina. Cuando Remote Link informe de ese problema de sesión o permiso, seleccione **Conecte este panel al concentrador** en la página Enlace remoto para abrir el formulario de emparejamiento único. Ejecute el comando mostrado en el Hub e introduzca su código. La página valida el acceso de enlace remoto de la nueva sesión antes de que cierre el formulario. + +El rol **Child** también requiere un entorno de ejecución independiente OpenCodex que se ejecuta en su puerto configurado, porque el Child se reinicia exactamente en ese puerto. Si el panel de control dice que OpenCodex no se está ejecutando en su puerto configurado, reinicie allí primero. + + + +## Estado del enlace + +- **Conectado** significa que el túnel SSH está listo y el Child puede usar el enlace Home. +- **Reconexión** significa que el túnel está siendo reintentado. Las solicitudes pueden devolver temporalmente `503` con `Retry-After` mientras el reintento está en curso. En un Child que se conectó desde su propio tablero de instrumentos, una solicitud primero espera hasta 15 segundos para que regrese el túnel. +- **Fallido** significa que el enlace necesita atención. Revisa la autenticación SSH, la clave de host confirmada, el reenvío y el motivo que muestra el dashboard. Quien ejecuta el túnel sigue reintentando tras una suspensión, interrupción o reinicio: Home para un Child que añadió y Child para un enlace iniciado desde su propio dashboard. Tras un timeout o error de reenvío, espera un minuto y duplica la espera después de cada nuevo fallo, hasta cinco minutos. Los errores de autenticación se reintentan cada cinco minutos; una clave de host cambiada nunca se reintenta. Para forzar otro intento, elige **Reintentar** en el dashboard del Home o ejecuta allí `ocx link reconnect --link-id `. Esto reinicia el túnel del enlace, sin reiniciar OpenCodex. + +Un enlace fallido no cambia silenciosamente a un proveedor local. El Child devuelve un `503` reintentable sin reenviar la clave de enlace o solicitud cuando su túnel falla, se detiene o no se supervisa. También mantiene la clave local cuando otro proceso posee el puerto del túnel; libre ese puerto para que el túnel SSH del Child pueda enlazarlo. + +En un Child, `GET /healthz` solo indica que OpenCodex se está ejecutando. `GET /readyz` y `ocx ready` también comprueban si el enlace puede transportar una solicitud. Si no puede, la respuesta es `503` con `Retry-After: 1`, `"status": "pending"` y un objeto `link`, por ejemplo `{ "state": "unavailable", "reason": "home_unreachable" }`. Si puede, responde `200`, `"status": "ready"` y `{ "state": "available" }`. Los motivos posibles son `tunnel_connecting`, `tunnel_failed`, `tunnel_idle`, `tunnel_unavailable`, `sidecar_invalid`, `home_unreachable`, `home_unauthorized`, `link_auth_failed`, `link_credential_unavailable` y `link_unverified`. Un Child enlazado desde su propio dashboard consulta su túnel. Si el Home añadió el Child, este no tiene un túnel propio que inspeccionar: consulta al Home por el túnel con la misma comprobación sin credenciales que precede a cada solicitud reenviada, como máximo una vez cada cinco segundos. Si el Home no responde en medio segundo, informa `link_unverified`. + +Para confirmar qué Home atiende a un Child, compara el encabezado `x-opencodex-served-by` de `GET /v1/models` del Child con `instanceId` de `GET /healthz` del Home. El Child retransmite el encabezado sin cambios, por lo que los valores coinciden mientras el enlace funciona. Es un identificador opaco, nunca un nombre de equipo; consulta [Identidad del Home y encabezado served-by](/es/reference/management-api/#home-identity-and-the-served-by-header). + + + +## Lo que un Child muestra y administra + +Un Child se ejecuta en los proveedores, cuentas y configuraciones del Home, por lo que el Home es donde los cambia. + +- **Tablero.** El tablero de mandos del Child muestra el estado de solo lectura del Home y dice "Administrado por Home a través de enlace remoto". El panel de control y los proveedores leen el Home a través del enlace, y la franja de uso en el encabezado muestra la cuota del Home. La lista de modelos no se muestra en un Child, porque al construirlo se ejecuta el descubrimiento de proveedores en el Home; Codex en el Child ya ofrece los modelos Home. Por la misma razón, los selectores de modelos de delegación y sidecar en un Child enumeran los modelos nativos y las opciones actuales del Home, no la lista completa de rutas del Home. Guardar un cambio allí se rechaza con un mensaje que nombra el Home; hacer el cambio en el tablero de Home. El navegador del Child nunca recibe una credencial Home. +- **Codex ajustes.** `ocx sync` en el Child (y conectándolo) se aplica la configuración Codex OpenCodex se gestiona en el Home: Modo rápido, el modo multiagente, el conmutador de sidecar de búsqueda web y el subagente nativo por defecto cuando el Home los sincroniza. `ocx sync` y `ocx status` listan los valores que vinieron del Home. El esfuerzo de razonamiento predeterminado y los niveles de esfuerzo que se muestran en el selector de modelos de la aplicación Codex son la configuración de la aplicación Codex en cada computadora; OpenCodex no los administra en ningún ordenador. +- **CLI.** Las órdenes que solo leen, como `ocx account list`, `ocx provider quota` y `ocx usage`, leen el Home. Muestran lo que el Home ya ha observado: una lectura de un Child nunca hace que el Home sondee a un proveedor, actualice un token o inicie un proceso, por lo que los detalles de la cuota y la cuenta son tan frescos como la propia actividad del Home los mantiene. Las lecturas que solo existen para ejecutar el descubrimiento del proveedor o una actualización forzada, como `ocx models live`, `ocx models preset show` y `ocx account list --quota`, se rechazan como cambios. Los comandos que cambian la configuración son rechazados con un mensaje que nombra el Home y el enlace y dice que no se envió ninguna solicitud. `ocx status` describe el Home y el enlace. `ocx provider list` y `ocx config get` todavía muestran la propia configuración de este ordenador, etiquetada como local e inactiva mientras el ordenador está enlazado. `ocx config set`, `ocx config unset` y `ocx config import` todavía escriben localmente, cada uno con la misma nota, y `ocx provider add`, `remove` y `set-default` son rechazados porque esos proveedores no se utilizan mientras están vinculados. + +Estas lecturas necesitan una versión OpenCodex con el relé de gestión de enlace remoto tanto en el Home como en el Child. Un antiguo Home responde con un mensaje pidiéndote que lo actualices. + + + +## Eliminar un archivo Child + +Seleccione **Desconectar** para el Child y confirme el alias. El Home detiene el túnel, revoca la clave de enlace de ese Child y elimina el registro de enlace guardado. + +Si el Home no puede alcanzar el Child para ejecutar su comando de desconexión, elija **Eliminar aquí solamente**. Esto elimina el túnel local, la clave y el registro. A continuación, inicie sesión en el Child y ejecute: + +```bash +ocx disconnect +``` + +Para desconectar un enlace iniciado por Child, ejecute `ocx disconnect` en el Child. Desconecta el túnel del cliente y revoca el enlace en Home sobre SSH. Si la revocación Home falla, se imprime: `Home revoke failed; run ocx link revoke --link-id on the home.` + + + +## Solución de problemas + +Cuando un paso falla, el panel de control muestra la razón y, cuando SSH informó de uno, una breve pista desinfectada de su última línea de error no vacía debajo del mensaje. Los errores de shell remoto pueden aparecer allí incluso cuando el shell remoto emite texto que no es UTF-8; OpenCodex elimina los controles de terminal, las claves de enlace y las consultas de URL y limita la longitud de la pista. + +- **No se pudo conectar al host SSH**: el host debe aceptar su clave SSH sin una solicitud de contraseña; `ssh -o BatchMode=yes true` debe tener éxito desde una terminal. Un ayudante `ProxyCommand` como `cloudflared` debe instalarse en `/opt/homebrew/bin`, `/usr/local/bin`, `~/.bun/bin`, `~/.local/bin` u otro directorio en el PATH OpenCodex se ejecuta con. +- **ocx no se encontró en el equipo remoto**: OpenCodex busca `ocx` en el CAMINO de una sesión SSH no interactiva primero, luego en `~/.bun/bin`, `~/.local/bin`, `/opt/homebrew/bin` y `/usr/local/bin`. Si está instalado en otro lugar, agregue ese directorio a PATH en un archivo que el shell remoto lee para sesiones no interactivas, como `~/.zshenv` para zsh. +- **OpenCodex en el equipo remoto es demasiado viejo**: ejecute `ocx update` en ese equipo. El enlace remoto necesita 2.66.0 o posterior. +- **La computadora remota no reportó una versión OpenCodex**: `ocx --version` en ese equipo imprimió otra cosa, por ejemplo, el texto de uso de una instalación Windows no compatible. + +- **Las solicitudes fallan con `home_unreachable` cuando el Home no está disponible**: un Child nunca atiende solicitudes con sus proveedores locales. Si el túnel ya estaba caído antes del reenvío, devuelve un 503 reintentable y no envía nada al Home. Si el túnel se corta después de iniciar el reenvío, también devuelve `home_unreachable`, pero el Home puede haber recibido la solicitud. Un fallo de autenticación del relé devuelve `link_relay_auth_failed`: actualiza el Home y el Child o vuelve a enlazarlos. El permiso por dispositivo en la página **Remote Link** del Home, o `ocx fallback local on --device `, determina si GOAT puede usar las sesiones locales de ese dispositivo; consulta [Desactivar el fallback](/es/guides/fallback-off/). + +- **Un enlace iniciado por Home sigue Fallido por un error de reenvío después de una suspensión o un cambio de red:** ejecuta `ocx link status --json` en el Home. El campo `tunnel` muestra los intentos desde la última conexión, `nextRetryAt` y el fallo más reciente. Si `lastFailure.cause` es `remote_forward_conflict`, el servidor SSH del Child aún reserva el puerto de la sesión que perdió la conexión anterior del Home. Los nuevos túneles se rechazan hasta que libere ese puerto. OpenCodex sigue reintentando y se conecta cuando queda libre; nunca detiene procesos del Child. El servidor SSH detecta la sesión muerta al comprobarla. Sin `ClientAliveInterval` en `sshd_config` del Child, puede tardar lo que el keepalive TCP del sistema: dos horas por defecto en macOS. Configurar allí `ClientAliveInterval 15` y `ClientAliveCountMax 3` permite descartarla en aproximadamente un minuto. + + + +### Diagnósticos de respuestas 503 reintentables + +Un `503` generado por el relay incluye `x-opencodex-link-request-id`, creado por el servidor. Permite correlacionar el fallo con la evidencia local del Child en `link/diagnostics.jsonl` y su copia rotada `link/diagnostics.jsonl.1`, bajo el directorio de configuración de OpenCodex. Cada archivo tiene un límite de 256 KiB y permisos privados: directorio 0700 y archivos 0600 en POSIX, ACL privadas en Windows. Los registros solo contienen categorías fijas de evento, resultado y estado, identificadores de correlación generados, tiempos, generaciones, intentos numéricos y marcas de tiempo. No incluyen secretos, cuerpos de solicitud, encabezados, URL, identificadores de cuenta ni errores sin filtrar. Cada par evento/resultado se limita a un registro por segundo y el siguiente incluye cuántos se suprimieron: la ausencia de un registro no prueba que no hubiera un fallo. Si el reloj retrocede, se inicia otra ventana de limitación conservando ese recuento, incluso con la cola llena. El escritor asíncrono admite hasta 56 registros pendientes, cuenta el exceso como suprimido y cede la ejecución durante el trabajo de ACL en Windows. Registrar es una operación de mejor esfuerzo y no cambia la admisión de solicitudes. El apagado por señal y el reciclado independiente esperan hasta un segundo para vaciar la cola; el almacenamiento bloqueado, el cierre forzado o la pérdida de energía pueden hacer que se pierdan registros. + +`owner_lookup` registra comprobaciones de propiedad rechazadas; las correctas ordinarias no se registran. `owner_lookup.elapsedMs` mide solo la consulta de propietario. En `auth_timeout`, los eventos `relay_retry` y `relay_failure` informan la duración real del intento de transporte en `elapsedMs`, normalmente unos cinco segundos. `relay_recovered` con resultado `recovered` solo se emite cuando un reintento recibe una respuesta del proveedor con `upstream.ok`, HTTP 2xx; no demuestra que el cuerpo transmitido haya terminado. Por la limitación de frecuencia, la correlación por identificador es evidencia muestreada y no un seguimiento garantizado de todos los fallos. + +El Home escribe el mismo tipo de archivo para los túneles que ejecuta. Cada transición de un túnel iniciado por Home genera `tunnel_transition`, con `previousState`, `state`, causa en `outcome` (`auth`, `hostkey`, `forward`, `remote_forward_conflict`, `timeout`, `network`, `unknown`, `spawn_failed` o `listener_unavailable`; `connected`, `spawned` o `stopped` si no hubo fallo), el número de `attempt` desde la última conexión, `tunnelPort` y `retryAfterMs` si se programa otro intento. También se registra cada reintento fallido de un enlace ya fallido. La misma limitación de frecuencia se comparte entre todos los enlaces. + +Antes de enviar datos, OpenCodex permite un único reintento previo compartido entre el timeout de consulta de propietario y un timeout de autenticación de cinco segundos identificado expresamente. Obtiene una prueba nueva de propietario cuando corresponde y un socket físico nuevo, que autentica antes de enviar la credencial del enlace o el cuerpo. No reutiliza una aprobación anterior de propietario, ni omite controles, ni reinicia SSH u OpenCodex, ni vuelve a enviar un cuerpo ya despachado. Los límites de dos segundos para propietario y cinco para autenticación siguen aplicándose a cada intento. Otros fallos no admiten este reintento previo. + +Esto puede recuperar esos timeouts transitorios y aportar diagnósticos para fallos posteriores. No demuestra la causa histórica de [#7297](https://github.com/lidge-jun/opencodex/issues/7297). + + + +## Seguridad + +El Child utiliza los proveedores de la computadora Home y las credenciales del proveedor a través del enlace. El Home crea una clave de enlace separada para cada Child; la eliminación del enlace revoca esa clave. En el Child, la clave permanece dentro de OpenCodex: las credenciales que Codex o Claude Code envían allí no se reenvían al Home, incluidos Bearer, Azure `api-key`, Anthropic -compatible `x-api-key` y Google `x-goog-api-key`. Cualquier programa en el Child que alcanza `127.0.0.1:` utiliza el Home sin una llave, la misma confianza local que da una instalación independiente. Las páginas web de otros sitios son rechazadas. Compare la huella digital del host antes de la confirmación para que no se acepte por error una máquina incorrecta o una clave de host modificada. Las sesiones del panel de control emitidas desde una identidad de Tailscale no pueden administrar enlaces de máquina. + + + +## Referencia CLI + +```text +ocx link probe [--json] +ocx link add [--expect-fingerprint SHA256:…] [--json] +ocx link port [--json] +ocx link issue --alias --tunnel-port [--json] +ocx link status [--json] +ocx link revoke --link-id [--json] +ocx link reconnect --link-id [--json] +``` + + + +## Guías relacionadas + +- [Implementación remota de Hub](/es/guides/remote-hub/) +- [Espacio de trabajo remoto](/es/guides/remote-workspace/) + + + +### Compatibilidad con autenticación de relés + +Actualice tanto el Home como el Child cuando actualice a la autenticación de retransmisión vinculada a la conexión. Antes de enviar una credencial o cuerpo de enlace de una solicitud retransmitida, el Child verifica el Home en la misma conexión que utilizará para esa solicitud. Una conexión cerrada no se reemplaza silenciosamente. Un Home sin este protocolo causa un error de autenticación reintentable; actualizar el Home y Child, y volver a vincular cuando el enlace almacenado ya no se reconoce. No hay un interruptor de reserva inseguro. Una rotación pendiente pendiente de API sigue siendo válida hasta que expire o la rotación se confirme o se aborte. + +Eliminar los drenajes finales de enlace Home pendientes de solicitudes de retransmisión autenticadas antes de liberar su oyente. Detener el proceso aún cancela las conexiones activas. Esto no cambia qué credenciales de llamada se eliminan o qué rutas se pueden retransmitir, y no reemplaza la verificación de clave de host de SSH. + + + + +### Versiones del Home y del Child + +En el Home, `ocx link status --json` informa la versión `local` del Home, la versión de autenticación del relé y sus capacidades, y añade un bloque `peer` a cada enlace. No consulta nada por SSH: el Home aprende esos datos mediante la comprobación de autenticación que el Child envía antes de cada solicitud retransmitida. Desde 2.91.0, esa comprobación también contiene la versión y las capacidades del Child. El Home guarda lo aprendido en memoria; tras reiniciarlo, un enlace muestra `unknown` hasta que su Child retransmita otra solicitud. + +| Parte del enlace | Primera versión | +|---|---| +| `relay-auth/2`, autenticación del relé vinculada a la conexión | 2.69.0 | +| `link-management-relay`, administración de solo lectura del Home desde el Child | 2.84.0 | +| `link-peer-report/1`, el Child informa su versión y sus capacidades | 2.91.0 | + +`peer.compatibility` puede ser: + +- `compatible`: las versiones de autenticación del relé coinciden y el Home ofrece todas las capacidades declaradas por el Child. Un Child anterior a 2.91.0 no informa su versión: `peer.version` es `null` y `peer.versionRange` indica el intervalo deducido de la autenticación del relé, por ejemplo `{ "min": "2.69.0", "below": "2.91.0" }`. +- `degraded`: el Child declara una capacidad que el Home no ofrece. Actualiza el Home. +- `incompatible`: el Child solicita una versión de autenticación que el Home no admite, por lo que sus solicitudes se rechazan. `peer.reasons` indica qué lado actualizar. +- `unknown`: el Child no ha retransmitido solicitudes desde que arrancó el Home, o declaró una versión o lista de capacidades ilegible, por lo que no se puede comprobar su compatibilidad. + +La versión que declara el Child es una afirmación propia vinculada a su clave de enlace. OpenCodex solo la usa para mostrar información, nunca para autorizar solicitudes. Las instalaciones antiguas de `ocx` siguen recibiendo el documento de estado anterior: solo la CLI 2.91.0 o posterior solicita estos campos. + + + +### Autorización de emparejamiento independiente + +El comando `ocx gui pair --origin ` existente funciona mientras que OpenCodex se ejecuta como un servicio en segundo plano. Ejecutarlo bajo la cuenta que posee la casa privada OpenCodex del servicio, a continuación, introduzca el código de un solo uso devuelto en el panel de control local. No se requiere ningún terminal de servidor, contraseña adicional, Windows Hello o clave de hardware. El CLI y el servidor deben usar la misma versión actual y configuración doméstica; reinicie un servidor anterior después de la actualización. Las invitaciones a Hub de versión mixta también requieren actualizar el CLI y el servidor juntos. El emparejamiento rechaza un directorio de inicio o intent de configuración sincronizada; use el directorio protegido real como `OPENCODEX_HOME`. + +Internamente, el CLI crea un compromiso de autorización de corta duración e intenta eliminarlo después de su uso o falla. La lectura de la información en entorno de ejecución por sí sola no autoriza el emparejamiento, y el verificador no se almacena en el disco. Este es un límite de acceso de escritura privado-doméstico, no biométrico o autenticación de presencia humana: un programa con acceso completo a los archivos de ese usuario sigue siendo de confianza. La autorización de invitación de Hub existente no se modifica. Si una solicitud de emparejamiento falla, ejecute un comando nuevo después de resolver el problema reportado. Esto no agrega soporte para Windows SSH Remote Link. + +Si un proceso se interrumpe durante el emparejamiento, vuelva a ejecutar el comando para obtener una nueva autorización. No elimine manualmente el estado de emparejamiento mientras se ejecuta el servicio o un comando de emparejamiento. + +En Windows, el emparejamiento se rechaza si la carpeta de intención o el registro no es privado de la cuenta de servicio, o si su propietario y los permisos no se pueden verificar. Ambas entradas deben ser propiedad de esa cuenta; La propiedad de los administradores solo se acepta cuando los administradores son el propietario predeterminado del token de servicio y su función de administrador está habilitada. La lista de permisos debe estar protegida de la herencia y contener una entrada de permiso de control total ordinaria para la cuenta servidora. Además de eso, solo se aceptan entradas de permiso simple para SYSTEM y el grupo Administradores, porque SYSTEM y un administrador elevado ya pueden tomar posesión de cualquier archivo; un administrador no elevado no gana nada de esa entrada. Solo en la carpeta se permite la herencia hacia los elementos descendientes. Esta es la lista como Windows lo informa: las entradas duplicadas compatibles para el mismo recuento de cuentas que uno, y las entradas que no conceden nada se ignoran. El cheque deja registros rechazados en su lugar y no repara sus permisos ni cambia la propiedad. Restaurar una casa de configuración privada y, a continuación, ejecutar un nuevo comando de emparejamiento. + +La comprobación cubre la carpeta de intención y el registro. No protege contra el reemplazo de carpetas anteriores, derechos de eliminación en una carpeta principal, operaciones de restauración con privilegios o acceso a través de identificadores abiertos antes de que los permisos se vuelvan privados. Una solicitud con un compromiso coincidente puede bloquear el servidor durante un subproceso de verificación limitado a cinco segundos, incluso si su carpeta falla más tarde en la verificación de permiso. La configuración de inicio de proceso y búsqueda ejecutable precede a ese tiempo de espera. CLI limpieza puede realizar una verificación más. El presupuesto de subproceso de cinco segundos deja espacio dentro del tiempo de espera de solicitud de diez segundos del comando, pero la verificación lenta aún puede rechazar el emparejamiento. + + + +## Agregar un Child desde el terminal + +En el Home, ejecute `ocx link probe child-a --json` para inspeccionar la huella digital SSH ofrecida, el tipo de clave y la versión OpenCodex. Verifique la huella digital a través de una fuente confiable. A continuación, ejecute `ocx link add child-a --expect-fingerprint SHA256:… --json`. El comando sondea de nuevo y rechaza un desajuste antes de almacenar la confianza o emitir una clave. Sin el indicador de huella dactilar, requiere un terminal interactivo y un `yes` explícito después de mostrar la huella dactilar. Nunca imprime la clave de enlace. + +Home -las conexiones iniciadas ahora reinician el Child después de guardar su conexión, incluidas las instalaciones Child más antiguas y capaces. El Child ya debe servir independiente OpenCodex en su puerto configurado, exponer el soporte de reinicio vinculado y tener curl instalado. Actualice o desconecte un Child que no cumpla con este preflight. Las instalaciones de escritorio y de sistema OpenCodex tienen prioridad sobre las shims PATH genéricas; se omiten los candidatos rotos. Windows Los niños siguen sin recibir apoyo. + + + +### Equipos Windows + +`ocx link add` y el dashboard rechazan un equipo Windows durante el sondeo o la confirmación del host, antes de emitir una clave de enlace o iniciar un túnel. Esto incluye Windows OpenSSH con Git Bash, MSYS2 o Cygwin como shell (`uname -s` informa MINGW, MSYS o CYGWIN), y con cmd o PowerShell. Conecta esos equipos en modo Hub: ejecuta `ocx hub invite` en un Hub y el comando `ocx connect` que muestre en el equipo Windows. + +Un Windows Child enlazado por una versión anterior conserva su enlace. Ejecuta `ocx link cleanup` en el Home para localizar esos enlaces; añade `--link-id ` para revisar uno o `--json` para obtener un informe estructurado. Consulta la plataforma de cada Child iniciado por el Home mediante la confianza SSH fijada para ese enlace y no cambia nada. Para cada Windows Child, indica este orden de recuperación: ejecutar `ocx disconnect` y `ocx restart` en Windows; después, `ocx link revoke --link-id --force --yes` en el Home; por último, conectarlo en modo Hub. Una revocación normal falla en esos Children porque la desconexión remota ejecuta un comando POSIX que Windows rechaza. + +Reiniciar espera los giros y puede tardar varios minutos. El éxito requiere que el Child reiniciado cumpla con el rol de cliente y transmita un nuevo catálogo completo a este Home. La configuración de SSH tiene una asignación limitada derivada de la latencia medida; la verificación del relé comienza después del reinicio con su propia ventana de 15 segundos. Los errores nombran la fase fallida. Si un error informa la configuración residual Child, ejecute `ocx disconnect` y `ocx restart` en ese Child antes de volver a intentarlo. Home limpieza por sí sola no restaura Child configuración. Un tiempo de espera CLI reporta un resultado incierto; inspeccione Home `ocx link status` y Child `ocx connect status` primero. + +En un Child Home -iniciado, `ocx link status` informa el rol `child`, la identidad del enlace y el puerto del túnel de su conexión guardada, aunque su almacén de enlaces Home está vacío. El estado del túnel no observado localmente es `idle`. `ocx status` llama al par un enlace remoto Home. Cuando Home se ejecuta en el modo Hub, el estado lee su proyección soportada a través del relé local Child. Un Home independiente informa que no publica el estado de Hub. Child -la identidad del túnel iniciada proviene de su vagón lateral válido; la evidencia ilegible no reclama una dirección. diff --git a/docs-site/src/content/docs/es/guides/remote-workspace.md b/docs-site/src/content/docs/es/guides/remote-workspace.md new file mode 100644 index 00000000000..bab22c0a6b1 --- /dev/null +++ b/docs-site/src/content/docs/es/guides/remote-workspace.md @@ -0,0 +1,184 @@ +--- +title: "Espacio de trabajo remoto" +description: "Mantenga Codex, Claude Code, Pi y sus inicios de sesión en un concentrador OCX mientras que los equipos solo OCX proporcionan el espacio de trabajo y el entorno de compilación." +--- + +Para enlaces de máquinas SSH, véase [Enlace remoto](/es/guides/remote-link/). + +Remote Workspace permite que un OpenCodex Hub ejecute sus agentes de codificación, mientras que otro equipo suministra los archivos del proyecto, comandos, pruebas y compilación. Un teléfono o un tercer ordenador pueden controlar la sesión a través del panel de control de Hub. + +```text +Phone browser -> Computer 1 OCX Hub -> encrypted channel -> Computer 2 OCX Executor + Codex / Claude / Pi project and commands + logins and sessions no coding CLI login +``` + +El ejecutor solo necesita OpenCodex. No necesita Codex, Claude Code, Pi, un inicio de sesión ChatGPT o una clave API del proveedor. Abre un WebSocket saliente al concentrador, por lo que el ejecutor no necesita ningún puerto público o router. + +:::caution[Base experimental] +Remote Workspace requiere activación explícita y todavía no es un despliegue de producción. Linux ofrece herramientas de archivos y ejecución condicional de comandos mediante bubblewrap. Windows y macOS solo ofrecen herramientas de archivos: sus auxiliares nativos oficiales rechazan tanto las pruebas como las solicitudes de comandos. Los comandos de Windows seguirán sin admitirse hasta contar con un responsable verificado del ciclo de vida que conserve la autoridad de limpieza incluso durante la cancelación. Los comandos no admitidos se rechazan y nunca se ejecutan como alternativa en el Hub. +::: + + + +## Compatibilidad con RPC y tiempos de espera + +El espacio de trabajo remoto utiliza RPC v2 encriptado. El Hub y cada Ejecutor deben soportar v2; Los pares de RPC v1 fallan en lugar de volver a la ejecución inmediata, así que actualice el concentrador y los ejecutores juntos. + +Un tiempo de espera solicita la cancelación del ejecutor, pero no lo confirma. Una subvención puede estar ya en tránsito, o su funcionamiento puede estar ya en ejecución. El tiempo de espera predeterminado de RPC es de 65 segundos, y `timeoutMs` acepta valores inclusivos de 1 a 120,000 milisegundos. + + + +## Configurar el Hub + +El ordenador 1 posee cada inicio de sesión de agente de codificación y cada sesión de modelo. Instale e inicie sesión en los agentes que desee usar allí, luego ejecute OpenCodex como un Hub: + +```bash +ocx config set runtimeRole hub +OCX_REMOTE_WORKSPACE_ENABLED=1 ocx start +ocx gui +``` + +Configure `OCX_REMOTE_WORKSPACE_ENABLED=1` en el proceso Hub en sí; configurarlo solo para un comando de panel de control no habilita un servicio ya en ejecución. Un Hub sin opt-in explícito devuelve el estado deshabilitado sin crear claves de espacio de trabajo ni sondear los tiempos de ejecución del agente de codificación. + +Utilice una implementación HTTPS autenticada cuando abra el panel de control desde un teléfono u otro equipo. Véase [Implementación remota de Hub](/es/guides/remote-hub/) para el patrón de integración de gestión y Tailscale admitidos. No publique un puerto de panel local no autenticado. + +Codex Remote Workspace utiliza los perfiles de permisos actuales de App Server. Si la configuración seleccionada del Hub Codex todavía establece el legado `sandbox_mode` o `sandbox_workspace_write`, el panel de control informa que Codex no está disponible en lugar de comenzar con un límite más débil. Migre ese perfil Codex antes de usar la función; no configure tanto el sandbox heredado como un perfil de permisos. + + + +## Inspeccione el Hub sin iniciar una sesión + +```bash +ocx remote-workspace hub --help +ocx remote-workspace hub status --json +ocx remote-workspace hub runtimes --json +ocx remote-workspace hub sessions --json +``` + +Estos utilizan el concentrador de gestión en ejecución seleccionado. El `remote-workspace status` existente sigue leyendo el estado del Ejecutor local. Devuelve el estado `{available:true,devices,runtimes,sessions}`; devuelve el entorno de ejecución `{runtimes:{codex:{available,...},claude:{available,...},pi:{available,...}}}`; devuelve las sesiones `{sessions:[...]}`. La disponibilidad en entorno de ejecución es un objeto, no una matriz, y su comprobación puede probar la disponibilidad ejecutable. Las raíces del dispositivo exponen los ID y las etiquetas, no las rutas del sistema de archivos del Ejecutor. Las sesiones incluyen eventos públicos recientes; la salida del terminal humano escapa a los caracteres de control. + +Un concentrador disponible con el dispositivo/sesión vacío muestra las salidas 0. Cuando la activación de Hub está desactivada, el despachador externo puede devolver HTTP 200 con `available:false`, dispositivos y sesiones vacíos y `runtimes:{}`. El CLI emite esa estrecha observación no disponible con una instrucción de activación / concentrador fija y sale 1. No presenta indisponible como éxito vacío. Un no Hub interno HTTP 409 devuelve la salida 5 con guía stderr; el rol de cliente, el transporte y las respuestas mal formadas también siguen fallando. + +Compruebe el Hub previsto y su activación `OCX_REMOTE_WORKSPACE_ENABLED=1` cuando no esté disponible; no cambie silenciosamente la configuración como recuperación. Estas observaciones no autorizan ni realizan emparejamientos, creación de sesiones, solicitudes, revocación o cambios de confianza. Esos siguen siendo los flujos de trabajo separados del panel de control / sesión a continuación. + + + +## Emparejar a un ejecutor + +1. Empareje el navegador con el Hub a través del panel de control. Ejecute el comando `ocx gui pair --origin` mostrado en el concentrador e introduzca su código de una sola vez; una sesión local o de Tailscale automáticamente iniciada puede ver el estado pero no puede controlar el espacio de trabajo remoto. +2. Abra **Espacio de trabajo remoto** en ese panel de Hub emparejado. +3. Seleccione **Crear código de emparejamiento**. +4. En el equipo 2, cambie al directorio del proyecto que desea exponer. +5. Copie el comando **Terminal Linux / macOS** o **Windows PowerShell** generado para ese equipo. Empareja el directorio actual y mantiene conectado `ocx remote-workspace agent` en ese terminal. + +El flujo manual equivalente es: + +```bash +cd /path/to/project +printf '%s\n' 'ONE-TIME-CODE' | ocx remote-workspace pair 'https://your-hub.example' \ + --pairing-code-stdin --root "$PWD" +ocx remote-workspace agent +``` + +En Windows PowerShell, utilice el comando que se muestra en el panel de control. La forma manual equivalente es: + +```powershell +$pairingCode = 'ONE-TIME-CODE' +$pairingCode | ocx remote-workspace pair 'https://your-hub.example' ` + --pairing-code-stdin --root (Get-Location).Path +if ($LASTEXITCODE -eq 0) { ocx remote-workspace agent } +``` + +El ejecutable OCX Bun actual se agrega automáticamente como un archivo de solo lectura al sandbox Linux. Si el proyecto necesita una cadena de herramientas instalada por el usuario fuera de las rutas del sistema, empareje explícitamente sin exponer el resto del directorio principal: + +```bash +printf '%s\n' 'ONE-TIME-CODE' | ocx remote-workspace pair 'https://your-hub.example' \ + --pairing-code-stdin --root "$PWD" \ + --toolchain-root "$HOME/.nvm/versions/node/v24/bin" +``` + +La fuente de ayuda nativa está empaquetada para su revisión. Construirlo no habilita los comandos Windows o macOS en este transporte. `--executor-helper` sigue siendo un selector de ayuda revisada; la existencia binaria o una ruta configurada no prueban el soporte de comandos. + +El código de una sola vez se lee de la entrada estándar, no de los argumentos de la línea de comandos. El emparejamiento crea una clave de firma de dispositivo local y un portador con alcance de dispositivo. El Hub almacena solo su hash y nunca recibe la ruta real del Ejecutor. Detener el agente en primer plano con Ctrl+C; ejecutarlo nuevamente vuelve a conectar el mismo dispositivo. + +Compruebe la inscripción local sin imprimir secretos: + +```bash +ocx remote-workspace status +``` + + + +## Iniciar una sesión de codificación remota + +En el panel de control, elija: + +1. el ordenador en línea; +2. una carpeta de espacio de trabajo aprobada localmente; +3. Codex, Claude Code, o Pi desde el Hub; y +4. un modo de acceso. + +**Solo lectura** es el valor predeterminado y expone la lista de directorios y la lectura de archivos. La opción de escritura se muestra como **Editar archivos y ejecutar comandos** solo cuando el Ejecutor pasó una sonda de caja de arena de comandos; de lo contrario, se muestra como **Editar solo archivos**. El panel de control muestra dos ubicaciones separadas, por lo que está claro que el modelo y el inicio de sesión permanecen en el concentrador mientras se ejecutan las operaciones del espacio de trabajo en el equipo seleccionado. + +Envía mensajes desde el panel de Hub en el ordenador 1, el ordenador 3 o un teléfono. La sesión no puede cambiar a otro equipo o carpeta en silencio. Si el Ejecutor se desconecta, la sesión entra en **Ejecutor offline** y nunca vuelve al sistema de archivos del Hub. + +La presentación inmediata reconoce la aceptación de inmediato; el panel de control sondea la sesión para el progreso y la finalización. Si se pierde el acuse de recibo, el borrador permanece visible con un aviso de envío desconocido. Compruebe el progreso de la sesión antes de volver a enviarla; el panel de control nunca vuelve a intentar un mensaje automáticamente. + +**Detener** permanece disponible mientras se ejecuta un mensaje. Interrumpe el giro del agente de codificación Hub, cancela un comando activo del Ejecutor y evita que una respuesta tardía vuelva a abrir la sesión detenida. + + + +## Trabajar con sesiones lado a lado + +La lista de sesiones de la izquierda abre una sesión en el panel enfocado. Arrastre una sesión hacia la izquierda, derecha, arriba o abajo de otro panel para dividir el área de conversación. Puedes mostrar hasta cuatro sesiones diferentes a la vez. Una sesión ya visible se mueve entre paneles en lugar de abrir un compositor duplicado. + +Utilice **Dividir a la derecha** o **Dividir a continuación** junto a una sesión para la alternativa accesible por teclado. Arrastre un divisor para cambiar el tamaño de los paneles, o enfoque el divisor y use sus teclas de flecha. **Home** y **Fin** establecen el divisor en su tamaño mínimo y máximo. Cada sesión mantiene su propio borrador, estado de envío y acción Detener, por lo que un turno pendiente en un panel no bloquea una sesión diferente. **Cerrar panel** cambia el diseño solamente; no detiene la sesión. + +El diseño del panel se restaura para este Hub en el mismo navegador. Solo se guardan los identificadores de sesión y las posiciones del panel y los tamaños de los divisores; el texto borrador y la salida del modelo no se escriben en el almacenamiento del navegador. Recargar la página borra los borradores no enviados. En pantallas de hasta 760px de ancho, los paneles se apilan verticalmente sin redimensionar los divisores; las posiciones divididas y los tamaños guardados regresan cuando la pantalla es más ancha. + +Esta vista es compartida por el panel del navegador y el panel de escritorio OpenCodex. Los usuarios de CLI pueden abrir el panel de control con `ocx gui` y seleccionar **Espacio de trabajo remoto** después de su configuración normal de Hub. No cambia la interfaz del terminal de `codex` o el diseño de la conversación dentro de la aplicación de escritorio oficial separada ChatGPT / Codex. + + + +## Reiniciar y reconectar el comportamiento + +El concentrador mantiene los metadatos de sesión limitados y una pequeña instantánea de evento reciente. Después de un reinicio de Hub, una sesión inacabada espera a su Ejecutor original. Una vez que el dispositivo se vuelve a conectar, el siguiente mensaje reanuda el hilo original Codex, la sesión Claude Code o el identificador de sesión Pi. + +Claude Code crea su historia duradera en el primer aviso completado. Si el Hub se detiene antes de que una nueva sesión Claude haya completado algún mensaje, no hay conversación que reanudar; inicie una nueva sesión en su lugar. + +Un manifiesto de capacidad cambiado no debilita silenciosamente una sesión existente. Inicie una nueva sesión si el Ejecutor pierde la contención de comandos o si sus herramientas disponibles cambian. Revocar una computadora cierra su socket y detiene las sesiones vinculadas a él. + + + +## Límites de seguridad + +- Las credenciales del proveedor y el historial de agentes de codificación permanecen en el concentrador. +- Las claves privadas del ejecutor, el portador del dispositivo y las rutas raíz reales permanecen en su estado OCX solo de propietario. +- Los errores de código de emparejamiento están limitados por par observado por kernel en cada oyente. Diez códigos fallidos en diez minutos devuelven un `429` genérico con `Retry-After`; el Hub conserva solo hashes limitados y expirados de esas identidades de origen. Los usuarios de Tailscale Serve comparten el bucket de loopback del oyente de administración porque un llamador local directo podría falsificar su encabezado de identidad. +- Cada sesión de trabajo utiliza un protocolo de enlace efímero P-256 ECDH firmado por Ed25519, y pide mensajes AES-256-GCM. +- Un socket no se muestra como en línea hasta que ambas partes estén de acuerdo en su manifiesto de capacidad actual. +- La reconexión puede eliminar una capacidad cuando su sandbox local no está disponible, pero nunca agrega una capacidad fuera de la concesión registrada en el emparejamiento. +- Cada solicitud está vinculada a un hilo de modelo, dispositivo, raíz, modo de acceso y conjunto de capacidades. +- Las rutas son relativas, canónicas, limitadas y rechazadas en enlace simbólico, unión o escape de directorio padre. Windows nombres de dispositivos, flujos de datos alternativos y alias de espacio/punto final son denegados. +- Las operaciones del ejecutor se serializan, las identidades de archivo abiertas se vuelven a verificar y los hashes de escritura se vuelven a verificar inmediatamente antes del reemplazo atómico. Reemplazar una raíz aprobada requiere emparejarla de nuevo, y las raíces de la cadena de herramientas se revalidan antes de cada comando. +- Las lecturas/escrituras de archivos rechazan los archivos vinculados. Antes de la ejecución de comandos, OCX escanea un máximo de 250.000 entradas de espacio de trabajo y desactiva la ruta de acceso de los comandos si alguna entrada que no sea de directorio tiene varios enlaces; los sandboxes de ruta no pueden probar si el otro nombre de ese inodo está fuera de la raíz aprobada. +- Los comandos Linux se ejecutan a través de bubblewrap con un espacio de trabajo grabable, un entorno despejado, espacios de nombres de procesos privados, el ejecutable actual de OCX Bun como un solo archivo de solo lectura, salida y tiempo de espera limitados y red desactivada de forma predeterminada. Las pruebas de confinamiento dedicadas requieren un entorno alojado configurado explícitamente; un conjunto genérico verde no prueba que se ejecutaron. +- macOS solo anuncia herramientas de archivo. Un grupo de procesos no puede contener un descendiente después de que llame al `setsid()`, e importar un amplio perfil del sistema de cinturón de seguridad de Apple simplemente para iniciar un comando expondría una autoridad de servicio de host no relacionada. Por lo tanto, el ayudante nativo rechaza tanto sus solicitudes de sonda como de comando directo hasta que OCX tenga un propietario de contención descendiente estrecho y revocable. +- Las solicitudes nativas de comandos en Windows y macOS se rechazan. Las pruebas de rechazo del auxiliar directo deben distinguirse de la evidencia de confinamiento funcional de comandos; la aceptación de comandos en Windows sigue pendiente. +- El ayudante nativo anclado debe estar fuera de cada espacio de trabajo escribible aprobado. OCX comprueba esto tanto antes de la compatibilidad con comandos publicitarios como inmediatamente antes de cada comando, por lo que el código del espacio de trabajo no puede reemplazar al binario que hace cumplir su siguiente sandbox. +- Detener una sesión cancela un comando activo de Ejecutor y limpia el proceso del modelo Hub y el puente de herramientas de bucle invertido. Windows detiene el árbol de proceso de npm en lugar de dejar atrás a su hijo Node; Linux y macOS fuerza de parada un CLI sólo si se ignora la ventana de parada elegante. + +El Hub ve intencionadamente mensajes y salidas del modelo porque ejecuta el agente de codificación. El cifrado de extremo a extremo protege las cargas útiles de Executor RPC. Se confía en el concentrador emparejado para seleccionar raíces aprobadas sobre WSS autenticado; no es ciego a su propia conversación de modelo. + + + +## Alcance actual + +Remote Workspace no copia ni sincroniza credenciales con otros equipos. Está separado del enrutamiento del proveedor de Remote Hub y de cualquier futuro cómputo alojado o producto Super Sync. Una versión de producción aún requiere un paquete de ayuda firmado Windows, una prueba nativa de CI en los binarios exactos, una revisión independiente del mantenedor y una verdadera ejecución de aceptación de tres computadoras. + + + +## Rápida aceptación API + +`POST /api/remote-workspace/sessions/:id/prompt` devuelve HTTP 202 con la instantánea de sesión aceptada. Su ID de sesión y la secuencia de eventos monotónicos identifican la instantánea de aceptación; 202 no significa que el modelo se haya completado. Encuesta `GET /api/remote-workspace/sessions` para eventos posteriores y estado de la terminal. Reconectar y reanudar el entorno de ejecución permanecen ocupados mientras ese turno está activo. Un acuse de recibo perdido deja la aceptación desconocida, por lo que los clientes deben encuestar antes de elegir si enviar nuevamente. diff --git a/docs-site/src/content/docs/es/guides/response-inspection.md b/docs-site/src/content/docs/es/guides/response-inspection.md new file mode 100644 index 00000000000..7e07dc1c122 --- /dev/null +++ b/docs-site/src/content/docs/es/guides/response-inspection.md @@ -0,0 +1,22 @@ +--- +title: "Inspección de respuestas y grandes respuestas" +description: "Cómo interactúan la retención diagnóstica limitada y la inspección de transmisión con la entrega de respuesta." +--- + +OpenCodex mantiene los diagnósticos de respuesta limitados sin hacer que el límite de registro sea un límite en los bytes entregados a su cliente. Otros límites de proveedor, solicitud y transporte siguen aplicándose de forma independiente. + + + +## JSON y respuestas de error ordinarias + +La inspección JSON retiene como máximo 32 MiB de bytes fuente. Si el cuerpo excede esa asignación, el registro deja caer su copia retenida y continúa reenviando la respuesta original. No analiza un prefijo truncado como uso autorizado o metadatos del modelo. El uso ya suministrado por otra ruta de confianza se conserva; el uso faltante no se reemplaza con un cero inventado. Los diagnósticos de error ordinarios no JSON retienen solo los primeros 8 KiB y pasan a través de la lógica de redacción existente. + +El cliente recibe trozos a medida que los lee en lugar de esperar una inspección de diagnóstico de todo el cuerpo. Un fallo de lectura se registra como 502 y la cancelación como 499 en el historial de solicitudes; estos resultados de diagnóstico no reescriben las cabeceras HTTP que ya se han enviado. El registro se finaliza una vez. + + + +## Respuestas de streaming + +La inspección nativa SSE se detiene cuando se adelanta demasiado al consumo del cliente. La asignación es de 32 MiB más la sobrecarga de código fuente / nativo-prefetch, no un límite total de tamaño de respuesta o un límite en toda la memoria del proceso. Aún se inspecciona una respuesta más larga a través de su evento de finalización real, incluido el uso del terminal y el estado de continuación. + +Después de que el cliente se desconecta, el drenaje limitado existente aún puede observar una finalización tardía de hasta 15 segundos o 32 MiB de inspección adicional. Un cierre forzado es diferente: descarta candidatos no completados en lugar de registrarlos como una respuesta completa. La selección de transporte existente y los límites de memoria WebSocket no cambian. No se requiere ninguna configuración nueva. diff --git a/docs-site/src/content/docs/es/guides/routing-profile-editor.md b/docs-site/src/content/docs/es/guides/routing-profile-editor.md new file mode 100644 index 00000000000..16e68023c0a --- /dev/null +++ b/docs-site/src/content/docs/es/guides/routing-profile-editor.md @@ -0,0 +1,81 @@ +--- +title: "Editor de perfiles de enrutamiento" +description: "Cree, edite, valide, ejecute en seco y elimine perfiles de directivas de enrutamiento del panel de control de OpenCodex." +--- + +La pestaña **Modelos → Routing** en el panel de control OpenCodex puede administrar `config.routingProfiles` sin editar `config.json` a mano. + + + +## Crear un perfil + +1. Abra **Enrutamiento** en el panel de control. +2. Seleccione **Crear perfil**. +3. Introduzca un `id`. El modelo canónico id es `policy/`. +4. Agregue uno o más candidatos explícitos de proveedor/modelo. +5. Configure los requisitos opcionales, las ponderaciones de puntuación, los límites de costo (`onUnknownCost`, `maxEstimatedCostUsd`) y el comportamiento de evidencia desconocida. +6. Guardar el perfil. + +Los ID de perfil son inmutables después de la creación. Para usar un id diferente, cree un nuevo perfil y elimine el antiguo después de actualizar las llamadas. + + + +## Validación y persistencia + +El panel de control envía el mismo objeto de perfil utilizado por `config.routingProfiles` a la administración API. El servidor valida el candidato completo antes de escribirlo: + +- ids y alias deben seguir las reglas de nombres y colisiones de perfiles de enrutamiento; +- todos los proveedores candidatos deben existir y estar habilitados; +- Los candidatos duplicados son rechazados. +- Los límites y requisitos numéricos deben permanecer dentro de sus rangos admitidos; y +- al menos un peso de optimización debe ser positivo. + +Un guardado exitoso mantiene el perfil a través del escritor de configuración normal, reconcilia el estado en vivo y actualiza el catálogo de modelos. Los errores de validación dejan la configuración anterior sin cambios y se muestran en el editor. + +Cuando se configura `limits.maxEstimatedCostUsd`, `limits.onUnknownCost` se establece por defecto en `"allow"`: una estimación de costo desconocida no obtiene una exclusión específica de la tapa, y el sello `cost.capOutcome: "unknown-allowed"` de trazas de ruta de ejecución en seco / en vivo para que los operadores puedan decir que la tapa no fue probada. Establecer `"exclude"` cuando el techo debe fallar cerrado (`cost-limit-unknown`, con `cost.capOutcome: "unknown-excluded"`). La configuración de `onUnknownCost` solo es inerte y no emite un resultado de tapa. Esto es independiente de `unknownEvidence.cost`, que aún puede excluir o penalizar precios desconocidos independientemente del resultado del límite. + + + +## Ejecutar en seco un perfil guardado + +Las capacidades candidatas usan la configuración efectiva del proveedor después de que se aplican las anulaciones del registro. Por lo tanto, los requisitos locales (`localOnly` y `remoteAllowed`) utilizan la dirección de flujo ascendente efectiva. Si esa dirección no se puede clasificar, la configuración `unknownEvidence.capability` del perfil decide la elegibilidad. Una configuración de proveedor no válida que no se puede resolver siempre se excluye con `route-unavailable`, incluso cuando se permiten capacidades desconocidas. Los proveedores desaparecidos o desactivados también se excluyen con `route-unavailable` antes de anotar. + +Seleccione un perfil guardado y use **Evaluación en seco** para agregar evidencia de solicitud, como el tamaño de la ventana de contexto, el uso de herramientas, la entrada de imágenes o la salida estructurada. Dry-run evalúa la elegibilidad y la puntuación, pero nunca envía una solicitud de modelo ascendente. + +Las ediciones no guardadas no son usadas por dry-run. Guarde primero el perfil para que la revisión y la evaluación mostradas se refieran a la misma configuración. + + + +## API de administración + +El editor utiliza estos puntos finales: + +- `GET /api/routing-profiles` lista perfiles normalizados y revisiones. +- `PUT /api/routing-profiles` crea o actualiza un perfil. Envíe `mode: "create"` o `mode: "update"`; el modo create se niega a sobrescribir un id existente. +- `DELETE /api/routing-profiles?id=` elimina un perfil. +- `POST /api/routing-profiles/dry-run` evalúa un perfil guardado sin enviar aguas arriba. + +Ejemplo de guardar carga útil: + +```json +{ + "id": "fast", + "mode": "create", + "profile": { + "alias": "ocx/fast", + "candidates": [ + { "provider": "anthropic", "model": "claude-sonnet-5" }, + { "provider": "openai", "model": "gpt-5.6" } + ], + "require": { "tools": true, "minContextWindow": 128000 }, + "optimize": { "latency": 0.55, "health": 0.25, "cost": 0.1, "quota": 0.1 }, + "limits": { "maxEstimatedCostUsd": 0.5, "onUnknownCost": "allow" }, + "unknownEvidence": { + "capability": "exclude", + "health": "penalize", + "quota": "penalize", + "cost": "penalize" + } + } +} +``` diff --git a/docs-site/src/content/docs/es/guides/sidecars.md b/docs-site/src/content/docs/es/guides/sidecars.md new file mode 100644 index 00000000000..169989a929a --- /dev/null +++ b/docs-site/src/content/docs/es/guides/sidecars.md @@ -0,0 +1,149 @@ +--- +title: "Sidecars: búsqueda web y visión" +description: "Añade búsqueda web y comprensión de imágenes a los modelos enrutados mediante sidecars de ChatGPT, Anthropic y otros backends explícitos." +--- + +No todos los modelos enrutados ofrecen **búsqueda web alojada** o **entrada de imágenes** de forma nativa. opencodex cubre esas capacidades con dos sidecars. Ambos admiten una sesión de ChatGPT mediante un proveedor `forward` o credenciales Anthropic OAuth guardadas. La búsqueda también admite Grok OAuth con el backend `xai` seleccionado explícitamente. Los errores del sidecar se devuelven como resultados de herramienta o marcadores de imagen, sin hacer fallar todo el turno. + +:::note[Selección automática del backend] +La configuración explícita de `backend` tiene prioridad. Cuando no se configura, cada sidecar usa su propio valor predeterminado: +**Búsqueda web** usa `openai` por defecto; `anthropic` y `xai` solo se usan cuando se configuran explícitamente. El backend de búsqueda web `xai` requiere una cuenta Grok OAuth almacenada y utilizable, y no cambia a otro backend si esa cuenta no está disponible. +**Visión** usa `anthropic` cuando un proveedor Anthropic OAuth habilitado tiene una cuenta activa que no está marcada como `needsReauth`; de lo contrario, usa `openai`. Seleccionar `anthropic` explícitamente sin esa credencial rechaza la operación. Visión solo admite `openai`, `anthropic` y `routed`; los modelos de visión xAI elegibles usan `routed`. Para ambos sidecars, `openai` requiere autenticación de inicio de sesión ChatGPT y un proveedor `forward` habilitado. +::: + + + +### Backends de búsqueda web adicionales (solo explícitos) + +Además de ChatGPT y Claude, hay tres backends de búsqueda adicionales. Todos requieren **selección explícita**: encontrar una credencial no los activa. Si falta la credencial necesaria, no se crea un plan de sidecar ni se sustituye por otro backend; la solicitud sigue la ruta normal. + +| Backend | Ejecución | Credenciales | Notas | +| --- | --- | --- | --- | +| `xai` | Grok alojado `web_search` (+ opt-in `x_search` ) en `api.x.ai` Responses | Almacenado Grok OAuth (`ocx login xai`) | `webSearchSidecar.xSearch` permite la búsqueda X con `allowedXHandles` / `excludedXHandles` (máximo 20, mutuamente excluyentes) e ISO `fromDate` / `toDate`. Modelo predeterminado `grok-4.6`. | +| `gemini` | `google_search` puesta a tierra en el transporte Antigravity | Almacenado Antigravity OAuth con un proyecto descubierto (`ocx login google-antigravity`) | Modelo predeterminado `gemini-3.8-flash`; el razonamiento selecciona el nivel coincidente. | +| `exa` | Exa Search API (resumen de resultados no LLM) | `webSearchSidecar.exaApiKey` | La clave es solo escritura a través de la administración API (nunca se hizo eco, se redactó desde los registros). No se aplica ningún modelo de sidecar. | + + + +## Sidecar de búsqueda web + +Cuando Codex solicita `web_search` para un modelo enrutado sin paso, opencodex: + +1. **Sustituye** la herramienta alojada `web_search` por una función sintética `web_search(query)` que el modelo enrutado puede invocar. Conserva las opciones originales para la llamada al sidecar. +2. Ejecuta el modelo en un pequeño **bucle de agente**. Cuando llama a `web_search`, el sidecar OpenAI usa `web_search` con `gpt-5.6-luna` por defecto; el de Anthropic usa `web_search_20250305` con `claude-sonnet-5`. La respuesta y sus citas se convierten en un resultado de herramienta. El backend xAI usa la búsqueda alojada `web_search` con `grok-4.6` por defecto y añade `x_search` a la misma solicitud si está habilitado. +3. **Repite** hasta que el modelo responda o el total de consultas reales alcance `maxSearchesPerTurn` (3 por defecto). Al alcanzar el límite, retira la herramienta de búsqueda y solicita una respuesta final. Las llamadas a herramientas reales del cliente, como `apply_patch` o shell, terminan el turno para que Codex las reciba. + +Cuando el modelo agrupa varias consultas en una llamada `web_search`, sus resultados comparten un resultado de herramienta de 8.000 caracteres. El presupuesto se divide entre las consultas antes de que se corte nada, por lo que ninguna consulta desaparece del resultado. Las respuestas acortadas y las fuentes no listadas están marcadas con sus tamaños originales, lo que permite que el modelo indique los resultados recortados de las búsquedas que no encontraron nada. Los giros de salida estructurada reciben la misma información que un documento válido JSON. Si una llamada solicita más consultas de las que un resultado puede describir, opencodex enumera el estado de cada consulta sin su contenido y cuenta las consultas que no pudo enumerar. + +Cada iteración del modelo enrutado solicita `stream: true` al proveedor. Sin embargo, opencodex almacena por defecto todos los eventos semánticos antes de decidir si buscar o devolver la respuesta final. Solo obtiene de inmediato el estado y los encabezados finales de la primera iteración, junto con sus rotaciones de claves por 429. Las llamadas sintéticas de búsqueda y las salidas preliminares no se muestran al cliente como salida del modelo. + +La opción `webSearchSidecar.streamRoutedModelOutput`, desactivada por defecto (`false`), transmite en vivo los deltas iniciales de texto y razonamiento de cada iteración, igual que la ruta sin sidecar. Esa ventana de transmisión se cierra definitivamente al comenzar la primera llamada a herramienta; la decisión de interceptar `web_search` sigue siendo atómica y la reproducción final omite lo ya transmitido. Esto hace visible el texto emitido antes de decidir buscar, que el modo almacenado descartaría, y parte de ese texto puede repetirse en la respuesta posterior. La vista general ofrece **Transmitir respuestas en vivo** en la tarjeta de búsqueda web (`PUT /api/sidecar-settings`, campo `webSearch.streamRoutedModelOutput`). + +Esta opción también se aplica a los adaptadores que gestionan sus propios turnos, incluidos Devin y Cursor. Cuando los sidecars de búsqueda y de imagen/vídeo son elegibles, la búsqueda tiene prioridad. Un primer evento OAuth 429 gira la cuenta en la solicitud inicial y en cada solicitud de respuesta posterior a la búsqueda, reproduciendo la solicitud con la herramienta de búsqueda y los resultados recopilados. La cancelación de una solicitud detiene las búsquedas posteriores, y la salida del bucle de búsqueda retenido comparte el límite de la memoria intermedia de traducción de la solicitud; exceder ese límite falla la respuesta en lugar de iniciar otra iteración del modelo. + +El texto de la fase de comentario de Kiro es independiente de esta opción: ya se transmite antes del evento terminal en el modo almacenado. Con o sin `streamRoutedModelOutput`, solo se retienen los eventos necesarios para decidir si buscar —las llamadas a herramientas y todo lo posterior al inicio de la primera llamada— hasta resolver la interceptación atómica de `web_search`. + +El resultado inyectado se envuelve en un límite de datos no confiables, con límite de longitud y desduplicado por URL de origen. En los giros de salida estructurada (`json_schema` / `json_object`) se entrega como compacto JSON en lugar de prosa. Para los modelos con ruta de solo texto, también se le dice al modelo de búsqueda que describa imágenes relevantes en palabras e incluya sus URL de origen. + +```json +{ + "webSearchSidecar": { + "enabled": true, + "backend": "anthropic", + "model": "claude-sonnet-5", + "reasoning": "low", + "maxSearchesPerTurn": 3, + "routedModelStallTimeoutMs": 200000, + "timeoutMs": 200000, + "streamRoutedModelOutput": false + } +} +``` + +El backend explícito xAI usa la credencial almacenada creada por `ocx login xai`. Su bloque opcional `xSearch` permite la búsqueda X y puede restringirlo a una lista de identificadores y un rango de fechas ISO: + +```json +{ + "webSearchSidecar": { + "backend": "xai", + "model": "grok-4.6", + "xSearch": { + "enabled": true, + "allowedXHandles": ["xai"], + "fromDate": "2026-08-01", + "toDate": "2026-08-21" + } + } +} +``` + +`allowedXHandles` y `excludedXHandles` son mutuamente excluyentes y admiten como máximo 20 cadenas cada uno. Las fechas usan `YYYY-MM-DD`. Una escritura mal formada en la API de administración devuelve `400`. Si el bloque persistido es inválido, se rechaza el plan en lugar de ampliar la búsqueda silenciosamente. + +El razonamiento `minimal` no se utiliza porque el backend alojado rechaza las herramientas en ese esfuerzo. Una búsqueda fallida se devuelve al modelo enrutado como un resultado de error limitado, lo que le permite responder desde el contexto que ya tiene. + +Hay cuatro tiempos de espera independientes. `stallTimeoutSec` es el límite base de inactividad de eventos del puente. `connectTimeoutMs` (`200000` por defecto) cubre únicamente DNS, TCP, TLS y los encabezados finales. `webSearchSidecar.routedModelStallTimeoutMs`, disponible solo en el archivo de configuración (`200000` por defecto, entero `1..2147483647`), limita la inactividad de bytes de respuesta de cada iteración del modelo y se reinicia con cada byte no vacío. `webSearchSidecar.timeoutMs` limita por separado cada solicitud de búsqueda alojada. El watchdog efectivo del puente usa `max(base stall, connect timeout, routed-model stall, sidecar timeout) + 30 seconds`. El límite de inactividad del modelo no es un límite de duración total de generación. Si el error ocurre antes de iniciar SSE, se devuelve JSON con un estado no 2xx; si ocurre después de enviar los encabezados, se comunica mediante SSE `response.failed`. + + + +## Sidecar de visión + +El preajuste del proveedor registra `zai-glm-5-3` de Mistral como modelo de solo texto. Si el sidecar de visión está habilitado y disponible, OpenCodex describe las imágenes adjuntas y envía sus descripciones a GLM. El catálogo de Codex anuncia adjuntos de imagen para esta ruta. Después de actualizar, ejecuta `ocx sync` y cierra por completo y vuelve a abrir Codex Desktop, o recarga la ventana de VS Code. Sin una opción de reinicio, la sincronización no reinicia un app-server existente de Codex, que puede conservar el catálogo anterior. También puedes usar `ocx sync --restart-codex` para sincronizar y reiniciar los procesos de Codex coincidentes y Desktop. Termina antes el trabajo activo: ese reinicio finaliza las conversaciones en curso. Consulta la [referencia de sincronización y reinicio](/es/reference/cli/lifecycle/#ocx-sync---restart-codex---restart-app-server-only). Después de abrirlo de nuevo, elige `mistral/zai-glm-5-3` y comprueba que puedas adjuntar imágenes. No necesitas modificar la modalidad del modelo. Mistral documenta la entrada nativa en su [referencia de GLM 5.3](https://docs.mistral.ai/models/zai-glm-5-3). + +El enrutamiento de imágenes tiene en cuenta las capacidades del modelo. Antes del envío, opencodex resuelve sus modalidades de entrada a partir de evidencia del proveedor en ejecución, declaraciones explícitas del operador, metadatos del backend y del registro, y metadatos generados. Si el destino es de solo texto, el sidecar describe la imagen **antes** de la llamada principal y la reemplaza por texto en su posición original. Si se confirma que admite imágenes, las recibe directamente. Para los modelos personalizados desconocidos se conserva el comportamiento de compatibilidad, sin suponer que son de solo texto. + +Para la ruta canónica ChatGPT Codex, opencodex utiliza el paquete de metadatos `openai-codex` en lugar de los metadatos públicos OpenAI API, por lo que se respetan las diferencias de modalidad específicas del backend. La ruta rápida nativa de Chat utiliza la misma puerta y no puede omitir un veredicto conocido de solo texto. Sin un plan de sidecar disponible, las imágenes en bruto se eliminan antes de un backend probado solo de texto. Con `visionSidecar.enabled: false`, el catálogo de modelos no agrega entrada de imagen respaldada por sidecar a los modelos de solo texto, incluidas las filas personalizadas y los miembros combinados. Se conservan el soporte de imagen nativa y las modalidades de imagen configuradas explícitamente. Omitir `enabled` mantiene activado el anuncio de sidecar; la visibilidad del catálogo no establece que las credenciales o la capacidad de sidecar estén disponibles. Los combos anuncian la entrada de imágenes solo cuando cada miembro acepta imágenes, ya sea de forma nativa o a través de un sidecar habilitado, y la configuración `imageInput` del combo no está deshabilitada, por lo que los clientes como la aplicación Codex permiten archivos adjuntos en lugar de bloquearlos antes de que se ejecute el sidecar. Cuando `visionSidecar.model` está ausente o en blanco, la ruta de ejecución OpenAI, el tablero de instrumentos y la administración API usan el retroceso `gpt-5.6-luna`. El inicio sigue migrando un valor `gpt-5.4-mini` heredado explícitamente persistente a `gpt-5.6-luna`; esa migración se aplica a un valor almacenado, no a un campo de modelo ausente. Guardar un combo multimodal desde el panel inscribe automáticamente a sus miembros que no son imagen: la página Combos los envía como `visionSidecarTargets` en `PUT /api/combos`, que escribe la declaración exacta de solo texto en el proveedor del miembro, por lo que no se necesita editar y recargar la configuración manual. La inscripción nunca sobrescribe una declaración con capacidad de imagen existente, y los miembros cuyas modalidades son desconocidas o no tienen entrada de texto no están inscritos: el panel los nombra y mantiene el interruptor de imagen del combo no disponible. El modelo DeepSeek `deepseek-flash` de origen es multimodal nativo (`text` y `image`) y no usa este sidecar por defecto. `noVisionModels` explícitas o declaraciones de solo texto siguen siendo autoritativas. El primer partido `deepseek-chat`, `deepseek-reasoner` y `deepseek-v4-flash` permanece respaldado por sidecar por defecto; Las rutas Zen no han cambiado y no se probaron en esta actualización. + +- Las imágenes pueden provenir de mensajes de usuario, desarrollador y resultado de herramientas, incluidos los `view_image` de Codex. +- En la ruta OpenAI (paso de inicio de sesión ChatGPT), cada imagen se envía al modelo de visión configurado sobre el punto final Responses con el `reasoning.effort` seleccionado (`low` por defecto), y su descripción reemplaza la parte de imagen en línea. La ruta Anthropic utiliza el punto final Messages con su propia asignación de pensamiento-presupuesto e ignora esta configuración específica OpenAI. +- Para los modelos nativos con metadatos de capacidad conocidos, el razonamiento no compatible se normaliza al peldaño más alto soportado en o por debajo del nivel solicitado; si no existe ninguno, se usa el peldaño más bajo soportado. Los modelos desconocidos o personalizados siguen siendo permisivos cuando no hay metadatos de capacidad confiables. +- Las descripciones se ejecutan con concurrencia limitada (3 a la vez, orden de entrada preservado). El contexto del usuario enviado al descritor tiene un límite de 800 caracteres, y cada descripción inyectada tiene un límite de 2.000 caracteres. La solicitud no envía `max_output_tokens`, que el backend ChatGPT rechaza. +- Las URL de las imágenes se validan antes del reenvío: las URL de datos deben usar `png` / `jpeg` / `jpg` / `webp` / `gif`, y los datos de base64 están limitados a aproximadamente 20 MB. Solo se aceptan los esquemas `data:` y `https:`; las imágenes `https` remotas son buscadas por el backend OpenAI, no por el proxy. +- La coincidencia de `noVisionModels` ignora un sufijo Ollama-style `:size`, por lo que una entrada `gpt-oss` también cubre `gpt-oss:120b`. +- Si falla la descripción, el modelo recibe un marcador de error de procesamiento corto. (Sin un plan de sidecar disponible, no se intenta ninguna descripción - la imagen sin procesar se elimina, como se describió anteriormente). +- `maxDescriptionsPerTurn` (por defecto 8) limita las nuevas descripciones por turno de modelo principal. Los golpes de caché y los duplicados del mismo turno no lo consumen. Las descripciones de imágenes exitosas de `data:` se almacenan en caché por backend, modelo, detalle, bytes de imagen y contexto de mensaje, más el esfuerzo de razonamiento en las claves de caché de OpenAI (las de Anthropic lo omiten, ya que ese campo se ignora allí); las imágenes mutables de `https:` no se almacenan en caché. + +La API de administración y el selector del dashboard muestran modelos capaces de aceptar imágenes. Si está disponible el backend correspondiente, siempre se ofrecen `gpt-5.6-luna` (OpenAI) y `claude-haiku-4-5` (Anthropic) como opciones de referencia. `PUT /api/sidecar-settings` puede conservar un identificador personalizado o aún desconocido por el catálogo. Un sidecar de visión enrutado configurado explícitamente sigue siendo utilizable salvo que la evidencia demuestre que no acepta imágenes. Así se conserva la elección del operador sin enviar bytes de imagen a un modelo confirmado como de solo texto. + +```json +{ + "visionSidecar": { + "enabled": true, + "backend": "openai", + "model": "gpt-5.6-luna", + "reasoning": "medium", + "maxDescriptionsPerTurn": 8, + "timeoutMs": 45000 + } +} +``` + +Un modelo está marcado solo con texto por proveedor: + +```json +{ + "providers": { + "ollama-cloud": { + "baseUrl": "https://ollama.com/v1", + "noVisionModels": ["glm-5.2", "gpt-oss", "qwen3-coder", "deepseek-v4-flash"] + } + } +} +``` + + + +## Controles del panel de control y desactivación + +La tarjeta del sidecar de visión en el dashboard permite activarlo o desactivarlo y configurar `maxDescriptionsPerTurn` y `timeoutMs`, además del modelo, el backend y el razonamiento. Desactivarlo conserva todos esos ajustes para la próxima activación. + +`PUT /api/sidecar-settings` acepta los mismos campos. Las actualizaciones parciales no modifican las claves omitidas. `timeoutMs` admite enteros entre 1 y 2147483647 ms, los mismos límites del entorno de ejecución. + +Si cambia el estado efectivo del sidecar de visión, al guardar también se actualizan el catálogo administrado de Codex y la caché de modelos. Si la actualización no termina, la respuesta incluye `catalogRefreshPending: true`. El ajuste guardado se conserva. Publicar el catálogo no demuestra que un cliente en ejecución lo haya recargado. + +La tarjeta del sidecar de búsqueda web tiene un control equivalente: la primera opción del selector es **Desactivado**. Elegirla tiene dos efectos: OpenCodex deja de interceptar `web_search` y la integración de Codex escribe `web_search = "disabled"` en `~/.codex/config.toml`. Codex sigue anunciando su herramienta alojada `web_search` hasta que su propia configuración la desactiva; el modelo puede llamar a cualquier herramienta anunciada. Para que un servidor MCP sea la única vía de búsqueda, se necesitan ambos cambios. + +`web_search` es una clave de Codex con los valores `disabled`, `cached`, `indexed` y `live`. OpenCodex solo escribe `disabled` mientras el sidecar está desactivado y retira la línea de su propiedad al volver a activarlo: si la herramienta nativa siguiera desactivada, no habría llamadas que interceptar. Esta escritura requiere que `~/.codex/config.toml` esté administrado mediante `ocx sync`. La respuesta de administración la informa como `codexWebSearch`; la tarjeta de búsqueda advierte si no se pudo escribir y `ocx agent sidecar web --enabled off` indica si se escribió. Solo se intenta cuando al guardar cambia el estado efectivo. Si no cambió, se devuelve `not_requested` y no se imprime información adicional. Si el operador había configurado manualmente una línea raíz `web_search`, se reemplaza mientras el sidecar está desactivado para evitar claves TOML duplicadas. Su texto exacto se guarda en el diario de Codex y se restaura en su ubicación al reactivar el sidecar, incluso si la línea se añadió después de la instantánea del diario, algo que `ocx restore` por sí solo no puede cubrir. Ese registro también permite reconocer la línea `disabled` de OpenCodex si Codex reescribe `config.toml` y elimina el comentario de propiedad. + +También puedes establecer `enabled: false` directamente en `config.json`. La búsqueda y la descripción de imágenes mediante Anthropic OAuth reutilizan la identificación existente de Claude Code OAuth, pero requieren pruebas prolongadas con la cuenta y la carga de trabajo previstas. + +Vea el [Referencia de configuración](/es/reference/configuration/server/#sidecars) para cada campo. diff --git a/docs-site/src/content/docs/es/guides/sub-agent-surface.md b/docs-site/src/content/docs/es/guides/sub-agent-surface.md new file mode 100644 index 00000000000..4b7c7b8144d --- /dev/null +++ b/docs-site/src/content/docs/es/guides/sub-agent-surface.md @@ -0,0 +1,306 @@ +--- +title: "Superficie del subagente (v1 / base / v2)" +description: "Controle cómo Codex genera y gestiona subagentes en todos los modelos." +--- + + + +## Qué son los subagentes + +Un subagente es un trabajador separado Codex que el agente principal puede crear para una tarea enfocada. Tiene su propio contexto y herramientas, por lo que varias tareas independientes pueden ejecutarse en paralelo. opencodex controla qué superficie de colaboración Codex expone a esos trabajadores, qué modelos Codex ofrece para ellos y cómo un modelo fallido puede retroceder. No decide cuándo su agente principal debe delegar. + + + +## Modos + +Elija el modo para **Nuevas sesiones**. Las sesiones existentes mantienen la superficie con la que comenzaron. + +| Modo | Herramientas de Codex | Para quién se recomienda | +| --- | --- | --- | +| **v1** (predeterminado) | Herramientas clásicas en un espacio de nombres: `spawn_agent`, `send_input`, `resume_agent` y `close_agent`. Al crear un subagente se puede elegir otro modelo directamente. | Para quienes delegan entre proveedores, especialmente desde un agente nativo hacia subagentes enrutados. Es el modo que incluye una instalación nueva. | +| **base** | Asignaciones originales por modelo: GPT-5.6 Sol/Terra usan v2; Luna, v1. Los demás siguen la opción `multi_agent_v2` de Codex. | Para quienes quieren conservar esas asignaciones y usan modelos principales y subagentes del mismo lado del límite de proveedores. Sol y Terra quedan en v2. | +| **v2** | Herramientas planas `spawn_agent`, `send_message`, `followup_task`, `interrupt_agent` y listado de agentes, con sesiones concurrentes. | Para quienes necesitan el flujo concurrente y comprenden la herencia de modelos y la limitación de tareas cifradas descrita abajo. | + +En **v2**, la opción **Mantener ChatGPT en v1** (`keepNativeChatGptOnV1`) conserva Sol/Terra en v1 para que puedan crear subagentes Grok o Claude. Los agentes principales nativos de ChatGPT cifran el cuerpo de las tareas `NEW_TASK` en v2 y los modelos enrutados no pueden leerlo. Los agentes principales enrutados permanecen en v2, donde las tareas de sus subagentes son texto plano. Para este modo híbrido, OpenCodex desactiva la anulación global `multi_agent_v2`, porque Codex la aplica antes que los ajustes por modelo del catálogo. Es una opción de v2, no un cuarto modo de catálogo. + +:::tip[¿Tienes dudas?] +Usa **v1**, el modo predeterminado. Elige **base** o **v2** solo si el modelo principal y el subagente están del mismo lado del límite de proveedores: en ambos modos, una tarea enviada desde un modelo nativo de ChatGPT a uno enrutado llega cifrada y falla. La opción híbrida de v2 descrita arriba evita ese cruce conservando los modelos nativos en v1. El dashboard pide confirmación antes de elegir base o v2 y enlaza a [Por qué v1 es el valor predeterminado](/es/guides/subagent-v1-default/). +::: + + + +## Interruptores de modelo y compactación de chat lateral + +Codex puede compactar la historia heredada antes del primer turno de un chat lateral o después de un cambio de modelo. Un disparador compara los marcadores de compatibilidad `comp_hash` de los modelos anteriores y de destino: cuando ambos están presentes y difieren, Codex se compacta incluso si el historial se ajusta al contexto del destino. + +OpenCodex representa compatibilidad desconocida para modelos enrutados como `comp_hash: null`, en lugar de inventar un marcador `"opencodex"` o copiar uno de una plantilla nativa. Las reconstrucciones de catálogo también borran esos marcadores antiguos en OpenCodex filas retenidas durante una interrupción de descubrimiento del proveedor. Los modelos nativos y los alias explícitos Codex-forward mantienen sus marcadores ascendentes, por lo que aún se aplican verificaciones de incompatibilidad nativa genuinas. Este comportamiento es independiente de la superficie del subagente v1/v2 y del modelo configurado para realizar la compactación. + +El contexto normal y la compactación de límite de token todavía se aplican. Este cambio elimina el desajuste de hash sintético; no selecciona qué mensajes visibles hereda un chat lateral ni restaura los mensajes originales de un contexto ya compactado. El soporte de contenido del proveedor sigue siendo una restricción separada. + + + +## Entrada de tarea externa + +Codex puede entregar la entrada inicial o seguimiento de una tarea en una envolvente en forma de resultado sin un `call_id`. En las rutas traducidas, OpenCodex reconoce solo la forma completa de `function_call_output` con `id`, `name` y `namespace` sin espacios en blanco y salida de texto/imagen compatible, luego la trata como un turno de usuario. Esto también inicia el nuevo límite de conversación durante la continuación y borra el razonamiento pendiente del turno anterior. La guía para desarrolladores generada se coloca antes de la tarea actual tanto en los mensajes analizados como en el historial sin procesar guardado, preservando el mismo orden cuando se reproduce ese historial. + +Los sobres mal formados, vacíos, opacos o incompletos aún fallan en la validación. Los resultados reales de la herramienta mantienen su `call_id` requerido; el paso nativo y la compactación enrutada (portátil) aplican el mismo mapeo de giro de usuario a sus cuerpos sin procesar; el `/responses/compact` directo mantiene su manejo de entrada sin procesar existente. Véase [el contrato del adaptador](/es/reference/adapters/#external-task-input-on-translated-responses-routes). + + + +## Cómo funciona + +El modo seleccionado controla el campo `multi_agent_version` en cada entrada de catálogo Codex dice: + +- **v1** sellos `multi_agent_version = "v1"` en cada modelo. +- **base** restaura los pines de aguas arriba. Las entradas sin pines siguen la bandera de la característica nativa `multi_agent_v2`. +- **v2** sellos `multi_agent_version = "v2"` en todos los modelos, excepto cuando **Mantener ChatGPT en v1** está habilitado: ChatGPT -las filas nativas permanecen `"v1"` y las filas enrutadas o combinadas permanecen `"v2"`. + +opencodex aplica esto como el pase final tanto al catálogo en vivo `/v1/models` como al catálogo sincronizado al disco. Es por eso que un cambio de modo afecta a las nuevas sesiones de App, CLI y TUI creadas de manera consistente. + +Para una lista v2, la elegibilidad tiene tres estados: una entrada sellada `"v2"`, explícitamente establecida en `null`, o con ningún campo `multi_agent_version` es elegible. Se excluye un pin genuino `"v1"` porque establece que el modelo pertenece a la otra superficie de colaboración. + + + +## Qué modelos anuncia `spawn_agent` + +Codex muestra como máximo cinco modelos en la descripción de `spawn_agent`. Los elige ordenando las filas visibles del catálogo por `priority`, de menor a mayor, y tomando las cinco primeras. La lista de la página **Subagentes** (`subagentModels`) influye en esa selección al asignar a sus modelos las prioridades más bajas, en el orden configurado (`0` a `4` si no hay selectores de cuenta). No limita la selección exclusivamente a esos modelos. + +Si destacas entre uno y cuatro modelos, Codex completa los espacios restantes con las siguientes filas por prioridad. Esas filas no las elegiste tú y el dashboard no muestra cuáles son. Dependen del catálogo: + +| Catálogo | Filas que completan los espacios restantes | +| --- | --- | +| Sin selectores de cuenta de Codex | Las demás filas enrutadas `provider/model`. Todas tienen prioridad `5`, por lo que se ordenan alfabéticamente por proveedor y después por identificador de modelo. Las filas GPT nativas no destacadas tienen una prioridad de al menos `100` más la cantidad de identificadores destacados, y aparecen después. | +| Con selectores de cuenta de Codex | Las filas nativas calificadas por cuenta (`/`), inmediatamente después de las destacadas. Las filas enrutadas no destacadas pasan a la prioridad `1005` y quedan detrás. | + +Por ejemplo, sin selectores de cuenta y con esta lista: + +```json +{ "subagentModels": ["xai/grok-4.5", "anthropic/claude-sonnet-5"] } +``` + +| Posición | Modelo | Prioridad | Motivo | +| ---: | --- | ---: | --- | +| 1 | `xai/grok-4.5` | `0` | Primera entrada de la lista | +| 2 | `anthropic/claude-sonnet-5` | `1` | Segunda entrada de la lista | +| 3 | `deepseek/deepseek-v4-flash` | `5` | Primera fila enrutada restante en orden alfabético | +| 4 | `google/gemini-3-pro` | `5` | Siguiente fila enrutada | +| 5 | `moonshot/kimi-k3` | `5` | Siguiente fila enrutada | +| 6+ | `zai/glm-5.2`, y después las filas GPT nativas | `5`, y después `102` | Fuera de las cinco primeras | + +Con la lista vacía, opencodex no fija ninguna prioridad y se eligen las cinco filas según las prioridades habituales del catálogo. + +Los modelos que completan la lista se anuncian normalmente, así que el agente principal puede elegirlos. La lista tampoco es una lista de permisos: Codex acepta un modelo del catálogo que esté fuera de las cinco primeras filas si el agente principal lo nombra exactamente. Para controlar lo que anuncia Codex: + +- Destaca cinco modelos. Una lista completa no deja espacios por rellenar. +- Desactiva un modelo que no quieras que se ofrezca, o exclúyelo de `selectedModels` de su proveedor. Sale del selector y no puede completar un espacio. +- `modelPickerOrder` cambia las prioridades usadas para ordenar. Una lista formada solo por modelos enrutados mueve sus filas no destacadas a `1000` o más, de modo que las filas enrutadas que no figuren en ella completan primero los espacios. Si contiene un identificador nativo sin calificar, ordena todo el selector, incluidas las filas destacadas: las filas de la lista ocupan los espacios antes que cualquier fila que no figure en ella. Véase [Orden de modelos](/es/guides/model-ordering/). + +En v2, Codex excluye las filas con valor fijo `"disabled"` antes de elegir las cinco; el resto funciona igual. La guía v2 de opencodex (`{{roster}}`) solo nombra los modelos configurados que estén entre esas cinco filas. Por eso los modelos de relleno aparecen en la descripción de la herramienta de Codex, pero no en la guía de opencodex. Codex lee el catálogo al iniciar una sesión, así que los cambios de la lista se aplican a sesiones nuevas. + + + +## Modelo de delegación y esfuerzo + +El **Delegación de subagentes** del panel de control controla tres configuraciones relacionadas: + +- `injectionModel` es el modelo de trabajador preferido nombrado en la guía opencodex. +- `injectionEffort` es el `reasoning_effort` opcional para solicitar ese modelo. +- `injectionPrompt` reemplaza el texto de guía v2 incorporado. + +La opción **Sugerir**, junto al modelo de delegación, pide una breve descripción del trabajo que Codex suele delegar. Realiza una llamada a tu modelo predeterminado de Codex para evaluar la tarea y propone el modelo más económico que resulte suficiente, con un nivel de esfuerzo de los disponibles en el selector. También explica los motivos y qué señales justificarían subir o bajar de nivel. La sugerencia no se aplica hasta pulsar **Usar este**: ese botón guarda el modelo y el esfuerzo igual que una selección manual. Los niveles se obtienen de `codexRoleTiers` o del precio, como en la [asignación automática de roles](/es/guides/integrations/#auto-assign). + +`multiAgentGuidanceEnabled` por defecto está encendido y es el switch maestro para opencodex, guía de autoría en ambas superficies. Apagarlo suprime tanto el bloque de designación v2 como el texto proactivo v1. + +Para las solicitudes Responses sin estado en forma de matriz, opencodex coloca la guía generada después de los metadatos líderes del sistema y del desarrollador, incluido el desarrollador `additional_tools`, y antes de la entrada conversacional. `previous_response_id` continuaciones reutilizan la guía etiquetada solo cuando coincide con el último elemento etiquetado en su prefijo de reproducción de confianza. Otra guía generada se reutiliza cuando existe un elemento de desarrollador generado exacto en ese prefijo. Cuando la guía cambia, el protocolo de la herramienta líder permanece primero y el reemplazo se inserta antes de la entrada conversacional actual. + +Estas son instrucciones para el agente principal, no un router de generación del lado del proxy. En v2, una bifurcación de historia completa hereda el modelo padre y rechaza anulaciones de modelo o esfuerzo. Por lo tanto, la guía le dice a Codex que use `fork_turns: "none"` (o un recuento de giro parcial positivo como `"3"`) cuando pase `model` o `reasoning_effort`, y que haga que el mensaje de tarea sea autónomo. + +El texto personalizado `injectionPrompt` puede usar los cuatro marcadores de posición: + +| Marcador de posición | Reemplazado por | +| --- | --- | +| `{{model}}` | El modelo preferido efectivo para esta solicitud. Un `injectionModel` nativo desnudo solo está calificado para la cuenta cuando la solicitud se dirige a un selector de cuenta explícito. Un valor desnudo no resuelto o ambiguo se convierte en una cadena vacía; un id explícito no resuelto calificado o encaminado permanece sin cambios. | +| `{{effort}}` | El `injectionEffort` configurado, o una cadena vacía | +| `{{roster}}` | La lista resuelta de selector visible y superficie compatible | +| `{{fallback}}` | La guía de respaldo global configurada | + +La guía v2 incorporada tiene un presupuesto de 700 caracteres. Si superara el presupuesto, opencodex eliminaría la lista primero en lugar de truncar las instrucciones básicas de generación. La guía integrada se activa solo cuando se resuelve un modelo preferido, una lista elegible o una cadena de reserva. Un `injectionModel` configurado es suficiente para representar un mensaje personalizado; si un valor desnudo no puede resolverse de manera única, `{{model}}` se expande a una cadena vacía. + +En la v1, opencodex inyecta la misma orientación de delegación proactiva que el preajuste recomendado de v2 solo a `max` o `ultra` esfuerzo. Solo cambia el desencadenador de delegación: no se necesita ninguna solicitud de delegación por separado; todavía se aplican las instrucciones de usuario, la autoridad, el alcance de la tarea y las reglas de la herramienta de colaboración. No agrega un modelo preferido, una lista, una lista de reserva o un mensaje personalizado en la v1. En el modo de código Codex, opencodex ve las herramientas v1 cuando la descripción de la herramienta `exec` las enumera. Cuando Codex los aplaza para la búsqueda de herramientas, lo que hace para cada modelo de catálogo opencodex, opencodex se basa en la lista de herramientas diferidas que Codex Desktop envía con la conversación; si esa lista nombra `multi_agent_v1`, se agrega la guía proactiva. Un cliente Codex que no envía la lista no da opencodex ninguna señal de que v1 está disponible, por lo que la guía no se agrega allí. + +La opción `syncCodexSubagentDefaults` está **desactivada de forma predeterminada** y es independiente de la guía para el agente. Si opencodex administra el enrutamiento activo de Codex, al sincronizar o reiniciar puede escribir los valores elegidos en `[agents] default_subagent_model` y `default_subagent_reasoning_effort`, con marcadores de propiedad, dentro del TOML de Codex. Solo actualiza o elimina campos que tengan esos marcadores. Si cualquiera de los dos campos pertenece al usuario, deja ambos intactos en lugar de escribirlos parcialmente. Si el TOML es ambiguo, rechaza la escritura. También respeta los gestores de proveedores externos y el enrutamiento raíz definido por el usuario. + + + +## Cadenas de fallback + +Para un trabajador generado, opencodex crea este orden de prioridad: + +1. El modelo primario solicitado. +2. Una cadena por modelo de `subagentModelFallbackByModel` en opencodex config, tecleada por el modelo primario solicitado. +3. La lista global `subagentModelFallback` en opencodex config. + +Las cadenas de reserva per-rol pertenecen a la configuración opencodex, no a la `$CODEX_HOME/agents/*.toml`. Codex 0.146+ estrictamente deserializa los archivos de rol de agente y rechaza `model_fallback` como un campo desconocido, lo que omite toda la definición de rol (#1190). opencodex todavía puede leer una línea `model_fallback` heredada del TOML para la compatibilidad con versiones anteriores, pero `ocx doctor` advierte al respecto y Codex en sí ignorará el rol afectado. + +Los identificadores de modelos duplicados se eliminan mientras se conserva la primera aparición. Durante la selección, opencodex omite candidatos que están deshabilitados, no enrutables, respaldados por un proveedor deshabilitado, marcados como no saludables, dentro de un tiempo de reutilización, falta una cuenta Codex agrupada utilizable o más allá del umbral de cuota configurado. Las sondas de disponibilidad se almacenan en caché durante `subagentModelFallbackPollMs` (60 segundos por defecto). + +Fallback no hace legibles las tareas cifradas incompatibles. Cuando la tarea hija se cifra para ChatGPT, la selección se restringe a ChatGPT objetivos nativos canónicos y rutas de autenticación de clave directa Responses explícitamente confiables con `allowEncryptedV2AgentTasks: true`, incluso si otro modelo externo aparece antes en la cadena. Los combos siguen siendo canónicos. + + + +## Entrega de tareas cifradas v2 + +Codex puede enviar una tarea hijo v2 nativa a enrutada solo como `encrypted_content` encriptado en el backend. Esa carga útil puede ser leída por el backend nativo ChatGPT, pero no por un proveedor externo. Este es el conocido [limitación #92](https://github.com/lidge-jun/opencodex/issues/92). + +opencodex falla de manera segura en lugar de reenviar una tarea vacía o ilegible: + +- Una ruta no nativa directa inelegible devuelve HTTP 400 con `error.code = "unreadable_encrypted_agent_task"` y no hace eco del texto cifrado. Un proveedor elegible de clave directa Responses que opte explícitamente por `allowEncryptedV2AgentTasks: true` recibe el texto cifrado opaco y evita este error. +- Un combo primero considera objetivos canónicos nativos ChatGPT. Si no hay ninguno disponible o se agotan sus intentos, la recuperación habilitada puede hacer que la tarea sea legible para un destino enrutado disponible. Sin una recuperación exitosa y un objetivo elegible, el texto cifrado ilegible nunca se reenvía. +- Una tarea de texto plano legible mantiene la ruta normal y el comportamiento de reserva. + +Las opciones de recuperación son seleccionar un hijo nativo ChatGPT, confiar explícitamente en un relé de clave-auth directa Responses que puede consumir la carga útil opaca, agregar un destino nativo ChatGPT al combo, usar v1 para la delegación de proveedor heterogéneo o reenviar la tarea como contenido de texto plano v2 `agent_message` cuando se controla la persona que llama. + +Una opción experimental, desactivada por defecto `agentTaskRecovery` puede recuperar esta forma específica nativa a la ruta a través de un paso de Responses sin procesar al punto final fijo ChatGPT `/responses` utilizando la forma de credencial entrante utilizada por el proveedor canónico `openai` con `authMode: "forward"`. La recuperación solo está disponible mientras el proxy está vinculado a loopback. Nunca sustituye la autenticación de clave API, otra credencial de proveedor u otra cuenta Codex. Solo `authorization`, que coincide con `chatgpt-account-id`, `originator` y metadatos opcionales `openai-beta` / `user-agent` se reenvían; `content-type` y `accept` se generan localmente, y ninguna otra cabecera de llamada cruza el límite. Consume cuota, agrega latencia, retiene brevemente el texto plano recuperado en una caché en memoria limitada y depende del comportamiento del backend indocumentado ChatGPT. Debido a que un modelo devuelve el texto recuperado, la fidelidad byte por byte no está garantizada. Rechaza a los llamantes genéricos/proxy API. Recuperación fallida antes de que cualquier intento nativo devuelva `unreadable_encrypted_agent_task`; después de que los intentos nativos hayan fallado, se retiene su último error. Consulte [Configuración del agente: recuperación de tareas cifradas v2](/es/reference/configuration/agents/#encrypted-v2-task-recovery) para conocer los límites y la configuración de confianza completos. + +La misma recuperación también cubre un hilo en vivo cambiado de un modelo nativo ChatGPT a uno enrutado. Tal hilo reproduce un mensaje de agente cifrado acuñado en cada turno posterior, por lo que antes de [#4089](https://github.com/lidge-jun/opencodex/issues/4089) falló en cada turno y la única solución fue comenzar un nuevo hilo. Ese turno de interruptor no es un turno de aparición, por lo que la ruta directa ya no restringe la recuperación a turnos de subagentes creados; la recuperación combinada aún lo hace. + +El enrutamiento combinado prefiere un objetivo canónico nativo seleccionable ChatGPT para tareas cifradas. Si ninguno es utilizable, o los intentos de autorización nativa se agotan, una recuperación habilitada explícitamente puede hacer que la tarea sea legible para un destino enrutado disponible. Toda la confianza de recuperación y los protectores de no persistencia anteriores siguen siendo aplicables; un objetivo nativo configurado pero deshabilitado o que se enfría no bloquea esta reserva, y la cancelación nunca se convierte en un error de tarea ilegible. + + + +## Rechazado el historial cifrado + +Un servidor upstream Responses puede rechazar partes cifradas en la salida anterior de la función/herramienta personalizada o el contenido `agent_message` con `Encrypted function output content could not be decrypted or decoded.`. Antes de que se confirme cualquier salida, opencodex reemplaza esas partes con `[encrypted content omitted]` y reconstruye la solicitud una vez. El contenido legible circundante permanece intacto; el contenido omitido no es descifrado o recuperado por este reintento. + +Si la solicitud reconstruida recibe otro SSE `error` desnudo seguido por EOF, ambos modos de retransmisión conservan el mensaje de error en un terminal `response.failed` en lugar de informar `adapter_eof`. Otros `response.failed` eventos aguas arriba siguen SSE fallas. Esta recuperación de historial no cambia las restricciones de entrega de tareas v2 cifradas descritas anteriormente. + + + +## Cambiar el modo + +### GUI + +- **Tablero** → primera celda de estadística: elija **v1**, **base** o **v2**. +- **Modelos** → control segmentado de la fila superior: elija el mismo modo global. +- **Tablero** → **Delegación de subagentes**: establece el modelo/esfuerzo de guía y la opción de opt-in por defecto nativa. +- **Subagentes**: elija y ordene la lista y configure la cadena de reserva global. + +### CLI + +Utilice `ocx v2` para la configuración de la superficie de colaboración y las funciones nativas: + +```bash +ocx v2 status +ocx v2 mode v1 +ocx v2 mode default +ocx v2 mode v2 +ocx v2 threads 8 +``` + +Utilice `ocx agent` para la configuración de delegación, lista, límite de esfuerzo y reserva: + +```bash +ocx agent status +ocx agent injection set --model anthropic/claude-sonnet-5 --effort xhigh +ocx agent injection suggest "read-only searches across the repo" --apply +ocx agent subagents set gpt-5.6-sol,anthropic/claude-sonnet-5 +ocx agent fallback set gpt-5.6-luna,xai/grok-4.5 --poll-ms 60000 +ocx effort set --subagent max +``` + +El comando de nivel superior `ocx effort` es el punto de entrada canónico para la inspección de esfuerzo y tapas (p. ej. `ocx effort high`, `ocx effort status`, `ocx effort clear`), con `ocx agent effort` preservado como una ruta compatible con versiones anteriores. Obsérvese que `ocx effort clear` elimina las tapas de agente principal y subagente activo mientras deja intacta la delegación `injectionEffort` (use `ocx effort set --injection -` o `ocx agent injection set --effort -` para borrar el esfuerzo de inyección). + +Pase `-` para borrar un valor nullable de `ocx agent injection`, o use la acción relevante de `clear` para una lista o lista de reserva. Vea el [CLI referencia](/es/reference/cli/) para todas las familias de comando. + +### API + +La gestión API expone los puntos finales coincidentes `GET` y `PUT`: + +| Punto final | Administra | +| --- | --- | +| `/api/v2` | Modo de superficie, bandera de función nativa y configuración de subprocesos | +| `/api/injection-model` | Modelo preferido, esfuerzo, prompt personalizado, orientación y sincronización predeterminada nativa | +| `/api/effort-caps` | Límites máximos de esfuerzo del agente principal y del subagente | +| `/api/subagent-models` | Lista de pedidos de hasta cinco modelos | +| `/api/subagent-model-fallback` | Orden de reserva global e intervalo de encuesta | + +Por ejemplo: + +```bash +curl -X PUT http://localhost:10100/api/v2 \ + -H 'Content-Type: application/json' \ + -d '{"multiAgentMode":"v2"}' + +curl -X PUT http://localhost:10100/api/injection-model \ + -H 'Content-Type: application/json' \ + -d '{"model":"anthropic/claude-sonnet-5","effort":"xhigh"}' +``` + +## FAQ + + + +### ¿La elección de un modelo de delegación obliga a Codex a generarlo? + +No. La guía puede recomendar un modelo, y la sincronización nativa predeterminada puede proporcionar un valor predeterminado de Codex, pero el agente principal aún decide si delegar. + + + +### ¿Por qué mi subagente v2 usó el modelo principal? + +Una bifurcación v2 con el historial completo hereda el modelo del agente principal. Para indicar otro modelo o esfuerzo de razonamiento al crear el subagente, establezca `fork_turns` en `"none"` o en un recuento parcial positivo. + + + +### ¿Por qué falta un modelo configurado en la lista de v2? + +Puede estar oculto por el selector, fuera del límite de visualización de cinco modelos, falta en el catálogo o anclado a v1. Un `"v2"`, `null`, o el valor de superficie ausente es elegible; un verdadero `"v1"` pin no lo es. + + + +### ¿Por qué `spawn_agent` muestra modelos que no destaqué? + +Codex completa hasta cinco posiciones según la prioridad de las filas del catálogo. Si destacas menos de cinco modelos, las filas siguientes ocupan los espacios restantes. Véase [Qué modelos anuncia `spawn_agent`](#which-models-spawn_agent-advertises). + + + +### ¿Los cambios de modo afectan a las sesiones en ejecución? + +No. Inicie una nueva sesión Codex después de cambiar el modo. Si un host de aplicaciones de larga duración aún muestra un estado de catálogo obsoleto, ejecute `ocx sync` y reinicie esa superficie Codex. + + + +### ¿Qué sucede cuando opencodex no puede confiar en el catálogo? + +opencodex compara el catálogo del modelo en el disco con la hora de inicio de cada Codex app-server propiedad del usuario actual, produciendo uno de los cuatro estados: + +| Estado | Descripción | v2 Orientación | +|---|---|---| +| `fresh` | Todos los servidores de aplicaciones comenzaron después de que se escribió el catálogo | Orientación completa: modelo preferido, plantel, fallbacks | +| `not_running` | No se detectó ningún servidor de aplicaciones | Orientación completa | +| `stale` | Al menos un servidor de aplicaciones precede al catálogo | **No opencodex - Guía del modelo** | +| `unknown` | La comparación no se pudo hacer | **No opencodex - Guía del modelo** | + +Para `stale` y `unknown`, opencodex retiene sus propias reclamaciones derivadas del disco - modelo preferido, lista, reserva y orientación personalizada - porque el Codex en ejecución puede no ser capaz de generar lo que anuncia el catálogo de discos. + +Esto **no** indica al modelo que deje de configurar `model` o `reasoning_effort`. La observación abarca todos los app-servers del usuario, mientras que la solicitud entrante no identifica al proceso que la envió. Por tanto, no se puede atribuir un proceso obsoleto a esa solicitud. Prohibir las anulaciones basándose en esa observación bloquearía opciones que la herramienta activa `spawn_agent` puede anunciar legítimamente en una sesión nueva. El esquema de la herramienta activa sigue siendo la autoridad. + +`unknown` no es sinónimo de `stale`. Significa que la comparación en sí falló - una marca de tiempo de catálogo ilegible, un tiempo de inicio de proceso ilegible o una enumeración de proceso fallido - y se informa por separado por `ocx doctor`. `stale` se borra solo después de que cada Codex app-server detectado se inicia después de la escritura final del catálogo; no necesariamente se borra `unknown`. + +En Windows, esta comprobación de aviso utiliza el descubrimiento asíncrono de PowerShell/CIM en la ruta de solicitud v2. Las comprobaciones en frío simultáneas comparten un descubrimiento en vuelo. Los estados observados se almacenan en caché durante cinco segundos; un error `unknown` se almacena en caché durante solo 250 milisegundos, por lo que un error CIM transitorio se reintenta rápidamente. Una consulta de CIM lenta o defectuosa puede retrasar o suprimir solo la guía del modelo OpenCodex; no bloquea el bucle de eventos Bun, `/healthz` o el tráfico proxy no relacionado. Las operaciones explícitas del ciclo de vida CLI /service conservan el recopilador de procesos síncrono y cerrado por error, ya que pueden señalar procesos. + +Solo un cambio real cuenta. Una sincronización cuyo resultado es idéntico en bytes al catálogo ya en disco deja el archivo intacto, por lo que reiniciar el proxy o volver a sincronizar un conjunto de modelos sin cambios no hace que un Codex en ejecución parezca obsoleto. + + + +### Esfuerzo de razonamiento + +`injectionEffort` afecta solo a la orientación del trabajador delegado y, cuando está explícitamente habilitada, a los valores predeterminados del subagente Codex nativo. No cambia el esfuerzo de la sesión de padres. `ultra` es un nivel superior orientado al cliente que Codex convierte a `max`; opencodex luego mapea o fija el valor para el proveedor seleccionado. + + + +### Cap. de contexto + +El límite de contexto del modelo es independiente del modo de subagente. Configure en la página Modelos; los modelos nativos OpenAI conservan sus ventanas de contexto real. + +El campo experimental `plaintextV2AgentMessages` no se establece en una nueva configuración y se ejecuta solo cuando se establece en `true`. La persona que llama debe usar el cable Responses y el destino final debe usar `adapter: "openai-responses"`, `authMode: "forward"` y la URL base exacta `https://chatgpt.com/backend-api/codex`. OpenAI API - proveedores clave, pasarelas compatibles personalizadas, rutas a otros proveedores, y no Responses personas que llaman están excluidos. Para una nueva llamada a la herramienta ChatGPT v2 nativa elegible, la opción asigna alias con alcance de solicitud al espacio de nombres y tres nombres reservados de la herramienta de mensajes, elimina el marcador de mensajes y restaura las identidades originales en la respuesta. Maneja `spawn_agent`, `send_message` y `followup_task` y no agrega ninguna petición de recuperación. HTTPS permanece encriptado, pero el texto de la tarea se puede conservar en el historial Codex, las solicitudes del proveedor de rutas y el estado de respuesta/depuración local. El texto cifrado existente no cambia, y la opción depende del comportamiento indocumentado ChatGPT y Codex. Véase [Configuración del agente: Mensajes de agente de texto sin formato v2](/es/reference/configuration/agents/#plaintext-v2-agent-messages). Si una respuesta de flujo continuo ChatGPT no lleva ningún tipo de contenido, o una que no es ni `application/json` ni un flujo de eventos reconocible, opencodex comprueba un prefijo de evento Responses limitado antes de restaurar los nombres de herramienta de mensaje. Una respuesta `application/json` toma el camino JSON limitado en su lugar. La sonda espera como máximo `stallTimeoutSec` por su prefijo, y un cuerpo que permanece silencioso, no reconocido o ilegible falla en cerrarse en lugar de alcanzar Codex como una respuesta exitosa. diff --git a/docs-site/src/content/docs/es/guides/subagent-v1-default.md b/docs-site/src/content/docs/es/guides/subagent-v1-default.md new file mode 100644 index 00000000000..63d5380e260 --- /dev/null +++ b/docs-site/src/content/docs/es/guides/subagent-v1-default.md @@ -0,0 +1,120 @@ +--- +title: "Por qué v1 es la interfaz de subagentes predeterminada" +description: "Qué impide la limitación de tareas cifradas de v2, por qué OpenCodex utiliza v1 y qué opciones existen si prefiere v2." +--- + +OpenCodex se instala con la interfaz de subagentes en **v1**. Las páginas Panel, Modelos y Subagentes solicitan confirmación antes de cambiar a **base** o **v2** y enlazan esta explicación. La CLI no solicita esa confirmación. + +El motivo es concreto: de forma predeterminada, en v2 un modelo enrutado no puede leer la tarea cifrada que recibe de un modelo nativo de ChatGPT. Esto afecta al caso habitual de un agente GPT que crea un subagente Grok, Claude o GLM. Las excepciones explícitas son `keepNativeChatGptOnV1`, que conserva los modelos nativos de ChatGPT en v1 mientras los enrutados usan v2; un destino autorizado que pueda procesar la tarea cifrada mediante `allowEncryptedV2AgentTasks: true`; o la recuperación experimental `agentTaskRecovery`, descritas más abajo. + + + +## Qué ocurre cuando falla + +La creación del subagente se rechaza para evitar que reciba una tarea vacía sin advertencia: + +```json +{ + "error": { + "code": "unreadable_encrypted_agent_task", + "message": "Routed V2 worker task is encrypted for the native ChatGPT backend and cannot be read by the selected provider. Use plaintext V2 agent-message delivery or select a native ChatGPT model." + } +} +``` + +La respuesta es HTTP 400 y nunca devuelve el texto cifrado. El rechazo es deliberado: reenviar una carga ilegible entregaría al subagente instrucciones vacías y podría producir una respuesta incorrecta presentada con seguridad. + + + +## Por qué ocurre + +![Comparación de la delegación: en v1, ChatGPT envía una tarea sin cifrar mediante OpenCodex y el subagente enrutado puede leerla. En v2 envía encrypted_content del backend de ChatGPT; OpenCodex no puede descifrarlo y la solicitud falla con unreadable_encrypted_agent_task al cruzar el límite entre proveedores.](../../../../assets/subagent-v2-encrypted-task.svg) + +En v1, el agente principal emite la tarea del subagente como texto sin cifrar. OpenCodex la lee y la enruta; el subagente recibe instrucciones que puede ejecutar. + +En v2, el agente principal emite la tarea como `encrypted_content`, generado por el backend de ChatGPT. La clave permanece en ese backend; OpenCodex nunca la tuvo. El proxy no puede descifrar ni reescribir el contenido: es texto cifrado real. Es una limitación estructural y ningún ajuste del proxy puede eliminarla. + +La comparación de estas tres combinaciones muestra dónde aparece el límite: + +| Combinación | v1 | v2 | +| --- | --- | --- | +| Agente ChatGPT a subagente enrutado | funciona | **falla de forma predeterminada**; excepciones: `keepNativeChatGptOnV1` conserva el agente nativo en v1, un destino autorizado usa `allowEncryptedV2AgentTasks: true` o la recuperación experimental `agentTaskRecovery` recupera la tarea | +| Agente enrutado a subagente enrutado | funciona | funciona | +| Agente ChatGPT a subagente ChatGPT | funciona | funciona: el backend puede descifrar lo que generó | + +El backend puede leer su propio texto cifrado. El problema aparece al cruzar hacia otro proveedor. + + + +## ¿Está resuelto en Codex? + +Todavía falta la parte necesaria para este caso. Codex integró [openai/codex#35845](https://github.com/openai/codex/pull/35845), que permite recibir mensajes de colaboración sin cifrar. Ese cambio afecta al receptor: procesa texto que ya fue generado sin cifrar, pero no hace que un agente de OpenAI lo emita de esa forma. + +La parte de envío sigue descrita en [#36376](https://github.com/openai/codex/issues/36376), reproducida con las versiones CLI 0.146 a 0.151 en Windows, macOS y Linux, y en [#37197](https://github.com/openai/codex/issues/37197), que solicita una política de entrega para el emisor. No hay un compromiso de implementación ni una fecha estimada del mantenedor. + +OpenCodex registró esta consecuencia en [#92](https://github.com/lidge-jun/opencodex/issues/92), cerrada como no planificada: este repositorio no puede resolver el cifrado del emisor. La issue remite al trabajo en Codex. + + + +## Qué hace cada modo + +| Modo | Interfaz | Cuándo elegirlo | +| --- | --- | --- | +| **v1** (predeterminado) | Todos los modelos anuncian las herramientas clásicas de creación con espacio de nombres. Cada creación puede indicar otro modelo directamente. | Si delega entre proveedores. Es el valor incluido en la instalación. | +| **base** | Respeta la asignación de Codex por modelo: Sol y Terra usan v2, Luna usa v1 y los modelos sin asignación siguen la opción de Codex. | Si desea la interfaz prevista por Codex y delega dentro de un mismo proveedor. | +| **v2** | Todos los modelos anuncian las herramientas concurrentes sin espacio de nombres. | Si desea las sesiones concurrentes nuevas y ambos agentes están del mismo lado del límite entre proveedores. | + +base aparece en segundo lugar porque asigna v2 a Sol y Terra, modelos utilizados habitualmente como agentes principales. Para delegar de ChatGPT a un modelo enrutado, base tiene la misma limitación que v2. + + + +## Si ya eligió base o v2 + +La actualización no sobrescribe una elección existente. El panel muestra el aviso una vez y espera una respuesta. + +- **Continuar** conserva el modo actual y deja de preguntar. +- **Cambiar a v1** aplica v1 y deja de preguntar. + +Ambas respuestas quedan registradas. Cerrar el aviso sin responder lo deja pendiente para la siguiente apertura del panel. + +El modo se aplica a las sesiones **nuevas** de Codex. Inicie otra sesión después del cambio. Si un proceso de la aplicación que lleva tiempo abierto todavía muestra la interfaz anterior, ejecute `ocx sync` y reinicie esa aplicación. + + + +## Si prefiere utilizar v2 + +Hay cuatro opciones, en el orden recomendado: + +1. **Mantener ChatGPT en v1.** Dentro de v2, `keepNativeChatGptOnV1` conserva Sol y Terra en v1 para que puedan crear subagentes Grok o Claude; los agentes principales enrutados utilizan v2. +2. **Delegar dentro del mismo proveedor.** Un agente enrutado que crea otro subagente enrutado utiliza texto sin cifrar en v2 y funciona normalmente. +3. **Confiar en un relay directo de Responses con clave API.** Un proveedor marcado explícitamente con `allowEncryptedV2AgentTasks: true` recibe la carga opaca en lugar de HTTP 400. Utilícelo únicamente con un destino que sepa que puede procesarla. +4. **Activar `agentTaskRecovery`.** Es experimental y está desactivado de forma predeterminada. Recupera los elementos cifrados ilegibles `NEW_TASK`, `MESSAGE`, `FOLLOWUP_TASK` y `FINAL_ANSWER` mediante el backend de ChatGPT, con consumo de cuota, latencia y dependencia de un comportamiento no documentado. La recuperación de Combo sigue limitada a los turnos de subagentes creados; los fragmentos de tokens divididos no son compatibles. + +Consulte [Interfaz de subagentes](/es/guides/sub-agent-surface/) para conocer su funcionamiento y [Configuración de agentes](/es/reference/configuration/agents/) para los ajustes. + + + +## Cuándo dejará de ser necesaria esta página + +Cuando Codex permita que un agente nativo de ChatGPT emita sin cifrar la tarea de un subagente enrutado, desaparecerá el motivo de este valor predeterminado. Entonces podrá volver a base, dejar de mostrar la confirmación y conservar esta página como registro histórico. + + + +## Cambiar el modo + +Panel, Modelos y Subagentes comparten el selector v1/base/v2 y solicitan confirmación antes de pasar a base o v2. Desde la CLI: + +```bash +ocx v2 status +ocx v2 mode v1 +``` + +La CLI no solicita confirmación. Modifica la misma configuración; elija el modo teniendo en cuenta estas limitaciones. + + + +## Límite de subagentes simultáneos + +En **Modelos → Ajustes del modelo**, el control de subagentes establece el máximo de agentes secundarios simultáneos, sin contar al principal. Está disponible en v1, base y v2, incluido el modo híbrido con la opción global de v2 desactivada. El modo de interfaz y este límite se eligen por separado. + +Aumentar el límite permite más subagentes; no los crea automáticamente ni garantiza mayor velocidad. Inicie una sesión nueva de Codex después de cambiarlo. Si un proceso de la aplicación que lleva tiempo abierto sigue usando el límite anterior, reinícielo. diff --git a/docs-site/src/content/docs/es/guides/video-bridge.md b/docs-site/src/content/docs/es/guides/video-bridge.md new file mode 100644 index 00000000000..bbd4fc9f966 --- /dev/null +++ b/docs-site/src/content/docs/es/guides/video-bridge.md @@ -0,0 +1,91 @@ +--- +title: "Puente de video" +description: "Generar vídeos con Grok Imagine Video a través de un modelo que no sea OpenAI." +--- + + + +## Descripción general + +El puente de video permite generar videos con Grok Imagine Video de xAI desde cualquier modelo ajeno a OpenAI enrutado mediante opencodex. Al activarlo, se añade la herramienta sintética `video_gen` a la conversación. El modelo la llama como una función; opencodex intercepta la llamada, envía el trabajo a xAI, consulta su estado hasta que termina y descarga el resultado. + + + +## Requisitos previos + +- Un proveedor `xai` con una **clave API**: `ocx login xai` por sí solo no basta; el puente requiere autenticación con clave. +- Un modelo de otro proveedor, como Anthropic Claude o Google Gemini. +- opencodex configurado para enrutar mediante ese proveedor. + +> **⚠ Se requiere una clave del proveedor:** El puente solo se activa cuando `xai` utiliza autenticación con clave API. Añada esta referencia a su configuración: +> +> ```json +> { +> "providers": { +> "xai": { "adapter": "openai-chat", "apiKey": "${XAI_API_KEY}", "authMode": "key" } +> } +> } +> ``` +> +> Si configuró el proveedor con `ocx login xai` (OAuth), permanece en `authMode: "oauth"` y el puente no se activa. Para usarlo, establezca `XAI_API_KEY` en el entorno, conserve la referencia `${XAI_API_KEY}` del ejemplo y configure explícitamente `authMode: "key"`. Mantenga las claves literales fuera de commits, registros e informes compartidos. + + + +## Configuración + +Agregue `videoBridgeEnabled: true` a su configuración `images`: + +```json +{ + "images": { + "bridgeEnabled": true, + "videoBridgeEnabled": true, + "videoBridgeModel": "grok-imagine-video", + "videoMaxRounds": 2, + "videoTimeoutMs": 300000 + } +} +``` + +| Opción | Predeterminado | Descripción | +|--------|---------|-------------| +| `videoBridgeEnabled` | `false` | Interruptor maestro. Debe estar explícitamente habilitado. | +| `videoBridgeModel` | `"grok-imagine-video"` | Id. de modelo de vídeo xAI. | +| `videoMaxRounds` | `2` | Número máximo de rondas de generación de video antes de forzar la respuesta final. | +| `videoTimeoutMs` | `300000` (5 min) | Plazo máximo por video, incluidas las consultas de estado. | + + + +## Cómo funciona + +1. opencodex detecta un modelo enrutado no OpenAI con `videoBridgeEnabled: true` +2. Una herramienta de función sintética `video_gen` se inyecta en la conversación +3. Cuando el modelo llama al `video_gen`, opencodex envía un trabajo al endpoint `/videos/generations` de xAI +4. El puente sondea el estado del trabajo cada 5-15 segundos, enviando mensajes de latido para mantener viva la transmisión +5. Cuando el video está listo, se descarga en el directorio de artefactos +6. La ruta local del archivo se devuelve al modelo como resultado de la herramienta + + + +## Parámetros soportados + +La herramienta `video_gen` acepta: + +| Parámetro | Tipo | Alcance | Descripción | +|-----------|------|-------|-------------| +| `prompt` | cadena | requerido | Indicación detallada de generación de vídeo | +| `duration` | entero | 1-15 | Duración del vídeo en segundos | +| `resolution` | cadena | `"480p"`, `"720p"` | Resolución de vídeo | +| `aspect_ratio` | cadena | 7 relaciones | `16:9`, `9:16`, `1:1`, `4:3`, `3:4`, `3:2`, `2:3` | + + + +## Limitaciones + +- **xAI solamente**: La generación de video solo está disponible mediante la API Grok Imagine Video de xAI +- **Asíncrono**: La generación de video toma 30-120 segundos +- **Coste**: la generación de video es una función de pago de xAI. Consulta las [tarifas oficiales](https://docs.x.ai/developers/pricing) antes de usarla. +- **Un video por llamada**: Cada llamada `video_gen` produce un vídeo +- **Coexiste con Image Bridge**: Ambos puentes se pueden habilitar simultáneamente +- **Prioridad de búsqueda web**: Cuando un sidecar de búsqueda web está activo durante un giro (no adaptador `runTurn`), el puente de vídeo se salta - los dos no pueden funcionar simultáneamente. Se emite un `console.warn` para que pueda detectarlo en registros. +- **Plazo compartido entre el envío y las consultas**: `videoTimeoutMs` empieza antes de enviar el trabajo. La solicitud de envío (60 s) y las consultas posteriores comparten el mismo plazo máximo. diff --git a/docs-site/src/content/docs/es/guides/web-dashboard.md b/docs-site/src/content/docs/es/guides/web-dashboard.md new file mode 100644 index 00000000000..39f418110a0 --- /dev/null +++ b/docs-site/src/content/docs/es/guides/web-dashboard.md @@ -0,0 +1,317 @@ +--- +title: "Dashboard web" +description: "Dashboard de opencodex para gestionar el proxy, proveedores, modelos, delegación, cuentas, uso y registros." +--- + +opencodex incluye un dashboard web local, una aplicación Vite/React en `gui/` servida por el proxy. Permite gestionar proveedores, cuentas de Codex/ChatGPT, el catálogo de modelos, sidecars, subagentes y tráfico de solicitudes. + + + +## Abrirlo + +```bash +ocx gui +``` + +El comando abre `http://localhost:` en el navegador, o `http://127.0.0.1:` si está habilitado el acceso de administración del hub. Si hace falta, inicia primero el proxy. Para desarrollar, puedes ejecutar el servidor de la GUI por separado contra un proxy activo; inicia cada comando en su propia terminal: + +```bash +ocx start +bun run dev:gui +``` + + + +## Iniciar sesión + +Cuando el proxy escucha en la dirección local predeterminada de loopback (`localhost` / `127.0.0.1`), el dashboard no pide un token. El proxy incorpora sesiones de GUI de corta duración en la página servida y las renueva automáticamente cuando caducan o se reinicia. Solo un dashboard que escucha en un hostname fuera de loopback requiere el token de administración: `OPENCODEX_ADMIN_AUTH_TOKEN` o el archivo generado automáticamente `~/.opencodex/admin-api-token`. + +Si el dashboard remoto necesita esa credencial, muestra un formulario de contraseña estándar para que el gestor de contraseñas del navegador pueda ofrecer guardarla y completarla. El dashboard conserva el token únicamente en memoria y nunca lo escribe en `localStorage` ni en `sessionStorage`. Guardarlo depende exclusivamente del navegador o del gestor de contraseñas. + + + +### Encontrar el token de administración + +Solo necesitas este token cuando el proxy escucha fuera de loopback. Un dashboard local no lo pide. Si uno local solicita autenticación, consulta [Cuando un panel local no puede iniciar una sesión](#when-a-local-dashboard-cannot-start-a-session). + +El proxy genera el token la primera vez que se inicia. Por diseño, no lo imprime. Puedes leerlo desde su archivo: + +```bash +cat ~/.opencodex/admin-api-token +``` + +Si `OPENCODEX_HOME` está establecido, la ruta es `$OPENCODEX_HOME/admin-api-token`. En Windows, la ubicación predeterminada es `%USERPROFILE%\.opencodex\admin-api-token`. Un token generado consta de `ocx_admin_` seguido de 43 caracteres. Si un archivo no tiene ese formato, el proxy lo rechaza en lugar de regenerarlo silenciosamente. + +Para elegir el valor, establece `OPENCODEX_ADMIN_AUTH_TOKEN` antes de iniciar el proxy. La variable tiene prioridad: en ese caso no se lee ni se crea el archivo. Usa un valor diferente de la credencial de datos (`OPENCODEX_API_AUTH_TOKEN` o una clave API configurada); se rechaza la reutilización de una misma credencial en ambos planos. + +Ningún comando de la CLI imprime el token. `ocx doctor` solo informa si hay una credencial, sin revelar su valor. + + + +### Cuando un panel local no puede iniciar una sesión + +El dashboard en `localhost` obtiene su propia sesión y no debería pedir un token. Si no puede iniciar una sesión, la causa es la dirección utilizada: el proxy no reconoció la solicitud como loopback. Abre la dirección exacta que muestra el proxy al iniciar, normalmente `http://127.0.0.1:`, y usa ese host y puerto en lugar de una IP de la red local o un alias. + + + +## Diseño de panel + +La barra lateral tiene ocho entradas: **Dashboard**, **Conectar**, **Codex**, **Proveedores**, **Modelos**, **Subagentes**, **Uso y registros** y **Enlace remoto**. **Conectar** muestra las pestañas **Codex**, **Claude**, **Claude Desktop**, **Grok Build** y las demás integraciones. Claude muestra directamente los ajustes de Claude Code, sin subpestañas; Claude Desktop tiene una pestaña independiente en `#claude/desktop`. Conectar no usa un selector de secciones. **Subagentes** agrupa Subagentes y Asesor (`#advisor`); **Uso y registros** agrupa Uso, Registros y depuración, y Almacenamiento; **Enlace remoto** agrupa Enlace remoto (`#remote`) y Espacio de trabajo remoto (`#remote-workspace`, si está disponible). Estos grupos usan un selector de secciones. **Codex** sustituye el nombre anterior **Codex Set**. Se conservan `#codex-set`, `#claude`, `#claude/code` y `#claude/desktop`; el marcador antiguo `#claude/settings` abre Code y `#claude/account` redirige a `#providers?provider=anthropic&tab=accounts`. Inicio (`#startup`) no aparece en la barra lateral. + +La medición del tiempo hasta la primera salida de Responses incluye texto, razonamiento, argumentos de funciones transmitidos y entradas de herramientas personalizadas. Por tanto, un turno que solo llama a herramientas puede tener esa medición aunque no genere prosa. Los deltas vacíos y los avisos de inicio de herramienta no activan el temporizador. Se mide la primera salida observada por el proxy, no el comienzo del razonamiento oculto ni la velocidad exacta de generación del modelo. + +La vista general usa tarjetas de estado y filas de ajustes de ancho completo. En pantallas amplias, las etiquetas comparten una columna y los controles de modelo y esfuerzo otra. En pantallas estrechas, los controles pasan debajo de sus etiquetas y conservan el orden de lectura. Las versiones largas se acortan visualmente; pasa el puntero por la etiqueta o el valor para leerlos completos. + + + +### Barra de resumen de cuotas + +La parte superior de cada página, salvo Inicio, muestra en una línea el uso de cuota de los proveedores, por ejemplo `OpenAI 31% | Claude 54% | xAI 12% | Google 8%`. Lee los mismos informes de `GET /api/provider-quotas` que la página Proveedores, cada 60 segundos mientras la pestaña está visible, y nunca fuerza una actualización al proveedor. + +- Cada indicador muestra una ventana preferida entre las informadas: primero la semanal, luego la mensual, la de cinco horas y, por último, una ventana con nombre propio del proveedor o sus créditos prepagados. +- El indicador se vuelve ámbar al 70 % de uso y rojo al 90 %. +- Pasa el puntero o enfoca el indicador con el teclado para ver todas las ventanas informadas, sus reinicios y la hora de lectura. El detalle sigue abierto al mover el puntero hacia él, incluso al cruzar la separación visual. En una pantalla táctil, el primer toque abre el detalle. +- Haz clic, o toca por segunda vez, para abrir la pestaña Cuentas de ese proveedor. El enlace **Abrir gestión de cuentas** del detalle abre la misma pestaña; se puede alcanzar con Tab y activar con Enter. Escape cierra el detalle y devuelve el foco al indicador si estaba dentro. +- La barra permanece en una línea. Si no caben los indicadores, desplázala horizontalmente o usa los botones « y » de los extremos. +- Se omiten los proveedores sin ventanas de cuota informadas. Si ninguno informa una, la barra se oculta. +- El extremo derecho muestra la hora de la última lectura del dashboard. Se vuelve ámbar si falló la lectura más reciente y se siguen mostrando los datos anteriores. + + + +## Lo que puedes hacer + +| Zona | Lo que hace | +| --- | --- | +| **Resumen del panel** | Modo multiagente, estado en línea, versión, tiempo de actividad, recuento de proveedores, total de 30 días de token, proveedores activos y modelos nativos/enrutados disponibles. | +| **Retención del razonamiento nativo** | Activa por separado el reenvío de razonamiento cifrado al cambiar de modelo nativo o de cuenta. Ambas opciones están desactivadas por defecto; la retención entre cuentas es experimental. Véase [el ámbito de configuración](/es/reference/configuration/server/#native-reasoning-retention). | +| **Delegación de subagentes** | Elija un modelo nativo o enrutado y un esfuerzo de razonamiento opcional compartido por la guía de delegación OpenCodex y el opt-in nativo predeterminado separado. Este no es un router proxy por spawn; ver más abajo. | +| **Sidecares** | Elija el modelo de búsqueda web y el esfuerzo más el modelo de descripción de la visión. Los cambios se aplican en la siguiente solicitud. | +| **Mantenimiento** | Vuelva a sincronizar el catálogo de modelos Codex, inspeccione las advertencias de omisión de configuración de proyecto-local, compruebe la versión más reciente o de vista previa y ejecute una actualización con reinicio proxy opcional. En el shell de escritorio, su entrada de actualización abre la página de actualización de la aplicación nativa en lugar de ejecutar el actualizador de paquetes. | +| **Seguridad de inicio** | Mostrar si el enrutamiento Codex inyectado sobrevive a un reinicio, con servicio separado y estado del lanzador más comandos de reparación exactos. | +| **Bandeja Windows** | Instale una bandeja de inicio de sesión por usuario para iniciar, detener, reiniciar, acceder al panel y el estado del proxy con un solo clic. La bandeja es un controlador, no un servicio de reinicio proxy. | +| **Codex autostart** | Permitir que se ejecute una shim de lanzador Codex ya instalada `ocx ensure`. Este conmutador no instala un servicio de shim o de fondo. | +| **Proveedores** | Agregar, editar, establecer el valor predeterminado (solo proveedores habilitados), habilitar/deshabilitar y eliminar proveedores; administrar grupos de cuentas OAuth y grupos de claves API donde sea compatible. La eliminación del valor predeterminado actual cambia al primer proveedor habilitado restante cuando existe; de lo contrario, se rechaza la eliminación y se mantiene el valor predeterminado actual. La configuración de proveedores puede deshabilitar la detección de modelos en vivo para puntos finales con falta, lento o sobredimensionado `/models` catálogos. Por Claude (Anthropic) OAuth Cada cuenta iniciada muestra sus propias barras de límite de velocidad de 5 horas y semanalmente (el uso es por credencial); una sonda fallida mantiene las últimas barras conocidas y las marca como no disponibles hasta la próxima actualización exitosa. **Actualizar todas las cuotas** control que obliga a un servidor a releer cada proveedor configurado; un proveedor cuya sonda ascendente falla mantiene su última fila correcta, por lo que la línea de estado informa que la verificación completada en lugar de reclamar cada valor es nueva, y la propia edad de cada fila mantiene la señal de frescura por proveedor. | +| **Añadir proveedor** | Una búsqueda por encima de las pestañas llega a los cuatro a la vez — Cuentas, Gratis, Local, Pagado. Mientras una consulta está en vivo, los resultados se agrupan por pestaña con un recuento de cada uno, y la pestaña seleccionada se mantiene en lugar de saltar. Presione ArrowDown en el cuadro de búsqueda para enfocar la primera acción de resultado disponible, omitiendo los botones desactivados; si no hay ninguna acción disponible, el enfoque permanece en el cuadro de búsqueda. Los tiempos de ejecución locales (Ollama, vLLM, LM Studio, LitelLM) tienen su propia pestaña, y una larga nota del proveedor se fija a dos líneas con el texto completo a un clic de distancia. Claude Code CLI (suscripción) se encuentra bajo Pagado con una suscripción CLI insignia, y al seleccionarlo advierte que se factura la suscripción iniciada a través de Claude `claude -p` y nunca usa una clave API (usar `anthropic-apikey` ej., para facturación de claves). | +| **Codex Autonomía** | Agregue cuentas de grupo ChatGPT/Codex, seleccione la cuenta de la siguiente sesión, actualice las cuotas de 5h / semanal / 30d, habilite o deshabilite el cambio automático de cuota, establezca su umbral 1–100% y configure la conmutación por error de transitorios. | +| **Subagentes** | Presenta hasta cinco modelos ruteados nativos o con espacio de nombres en el `spawn_agent` Anule la lista. | +| **Modelos** | Alternar GPT nativo y modelos enrutados, establecer listas de proveedores y límites de contexto, elegir v1/base/v2 y configurar el límite de hilos v2. La página distingue un catálogo guardado en el concentrador, un catálogo obtenido por este cliente y la activación en un cliente en ejecución. Una marca de tiempo fetch no prueba que incluya la última función de guardado del concentrador, y la activación en entorno de ejecución se muestra como no verificada. Los proveedores configurados permanecen visibles como grupos de modelo cero cuando la detección está desactivada o no devuelve filas. | +| **Registros** | Actualizar automáticamente las solicitudes recientes con tokens, el esfuerzo solicitado y (cuando esté disponible) el esfuerzo de salida efectivo, el modelo resuelto, el proveedor, el estado, la identificación de la solicitud, la duración y los detalles del error. La vista de detalle incluye el campo exacto del cable de razonamiento cuando el adaptador emite uno. Filtrar por ID de conversación/sesión opaca (cuando el cliente envía uno) a tokens total y costo de lista-precio estimado para el anillo de registros cargado actualmente. | +| **Uso / Depuración** | Inspeccione la cobertura y las tendencias de uso de token. La tabla Modelos de la página de Uso también divide cada modelo en tokens de entrada, tokens de salida, aciertos de caché, escrituras de caché y tasa de aciertos de caché; un guion significa que la telemetría de caché para esa métrica no está disponible. O habilite el transporte de proveedores y los diagnósticos de extracción de uso. | +| **Almacenamiento** | Desglose de disco CODEX_HOME de solo lectura (sesiones, archivos, bases de datos, archivos adjuntos). Limpieza archivada opcional: vista previa del N% más antiguo, luego cuarentena a `CODEX_HOME/.trash` (predeterminado) o eliminar permanentemente detrás de una casilla de verificación explícita. **Política de autolimpieza** es opt-in y **por defecto OFF** (`storageCleanupPolicy.enabled`); configurar umbral/objetivo/programa/modo en la página Almacenamiento, o activar **Corre ahora**. Las entradas en cuarentena se pueden restaurar desde la página Almacenamiento (JSONL + hilos). Las sesiones activas son de solo lectura. La limpieza y la restauración se rechazan mientras Codex tiene el nuevo/activo `state_*.sqlite` Cerrada. | +| **Detener** | Detenga con gracia el proxy y el servicio de fondo instalado, restaure Codex nativo y salga (`POST /api/stop`) En Windows con el programador de tareas backend, el panel de control se niega y le pide que ejecute `ocx stop` en su lugar: ese contenedor puede volver a reenviar el proxy después de que finalice la tarea, y solo una parada que se ejecute fuera de este proceso puede verificar la ventana de reinicio antes de restaurar la configuración del cliente. Nada cambia cuando se niega. También se niega para un proxy la aplicación de escritorio OpenCodex se ejecuta, que la aplicación comenzaría de nuevo: utilizar la bandeja de la aplicación **Detener proxy** o **Salir** Ahí. | + +Si no se pueden incluir algunos registros de uso, la página Uso, Panel de control, espacio de trabajo del proveedor, proveedor Las vistas de catálogo y clave API muestran una advertencia incluso cuando no quedan registros legibles. Condes, fechas y Los rankings de uso solo reflejan registros legibles. **Modelos → La mayoría de las instantáneas usadas →** Rechazar para guardar una instantánea incompleta; elija otro orden o repare el historial antes de volver a intentarlo. + + + +### Selección de cuenta + +La selección de cuenta se comparte con el enrutamiento de solicitudes. La selección de una cuenta OAuth tiene efecto en el next request incluso cuando un grupo está habilitado. Una selección saludable no es reemplazada simplemente porque otra cuenta genérica OAuth tiene más cuota no utilizada. Si la cuenta devuelve 429, failover aún puede seleccionar otra cuenta utilizable con el grupo apagado. Un compromiso automático La selección actualiza el panel de control inmediatamente; los cambios en la cuenta no esperan la actualización de la cuota temporizador. Las solicitudes que ya se envían en el flujo ascendente conservan sus credenciales originales. + + + +### Filtrar registros de solicitudes + +Un rechazo de repetición de proxy mantiene HTTP 429 y código de error `upstream_reset_replay_refused`Pero... La causa de su solicitud y de su intento de fracaso es `transport-ambiguous`, con permiso de reenvío +`refused-ambiguous`: el flujo ascendente puede haber procesado ya el giro. Un auténtico proveedor Quedan 429 `rate-limit` con permiso de reenviar `permitted`. + +Un movimiento Codex a otra cuenta después de que HTTP 402 aparece como **Cuota de cuenta agotada (402)** +en los detalles de recuperación del intento y cuenta como una recuperación de cuota en métricas exportadas. + +Los filtros de registro combinan superficie, solicitudes interceptadas, proveedor, modelo exacto, estado, tiempo, velocidad y el ID de conversación sobre el anillo de solicitud cargado actualmente. Proveedor y modelo Las opciones también incluyen intentos de reserva; la coincidencia del modelo ignora el caso y los espacios circundantes pero no coincide con nombres parciales. Las opciones que desaparecen del ring se restablecen a Todos. El campo de conversación también acepta un pegado `codex://threads/` El enlace profundo, la forma a Codex "copiar enlace de sesión" pone en el portapapeles — la envoltura y cualquier metadata de enlace tal como `?hostId=…` se ignoran y el id de hilo desnudo es coincidente, el mismo valor +`ocx logs filter --conversation` búsqueda desenvolver. + +Las ventanas de tiempo cubren los últimos 15 minutos, horas o días y se actualizan cada 30 segundos mientras se La pestaña Registros está activa, incluso con actualización automática desactivada. Windows utiliza la marca de tiempo proxy de la respuesta de los registros y avance con el tiempo transcurrido del navegador, por lo que un reloj del navegador diferente No cambia el límite. Los proxies más antiguos sin esa marca de tiempo retienen el reloj del navegador hasta que una muestra válida esté disponible. La velocidad utiliza la salida tokens por segundo sobre el Duración total de la solicitud: por debajo de 15, 15 a menos de 50, o al menos 50. Los valores de velocidad no disponibles son Se excluye cuando un filtro de velocidad está activo. Éxito significa 2xx; errores significa 4xx o 5xx. + +Registros de etiquetas cada estimación de decodificación **Ventana de generación** o **Después de la salida visible** en la lista e intenta la tabla, y utiliza **Velocidad de salida durante la generación (est.)** o +**Velocidad de salida después de la primera salida visible (est.)** en solicitar detalles. Respuestas antiguas en caché sin un método de sincronización mostrar **Tiempo desconocido** y **Tasa de salida (est.; método de temporización desconocido)** +en detalles. Una leyenda visible debajo de la tasa de detalle explica el método de sincronización; una rate no tiene título. Cuando el proxy observa ambos extremos, es salida tokens sobre la ventana de generación: desde el primer elemento o bloque de salida, razonamiento incluido, hasta el último delta de salida. Las filas más antiguas sin esa ventana usan el tiempo después de la primera vista. token hasta el final de la solicitud. Ambos son observaciones del lado proxy, no la sincronización interna token del proveedor, por lo que el valor es siempre una estimación, y una ventana de menos de un segundo no se muestra como no disponible. Ambos numeradores incluir la salida de razonamiento informada tokens, por lo que las dos bases de tiempo no son directamente comparables. Los registros históricos no se reescriben y las marcas de tiempo de generación que faltan no se inventan. El end-to-end La columna tok/s y el filtro de velocidad anteriores no se ven afectados. + +Los filtros activos muestran el recuento correspondiente del total cargado. Restablecer filtros restaura todo filas y devuelve el foco del teclado al control de toda la superficie; “Sin solicitudes coincidentes” difiere de un anillo de registro vacío. Utilice las teclas de flecha o Home/End en el selector de superficie. Estos controles no consultan registros históricos más allá del anillo cargado. + +El selector de idioma incluye **Portugués** (Portugués brasileño, `pt-BR`) Los idiomas del navegador portugués lo seleccionan automáticamente a menos que ya se guarde una preferencia de idioma compatible. + + + +### Vincular a una sección + +Hay un solo diseño, por lo que no hay ningún interruptor de diseño para configurar. Las secciones del panel son direccionable en su lugar: `#dashboard` abre Vista general, y `#dashboard/providers` y +`#dashboard/models` Abre los otros dos. Recargar, marcar y Atrás todos mantienen la sección que estabas encendido. **Registros** Funciona de la misma manera con `#logs` y `#logs/debug`. Un viejo `#providers/workspace` +Marcador ahora aterriza en `#providers`. + +Valores de costos en **Registros** y **Uso** son equivalentes de lista-precio de API calculados a partir de tokens notificado. Para un intervalo de uso personalizado, el servidor debe confirmar las horas de inicio y fin solicitadas. Si un proxy de ejecución anterior no admite esos límites, el panel de control y CLI rechazan su informe; Actualizar y reiniciar ese proxy antes de volver a intentarlo. Restablecer un precio de modelo manual afecta solo a modelo, conservando otras tasas ahorradas independientemente. Los **Uso** Las tablas de resumen y Modelos/Proveedores muestran el rendimiento de salida de extremo a extremo del historial de uso para el rango y los filtros seleccionados: salida sumada tokens dividida por segundos de reloj de pared sumados, no un promedio de tasas individuales. El recuento de muestras se mide por intentos (o solicitudes de filas heredadas sin intentos); se excluyen las muestras que carecen de salida finita positiva tokens o duración. Un guión significa que no hay muestra calificada o el servidor devolvió una tasa inutilizable. Esto incluye la espera de predecodificación y no es una velocidad de decodificación estimada. + +Los **Uso** Las tablas de modelos y proveedores muestran la porción estimada para cada fila. Solicitudes sin un precio coincidente o uso utilizable se cuentan como excluidos junto a esa cantidad cuando el proxy Informes de precios campos de cobertura. El uso que se midió solo parcialmente (`unreported` o `unsupported`) no tiene precio, y una parte excluida excluye toda la solicitud del recuento de precios de esa fila. A que no alcanzó ningún nivel ascendente, o que se negó con un error HTTP antes de cualquier salida, gastado nada y no lo hace; una cancelación de cliente (499), o una etapa cuya respuesta comenzó o terminó sin un estado pero no informó uso, puede haber sido facturado, por lo que lo hace. Un rechazo seguido de una medida enviar correctamente contribuye a que envíe el costo al resumen, incluso cuando el estado de uso agregado es `unreported`. Una fila con solo solicitudes excluidas muestra un guion inicial con ese recuento en lugar de una estimación de cero dólares, y un valor de cero dólares mostrado es una estimación de precio confirmado. Un proxy más antiguo que informa que no hay campos de cobertura mantiene un guión desnudo sin contar, por lo que falta La cobertura permanece distinta de una fila totalmente excluida y de una estimación cero confirmada. Estos no son recibos de facturación o evidencia de un cargo real; uso de suscripción o créditos del proveedor puede aplicar en su lugar. + +Las filas del modelo de proveedor pueden incluir **Uso del modelo solicitado no resuelto**: la ruta guardada envió el nombre solicitado sin cambios al proveedor predeterminado. Estos tokens pertenecen a ese proveedor de servicio, no necesariamente el proveedor nombrado en la solicitud. El panel conserva el nombre original y uso en lugar de adivinar qué modelo corrió. Para los nombres no resueltos que contienen barras, una El precio del modelo del proveedor por sí solo no es suficiente para estimar el costo; un proveedor exacto o un precio configurado Todavía se aplica. Las acciones del modelo se calculan dentro del proveedor seleccionado. Solicitudes para un desconocido reserva `policy/` nombre ahora falla antes de llegar a un proveedor de origen; se conserva el uso histórico. + +El proveedor seleccionado **Descripción general** y **Uso** tabuladores muestran **Uso de la cuenta corriente** debajo de la Estadísticas de uso. **Cuentas** y **Claves API** muestre la cuota propia de cada credencial soportada, incluyendo saldos de crédito. La visión general de todo el proveedor todavía muestra la capacidad combinada cuando está disponible; no se sustituye por una lectura de cuenta corriente faltante. Búsqueda sin soporte, sin pasivo observación, carga, búsqueda fallida con valores conocidos por última vez y cero medido están separados estados. **Control de cuotas completado** significa la lectura settled—not que una observación pasiva se convirtió en nuevo o que todas las mediciones anteriores se actualizaron. + + + +## Visibilidad del modelo + +Los **Modelos** Los switches muestran la visibilidad final de Codex: un modelo enrutado solo está activado cuando su lista de proveedores lo incluye (o no está configurada) y no está desactivado. Activar un modelo reconcilia ambos filtros atómicamente; **Todos en** borra la lista de proveedores para que los modelos recién descubiertos también estén encendidos. + +Los switches responden de inmediato para que pueda seguir cambiando modelos mientras se ejecutan los archivos guardados en segundo plano. haga clic en ordenar. La retroalimentación guardada aparece después de que la cola termina y la lista se reconcilia con la servidor. Falló guarda restaurar el estado del servidor cuando se puede leer y mostrar un error. Espere a que retroalimentación antes de salir de Modelos o cambiar de servidores: los cambios en cola no enviados se descartan a la salida. + + + +### Administrar modelos en un espacio de trabajo de proveedor + +En un proveedor **Modelos** token: **Eliminar** elimina la definición personalizada almacenada. Un subyacente El modelo nativo o el modelo descubierto en vivo pueden volver a aparecer, por lo que el recuento de modelos puede permanecer igual. +**Ocultar** solo cambia la visibilidad del catálogo: no elimina la definición ni cambia directamente política de enrutamiento. Uso **Gestionar la visibilidad en modelos** para abrir el **Modelos** página y restaurar visibilidad, incluso cuando la pestaña del proveedor no tiene filas. + +**Añadir** guarda una definición personalizada; no borra una regla de selección de proveedores o ocultación existente. Por lo tanto, un modelo guardado puede permanecer oculto. Si el modelo ya se conoce, gestionar su visibilidad en **Modelos**. Todavía se guarda un guardado confirmado con una actualización de catálogo fallida: siga la actualización mensaje en lugar de añadirlo de nuevo. Si el cambio no se puede confirmar, actualice el estado del modelo antes de volver a intentarlo. + +El recuento de modelos del proveedor es el número de entradas únicas no desactivadas en el modelo actual. inventario devuelto por el servidor, antes de buscar o mostrar truncamiento. No es el proveedor tamaño de lista de permisos, un recuento de descubrimiento en vivo o prueba de que se descubrió una entrada de origen. Selección Las insignias y la información de descubrimiento permanecen separadas de esa cuenta. + + + +## Selector de delegación vs enrutamiento de generación + +El selector **Delegación de subagentes** guarda `injectionModel` y, opcionalmente, `injectionEffort`. **Guía multiagente de OpenCodex** controla de forma independiente las instrucciones de delegación que usan esos valores. En los turnos v2 elegibles, la guía indica al agente principal qué modelo y esfuerzo pasar a `spawn_agent`. Borrar el modelo también borra el esfuerzo guardado. + +La opción **Usar como valores predeterminados de subagentes nativos de Codex** está desactivada de forma predeterminada. Si OpenCodex administra el enrutamiento activo, aplica la misma selección a los valores nativos de `[agents]` en la siguiente sincronización o reinicio. Respeta la configuración de proveedores externos del usuario. Solo afecta a tareas de Codex creadas después y no provoca delegación por sí misma. Los valores de `[agents]` definidos por el usuario se conservan, por lo que pueden seguir teniendo prioridad sobre los solicitados. + +:::caution +Ninguno de los controles es un router de generación de modelos cruzados del lado proxy. La guía OpenCodex le pide a Codex que pase Anulaciones para `spawn_agent`; nativo `[agents]` los valores predeterminados se aplican solo cuando Codex crea una nueva tarea después de han sido sincronizados. Véase +[Interfaz de subagentes](/es/guides/sub-agent-surface/) para el comportamiento canónico v1/base/v2. +::: + + + +## Sesiones, claves y uso de Remote Hub + +En **Conectar → Claves API**, cada fila tiene un botón para eliminar su clave tras pedir confirmación. Al pulsar una clave, una sesión autorizada de forma independiente puede mostrar su valor completo y un botón **Copiar**. + + + +### Lectura de una clave API existente + +Para mostrar el valor completo de una clave guardada, se necesita una sesión del dashboard autorizada mediante emparejamiento explícito o una identidad de Tailscale de confianza. Una sesión local automática puede mostrar la lista enmascarada, pero no revelar valores existentes; un token de administración sin esa sesión tampoco sirve. Usa el [flujo de emparejamiento](/es/guides/remote-hub/#pairing-this-browser-with-a-hub) antes de solicitar el valor. Si se rechaza, la página explica el requisito. El formulario local solo se ofrece en un dashboard independiente del mismo origen, abierto por HTTP en la dirección literal `127.0.0.1` o `[::1]`, y el origen debe coincidir con la dirección literal de loopback configurada en el servidor. Si abriste `http://localhost:` u otro alias, comprueba esa configuración y abre `http://127.0.0.1:` para un servidor enlazado a `127.0.0.1`, o `http://[::1]:` para uno enlazado a `::1`. Un servidor configurado con hostname `localhost` no tiene un origen local elegible para este formulario. El dashboard no puede deducir la dirección configurada a partir de un alias; por eso muestra una denegación genérica sin proponer otra URL. En ese caso usa el emparejamiento de Remote Hub o Tailscale de confianza, si está disponible. Vuelve a emparejar si la sesión caduca o se revoca. El inicio de sesión normal y la creación, rotación y eliminación de claves no cambian. + +Después del emparejamiento, vuelve a pulsar la clave para solicitar su valor; emparejar por sí solo no revela ninguna clave. Los valores visibles y los avisos de copia se borran al quitar o sustituir la sesión compartida, iniciar un emparejamiento, salir de esta página, ocultar la pestaña o ventana de Desktop, o cambiar de servidor. Esto también afecta a los valores recién creados o de reemplazo: copia el valor de una sola visualización antes de salir. Si una creación o rotación termina después de cambiar de sesión o vista, su valor permanece oculto. Al regresar al servidor original, se vuelve a validar la lista de claves. Las rotaciones pendientes siguen disponibles para confirmarlas o cancelarlas expresamente. + +La administración desde el dashboard está separada del tráfico de modelos directo entre cliente y hub. **Conectar → Claves API** muestra las rotaciones pendientes, revela el secreto de reemplazo una sola vez y requiere confirmación o cancelación explícita. Cerrar sesión en el navegador invalida únicamente la sesión remota actual. Con conexión se consulta el uso guardado en el hub filtrado por el `apiKeyId` del cliente; sin conexión se muestra el uso local, sin duplicarlo. + +La garantía de anulación del modelo solo se aplica a la guía v2 **incorporada**. Un `injectionPrompt` personalizado la reemplaza por completo y debe incluir `{{model}}` y `{{effort}}`, y opcionalmente `{{roster}}`, para que esos valores aparezcan en la guía. + +El selector ofrece modelos nativos y enrutados habilitados, además de la escalera de esfuerzo global Codex. El API valida el esfuerzo seleccionado globalmente; Codex todavía valida un esfuerzo de generación contra el objetivo Entrada de catálogo. + + + +## Autenticación de Codex y grupos de cuentas + +La página **Codex Auth** administra la ruta nativa de ChatGPT/Codex: + +El modo Pool selecciona en las cuentas Codex principales y agregadas; Direct utiliza solo el inicio de sesión de la persona que llama/principal. Las solicitudes en vuelo mantienen sus credenciales capturadas y una reautenticación 401/403 o un tiempo de reutilización 429 puede borrar la afinidad y rotar a otra cuenta Pool elegible. Esto es separado de `openai-apikey` +y otros proveedores. + +:::caution[Responsabilidad sobre las políticas del proveedor] +El grupo de cuentas es una función técnica de administración de cuentas, enrutamiento y resiliencia. Esto no afirma que tener varias cuentas esté prohibido: el cumplimiento depende de la configuración de cada cuenta y del patrón de uso. OpenCodex no respalda el uso de cuentas adicionales para eludir límites de solicitudes, cuotas, límites del plan u otras restricciones del proveedor, ni compartir credenciales entre personas. Usted es responsable de cumplir los términos vigentes del proveedor para cada cuenta y forma de uso. Las restricciones, suspensiones o cancelaciones de cuentas quedan fuera del control de OpenCodex. Los mantenedores no ofrecen asesoramiento sobre políticas ni pueden resolver las medidas que aplique el proveedor. Consulte los +[Términos de uso de OpenAI](https://openai.com/policies/terms-of-use/). +::: + +- La elección manual se aplica en la siguiente solicitud, incluso de un hilo ya vinculado; las solicitudes en curso conservan las credenciales que capturaron. Además, la cuenta queda fijada con una insignia **FIJADA**: ninguna prioridad superior la sustituye hasta que se agote, elijas otra o cambies el orden de selección de alguna cuenta. Pulsar de nuevo la insignia pide confirmar que se libere esa fijación. Al confirmar, los hilos vinculados conservan su cuenta y las solicitudes nuevas o no vinculadas vuelven al orden y los umbrales. Una confirmación antigua no puede liberar una fijación más reciente. Si la operación se rechaza o su resultado es incierto, revisa la vista actualizada antes de volver a confirmar. +- Cada cuenta tiene un control **Orden de selección**: primero, antes, normal, después y último. Solo se recurre a un orden inferior cuando todas las cuentas superiores están agotadas o no disponibles. El cambio afecta a la siguiente solicitud no vinculada, sin mover hilos que ya tengan cuenta. La cuenta principal de Codex participa en el mismo orden y puede reservarse como **Última**. Una prioridad personalizada de `ocx account priority` sigue siendo visible y seleccionable aunque no coincida con esos cinco valores. +- La afinidad evita cambiar de cuenta en cada solicitud. Con `pool.cacheAffinity` activado por defecto, un hilo mantiene su cuenta aunque cruce el umbral de uso, hasta que se agote o no pueda atenderlo. Solo se mueve a otra con margen de cuota real y uso estrictamente menor. `false` permite volver a evaluar el cambio al cruzar el umbral, pero mantiene esos requisitos del destino. +- Las sesiones nuevas pueden elegir la cuenta elegible de menor uso. Los planes pagados puntúan las 5h más calientes conocidas, semanal, o 30d ventana; Los planes Go/Free solo usan la ventana 30d. +- Si WHAM proporciona `limit_window_seconds`, Codex Auth clasifica como 30d una ventana principal de al menos 28 días, en lugar de suponer que es semanal. Si la respuesta no indica la duración, conserva la interpretación semanal anterior. +- **Actualizar las cuotas** vuelve a leer el uso de la cuenta inmediatamente, por lo que el enrutamiento y las tarjetas de cuenta usan lo mismo valores. +- Los registros de solicitudes Pool usan etiquetas opacas, como `p3fa91c`, nunca correos electrónicos de cuenta. +- Cada cuenta también muestra su etiqueta de registro estable, el total de tokens observado en 30 días, una estimación de coste equivalente de API y la proporción de intentos con uso medido. Los precios personalizados de `modelCosts` tienen prioridad sobre el catálogo verificado y los precios de respaldo; el uso histórico se vuelve a valorar con los precios activos al consultarlo. Es una estimación para conciliación, no una factura de ChatGPT Plus o Pro. Los registros históricos de `openai` anteriores a la atribución explícita siguen siendo ambiguos y no se asignan a la cuenta principal actual. +- **Apuntar a una cuenta específica de Codex desde el selector de modelos** Es una opción explícita. Cuando está habilitado, Las filas del selector GPT ordinarias se reemplazan por una entrada por selector de cuenta pública. La elección de uno bloquea esa conversación a la cuenta asignada: no rota, retrocede o cambiar la cuenta Pool activa. El inicio de sesión de la aplicación Codex incorporado tiene su propio selector; mapas generados normalmente utilizan `main`con un sufijo de colisión segura como `main-2` cuando sea necesario. Cuentas añadidas reciba etiquetas estables y seguras para la privacidad, y se conservan las etiquetas selectoras personalizadas existentes. Las conversaciones existentes y las selecciones de modelo guardadas continúan el enrutamiento. Desactivar la configuración Oculta las entradas generadas del selector sin eliminar cuentas, selectores ni rutas exactas. Llanura GPT Los ID de modelo continúan usando el comportamiento configurado Pool o Direct. +- Los cambios de agregar, quitar y seleccionar cuentas se guardan antes de actualizar el catálogo de modelos. Si esa actualización limitada no puede terminar, el panel de control muestra un aviso ámbar de éxito con recuperación; ejecutar `ocx sync` para reintentar. El cambio de cuenta o configuración en sí permanece guardado. + +La descripción general de los proveedores resume por separado el uso del modo Pool como una capacidad ponderada solo para pantalla estimación, junto con la cuota bruta de la cuenta efectiva y la próxima recuperación de capacidad. Véase +[Capacidad del grupo](/es/guides/providers/#providers-overview-pool-capacity) por el campos visibles, significado de cobertura incompleta y límite de enrutamiento. + + + +## Tú decides si dar una estrella + +El botón de la barra lateral y la pregunta que `ocx start` muestra en una terminal interactiva usan **tu propia sesión de `gh`**. opencodex no guarda un token de GitHub para esta acción; solo registra tu respuesta. + +Como esta acción modifica tu cuenta de GitHub, se rechazan las llamadas dirigidas por agentes en lugar de permitir que respondan por ti: + +- `ocx start` y `ocx service install` omiten la pregunta interactiva cuando detectan un agente o entorno automático (`CLAUDECODE`, `CODEX_THREAD_ID`, `CURSOR_TRACE_ID`, `CI`, entre otros). El agente debe trasladar la pregunta una sola vez con una opción clara Sí/No. El silencio queda pendiente: no se registra como Sí ni como No y el agente no debe repetirla en respuestas o sesiones posteriores. Una versión posterior puede volver a activar el aviso de la CLI según los plazos de `AGENTS_INSTALL.md`. +- `POST /api/github/star` devuelve `403` con `code: "agent_consent_required"` cuando el proxy detecta una sesión de agente y la solicitud no acredita una sesión del navegador del panel. Tener el token de administración no constituye consentimiento: un agente local puede leer ese archivo. +- El botón del panel sigue disponible. Un clic real aporta la evidencia de sesión del mismo origen, incluso si el agente inició el proxy. +- Una respuesta negativa termina el asunto; no se insiste ni se añaden indicaciones a los mensajes del modelo para retomarlo después. + + + +## Cómo el panel de control habla con el proxy + +La GUI es un cliente ligero de la API JSON de administración del proxy. Algunos endpoints útiles son: + +| Punto de conexión | Finalidad | +| --- | --- | +| `GET` / `PUT /api/settings` | Lee los configuración o actualiza el inicio automático Codex, los configuración de flujo/memoria y la visibilidad del selector de segmentación de cuentas. | +| `GET` / `POST /api/github/star` | Lea el `gh`-derivada del estado de estrella, o la estrella del repositorio. El POST es rechazado con `403` `agent_consent_required` para llamadas dirigidas por agentes sin una sesión de panel. | +| `GET /api/startup-health` | Lea los diagnósticos de enrutamiento, servicio, shim y seguridad de reinicio sin secretos. | +| `POST /api/startup-action` | Instale el servicio en segundo plano o la shim de lanzador Codex a través de acciones fijas y permitidas. | +| `GET` / `POST /api/windows-tray` | Lea o cambie la instalación de la bandeja Windows y el estado del proceso visible. POST acepta `install`, `start`, `stop`, o `uninstall`. | +| `POST /api/sync` | Reconstruye el catálogo compartido y marca la caché de modelos de Codex como obsoleta. | +| `GET /api/update/check` · `POST /api/update/run` · `GET /api/update/status` | Revisar, ejecutar y supervisar los trabajos de autoactualización. Los PID de los trabajadores persisten para que un trabajo bloqueado se recupere automáticamente; los trabajos heredados sin PID se recuperan después de diez minutos. | +| `GET` / `PUT /api/sidecar-settings` | Leer o establecer la configuración del modelo de búsqueda/visión sidecar. | +| `GET` / `PUT /api/injection-model` | Leer o establecer la selección compartida de modelo/esfuerzo de subagente y los conmutadores de orientación/nativo-predeterminado independientes. | +| `GET` / `PUT /api/v2` | Lea o establezca el modo de superficie, el indicador de características Codex y el límite de hilos v2. | +| `GET /api/providers` · `POST /api/providers` · `PATCH /api/providers?name=...` · `DELETE /api/providers?name=...` | Listar, agregar/reemplazar, habilitar/deshabilitar, establecer el valor predeterminado o eliminar proveedores. `PATCH` utiliza independiente `{ "setDefault": true }` en un proveedor habilitado; `POST` puede incluir `setDefault` al crear/reemplazar (también solo habilitado). Eliminación de la actual por defecto reasigna al primer proveedor habilitado restante cuando existe uno; de lo contrario, el API devuelve `409` con `code: "last_provider"` y mantiene el valor predeterminado actual. | +| `GET /api/models` · `PUT /api/disabled-models` | Enumera filas de modelos nativos/enrutados y actualiza el conjunto de modelos deshabilitados compartidos. | +| `GET /api/selected-models` · `PUT /api/model-visibility` | Lea las listas de proveedores y cambie atómicamente la visibilidad final de un modelo o grupo de proveedores. | +| `GET /api/key-providers` · `GET /api/oauth/providers` | Lea los catálogos de proveedores API y OAuth. | +| `GET /api/oauth/accounts?provider=..."a=1` · `GET /api/providers/keys?name=..."a=1` | Lea cada cuenta o cuota de clave donde sea compatible, sin cambiar la credencial activa. Añadir `refresh=1` para omitir la caché de cuota establecida; se puede compartir una lectura de la misma credencial en vuelo. Omita `quota=1` para una lista local barata con cada fila de `quotaMode`: `probe`, `passive`, o `unsupported`. Las lecturas pasivas devuelven las observaciones existentes sin una sonda de red. Ninguna lectura es lo mismo que el 0% utilizado, y las cuotas para múltiples claves no se suman. | +| `POST /api/oauth/login` · `GET /api/oauth/status` | Inicie un flujo de proveedores OAuth y realice una encuesta para su finalización. | +| `GET /api/codex-auth/accounts?refresh=1` | Listar cuentas principales y de grupo, forzar la actualización de cuotas e informar la cuenta principal `hasCredential` / terminal `needsReauth` Estado. | +| `PUT /api/codex-auth/active` · `PUT /api/codex-auth/auto-switch` · `PUT /api/codex-auth/failover` | Seleccione la cuenta para la siguiente solicitud y configure el enrutamiento del grupo. | +| `GET /api/codex-auth/active` · `PUT /api/codex-auth/accounts/priority` | Lea la cuenta efectiva (incluyendo `pinned` ¿Cuál es la cuenta `pinnedAccountId`y establecer el orden de selección de una cuenta. | +| `POST /api/codex-auth/login` · `GET /api/codex-auth/login-status` | Agregar una cuenta de grupo a través del inicio de sesión del navegador. | +| `GET /api/logs?tail=50&limit=20&offset=0&provider=...&status=5xx` | Lea los metadatos de las solicitudes recientes con filtros opcionales de cola, proveedor y estado exacto/clase. Con `limit`/`offset`, paging camina hacia atrás desde la fila más reciente (`offset=0` devuelve la última página). Forma de respuesta: `{ timeZone, generatedAt, total, logs }` donde `total` es el recuento de filas filtradas antes de la paginación. | +| `GET` / `PUT /api/subagent-models` | Leer o establecer los cinco destacados `spawn_agent` Anule los modelos. | +| `POST /api/stop` | Detenga el proxy/servicio, restaure el Codex nativo y salga. Rechazado con `respawnable_service` en el Backend del Programador de Tareas Windows, con `self_unload_service` cuando este proxy es en sí mismo el trabajo instalado de lanzamiento / sistema, y con `service_state_unknown` cuando no se puede leer el estado del Programador de tareas; nada cambia en ninguno de esos casos. Una sesión de dashboard también es rechazada, con `desktop_supervised`Mientras que la aplicación de escritorio OpenCodex ejecuta el proxy. | + +:::tip +Adición **Ollama Nube** u otro proveedor de catálogo desde el panel copia su texto contra visión En el caso de que la configuración del proveedor sea guardada, [visión sidecar](/es/guides/sidecars/) +se cierra correctamente sin clasificación manual. +::: + + + +### Emparejar este navegador con un hub + +La inscripción de la máquina y la autenticación del navegador son independientes. El panel de emparejamiento nombra el concentrador y muestra un `ocx gui pair --origin` comando para el origen exacto actualmente abierto en su navegador. Ejecute ese comando en el concentrador o envíelo al operador del concentrador y solicite un código de emparejamiento único. Pegue ese código en el panel; una clave API de datos o admin token no es un código de emparejamiento. + +Mientras la autenticación del navegador está pendiente, el panel de control no recomienda reiniciar un cliente conectado saludable. Completar el emparejamiento actualiza los datos del panel de control inmediatamente, incluido un error de autenticación previamente almacenado en caché. La expiración de la sesión vuelve al emparejamiento; la denegación de permiso mantiene su propia guía de configuración de acceso. Otras actualizaciones fallidas pueden mostrar los últimos datos recibidos con un aviso de datos obsoletos y una acción de reintento. + + + +### Teclado de la tabla de uso y controles táctiles + +Los días del mapa de calor de uso tienen un punto de entrada de pestaña. Usa Arriba/Abajo para días adyacentes e Izquierda/Derecha para semanas adyacentes. Las barras semanales exponen los detalles del mismo día en el enfoque del teclado, el puntero o el tacto. Las etiquetas de día incluyen la fecha, el recuento de solicitudes y el recuento de token; las superposiciones de información sobre herramientas permanecen dentro de la ventana. + +### Claude + +**Claude** es una pestaña dentro **Conectar**, cuya tira de pestañas coloca Codex, Claude, Claude Desktop y Grok Build en ese orden. Claude no tiene subpestañas: muestra la configuración de Claude Code directamente. La página comienza con **Claude Code CLI de primera mano**, seguido de **Empezar**, **General** +(compatibilidad, instrucciones del agente y controles de contexto), **Modelo de ayudante de fondo**, +**Interceptación modelo**, **Modelos disponibles**, y finalmente **Conexión Claude**. Una pegajosa barra de Guardar muestra **Sin cambios** o **Cambios no guardados**, con **Reversión** para descartar ediciones y **Guardar** Comprometer A ellos. Ambos interruptores se aplican inmediatamente; **Guardar** Nunca los cambia. Cuando se detiene la interceptación, la página muestra por qué y ofrece **Iniciar interceptación**, que lo inicia en su lugar sin reiniciar OpenCodex. Las subpestañas de Código, Configuración y Cuenta anteriores han desaparecido; todo lo que mostraba la vista Configuración de solo lectura, excepto el número de puerto de intercepción, está en esta página. + +**Escritorio Claude** es su propia pestaña Conectar en `#claude/desktop`. Contiene el selector de modo de escritorio y familias de modelos. Una fila de estado muestra si Claude Desktop ejecuta el perfil y si está guardado, con **Guardar** y **Guardar y aplicar** Al lado. + +Las cuentas Claude/Anthropic se administran solo en **Proveedores > Anthropic > Cuentas**: inicio de sesión y la opción del navegador, la lista de cuentas con interruptor, pausa, eliminar y volver a autenticar, el campo de código de pegado, la configuración del grupo de cuentas y la cuota. Claude ya no tiene una subpestaña Cuenta. Controles a nivel de proveedor, como el proveedor predeterminado, la eliminación y la opción habilitada permanecer en proveedores. + +Los marcadores `#claude` y `#claude/code` abrir esta página, y la anterior `#claude/settings` redirecciona a `#claude/code`; `#claude/desktop` selecciona la token Escritorio Claude separada. El viejo `#claude/account` Marcador redirige a `#providers?provider=anthropic&tab=accounts`. Legado `#integrations/claude` y `#integrations/claude/desktop` Los marcadores todavía redirigen a `#claude/code` y `#claude/desktop`, respectivamente. Las teclas de flecha se mueven entre pestañas; Home y End seleccione la primera y última pestaña. + + + + +## Pruebe un modelo de proveedor + +En **Proveedores**, **Conexión de prueba** comprueba la conectividad de descubrimiento. Utilice el separado **Terminación de la prueba** control para comprobar si un modelo seleccionado responde. Elija un modelo y acepte la confirmación de que la solicitud puede incurrir proveedor cargos. Cancelar la confirmación no envía nada. Cambiar el proveedor o modelo, o abandonando la página, cancela la prueba y descarta un resultado obsoleto. + +La prueba de finalización envía `Reply exactly OK.` una vez con una tapa de salida 32-token, una fecha límite de 20 segundos y un límite de 64 KiB. Se reporta TTFT en el primer delta de texto no vacío, latencia total, el modelo informado en sentido ascendente y una coincidencia, Desajuste o comparación desconocida con el id del modelo de cable. Falta o conflicto Los metadatos ascendentes no verifican la identidad del modelo. El panel muestra la razón de aplicabilidad cuando se configura la autenticación, el adaptador o el transporte no puede ser probado. No se muestra ningún texto generado, y el diagnóstico no actualizar el estado de enrutamiento, el historial de solicitudes o el catálogo de proveedores. + +El endpoint de administración autenticado es +`POST /api/providers/test-completion?name=` con exactamente +`{"model":"","confirm":true}`. Las sesiones del dashboard requieren su token CSRF habitual. La entrada inválida devuelve 400, un proveedor desconocido devuelve 404 y otra prueba concurrente para el mismo proveedor devuelve 409. Diagnóstico y aplicabilidad completos resultados devuelven 200, incluyendo un error estructurado cuando falla la inferencia. Destino Se aplican las configuración de política y salida del proveedor; los redireccionamientos, reintentos y conmutación por error están deshabilitados. Para el flujo de trabajo CLI, consulte [Proveedores y cuentas](/es/reference/cli/providers-accounts/). diff --git a/docs-site/src/content/docs/es/index.mdx b/docs-site/src/content/docs/es/index.mdx new file mode 100644 index 00000000000..531ac5f8f6a --- /dev/null +++ b/docs-site/src/content/docs/es/index.mdx @@ -0,0 +1,19 @@ +--- +title: "opencodex — Ejecuta Codex con cualquier LLM" +description: "Proxy universal de proveedores para OpenAI Codex y Claude Code: usa cualquier LLM con Codex CLI, App, SDK y Claude Code." +template: splash +head: + # Brand-first, no " | opencodex" suffix: Google matches the site name against + # the home page title, so the wordmark leads and is not duplicated. + - tag: title + content: "opencodex — Ejecuta Codex con cualquier LLM" + - tag: meta + attrs: + property: og:locale + content: es_ES +tableOfContents: false +--- + +import Landing from '../../../components/Landing.astro'; + + diff --git a/docs-site/src/content/docs/es/reference/adapters.md b/docs-site/src/content/docs/es/reference/adapters.md new file mode 100644 index 00000000000..3e59b26d830 --- /dev/null +++ b/docs-site/src/content/docs/es/reference/adapters.md @@ -0,0 +1,286 @@ +--- +title: "Adaptadores" +description: "Adaptadores de proveedores: destinos, construcción de solicitudes y particularidades de cada uno." +--- + +Un **adaptador** traduce entre el modelo interno de solicitudes y respuestas de opencodex y el formato de comunicación de un proveedor. Todos implementan `ProviderAdapter`. El siguiente extracto está abreviado; la interfaz completa y vigente está en `src/adapters/base.ts`: + +```ts +interface ProviderAdapter { + name: string; + buildRequest(parsed: OcxParsedRequest, incoming: IncomingMeta): AdapterRequest | Promise; + fetchResponse?(request: AdapterRequest, ctx?: AdapterFetchContext): Promise; + parseStream(response: Response, budget: TranslatorBudget): AsyncGenerator; + parseResponse?(response: Response, budget: TranslatorBudget): Promise; + runTurn?(parsed: OcxParsedRequest, incoming: IncomingMeta, emit: (event: AdapterEvent) => void): Promise; +} +``` + +`buildRequest` transforma un `OcxParsedRequest` en una solicitud HTTP al proveedor; `parseStream` y `parseResponse` convierten su respuesta en eventos internos `AdapterEvent`. `fetchResponse` permite que el adaptador gestione sus propios reintentos y tiempos de espera. `runTurn` admite transportes que no se pueden representar mediante una sola solicitud HTTP seguida de un flujo de respuesta. Después, [`bridge.ts`](/es/reference/architecture/#the-bridge) convierte esos eventos al formato SSE de Responses. + + + +## Entrada de tarea externa en rutas Responses traducidas + +La coordinación de tareas Codex puede entregar la entrada como `function_call_output` con campos `id`, `name` y `namespace` no en blanco y sin propiedad `call_id`. OpenCodex asigna este sobre completo a un mensaje de usuario antes de la traducción del adaptador. Su salida debe ser texto no en blanco o una matriz de texto totalmente compatible y partes de URL `input_image`. El texto y el orden de la imagen se conservan; detalle de la imagen `original` mapas a `high`. + +El contenido vacío, las partes mal formadas u opacas, las imágenes de solo identificación de archivo y los sobres parciales siguen siendo inválidos. Los resultados de la herramienta de función/personalizada ordinaria todavía requieren un `call_id` no vacío. Los metadatos de envolvente identifican una forma de compatibilidad y no conceden permisos adicionales. El paso a través nativo y la compactación enrutada (portátil) aplican la misma asignación de turnos de usuario a sus cuerpos sin procesar; el avance directo nativo `/responses/compact` mantiene sus reglas de cuerpo sin procesar existentes. + + + +## Continuación del punto de control después de la compactación enrutada + +Un modelo enrutado reproduce un punto de control OpenCodeX `ocx1:` como texto de usuario simple junto a las solicitudes anteriores retenidas. Cuando una solicitud lleva dicho punto de control decodificado, OpenCodeX agrega una nota corta a las instrucciones del sistema (rutas traducidas) o `instructions` (Responses passthrough). La nota enmarca las solicitudes completadas como historial y permite la continuación solo de trabajos no terminados ya autorizados y aún dentro de ese alcance, sin solicitar la misma autorización nuevamente mientras se aplica. Permisos existentes y puertas de confirmación permanecen en vigor: las decisiones pendientes o permisos requeridos deben ser resueltos antes de las acciones dependientes. Los puestos de control y las delegaciones, incluidos los de otro hilo, no otorgan autoridad o alcance ampliado. Los mensajes posteriores del usuario tienen prioridad, incluida una pausa, cancelación, reemplazo o cambio de alcance. Las solicitudes de compactación, las manchas nativas opacas y las solicitudes sin punto de control no reciben la nota. + +## `openai-chat` + +**Objetivos:** OpenAI **Chat Completions** (`POST {baseUrl}/chat/completions`; un `/chat/completions` o `/` en `baseUrl` se elimina primero) y todos los proveedores compatibles - xAI, Kimi, DeepSeek, GLM, Groq, OpenRouter, Ollama (local), y más. **Auth:** `key` (Portador). + +Para xAI, el adaptador de flujo ascendente resuelto puede ser `openai-chat` o `openai-responses`, dependiendo de los valores predeterminados del modelo y las anulaciones explícitas de `modelAdapters`. Ambos soportan autenticación de clave pública xAI API y Grok CLI OAuth. El registro de uso [`attempts[].credentialSource`](/es/reference/management-api/) sigue ese transporte resuelto; no infiere atribución de suscripción del protocolo entrante. + +- Convierte los mensajes internos a las funciones OpenAI; herramientas de mapas a `{type:"function", function:{…}}` y `tool_choice` (`auto` / `none` / `required` o una función con nombre). +- **Imágenes de resultados de herramientas** paseo en un mensaje de visión de usuario de seguimiento (`image_url` partes) lanzado una vez que se cierra la ronda de herramientas, ya que el contenido `role:"tool"` es solo texto; el marcador `[image]` permanece en el mensaje de la herramienta como el ancla. +- **Reescribe el mensaje de identidad GPT-5 del Codex** a una intro agnóstico modelo por lo modelos enrutados no pretenden ser OpenAI. +- Para las solicitudes `Qwen3.8-27B` traducidas (incluyendo identificadores separados por nombres de pasarela como `openai/Qwen3.8-27B`), las solicitudes Flash-Next (`flash-next` o `Qwen3.8-Flash-Next`, también con espacios de nombres de pasarela) y las solicitudes `OrcaSAQ-2-Cyber-27B` GGUF, un recordatorio de desarrollador de solo texto después del mensaje de sistema principal permanece en su ranura de conversación, pero se envía como `user`. La excepción Orca requiere `GGUF` en el segmento de modelo final antes de cualquier etiqueta de cuantificación de colon opcional; las variantes de Orca que no son GGUF mantienen su comportamiento de rol de desarrollador configurado. Estas plantillas de chat ancladas, por ejemplo [Qwen3.8-27B](https://huggingface.co/Qwen/Qwen3.8-27B/blob/1d4bf0f2ff6012fd82039f2fa52739d0dd7c60c0/chat_template.jinja), rechazan mensajes posteriores de `system` y no aceptan `developer`, mientras que los mensajes posteriores de `user` son válidos. Esto preserva el orden pero no puede preservar la precedencia del rol de desarrollador. Otros modelos mantienen su comportamiento configurado de rol de desarrollador; el passthrough de Chat nativo no cambia. +- **Abrazaderas `reasoning_effort`** al subconjunto anunciado del modelo cuando un nivel exacto no está disponible; `xhigh` y `max` siguen siendo etiquetas distintas a menos que un proveedor configure explícitamente un alias. El adaptador **lo omite por completo** para ids en `provider.noReasoningModels`. +- Corrientes `delta.content` (texto), `delta.reasoning_content` (pensamiento), y `delta.tool_calls[]`; recoge `usage`. Los proveedores listados en `reasoningDetailsModels` (MiniMax M-series) en su lugar leen los segmentos `delta.reasoning_details` estructurados, cuyo `text` llega como instantáneas acumulativas y se diffed por prefijo, y reproducen el razonamiento preservado como una matriz `reasoning_details`. +- Porque `api.mistral.ai`, ambas rutas de respuesta también aceptan tipeado `text` y `thinking` + matrices. El texto mantiene sus bytes y orden; el pensamiento permanece separado de la respuesta. Los bloques de texto adyacentes comparten el análisis de etiquetas en línea; el pensamiento escrito lo restablece. Los bloques de matriz no compatibles o mal formados devuelven un error ascendente. Otros anfitriones mantener su comportamiento existente. Esto no añade repetición de firma Mistral. +- Suprime texto desnudo `` cuando duplica una llamada estructurada, y colapsa dos bloques idénticos inmediatamente adyacentes cuando exactamente una llamada estructurada está de acuerdo con su función y entrada. Un doble `input` se reduce a una copia, unida directamente o por una nueva línea, y sólo cuando el objeto argumentos no tiene ninguna clave aparte de `input`. El espacio en blanco posterior después de que se suprime el par; el marcado no coincidente o de ejemplo permanece visible. +- ClinePass utiliza el formato de puerta de enlace verificado en vivo `reasoning: { enabled: true, effort }` (o `{ enabled: false }` cuando el razonamiento está deshabilitado); sus API documentos públicos no especifican actualmente esta forma de solicitud. El adaptador conserva los niveles solicitados `low`, `medium`, `high`, `xhigh` y `max`, acepta deltas de razonamiento de `delta.reasoning_content` o `delta.reasoning`, solicita el uso de flujo con `stream_options.include_usage` y lee el uso de envolventes de respuesta no de flujo. + +Las llamadas a herramientas de streaming conservan su identidad cuando un proveedor envía por primera vez un ID, luego asocia ese ID con un índice y luego envía fragmentos de argumentos de solo índice. Esos fragmentos se reúnen en una llamada con el nombre original y argumentos completos; las llamadas paralelas retienen identidades separadas. Cuando está presente, los índices de llamada a herramientas transmitidos deben ser enteros seguros no negativos. Los valores no numéricos y los números negativos, fraccionarios o inseguros terminan el flujo con un error ascendente antes de la coincidencia de identidad. Los índices ausentes y nulos permanecen como marcadores de posición del índice ausente; las cadenas numéricas no son forzadas. + +## `ollama-native` + +**Objetivos:** Ollama 's propio **Chat API** ( `POST /api/chat` ) en lugar de su superficie compatible con OpenAI. El proveedor incorporado `ollama-cloud` se selecciona en este adaptador; también se puede configurar en un proveedor Ollama personalizado o autoalojado por separado con `adapter: "ollama-native"`. **Auth:** `key` (Bearer) para endpoints personalizados/en la nube; no se envía ninguna credencial a loopback o `authMode: "local"` objetivos. + +- **La selección del registro es portante.** La fila incorporada `ollama-cloud` mantiene la URL base `https://ollama.com/v1` para el descubrimiento en vivo `/v1/models`, mientras que la inferencia se normaliza en `POST https://ollama.com/api/chat`. Un nivel de configuración `adapter` se descarta para esa fila de proveedor. El Ollama local incorporado ordinario permanece en `openai-chat`; elegir `ollama-native` para un punto final local o autoalojado es una decisión explícita de configuración del proveedor, detectada por el host para que un destino que no sea Ollama nunca se reescriba en silencio. +- **Metadatos del modelo:** `/v1/models` no lleva metadatos por modelo, por lo que para el canónico Ollama Cloud el proveedor del adaptador enriquece cada id descubierto a través de un *delimitado* `POST /api/show` (256 KiB por respuesta, 8 s por solicitud, concurrencia 4, 48 solicitudes, un plazo de 12 s para toda la fase) para llenar la ventana de contexto real y la capacidad de visión. La solicitud de demostración es del mismo origen y nunca sigue una redirección; los fallos degradan ese modelo y nunca fallan el descubrimiento. +- **Transmisión:** Ollama 's NDJSON nativo. El texto y los deltas `message.thinking` se reenvían a medida que llegan; un giro se completa solo en un registro de terminal `done: true`, y el `done: false` almacenado en memoria intermedia o un terminal faltante suprime completamente las llamadas parciales de texto y herramientas. +- **Razonamiento:** mapas en Ollama 's campo nativo `think` (`low` / `medium` / `high` / `max`, más booleanos), sujetado a la escala anunciada del modelo, y honra la semántica centinela `__omit__` configura aguas arriba. +- **Imágenes:** se envía de forma nativa en la matriz de mensajes `images` donde el modelo tiene capacidad de visión; se rechaza el video en lugar de enviarlo incorrectamente, y no se obtienen URL de imágenes remotas. +- **Herramientas:** declarado en la forma nativa de Ollama, las llamadas de herramienta transmitidas son registros de llamada completa con valor de objeto `arguments`, y la reproducción del resultado de la herramienta se empareja estrictamente con el identificador de llamada y el nombre de la herramienta. Los identificadores de llamada nativos válidos distinguen las llamadas incluso cuando el proveedor repite un índice de función. Los ID repetidos actualizan los argumentos de la misma llamada; Las entradas sin ID vuelven al índice, luego a la posición. Las llamadas retienen el primer orden visto. Con `parallel_tool_calls: false`, una segunda llamada de proveedor distinta aún falla el giro cerrado antes de que se emita cualquier llamada de herramienta. Codex puede grabar los comentarios del asistente antes de los resultados de una llamada pendiente. El texto / pensamiento sin nuevas llamadas de herramientas se aplaza hasta que se resuelva el lote, por lo que los resultados genuinos permanecen al lado de sus llamadas de origen. Un nuevo lote de llamada de herramienta aún establece el anterior; los resultados faltantes conservan un marcador explícito de estado desconocido. Las salidas adicionales para una llamada abierta se unen en orden de llegada; la salida que llega después de que se establece su lote se conserva como texto de conversación explícitamente atribuido, después de cualquier par de llamada/resultado pendiente. Los identificadores de llamada desconocidos y las identidades de herramienta no coincidentes permanecen inválidas; esto no crea ni ejecuta otra llamada de herramienta. La atribución generada para salidas tardías comparte un presupuesto de 256 KiB por solicitud JSON bytes. Exceder ese presupuesto rechaza la solicitud con HTTP 413 `request_too_large` en lugar de truncar las identidades o la salida de la herramienta. El mensaje de error nombra la causa y el límite. Para continuar, inicie un nuevo hilo: la compactación en la misma ruta Ollama reenvía el mismo historial y se rechaza nuevamente, a menos que la compactación se encamine a un proveedor diferente. `tool_choice: "none"` y `auto` se comportan normalmente; **`required` o una opción con nombre exacto falla cerrada**, porque Ollama 's `/api/chat` no tiene `tool_choice` campo para hacer cumplir con. +- **La salida estructurada se rechaza en Ollama Cloud canónico.** Ollama documenta que su nube no admite esa función y no recibe el campo `format`. OpenCodex rechaza la solicitud en lugar de devolver texto sin restricciones cuando se pide un esquema. Los destinos locales y personalizados `ollama-native` conservan la conversión nativa de `format`: `json_object` → `"json"` y `json_schema` → el objeto del esquema. + +## `openai-responses` + +**Objetivos:** el OpenAI **Responses API**. **`passthrough: true`** - normalmente reenvía el cuerpo de la solicitud sin procesar y la respuesta, con estrechas reescrituras de compatibilidad para puertas de enlace enrutadas. **Auth:** canónica OpenAI `forward` retransmite solo la lista de permisos de llamada segura; no canónico `forward` utiliza cabeceras estáticas configuradas sin retransmitir la autorización de llamada; `key` utiliza la clave de proveedor configurada. + +Cuando el historial de Google se reproduce al canónico ChatGPT Codex o al oficial OpenAI Responses API, el adaptador elimina el nivel de elemento `extra_content` de la solicitud HTTP saliente o WebSocket crea. Native `/responses/compact` aplica la misma proyección. La historia original mantiene la firma de pensamiento Google para Google giros posteriores. Otras Responses pasarelas conservan sus extensiones. + +El adaptador conserva el `User-Agent` del cliente entrante como un respaldo en ambos modos de autenticación porque algunos proveedores compatibles con Responses usan la huella digital del cliente Codex para el comportamiento de compatibilidad. Un proveedor configurado explícitamente `User-Agent` sigue siendo autorizado independientemente de la carcasa de la cabecera; si el llamante no envía ninguno, OpenCodex no inventa uno. Se pueden seleccionar metadatos adicionales del llamante con `forwardClientHeaders`; el proveedor `headers` gana para esta opción, y se rechazan los nombres de credenciales o de transporte. Canonical ChatGPT adelante auth conserva su lista de permisos de cabecera fija separada. Solo `originator`, `x-client-request-id`, `x-codex-app-version` y `user-agent` son compatibles con `forwardClientHeaders`; los nombres arbitrarios son rechazados en carga/escritura e ignorados en entorno de ejecución. + + + +### Compactación nativa en puertas de enlace personalizadas + +La compatibilidad con Responses por sí sola no es evidencia de soporte de compactación nativo. Las pasarelas personalizadas continúan usando resúmenes de texto portátiles a menos que el operador declare la capacidad relevante: + +- `supportsNativeCompactionTrigger: true` conserva las solicitudes de v2 `compaction_trigger` y la salida nativa. +- `supportsNativeCompactEndpoint: true` opta por rutas clave/local/directa en el punto final v1 separado. OAuth conserva la compactación enrutada y su ciclo de vida de credenciales existente. El soporte V2 no implica soporte v1. +- `decodesNativeCompactionBlobs: true` preserva manchas nativas en giros posteriores cuando no hay desajuste de proveedor de servicio conocido. Ninguna bandera de generación implica esta capacidad de reproducción. + +Custom native v1 también honra `preserveResponsesReasoningContent: true` para la entrada de razonamiento de texto plano, al igual que las solicitudes Responses personalizadas ordinarias. Ausente o `false` mantiene el contenido en blanco; OpenAI -los destinos compactos operados se mantienen en blanco incluso si la bandera está establecida. Los sobres internos `ocxr1:` siempre se eliminan. La preservación del texto sin formato es independiente de las banderas de generación, la capacidad de reproducción nativa de blob y las verificaciones de identidad de servicio. + +Si el proveedor personalizado también requiere resultados de herramientas adyacentes (`requiresAdjacentResponsesToolResults: true`), tanto el Responses ordinario como el v1 nativo eliminan el texto cifrado de razonamiento opaco y requieren una reproducción de texto sin formato. La falta de `reasoning_text` se llena desde el `summary_text` del artículo, o un marcador de posición mínimo si no existe un resumen utilizable. Se conserva el texto plano existente. OpenAI -operado compacto mantiene su propia política. + +Para una puerta de enlace cuyos **Generación v2 y reproducción** han sido verificados, combine estos campos en su configuración de proveedor existente, conservando su URL real y la autenticación configurada: + +```json +{ + "adapter": "openai-responses", + "supportsNativeCompactionTrigger": true, + "decodesNativeCompactionBlobs": true +} +``` + +Estas banderas no hacen que la puerta de enlace sea un destino oficial de OpenAI, credenciales de llamada directa, cambiar la selección de cuenta o omitir la desinfección de compatibilidad normal. Valide una respuesta compacta real y una conversación continua, no solo HTTP 200. Mantenga blobs en el backend que los acuñó; las opciones de enrutamiento de compactación de proveedores cruzados aún usan resúmenes portátiles. Los resúmenes de reserva V1 siguen siendo portátiles incluso cuando el destino acepta por separado los disparadores v2. Las rutas con capacidad nativa están excluidas de la recuperación de compactación de emergencia portátil para su protocolo respectivo. + +La selección del adaptador no selecciona el transporte ascendente. Las solicitudes elegibles pueden usar el [ruta proxy WebSocket](/es/reference/proxy-formats/#json-and-sse-output); la configuración del proxy WebSocket no válida o no compatible vuelve a HTTP / SSE. HTTP fetch-based Responses manejo utiliza el [outbound fetch configurado](/es/reference/configuration/server/#server-fields): un servidor SOCKS5 proxy de `config.proxy` o un SOCKS5 `ALL_PROXY` utiliza el túnel incorporado cuando `NO_PROXY` no exime el objetivo. Las variables proxy HTTP (S) específicas del esquema conservan su manejo nativo separado; no SOCKS `ALL_PROXY` no es una ruta de extracción HTTP nativa. + +Las pasarelas Responses no canónicas reciben el cliente ejecutado de Codex `tool_search` declaración como a herramienta de función pública segura contra colisiones. El historial de solicitudes coincidentes y las llamadas a la función JSON/SSE son traducido de nuevo a lo privado `tool_search` Ciclo de vida para el cliente. Canonical OpenAI avance mantiene el tipo privado nativo sin cambios. + +Las solicitudes con `authMode` distinto de `"forward"` convierten los elementos `agent_message` de Codex en mensajes públicos de usuario cuando contienen una matriz no vacía de partes de texto plano compatibles. Conservan esas partes y los metadatos legibles de autor y destinatario. `agent_message` es un tipo privado del backend de Codex de ChatGPT; los destinos enrutados observados rechazan el cuerpo completo con `422 unknown item type "agent_message"`. Como Codex reproduce el historial de subagentes en cada turno, el error se repite durante el resto del hilo. El contenido cifrado o desconocido queda sin modificar, al igual que todos estos elementos en proveedores con `authMode: "forward"`. Para xAI Responses en HTTPS, en `api.x.ai` o `cli-chat-proxy.grok.com` y con el puerto estándar, un resultado de subagente de tipo cadena que contenga al menos un carácter que no sea un espacio en blanco también se convierte en una parte `input_text`, conservando exactamente sus espacios y saltos de línea. Los demás destinos conservan los elementos cuyo valor es una cadena. Las cadenas vacías o compuestas únicamente por espacios en blanco y las partes que mezclan contenido cifrado o desconocido no se convierten parcialmente. Véase [Mensajes de agentes](/es/reference/configuration/providers/#routed-agent-messages) para la recuperación opcional de tareas cifradas. + +Para xAI Responses `auto` o `none` La selección de herramientas se omite cuando la normalización no deja herramientas en la solicitud, incluso cuando se elimina la búsqueda solo en caché. Selección de funciones forzadas válidas permanecen intactos. Las llamadas a herramientas personalizadas repetidas con ID de artículo no válido o que faltan reciben ID estables cuando su identificador de llamada, nombre y entrada son cadenas; su emparejamiento de llamada/resultado se conserva. + +El destino canónico ChatGPT Codex también normaliza dos formas públicas Responses que su extremo posterior más estricto rechaza: los mensajes `system` totalmente textuales dentro de `input` se agregan a la cadena `instructions` de nivel superior en orden de solicitud, y se elimina el campo `truncation` de nivel superior. Esta reescritura está limitada al destino. Los proveedores Responses de Key-Auth public/custom y las pasarelas de avance no canónicas mantienen ambos campos sin cambios; un mensaje de sistema multimodal nunca se pliega parcialmente o se deja caer silenciosamente. + +Para las continuaciones directas canónicas, las propiedades `prompt_cache_breakpoint` solo de cliente se eliminan recursivamente dentro de los límites transversales limitados. Cuando `store: false`, `item_reference` filas también se omiten porque el destino no puede resolver un elemento que no persistía. Función/herramienta `call_id` pares y `reasoning.effort` se conservan. + +[Compatibilidad con Luna Reserve](/es/reference/cli/providers-accounts/#luna-reserve-alongside-routed-models) utiliza esta ruta canónica ChatGPT -forward, no la clave-auth o las puertas de enlace arbitrarias Responses. Conserva la lista segura de permisos de llamadas y la normalización de solicitudes de destino que se describen aquí. OpenCodex envía su cabecera de capacidad de Reserva en la búsqueda de uso de cuenta principal propia; esa cabecera no es en sí misma permiso. Las solicitudes de compatibilidad elegibles vuelven a verificar la autorización vinculada a credenciales en el envío. Conversación y compactación son compatibles; ayudantes de visión, ayudantes de búsqueda web, y relé de búsqueda independiente no lo son. + +Para `key` auth, [`retryOn429`](/es/reference/configuration/) también se aplica aquí: un pre-stream 429 espera y reproduce la solicitud idéntica en la misma tecla antes de cualquier otro manejo, exactamente igual que la ruta de solicitud traducida `openai-chat` / Anthropic. Los transportes personalizados `runTurn` no forman parte del bucle de reintento HTTP. + +- El analizador sin estado Responses de DeepSeek recibe normalización del historial de alcance del proveedor: el contexto inyectado por gancho se mueve después de un lote de llamada de herramienta / resultado inequívoco. Las llamadas paralelas permanecen agrupadas antes de sus salidas coincidentes para que cada llamada permanezca en el turno del asistente de razonamiento. Los proveedores tolerantes y los identificadores ambiguos duplicados, faltantes o fuera de orden mantienen su orden de entrada original. + +- `forward` URL → `{baseUrl}/responses`. Un proveedor `key` se ajusta por defecto a la construcción heredada `{baseUrl}/v1/responses`. +- Un proveedor `key` puede establecer un relativo validado `responsesPath`; el adaptador elimina una barra posterior de `baseUrl` y envía `{trimmedBaseUrl}{responsesPath}`. Para Ark Agent Plan, use `baseUrl: "https://ark.cn-beijing.volces.com/api/plan/v3"` con `responsesPath: "/responses"`. +- En el modo `forward` solo se retransmite una lista de permisos de encabezado seguro (`FORWARD_HEADERS`): autorización, ID de cuenta ChatGPT y los encabezados beta/originador/sesión OpenAI. Esta es la ruta de inicio de sesión ChatGPT que también alimenta el [sidecares](/es/guides/sidecars/). + + + +## Afinidad de sesión de Command Code + +El adaptador OAuth `command-code` deriva un `x-session-id` opaco de la identidad del hilo de cliente, luego la identidad de conversación de repetición de razonamiento. Cuando ninguno de los dos está disponible, utiliza una clave de caché rápida solo si la integración ha clasificado explícitamente esa clave como perteneciente a una conversación. Las claves de caché compartidas o no clasificadas no establecen afinidad de sesión; las solicitudes sin una identidad utilizable reciben un ID de sesión nuevo. La recuperación y la reproducción de la historia guardada en caché preservan esta clasificación. + +El proveedor con clave API `commandcode` usa Chat Completions para la mayoría de los modelos y el adaptador Anthropic Messages (`x-api-key`) para los identificadores `claude-*`, que Command Code solo sirve en `/provider/v1/messages`. La selección fija del adaptador solo se aplica mientras el proveedor apunte a ese endpoint. `tokenlab` aplica la misma regla a `claude-*` en `https://api.tokenlab.sh/v1/messages`, el endpoint que TokenLab anuncia para Chat y Messages. Command Code permite reenviar `prompt_cache_key`; esto es independiente del encabezado de sesión del adaptador OAuth y no garantiza un acierto de caché. El preset OAuth `command-code` recibe `/alpha/generate` como NDJSON. Si la pasarela repite como texto el marcado de una llamada MiMo real, se elimina ese duplicado. El marcado que aparece después de prosa normal, incluso si su marcador llega dividido entre deltas posteriores del mismo bloque, se retiene y solo se elimina si una llamada nativa contiene el mismo contenido. Si no coincide, se emite como texto y nunca se convierte en una llamada. La espera solo dura mientras siga abierta una llamada nativa que pudiera ser su duplicado, incluida la primera llamada a esa misma herramienta que empiece después del marcado. Si esas llamadas terminan sin coincidencia, el texto se libera de inmediato; la llegada intermedia de razonamiento u otros eventos no lo libera. Tras una finalización correcta o el cierre de una llamada a herramienta, un bloque completo que contenga únicamente una llamada a una herramienta declarada y no tenga contraparte nativa se restaura como llamada real. Si el turno se interrumpe o falla, queda como texto. Si el analizador no puede interpretar una llamada aislada, pero esta abre, cierra y nombra una herramienta declarada, se descarta en lugar de imprimirse cuando llega la llamada real a esa herramienta o el turno termina correctamente. Una llamada de formato libre repetida sin el cierre `` se considera completa al llegar ``. Esto se aplica a todos los modelos MiMo servidos por Command Code. + +## `anthropic` + +**Objetivos:** Anthropic **Messages** ( `/v1/messages` ). **Auth:** `key` (`x-api-key` por defecto, o `Authorization: Bearer` con `apiKeyTransport: "bearer"`) o `oauth` (Portador + `anthropic-beta`, para Claude Pro/Max). + +- Convierte mensajes a bloques de contenido Anthropic (texto, imagen base64, `tool_use`, `thinking`). +- El razonamiento de la repetición Anthropic Messages comparte el presupuesto de traducción de la solicitud, incluida la sobrecarga de codificación/decodificación de copias. Las peticiones que la superan devuelven HTTP 413 con `translation_buffer_limit`; las firmas y los datos de razonamiento opacos nunca se truncan para encajar. Native Anthropic passthrough utiliza su contrato de tamaño de cuerpo separado. +- **Matemáticas de pensamiento extendido:** Anthropic requiere `max_tokens > thinking.budget_tokens`. El adaptador asigna el esfuerzo de razonamiento a un presupuesto (mínimo 1024... max 32000), luego calcula un seguro `max_tokens` con espacio libre de salida, y **caídas `temperature` / `top_p`** cuando el pensamiento está habilitado (Anthropic los prohíbe allí). +- **Pantalla de pensamiento adaptativo:** modelos de pensamiento adaptativo (Opus 4.7 +, Sonnet 5, Fable) se les pide `thinking.display: "summarized"`, por lo que una larga idea llega a Chat y Responses clientes como deltas de razonamiento en lugar de minutos de latidos del corazón. Una solicitud que oculta el resumen de razonamiento (`reasoning.summary: "none"`) mantiene el proveedor predeterminado. +- **Salida estructurada:** Responses `text.format` y Chat Completions `response_format` las solicitudes con `type: "json_schema"` se convierten en Anthropic `output_config.format`. El formato se fusiona en una configuración de salida de pensamiento adaptativo existente, conservando un `output_config.effort` compatible. Las solicitudes Anthropic Messages enrutadas conservan el mismo formato a través de la traducción OAuth almacenada. El adaptador refleja el subconjunto de esquemas JSON soportado por Anthropic TypeScript SDK: las restricciones no soportadas se mueven a `description` como guía de modelo, `oneOf` se convierte en `anyOf` y los esquemas de objetos reciben `additionalProperties: false`. Una raíz `$ref` retiene su `$defs` adyacente de modo que la referencia local permanece resoluble. OpenAI campos envolventes tales como esquema `name`, envolvente `description` y `strict` no son parte del formato de cable Anthropic. El modo objeto JSON sin esquema no tiene equivalente Anthropic y no se traduce. En la dirección inversa, los esquemas de salida traducidos Anthropic conservan el esquema original del llamante. `strict: true` requiere una raíz de objeto sin una unión de raíz y objetos cerrados completos en todas las propiedades anidadas, elementos de matriz, uniones y definiciones: `properties` debe ser un objeto, `additionalProperties` debe ser `false` y `required` debe contener exactamente sus nombres de propiedad. Los objetos incompletos, palabras clave de esquema desconocidas y valores fuera del subconjunto estricto documentado de OpenAI usan `strict: false` explícito; el clasificador usa una lista de permisos en lugar de perseguir cada restricción no soportada por separado. El proxy no inventa campos requeridos, cierra un objeto abierto o descarta el esquema del llamante simplemente para obtener el modo estricto. +- Siempre envía `anthropic-version: 2023-06-01`. Corrientes `content_block_delta` (`text_delta`, `thinking_delta`, compatibles `reasoning_delta`, `input_json_delta`). El decodificador SSE conserva el estado del evento a través de fragmentos de extracción y acepta un terminal `message_stop` sin una nueva línea posterior. En `message_stop`, el flujo traducido emite su resultado terminal y termina sin esperar a EOF aguas arriba. Los pings o comentarios posteriores no convierten ese mensaje completado en un error de flujo de búsqueda web. Los pings y los comentarios anteriores a `message_stop` siguen manteniendo viva la larga reflexión; los rechazos siguen siendo resultados incompletos no recuperables y las razones de detención de errores ascendentes siguen siendo fallas. +- Para los giros Anthropic Responses encaminados con herramientas de cliente, un protector de terminal limitado detecta el caso de alta confianza en el que el usuario solicitó una acción pero Claude termina con una reclamación de ejecución y sin llamada de herramienta. Realiza como máximo una continuación interna; las respuestas normales, las preguntas de aclaración, los giros que usan herramientas y las respuestas incompletas de transporte no se retiran automáticamente. + +## `google` + +**Objetivos:** Google **Gemini**, **Vertex AI**, y la Antigravity **Asistencia de código en la nube**. AI Studio utiliza +`/v1beta/models/{model}:streamGenerateContent`; los otros modos usan sus puntos finales nativos Google. +**Auth:** clave API, Vertex ADC o Google Antigravity OAuth, seleccionado por `googleMode`. + +- **Las denegaciones de ubicación son errores de permiso, no solicitudes inválidas.** Google rechaza ubicaciones geográficas o de centros de datos no compatibles con HTTP 400 `FAILED_PRECONDITION: User location is not + supported for the API use.` El proxy informa de esto como `… location not supported: …` y lo clasifica como `permission_error` con el código `location_not_supported`, por lo que un cliente no lee mal un rechazo de ubicación de red como un mensaje mal formado. La respuesta directa HTTP mantiene las rutas de terminal de solo mensaje ascendentes 400 infer 403 (clase de permiso). La restricción en sí es Google 's - el proxy no se enruta alrededor de él. +- → `systemInstruction`; mensajes → `contents[]` (asistente → `model` ); herramientas → `functionDeclarations`. Datos-URL imágenes → `inline_data`. +- Los identificadores de llamada a herramientas se sintetizan cuando Gemini los omite. Vertex y Antigravity preservan y reproducen valores opacos de `thoughtSignature` para que las continuaciones de resultados de herramientas conserven la continuidad del razonamiento de Gemini. La caché de firma se captura en el directorio config, por lo que las continuaciones también sobreviven a los reinicios de proxy. +- **Las formas de respuesta mal formadas fallan al cerrarse.** Un candidato reclamado, su `content`, o su `content.parts` que no es el contenedor documentado termina el turno con un error `google response contained invalid …` nombrando la razón estructural y el tipo del valor ofensivo - nunca su contenido. La ausencia se maneja por separado de la corrupción: una ausencia, `null` o `content` vacío o `parts` todavía completa el turno normalmente, un fragmento de flujo continuo cuyo `candidates` está ausente, `null` o vacío se omite para que el turno se complete en una trama terminal posterior, y una respuesta almacenada en memoria intermedia que no lleva ningún candidato en todos los retornos `google response contained no candidates`. Una raíz `data: null` keepalive marco todavía se omite como relleno. +- Los lotes de llamada de herramienta se cierran en un turno de usuario inmediatamente adyacente que contiene un pedido de `functionResponse` por llamada representable. Las historias interrumpidas reciben un marcador explícito de resultados perdidos; los resultados duplicados o independientes se conservan como texto marcado (y hermanos de imagen) en lugar de emitirse como partes no emparejadas inválidas de `functionResponse`. +- **Entrada de vídeo y procesamiento angélico.** La parte de contenido compatible con OpenAI `{"type": "video_url", "video_url": {"url": "…", "processing": "agentic"}}` se acepta en las rutas de ingreso de Chat y Responses. `url` es necesario; `processing` es opcional y está encajonado en la parte Gemini como `media_processing` (`STATIC` es el valor predeterminado de Gemini, `AGENTIC` solicita comprensión de video agente). El campo se encuentra en el **parte**, al lado de `inline_data` o `file_data`, por lo que se aplica a los bytes en línea y URIs buscados por igual: no es el `processing` de Interacciones API. Una solicitud que omite `processing` no gana campo, por lo que las llamadas existentes no cambian. + + Se manejan tres formularios de URL, y solo tres: + + | `url` | enviado como | + | --- | --- | + | `data:` URL | `inline_data` con el tipo de medio propio de la URL de datos | + | YouTube ver URL (`youtube.com`, `youtu.be`, `m.`/`music.`/`-nocookie` variantes) | `file_data.file_uri` | + | `https://generativelanguage.googleapis.com//files/` - el formulario de recursos de Archivos API, donde `` es `v1`, `v1beta` o `v1alpha` | `file_data.file_uri` | + + Cualquier otra URL remota se mantiene como el marcador de texto `[video: ]`, porque el adaptador no tiene ningún tipo de medio para él y no hay evidencia de que Gemini lo buscará. La lista de permisos se hace coincidir en el host de la URL analizada y la ruta sobre HTTPS, no en una subcadena, para que un host similar no se convierta en una referencia `file_data` que el proxy pida a Gemini que busque. La ruta está anclada en el inicio, por lo que el punto final de carga reanudable (`/upload//files/`) es *no* aceptado: no es un recurso legible, y `file_data.file_uri` pide a Gemini que no haga referencia a lo que se da. `file_data` lleva `file_uri` solamente; no se adjunta `mime_type` adivinado. + +- **Salida de imagen en línea:** cuando el modelo es uno de los ID de chat explícitos con capacidad de imagen (`gemini-3.1-flash-image`, `gemini-2.0-flash-preview-image-generation` o `gemini-3-pro-image-preview`), el adaptador envía `responseModalities: ["TEXT", "IMAGE"]`. No se incluyen los ID de generación de medios independientes, como `gemini-3-pro-image`. Las partes `inlineData` devueltas se materializan bajo el directorio OpenCodex `artifacts/` configurado y aparecen como enlaces de imagen de marcado descendente a la ruta opaca autenticada `/v1/opencodex/artifacts/` (no `file:` URI o rutas del sistema de archivos host). Cada imagen se limita a 50 MB y cada respuesta a 100 MB de datos decodificados; se rechazan las cargas útiles base64 mal formadas. Los artefactos se podan automáticamente cuando el recuento supera los 200 archivos. + +## `kiro` + +**Objetivos:** el servicio Amazon CodeWhisperer Streaming `GenerateAssistantResponse` utilizado por Kiro (`https://runtime.{region}.kiro.dev/` ). **Auth:** Kiro OAuth token de acceso como portador, con metadatos de región/perfil de la credencial Kiro. + +- Construye Kiro `conversationState`, mapea las herramientas Codex y los resultados de la herramienta, y envía bloques de imágenes compatibles por el cable Kiro. +- Conserva como máximo 20 imágenes en línea por mensaje y 100 por solicitud. Las imágenes antiguas del historial se omiten primero cuando la solicitud excede el límite, con un marcador de texto en los mensajes afectados; las imágenes recientes en el turno actual permanecen disponibles. +- Cuando una URL de datos de imagen en línea carece de bytes de imagen o una coma, omite esa imagen con un marcador de texto en su turno de usuario o resultado de la herramienta. Las referencias a imágenes remotas usan un marcador separado; ninguno de los marcadores repite la URL. +- Coalesce las salidas adyacentes de la misma herramienta original en un resultado Kiro. El texto permanece ordenado, las imágenes conservan los límites por mensaje existentes y cualquier indicador de error permanece establecido. Usuario, desarrollador, asistente u otra herramienta de salida termina el grupo. Se rechazan ID originales distintos que se asignan al mismo ID normalizado de Kiro. +- Las salidas combinadas mantienen texto real e información de fallos sin insertar una pista de salida vacía para un fragmento en blanco posterior. Un solo resultado mantiene su normalización existente; un grupo completamente vacío de texto recibe un recurso alternativo, con una redacción neutral cuando hay imágenes o una bandera de error. +- Trata un valor de cliente `parallel_tool_calls: true` como permiso en lugar de un requisito de cable. Kiro permanece serializado: el catálogo enrutado no anuncia ninguna capacidad de herramienta paralela y el adaptador no envía ningún campo de control paralelo aguas arriba, pero las vueltas de herramienta ordinarias Codex no se rechazan únicamente porque el cliente permite llamadas paralelas. +- Acepta Responses `text` controles que no son salida estructurada - `text.verbosity` y `text.format: {"type":"text"}` - sin reenviarlos. Kiro no tiene campo de alambre para ninguno, por lo que son ignorados en lugar de rechazados. La salida estructurada (`text.format` del tipo `json_schema` o `json_object`) todavía se rechaza: el cable Kiro no puede restringir la forma de la respuesta, y una persona que llama esperando JSON recibiría prosa. +- Decodifica `application/vnd.amazon.eventstream`, reconstruye eventos de texto / pensamiento / herramienta, detecta la herramienta truncada JSON y estima el uso porque el flujo ascendente no devuelve recuentos de tokens. +- Utiliza el `baseUrl` configurado literalmente cuando es personalizado. Una URL canónica `runtime.{region}.kiro.dev` sigue la región API de la credencial importada; solo esa forma canónica es elegible para un retroceso presupuestado a `q.{region}.amazonaws.com` después de un fallo de punto final, firma, DNS o conexión, o HTTP 502/503/504 recibido antes de la salida. +- Posee recuperación de conexión-reseteo segura para reproducción, esa única reserva de punto final elegible, una actualización/reproducción OAuth después de HTTP 401 y recuperación limitada para transitorios Kiro 429. Una revisión compartida y una única prueba posterior al enfriamiento evitan que las solicitudes simultáneas agoten los presupuestos de reintento independientes; los fallos de cuota difícil no se vuelven a intentar en esa misma cuenta y no se vuelven a reproducir otros errores de servicio. Cada envío físico Kiro utiliza la salida del proveedor configurada. Una fecha límite de encabezado devuelve 504; la cancelación de la persona que llama detiene el turno. Los cuerpos finales HTTP 5xx usan texto público fijo sin detalles previos. +- Su analizador sin flujo drena el mismo flujo de eventos para el bucle de búsqueda web. +- Informes de uso por cuenta. `AmazonCodeWhispererService.GetUsageLimits` en `https://management.{region}.kiro.dev/` devuelve la asignación del plan, que se convierte en la ventana de cuota mensual para esa cuenta; un saldo de prueba gratuita se informa como su propia ventana. La región proviene del perfil de la cuenta ARN, luego su región API /SSO almacenada. Una cuenta de AWS Builder ID no tiene un ARN de perfil propio, por lo que la sonda envía el mismo perfil de servicio Builder ID que utilizan las solicitudes de generación; ese ARN fijo nunca selecciona la región. Una respuesta ilegible o no reconocida se informa como desconocida en lugar de como uso cero, y una cuenta cuyo exceso está habilitado no se trata como agotada simplemente por pasar su límite. La operación no está documentada por AWS, así que trate los números como el mejor esfuerzo. Una cuenta sin ID de constructor sin un perfil utilizable ARN no hace ninguna solicitud de uso; el uso no está disponible mientras que una barra de cuota de mismo inicio de sesión anterior permanece visible. Las pruebas de cuota y agotamiento conocidas sobreviven al reinicio solo por el mismo inicio de sesión, cada uno hasta su propio reinicio o vida útil de diez minutos. La evidencia faltante, vieja o malformada se vuelve desconocida. El saldo crediticio preciso del plan se mantiene con la lectura de la cuota de identidad. Por separado, los valores de crédito Kiro `meteringEvent` son gastos de solicitud medidos: se usa el último valor dentro de una respuesta física y se agregan créditos de envíos facturados por separado. El uso de tokens sigue siendo estimado; los créditos nunca se infieren de los tokens. +- Después de una solicitud admitida, lee los modelos disponibles de esa cuenta desde el servicio de gestión regional sin retrasar la solicitud. Los resultados almacenados en caché agregan ID de modelo al catálogo enviado. Las respuestas vacías o no reconocidas retienen la lista enviada y cualquier lista de la última buena cuenta. La membresía modelo guía la preferencia de cuentas elegibles; las identificaciones desconocidas aún van hacia arriba. Los límites de entrada informados informan las ventanas de contexto, combinadas de manera conservadora con los límites enviados cuando la evidencia es parcial. Las cuentas que no han servido aún no tienen evidencia de lista. +- Participa en la rotación de cuentas múltiples. Con dos cuentas almacenadas, un rechazo de tasa de solicitud enfría brevemente la cuenta rechazada; un rechazo exacto de cuota mensual en HTTP 400 o 429 lo excluye hasta el reinicio observado o la expiración de la evidencia. Una suspensión confirmada de HTTP 403 pone en cuarentena esa cuenta en proceso, mientras que una 403 ordinaria no rota. La rotación reactiva permanece disponible cuando `oauthAccountFailover.enabled` es falsa. La selección consciente de rechazo antes del primer envío requiere preferencia proactiva, con la configuración del proveedor teniendo prioridad sobre la configuración global. Un giro completo del mismo inicio de sesión borra un veredicto de agotamiento más antiguo. Cada portador rotado lleva su propio perfil ARN y región. + + + +### Semántica de finalización + +El texto del asistente Kiro no tiene una fase de giro final propia confiable. Su terminal `metadataEvent` puede llevar un nativo `stopReason`, pero Kiro puede etiquetar la prosa de progreso como `END_TURN`. Por lo tanto, en los giros habilitados para herramientas, `END_TURN` y `STOP_SEQUENCE` solo prueban que la inferencia se detuvo; el texto ordinario permanece como comentario e ingresa la validación de finalización limitada. + +`END_TURN`, `STOP_SEQUENCE`, o una razón de parada faltante puede usar la ruta de compatibilidad. Otras razones explícitas ya han terminado la inferencia en sentido ascendente, por lo que el adaptador las informa en lugar de gastar otra solicitud de modelo: una superficie de límite de token de salida como salida incompleta que un cliente puede continuar, mientras que las superficies de agotamiento de ventana de contexto como un error de longitud de contexto no reintentable en lugar de como salida truncada. El filtrado y la barrera de protección se detienen en la superficie como salida incompleta filtrada, y una parada `TOOL_USE` que llega sin una llamada de herramienta real se informa como una contradicción en lugar de tratarse como progreso. + +Cuando existe una herramienta cliente normal, opencodex agrega una herramienta privada `codex_kiro_final_answer` a la solicitud ascendente; progrese flujos de texto como comentario y no puede terminar el turno. El adaptador consume la llamada privada, emite su respuesta como texto final, y nunca expone la herramienta privada a Codex o Claude Code. Debido a que la razón de parada solo llega al final de la secuencia, el texto del asistente en un turno habilitado para herramientas se mantiene hasta que se inicia una llamada de herramienta real o la secuencia termina, luego lo libera como comentario a menos que la herramienta privada proporcione la respuesta final. Cuando el sidecar de búsqueda web está activo, los comentarios publicados aún se transmiten antes del evento terminal; solo los eventos necesarios para decidir si el modelo solicitó una búsqueda sintética permanecen almacenados en el búfer. + +Una pregunta sin la que el modelo no puede proceder es también una respuesta final. El contrato inyectado le dice a un modelo enrutado que cuando necesita una decisión, una información o una aclaración que solo el usuario puede dar, debe entregar esa pregunta a través de `codex_kiro_final_answer` y detenerse, en lugar de escribir la pregunta como texto ordinario y continuar. Tal turno llega como cualquier otra respuesta completada: texto final con el turno terminado, no comentario y no una llamada de herramienta de cliente. Sin esto, el contrato sólo describe "todavía funciona" y "completamente", y un modelo de celebración de una pregunta de bloqueo no tenía manera de decirlo - el resultado observado fue una pregunta y una auto-invalidación emitida como un mensaje, seguido de otra llamada herramienta de la misma inferencia. + +Si Kiro se detiene sin llamar a la herramienta de finalización, el adaptador hace una continuación. Razonamiento: solo los reintentos conservan el turno original válido de usuario/resultado de la herramienta en lugar de fabricar un mensaje de asistente vacío; el progreso visible se reproduce con una instrucción propiedad del adaptador no vacía. Antes del transporte, la conversación generada se comprueba en busca de roles alternativos, giros estructurales no vacíos e identificadores de uso de herramientas/resultado coincidentes. La salida de la herramienta vacía recibe un marcador de posición neutral no vacío. El reintento no se puede repetir: un reintento vacío o solo razonado se devuelve como incompleto reintentable, mientras que una llamada de herramienta de cliente real mantiene el turno abierto. Una respuesta de la herramienta de finalización siempre se emite como `final_answer`, incluso cuando se repite exactamente el comentario anterior, porque la corrección de fase es más importante que la deduplicación cosmética. Las solicitudes libres de herramientas conservan el comportamiento normal de finalización del texto. + + + +### Esfuerzo de razonamiento + +La familia GPT-5.6 utiliza `additionalModelRequestFields.reasoning.effort`; `claude-opus-5` utiliza `additionalModelRequestFields.output_config.effort`. Para `gpt-5.6-luna` y `gpt-5.6-terra`, solo `low`, `medium`, `high` y `max` usan la ruta nativa verificada. Su selección `xhigh` conserva las instrucciones previas de pensamiento limitado en el contenido del usuario porque ese peldaño nativo no ha sido verificado. `gpt-5.6-sol` y `claude-opus-5` mantienen su comportamiento nativo existente `low`, `medium`, `high`, `xhigh` y `max`. Otros Kiro modelos usan razonamiento emulado; un control de esfuerzo anunciado no es prueba de apoyo nativo. + +## `cursor` + +**Objetivos:** Cursor 's `agent.v1.AgentService/Run` sobre HTTP/2 Conecte la transmisión en `api2.cursor.sh` por defecto. Con `upstreamHttpVersion: "http1.1"` (o `"h1"`), utiliza Cursor 's HTTP/1.1 par de compatibilidad: `agent.v1.AgentService/RunSSE` para la salida del servidor y `aiserver.v1.BidiService/BidiAppend` para mensajes de cliente. **Auth:** Cursor OAuth /token de acceso desde `provider.apiKey` o la cabecera de autorización reenviada. + +- Utiliza `runTurn` en lugar de la ruta ordinaria de extracción / análisis. Las solicitudes, los eventos del servidor, los argumentos de la herramienta, los puntos de control de uso y las respuestas del cliente se codifican con `@bufbuild/protobuf` esquemas en `cursor/gen/agent_pb.ts` y se enmarcan como mensajes de conexión. +- Reproduce el estado de la conversación a través de blobs dirigidos al contenido, mapea las llamadas de la herramienta del servidor al Codex, descubre los modelos en vivo del Cursor a través del protobuf `GetUsableModels` RPC y vuelve a intentarlo solo antes de que se envíe una solicitud de ejecución al cable. +- Después de un giro sin herramientas exitoso, el adaptador mantiene Cursor ConversationStateStructure devuelto en un almacén de proceso local y reutiliza ese punto de control en la siguiente continuación lineal validada en lugar de reconstruir toda la historia raíz. Los turnos de resultados de herramientas reutilizan el último turno completado punto de control más solo el sufijo descubierto cuando se conoce el límite del mensaje cubierto. La búsqueda de prefijos sin refrescar requiere una conversación Cursor recordada o un hilo de cliente estable (incluyendo la sesión de escritorio limitada / retroceso del hilo) y un punto de control propiedad de ese mismo conversación con el proveedor; de lo contrario, se reproduce completamente. Compactación, aislamiento helper/shadow, desajuste cuenta/modelo, falta de refs, fallos de decodificación, recuperación forzada-fresca, y invalid_argument reintentos caen de nuevo a la repetición completa existente. A El reinicio del proceso elimina el almacén en memoria y las repeticiones completas. Cursor Conectar todavía no expone cache_read_tokens autorizada, por lo que el uso de OpenCodex no es un contador de aciertos en caché. El respaldo de escritorio limitado almacena solo un propietario derivado de HMAC de proceso; sesión/hilo en bruto cabeceras y OAuth/material de autorización nunca se escriben en el estado del punto de control. Cursor El transporte en vivo respaldado por OAuth y el descubrimiento de modelos filtrados por cuenta siguen siendo experimentales; vea el + [guía del proveedor](/es/guides/providers/) y [Configuración del proveedor Cursor](/es/reference/configuration/providers/#cursor-provider-adapter-cursor) + para los configuración de inicio de sesión y transporte. La reutilización del punto de control es automática y no tiene ninguna configuración de usuario. +- Las continuaciones de herramientas de modelo externo mantienen la última solicitud de usuario real en la acción activa; los resúmenes automáticos y el contexto de entorno-navegador independiente siguen siendo contexto histórico. La entrada de usuario en blanco o solo imagen no revive una solicitud anterior. Grok 4.6 guía de modo de código requiere la emisión de resultados explícitos y nunca supone una celda vacía completa emitida salida. La salida faltante requiere una comprobación de estado de solo lectura, no una repetición de un efecto secundario completado. El aviso de repetición se restablece en un nuevo turno de usuario / desarrollador y permite las encuestas solicitadas. Si las raíces de los puntos de control superan el presupuesto de reproducción, el historial disponible se reconstruye bajo los mismos límites. Estas reparaciones no garantizan una redacción ni un comportamiento de razonamiento idénticos entre las rutas Cursor y xAI. +- Honores `upstreamHttpVersion` para el descubrimiento y la inferencia del modelo en vivo. `auto`, `http2` y `h2` conservan el transporte HTTP/2 existente; solo `http1.1` y `h1` seleccionan el modo de compatibilidad. +- Expone Cursor Router como `cursor/auto` más entradas explícitas `cursor/auto-cost`, `cursor/auto-balance` y `cursor/auto-intelligence`. Los niveles explícitos se codifican en `requested_model.parameters` mientras que la entrada `cursor/auto` heredada retiene el valor predeterminado de la cuenta/equipo. +- Envía niveles regulares `cursor/grok-4.5` con los identificadores de cable de descubrimiento en vivo exactos de Cursor (`cursor-grok-4.5-low`, `-medium` o `-high`). Mantiene el `cursor/grok-4.5-fast` seleccionable mientras envía el modelo canónico `grok-4.5` con parámetros separados `effort` y `fast=true`. +- Cursor -la ejecución nativa local de filesystem/shell/network se deniega de forma predeterminada. Las integraciones explícitas `mcpServers` y `desktopExecutor` tienen opt-ins separados; `nativeLocalExec: "on"` habilita el ejecutor incorporado más amplio y evita la aprobación/semántica de sandbox Codex, y el legado `unsafeAllowNativeLocalExec: true` permanece equivalente solo cuando `nativeLocalExec` no está activado. Los primeros `shellArgs` y `shellStreamArgs` son una excepción: ambos son rechazados antes de aparecer en cada plataforma hasta que la propiedad descendiente respaldada por el kernel esté disponible. Utilice herramientas de shell de cliente; la ejecución de shell de fondo y otras operaciones nativas conservan su política existente. +- La respuesta de denegación sigue al catálogo de solicitudes. Los modelos explícitos Claude -familia Cursor reciben una redacción fáctica que nombra las herramientas disponibles sin instrucciones para ocultar o evitar discutir la redirección. El comentario de enrutamiento de hecho puede preceder a la siguiente llamada a la herramienta sin finalizar el turno. Cuando no hay ningún cliente o herramientas MCP configuradas disponibles, se pide a los modelos Claude que respondan sin herramientas o informen la limitación en lugar de llamar a herramientas de shell/edición inexistentes. Otros modelos, incluyendo Auto/default, conservan la redacción silente-redirect existente y la guardia de comentarios. La disponibilidad de la herramienta, la política de ejecución y el comportamiento de aprobación/caja de arena no cambian. En el modo de código - un formulario libre unificado `exec` y sin puente de shell desnudo - los puntos de redirección dentro de `exec`, donde shell, archivo, búsqueda y búsqueda se anidan `tools.(...)` ayudantes de la celda JavaScript, y nunca recomienda que el modo de código de puente de shell de nivel superior no exponga. Un catálogo plano que lleva `shell_command` / `exec_command` o un `exec` unificado sin forma libre mantiene la redacción del puente; un catálogo que lleva ninguno - un cliente orquestador exponiendo solo sus propias herramientas Responses, por ejemplo - se redirige a los nombres de cable reales de la solicitud, por lo que el modelo apunta a una herramienta que existe en lugar de a un alias que no puede ver. +- Una puerta de política de datos Cursor reconocida se informa con su título, la acción que requiere y la URL de revisión del panel de control Cursor en lugar de una `failed_precondition: Error` desnuda. El reconocimiento se limita a los detalles estructurados conocidos: los detalles desconocidos o mal formados mantienen el error genérico de Connect, no se reenvía ni se ejecuta ninguna acción de texto, botón, URL o consentimiento ascendente, y el fallo no se puede volver a intentar. La revisión y aceptación de una política de datos sigue siendo una acción del usuario en el propio Cursor. + +Los esquemas de shell compatibles con Codex conservan los permisos de sandbox, la justificación, las reglas de prefijo reutilizables y el modo de inicio de sesión. Las herramientas de forma libre exponen una cadena requerida `input` y preservan su guía específica de herramienta, como la envoltura de parche requerida; los nombres desnudos `exec_command` y `shell_command` están reservados para puentes de concha no de forma libre. Espacio de nombres es una herramienta de forma libre personalizada que utiliza cualquiera de los nombres. Estas declaraciones de esquema no otorgan aprobación ni cambian la directiva de ejecución. + +## `devin` + +**Objetivos:** Cognition's `exa.api_server_pb.ApiServerService/GetChatMessage` sobre HTTPS Conectar transmisión en `server.codeium.com`. **Auth:** Devin/Cognition API clave de `provider.apiKey` o la cabecera de autorización reenviada. Login primero intenta importar la credencial que Devin CLI ya tiene instalada: `devin auth +login` completa el propio inicio de sesión PKCE del CLI y escribe un `devin-session-token` en su `credentials.toml`, que es la misma credencial `SeatManagementService.RegisterUser` mentas para un inicio de sesión en el navegador. Cuando no existe una credencial CLI utilizable, el inicio de sesión vuelve al inicio de sesión del navegador Auth0 e intercambia el token pegado a través de `RegisterUser` por una clave API de larga duración. `devin-cli` sobrevive solo como un alias obsoleto: `ocx login devin-cli` aún se encamina a `devin`, y una configuración guardada que nombra el antiguo id se reescribe al inicio. + +- Utiliza `runTurn` en lugar de la ruta ordinaria de extracción / análisis. Las solicitudes y los eventos del servidor se codifican con el encuadre manual de protobuf en `devin/cloud-direct/wire.ts`; la ruta ordinaria `buildRequest` / `parseStream` está deshabilitada. +- Las conversaciones con nombre reutilizan una trayectoria en turnos secuenciales, con alcance a la credencial resuelta y al host inquilino. La identidad de hilo propio tiene prioridad sobre los marcadores de sesión (`session_id`, `session-id` o `x-session-affinity`). Cuando se suministran una identidad de hilo propio y un `x-codex-parent-thread-id` no vacío, su par identifica la conversación, por lo que las ID propias iguales bajo diferentes padres permanecen separadas. Las identidades independientes propias y de solo sesión conservan su precedencia existente; un padre compartido solo no es una identidad de conversación. Los turnos superpuestos reciben distintas ID. El proxy retiene como máximo 256 entradas en la memoria, desaloja solo entradas inactivas y libera reclamaciones después de la finalización, el fallo o la cancelación. Reiniciar el proxy borra la retención. Las llamadas sin nombre continúan asignando un ID por solicitud. Esto admite continuidad pero no garantiza un éxito de caché ascendente o un ahorro particular. +- La continuidad del razonamiento lleva firmas de proveedores a través de turnos. Si Cognition rechaza una repetición firmada de Anthropic antes de la salida visible, Devin vuelve a intentarlo una vez con la firma retenida y el texto pensante conservado. +- Descubrimiento de modelos en vivo a través de `GetCascadeModelConfigs`; la semilla estática se filtra contra la lista en vivo de la cuenta para que los modelos no se retiren del plan en lugar de fallar a la hora solicitada. +- Las definiciones de herramienta se codifican en la solicitud y los eventos de llamada de herramienta se decodifican a partir del flujo de respuesta. Cognition impone un límite de longitud por herramienta-descripción (6998 caracteres) y una lista de bloques de frases exactas; el adaptador desinfecta los disparadores conocidos y trunca las descripciones demasiado largas antes de codificar. +- Las claves API de Devin/Cognition no tienen punto final de actualización. Si Cognition rechaza una clave almacenada con 401, OpenCodex marca esa cuenta para la reautenticación y puede usar otra cuenta de inicio de sesión para El turno. Correr `ocx login devin` de nuevo para una clave de inicio de sesión del navegador revocada. Una cuenta importada por CLI Puede seguir un `devin auth login` rotación de teclas solo cuando su ID de cuenta o correo electrónico almacenados coincide con la identidad CLI acuñada. Importaciones sin una identidad almacenada requieren un + `ocx login devin` Después de la rotación. Un legado `devin-cli` slot para esa misma cuenta ya puede Mantenga la nueva clave; una cuenta diferente que la mantenga bloquea la adopción. Si el archivo CLI es temporalmente ilegible o la verificación de identidad no está disponible, reintente después de que se recupere. Una cuenta en pausa permanece en pausa durante esta recuperación y devuelve 403. +- Solo la credencial es local cuando se usa la ruta de importación CLI. El turno en sí mismo va a Cognition de cualquier manera, por lo que las rutas de inicio de sesión de importación y navegador no difieren en nada más que de dónde vino la credencial. Instale el CLI con `curl -fsSL https://cli.devin.ai/install.sh | bash` o `brew install --cask devin-cli`, ejecute `devin auth login` una vez y luego agregue el proveedor. +- Una compilación anterior envió un segundo adaptador bajo el id `devin-cli` que ejecutó el turno como una sesión de Protocolo de cliente de agente contra un proceso secundario local `devin acp`. Se ha ido. Una configuración guardada que todavía nombra ese adaptador se reescribe a `devin` al iniciarse, incluida una fila con nombre personalizado como `"devin-acp"`. +- La solicitud de chat está calibrada, no adivinada. Tres cosas lo unen: la credencial es el token de sesión duplicado y unido en un encabezado `Authorization: Basic`, mientras que el cuerpo del protobuf mantiene una copia, la envolvente de la solicitud sube sin comprimir y `Metadata` #31 lleva una huella digital del dispositivo de 732 caracteres cuya longitud, no valor, el servicio verifica. En el interior `CompletionConfiguration`, el campo #2 es el límite de salida y el campo #3 es `max_newlines`, enviado a un valor fijo grande; intercambiar esos dos hace que cada turno falle con un `invalid_argument` opaco. Sin límite de llamadas o configurado, el límite de salida es el propio techo del modelo seleccionado del catálogo, y 8192 solo cuando el catálogo no está disponible. Se rechaza una temperatura de exactamente 0, por lo que se fija al valor aceptado más pequeño. +- Una pre-salida 429 con un retardo de recuperación indicado aparece inmediatamente por defecto, liberando la capacidad compartida del giro admitido. Establezca `OPENCODEX_DEVIN_STATED_RESET_WAIT_MS` en una asignación acumulativa positiva en milisegundos para esperar el retraso completo indicado y reproduzca la misma solicitud hasta dos veces. La asignación tiene un límite máximo de una hora; un valor ausente, vacío, inválido o negativo desactiva la espera. Una espera independiente optada mantiene el giro HTTP y su ranura de giro activo compartida abierta durante todo el retraso. Los giros de transmisión comienzan SSE en un latido del corazón de enfriamiento seguro, luego programa los latidos del corazón cada 500 ms o menos durante la espera para que el supervisor se mantenga alimentado. Una salida previa posterior 429 puede rotar aún a otra cuenta elegible OAuth; sin una se informa dentro del flujo ya abierto. Grok giros amortiguados retienen un HTTP 429 y `Retry-After` en un rechazo final. Los niños combinados muestran la presalida 429 inmediatamente, incluso cuando la espera está habilitada, de modo que el combo puede probar su siguiente objetivo sin mantener una respuesta no comprometida. Los retrasos que exceden la asignación restante en giros independientes aparecen en el 429 original sin un reintento temprano. El 429 final conserva el retraso declarado como una pista de enfriamiento. Un `~` en su mensaje marca un retraso recuperado de una oración de remolque de segunda mano en lugar de un valor de encabezado exacto. +- Para los flujos de Responses Codex, los fallos de límite de velocidad tipificados conocidos con un retardo válido se normalizan a `rate_limit_exceeded` con `Please try again in Ns.` antes del detalle redactado original. Esto permite que Codex honre el retraso indicado y use su notificación de reconexión nativa sin agregar un elemento de razonamiento al historial de conversaciones. Los reintentos del cliente son finitos y están controlados por el `stream_max_retries` del cliente; esto no promete recuperación después del apagado o reinicio de la aplicación. Deje `OPENCODEX_DEVIN_STATED_RESET_WAIT_MS` unset o `0` para que el cliente sea el propietario de la espera. Una asignación de proxy positivo mantiene la espera existente propiedad de proxy; el cliente sólo se entera de un rechazo final después, y los reintentos de cliente pueden multiplicar los intentos por solicitud del proxy. La conmutación por error de destino/cuenta combinada y el manejo Grok HTTP 429 conservan su orden existente. La ubicación exacta de la interfaz de usuario y el texto dependen de la versión Codex; esto no es una cuenta atrás personalizada. Los errores de límite de velocidad de solo mensaje usan el mismo formato de retardo más largo. Los errores escritos sin un retraso útil retienen su código original. Los reintentos de cliente crean nuevas solicitudes HTTP; no comparten el contador de envío o la asignación de espera acumulativa de una solicitud proxy. Esta asignación de compatibilidad no reemplaza los controles de una espera proxy habilitada explícitamente. +- Puente no oficial experimental; no se muestra en el panel de control preestablecido de forma predeterminada. Vea el [guía del proveedor](/es/guides/providers/) para instrucciones de inicio de sesión. + +El identificador de modelo que elige es una familia de modelos, y el esfuerzo de razonamiento elige la variante. Sin esfuerzo, se utiliza la variante por defecto de la familia: `swe-1-7` selecciona `swe-1-7-medium` y `swe-2` selecciona `swe-2-high`. Un esfuerzo cambia solo el esfuerzo y aterriza en la variante más baja en o por encima de él, o la más alta por debajo cuando no hay nada por encima, por lo que un peldaño faltante nunca baja el razonamiento: `swe-1-7` en `high` selecciona la fila máxima `swe-1-7`, `swe-2` en `low` selecciona `swe-2-medium` y `kimi-k3` en `medium` selecciona `kimi-k3-high`. `fast` selecciona la variante Fast y `1m`, `max-1m` o `none-1m` la variante de contexto 1M donde la familia tiene uno; de lo contrario no cambian nada. Un id con sufijo como `claude-opus-5-high-fast` mantiene su variante sin esfuerzo, y con uno mantiene su configuración rápida y contextual a menos que eso disminuya el esfuerzo: sin fila rápida en o por encima del esfuerzo, se usa la fila regular. Un id que nombra una variante que tu cuenta ha deshabilitado se envía con el nombre cuando el esfuerzo aún aterriza en ella, por lo que la solicitud falla con el propio error de esa variante en lugar de cambiar de nivel silenciosamente. La resolución nunca se traslada a otra familia. Cuando el catálogo de la cuenta no está disponible, el esfuerzo se agrega al id. + +## `zed` + +**Objetivos:** Zed Hosted AI's `POST /completions` punto final en `cloud.zed.dev`. +**Auth:** Zed identidad de cuenta de aplicación nativa más acceso token, intercambiado por un LLM de corta duración token. + +- Utiliza el inicio de sesión de devolución de llamada RSA nativo (`ocx login zed`) y empareja el `user_id` devuelto con el token de acceso para búsquedas de usuarios y organizaciones con alcance de cuenta. +- Envuelve los constructores de chat existentes Anthropic Messages, Google Gemini, OpenAI Responses y xAI dentro del sobre del proveedor de Zed, luego desenvuelve los eventos NDJSON/SSE de Zed en `AdapterEvent`. +- Fets una lista de modelos en vivo limitada y con alcance de cuenta para la visualización y la inferencia de proveedor-familia; la lista no es una lista de permisos de modelos, por lo que aún se reenvía una identificación de modelo suministrada por el llamante. +- Experimental, no oficial y no respaldado por Zed. Usarlo puede romper los términos de servicio de Zed y puede limitar o suspender la cuenta de Zed; ese riesgo es el del usuario. + +## `azure-openai` (alias: `azure`) + +**Objetivos:** **Azure OpenAI**. Envuelve `openai-responses` (así también `passthrough: true`). **Auth:** `key` a través del encabezado `api-key` (no portador). + +- Los delegados solicitan la construcción del paso Responses, valida que `baseUrl` no contiene ningún marcador de posición de plantilla sin resolver y reemplaza `Authorization` por `api-key`. El URL configurado apunta directamente a la v1 Responses API de Azure, por lo que el adaptador no anexa `api-version`. +- Comparte el estado de recuperación Responses para razonar otro proveedor producido: después de un `400 invalid_encrypted_content` vuelve a enviar una vez sin ese estado. Consulte [Formatos proxy](/es/reference/proxy-formats/) en "Cambiar de proveedores en una conversación existente". + + + +## Utilidades de imagen (`image.ts`) + +Ayudantes compartidos utilizados por los adaptadores con visión clara: + +- `parseDataUrl(url)` - dividir una URL `data:;base64,` en `{ mediaType, base64 }` para bloques de imagen Anthropic / Google. +- `contentPartsToText(content)` - Aplanar las partes de contenido al texto para mensajes de herramienta de solo texto (una imagen no descrita se convierte en un marcador corto de `[image]`, nunca en un bloque base64 de explosión de token). + + + +## Instantáneas de terminal Grok Build + +Las solicitudes marcadas con `x-opencodex-grok: 1` optan por una reparación de terminal estrecha Responses. Si `response.completed.response.output` falta o está vacío, opencodex puede reconstruirlo a partir de elementos reales, indexados de forma única, contiguos `output_item.done` cuyos campos sin procesar satisfacen las formas soportadas. Los deltas por sí solos no crean resultados. La evidencia malformada, contradictoria, duplicada, abierta o de gran tamaño mantiene el terminal vacío sin cambios; las respuestas fallidas e incompletas nunca se convierten en éxito. + +El marcador es una opción de compatibilidad seleccionada por el cliente, no una identidad autenticada o una concesión de permiso. Los clientes no identificados conservan su comportamiento existente. Esta reparación se ejecuta antes de la opción de proveedor separado `responsesSnapshotRepair` y no permite esa reparación de ciclo de vida más amplio. La búsqueda de herramientas, la herramienta personalizada, la función de finalización y el manejo de herramientas no declaradas mantienen su orden establecido. + + + +### DeepSeek y Claude Code artefacto + +Para el endpoint oficial DeepSeek Chat Completions, opencodex relaja la +`anyOf` restricciones en el Claude Code incorporado `Artifact` esquema de herramientas a evitar errores de validación de esquema HTTP 400. Se omite el modo estricto para esta herramienta. Campos definido sólo dentro de un `anyOf` ya no están limitados por esa unión; la herramienta debe validar sus entradas. Otras herramientas y proveedores conservan su comportamiento existente. diff --git a/docs-site/src/content/docs/es/reference/architecture.md b/docs-site/src/content/docs/es/reference/architecture.md new file mode 100644 index 00000000000..b4d7493cd5f --- /dev/null +++ b/docs-site/src/content/docs/es/reference/architecture.md @@ -0,0 +1,168 @@ +--- +title: "Arquitectura" +description: "opencodex integra el mapa del módulo —, el puente AdapterEvent, el analizador de solicitudes y el almacenamiento en caché." +--- + +opencodex es un único proceso Bun. Una solicitud ingresa como OpenAI Responses, se normaliza a un modelo interno, se enruta, se envía a un proveedor a través de un adaptador y se vuelve a Responses SSE. Véase [Cómo funciona](/es/getting-started/how-it-works/) para el flujo de extremo a extremo. + + + +## Mapa del módulo + +``` +src/ +├── cli/ # ocx command dispatch, init, status, provider commands +├── server/ # Bun.serve, /v1/* proxy, /api/* management API, WS bridge +├── codex/ # Codex config injection, catalog sync, auth/account integration +├── providers/ # provider metadata, API-key pool, quota and labels +├── adapters/ # wire adapters, shared guards/utilities, Cursor protobuf transport +├── oauth/ # OAuth providers, API-key catalog, token store/refresh +├── usage/ # request usage extraction, JSONL logs, summaries, totals +├── lib/ # runtime, process, retry, privacy, token estimate helpers +├── web-search/ # web-search sidecar (synthetic tool, loop, executor, parser) +├── vision/ # vision sidecar (describe + plan) +├── config.ts # ~/.opencodex/config.json, defaults, PID, env resolution +├── router.ts # model id → provider + adapter +├── bridge.ts # facade over bridge/ +├── bridge/ # AdapterEvent stream → Responses SSE (sse.ts) / JSON (response-json.ts) +├── reasoning-effort.ts # reasoning-effort translation, clamping, and catalog levels +├── responses/ +│ ├── parser.ts # Responses request → OcxParsedRequest +│ ├── schema.ts # Zod validation +│ └── compaction.ts # remote compaction prompts, envelopes, compact history +├── service.ts # launchd / systemd / Task Scheduler background service +├── types.ts # core interfaces + helpers (modelInList, namespacedToolName) +└── index.ts # public entry +``` + +Varios archivos de entrada anteriormente grandes ahora preservan la compatibilidad como fachadas: `codex/catalog.ts` exporta sus `codex/catalog/*.ts` módulos enfocados, `server/management-api.ts` despachos a `server/management/*.ts`, `server/responses.ts` exportaciones `server/responses/*.ts`, y `bridge.ts` reexportaciones `bridge/*.ts`. Una fachada es la ruta de importación estable, no la implementación: cada paso a continuación nombra el módulo que posee el código, y `structure/transports/responses.md` lleva el inventario completo del propietario para la superficie Responses. + + + +## Flujo de solicitudes + +`server/index/serve-options.ts` posee el límite HTTP y delega el plano de datos Responses a la fachada `server/responses.ts` y sus módulos `server/responses/*.ts`: + +1. `server/index/serve-options.ts` aplica CORS y la autenticación de API, registra los metadatos del ciclo de vida y rechaza trabajo nuevo durante el drenaje con HTTP 503, JSON `error.code: "server_restarting"` y `Retry-After: 5`. La respuesta usa la política CORS del servidor receptor. Atiende `GET /v1/models`, `POST /v1/responses`, `POST /v1/responses/compact` y `POST /v1/images/generations` / `POST /v1/images/edits` (reenviados por `server/images.ts` a un proveedor de la familia OpenAI para la herramienta integrada `image_gen` de Codex). `server/live.ts` gestiona `POST /v1/live` / `POST /v1/realtime/calls`, la unión WebSocket `/v1/live/{callId}` o `/v1/realtime?call_id=`, y se admite la actualización opcional WebSocket en `/v1/responses`. +2. `server/responses/request-prepare.ts` descomprime y analiza JSON, expande la entrada de `previous_response_id` recordada localmente, si existe, y llama a `responses/parser.ts`. +3. `router.ts` resuelve un identificador sin prefijo o `provider/model`. El servidor resuelve la afinidad de cuenta de Codex, actualiza OAuth cuando es necesario y aplica la credencial elegida. +4. Antes de la llamada principal, `vision/` describe las imágenes de los modelos incluidos en `noVisionModels`. Si no existe una ruta sidecar segura, se eliminan las imágenes en lugar de enviarlas a un proveedor de texto. +5. `server/adapter-resolve.ts` aplica las opciones de protocolo por modelo y construye el adaptador. Responses reenvía el cuerpo nativo; Cursor usa su transporte bidireccional `runTurn`; los adaptadores traducidos construyen, envían y analizan la solicitud. +6. En modelos enrutados que solicitan la herramienta alojada `web_search`, `web-search/` expone una función sintética, ejecuta la búsqueda real mediante el backend configurado (el sidecar de OpenAI/ChatGPT o Anthropic), devuelve los resultados al modelo y repite hasta el límite configurado. Los adaptadores HTTP ordinarios usan el bucle basado en fetch. Los que implementan `runTurn`, incluido Cursor, usan el bucle independiente `runTurnWebSearchLoop` de `server/responses/run-turn-execution.ts` cuando el plan de búsqueda cumple los requisitos. +7. `bridge/sse.ts` / `bridge/response-json.ts` generan Responses SSE o JSON. `server/request-log.ts` y `usage/` recogen estado terminal, latencia, etiquetas de proveedor y modelo y el uso de tokens disponible sin modificar la respuesta. + +La estimación de entrada previa al envío sigue lo que realmente envía el adaptador enrutado. Para los modelos `openai-chat` excluidos por la política efectiva de repetición de pensamiento de chat (una lista explícita `preserveReasoningContentModels`, o detección DeepSeek Flash/Pro cuando no está configurado), el adaptador elimina el pensamiento de asistente repetido, por lo que la estimación también lo excluye; el historial que nunca llega al proveedor, por lo tanto, no puede causar un rechazo de límite de contexto local. Los modelos que preservan el razonamiento, y otros adaptadores, envían ese pensamiento y aún lo cuentan. + + + +## El analizador + +`responses/parser.ts` valida la solicitud entrante con `responses/schema.ts` (Zod), luego construye un `OcxParsedRequest`: + +- **Messages** - `input` elementos se convierten en un normalizado `OcxMessage[]`: usuario / desarrollador / asistente / toolResult. `reasoning` artículos se convierten en bloques de pensamiento; `function_call`, `custom_tool_call`, y `tool_search_call` artículos se convierten en llamadas de herramientas, sus `*_output` contrapartes se convierten en resultados de herramientas. +- **Herramientas** - herramientas de función pasan a través; **namespaced (MCP) las herramientas se aplanan** a `namespace__name` (y restaurado en el camino de regreso); **freeform** herramientas (p. ej. `apply_patch`) y **tool_search** herramientas de descubrimiento están marcadas; **Herramientas alojadas** ( `web_search`, image gen,...) se dejan caer y se reinyectan por un sidecar sólo si va a manejarlos. +- **Imágenes** - preservado como partes de contenido real (URL de datos o https remoto), nunca alineado como texto. +- **Banderas de características** - `_webSearch` (búsqueda web alojada solicitada), `_structuredOutput` (`text.format` es json_schema / json_object), y `_compactionRequest` (compactación remota v2). + + + +## El puente + +`bridge/sse.ts` convierte el flujo interno `AdapterEvent` del adaptador en Responses SSE que Codex entiende: + +| AdaptadorEvent | Responses SSE emitido | +| --- | --- | +| `text_delta` | `response.output_text.delta` → `…done`, `response.content_part.done`, `response.output_item.done` | +| `thinking_delta` | `response.reasoning_summary_text.delta` → `…done`, artículo cerrar | +| `reasoning_raw_delta` | Un artículo crudo `reasoning_text` (o un sobre de ida y vuelta oculto) | +| `thinking_signature` / `redacted_thinking` | Conservado en un sobre de razonamiento `encrypted_content` | +| `tool_call_start` | `response.output_item.added` (tipo: `function_call` / `custom_tool_call` / `tool_search_call` ) | +| `tool_call_delta` | `response.function_call_arguments.delta` (omitido para forma libre / tool_search) | +| `tool_call_end` | `response.function_call_arguments.done` → `response.output_item.done` | +| `web_search_call_begin` / `web_search_call_end` | Un artículo vivo `web_search_call` más citas de URL | +| `heartbeat` | Marca la actividad ascendente; ningún elemento de salida visible por el usuario | +| `done` | `response.completed` (con uso) | +| `error` | `response.failed` (con `last_error`) | + +El puente también envía un **latido para mantener la conexión activa** (RC3). Durante el silencio del proveedor, emite el comentario SSE `: opencodex heartbeat` cada 2 segundos para reiniciar el temporizador de inactividad de Codex. Los analizadores de eventos descartan estos comentarios sin generar eventos, por lo que los decodificadores estrictos de Responses no reciben variantes desconocidas. El **tiempo de espera por inactividad** predeterminado es de 300 segundos para un proveedor público y está desactivado para uno local (`stallTimeoutSec`; `0` lo desactiva en todos los casos). Al agotarse, se cancela el flujo del proveedor y se emite `response.incomplete` con la razón `upstream_stall_timeout`, para que una conexión bloqueada no detenga Codex indefinidamente. + +Las llamadas a herramientas se desambiguan en tres tipos de elementos Responses usando el mapa de espacios de nombres, el conjunto de formularios libres y el conjunto de búsqueda de herramientas capturados por el analizador, de modo que MCP espacios de nombres, `apply_patch` herramientas de formularios libres de estilo y `tool_search` ejecutados por el cliente son de ida y vuelta. Una variante `buildResponseJSON()` produce un único objeto de respuesta que no es de flujo continuo a partir de los mismos eventos. + + + +## Administración API, OAuth y uso + +`server/management-api.ts` sirve al panel y delega los grupos de rutas en +`server/management/*.ts`. Sus rutas `/api/*` cubren la configuración y los ajustes +filtrados, la gestión de proveedores y grupos de claves, la selección de modelos, +los límites de contexto y los controles v2, la sincronización del catálogo, los +diagnósticos y registros de depuración, el uso y las cuotas, los sidecars, las +actualizaciones, las claves API de cliente generadas, OAuth, la selección y gestión +de cuentas Codex y la parada ordenada. + +El acceso de administración a `/api/*` utiliza la credencial independiente +`OPENCODEX_ADMIN_AUTH_TOKEN` o el token administrativo generado; el panel utiliza +sesiones de administración. La admisión de modelos en `/v1/*` usa credenciales del +plano de datos, como `OPENCODEX_API_AUTH_TOKEN` o las claves API de cliente +configuradas. `server/auth-cors.ts` exige una credencial de datos al escuchar fuera +de loopback. Un token de modelos no concede acceso administrativo. +Las entradas de `corsAllowOrigins` amplían la lista de orígenes locales permitidos. + +OAuth implementaciones en vivo en `oauth/`; tokens de acceso se cargan o actualizan inmediatamente antes de una llamada enrutada, mientras que `oauth/token-guardian.ts` puede actualizar proactivamente sólo los proveedores cuya política lo permite. Refresh se coordina con un solo vuelo en proceso, un bloqueo de archivos por cuenta y CAS de generación para que los escritores concurrentes no puedan bloquear una credencial más nueva. Una proyección de salud compartida (`oauth/health.ts`) alimenta `ocx status`, `ocx doctor`, la administración API y el tablero de instrumentos. Codex / ChatGPT credenciales de grupo y afinidad proceso-local hilo vivo por debajo de `codex/` y se mantienen fuera de las respuestas de gestión; afinidad borra en `401` / `403` / `429` (no fijado a través de límites de velocidad) y no persiste a través de reinicios. El uso de solicitudes se normaliza a `OcxUsage`, aparece en Responses eventos de terminal y se agrega por `usage/` para el panel de control y los diagnósticos JSONL opcionales. + + + +## Transporte y compactación + +`server/index/serve-options.ts` sirve HTTP / SSE en `/v1/responses` por defecto. Si Codex intenta una actualización Responses WebSocket mientras que `websockets` es `false`, opencodex devuelve `426 upgrade_required`; Codex luego vuelve a HTTP para esa sesión. Cuando se establece `"websockets": true`, el mismo punto final acepta la actualización y utiliza el puente WebSocket. + +Independientemente de esa configuración orientada al cliente, las solicitudes canónicas de reenvío ChatGPT con nivel raíz `stream: true` pueden usar el transporte aguas arriba Codex de WebSocket en el estable Bun 1.4.0 o más reciente. La ruta canónica ChatGPT conserva la intent HTTP Responses Lite en los metadatos de la trama WS y deriva su sugerencia de enrutamiento del modelo saliente real y el nivel de servicio. Los metadatos iniciales de la cuota/modelo ascendente se convierten en cabeceras de respuesta HTTP limitadas; las actualizaciones de cuotas posteriores se atribuyen a la cuenta de servicio, no se agregan retroactivamente a las cabeceras ya enviadas. Un fallo después de que se envió una solicitud WS no desencadena un reenvío automático HTTP. Estas asignaciones no habilitan la configuración WebSocket orientada al cliente ni cambian la selección de transporte de otros proveedores. El paquete Bun 1.3.14, prelanzamientos e identidades de entorno de ejecución no verificables usa HTTP / SSE. Las respuestas WS ascendentes exitosas mantienen el contrato SSE descendente y la derivación `tee()` a través de un relé de un solo lector ansioso limitado (4 MiB por trama sin procesar / envolvente y una cola de productores de 8 MiB). El desbordamiento de cola cierra el flujo ascendente y emite un evento terminal de flujo descendente `response.failed` seguido por `[DONE]`. + +Para el modelo saliente final `gpt-5.3-codex-spark`, el reenvío canónico ChatGPT desactiva explícitamente Responses Lite tanto en la cabecera HTTP como en los metadatos de trama WS nativos, incluso cuando un alias selecciona Spark, pero solo cuando el cuerpo saliente no lleva ningún elemento `additional_tools` con una matriz `tools` no vacía. Ese grupo ES la forma de entrega de herramientas Lite, por lo que un cuerpo de Spark que todavía lo usa mantiene Lite ON incluso si un llamante o un encabezado configurado dijeron lo contrario; de lo contrario, el marco anunciaría que no es Lite mientras que las herramientas existen solo en la forma Lite. Una identidad Lite cambiada retira el socket anterior; las solicitudes elegibles posteriores con la misma identidad pueden reutilizar el socket nuevo. Otros modelos y puertas de enlace mantienen su política Lite existente. Los metadatos nativos mal formados todavía caen de nuevo a HTTP con su cuerpo sin cambios. + +Cuando un proveedor rechaza una solicitud de flujo continuo con HTTP 413 antes de que comience SSE, OpenCodex emite un evento de terminal `response.failed` con `context_length_exceeded` en lugar de retransmitir el estado desconocido reintentable. Esto permite que Codex detenga su bucle de reconexión y aplique su propia política de compresión de contexto en el siguiente turno. OpenCodex no elimina silenciosamente mensajes o imágenes; reduzca la entrada actual o reintente después de la compactación. Las personas que no llaman API continúan recibiendo el HTTP 413 del proveedor. + +La compactación de contexto Codex funciona para modelos enrutados. `server/responses/compact.ts` maneja `POST /v1/responses/compact` ejecutando un giro de resumen enrutado interno y devolviendo el historial compactado, mientras que `responses/parser.ts` y `bridge/sse.ts` manejan la compactación remota v2 `compaction_trigger` gira emitiendo exactamente un elemento de salida `compaction` sintético. + + + +## El almacenamiento en caché y el catálogo + +- `codex/model-cache.ts` mantiene una caché TTL por proveedor, en memoria, de resultados en vivo de `/models` (por defecto 5 min, que coincide con la propia caché de Codex), con una recuperación obsoleta cuando falla una extracción. +- `codex/catalog/sync.ts`, exportado a través de la fachada `codex/catalog.ts`, fusiona modelos enrutados en el catálogo de Codex como entradas con nombre, clasifica primero [Modelos de subagentes](/es/guides/codex-integration/#the-subagent-picker), filtra `disabledModels` y puede restaurar completamente el catálogo prístino desde una copia de seguridad única. + + + +## Esfuerzo de razonamiento + +`reasoning-effort.ts` traduce las etiquetas de razonamiento de Codex en los valores de cable de cada proveedor. El catálogo Codex anuncia etiquetas Codex acepta (`low` / `medium` / `high` / `xhigh` / `max`), pero los proveedores anteriores pueden admitir solo un subconjunto más pequeño o requerir un alias real. El módulo: + +- Define el canónico `CODEX_REASONING_LEVELS` y su orden de clasificación. +- Sujeta un esfuerzo solicitado al nivel soportado más cercano cuando el nivel exacto no está disponible. +- Resuelve anulaciones por modelo y por proveedor `reasoningEffortMap` para asignaciones de cables personalizadas. +- Deja de lado el esfuerzo por completo para los modelos enumerados en `noReasoningModels`. + +Qwen3.8-Max es una excepción explícita de esfuerzo directo al antiguo contrato de presupuesto Qwen3.x. Alibaba Token Plan registra su escalera compatible con upstream como `low`, `medium` y `xhigh` (el valor predeterminado), y envía el valor efectivo como `reasoning_effort`; Codex -sólo las tapas de compatibilidad están sujetas a `xhigh` en el cable. El enriquecimiento del registro en entorno de ejecución repara metadatos preestablecidos persistentes anteriores que todavía clasifican este modelo como un modelo `thinking_budget`. + + + +## Tipos de núcleo + +El modelo interno vive en `types.ts`: `OcxParsedRequest`, `OcxContext`, la unión `OcxMessage`, `OcxContentPart` (texto / imagen), `OcxToolCall`, `OcxTool`, `AdapterEvent`, y los tipos de configuración (`OcxConfig`, `OcxProviderConfig`). Dos ayudantes son ampliamente utilizados: `namespacedToolName()` y `modelInList()` (tolerante `:size` -etiqueta que coincide con `noVisionModels` / `noReasoningModels`). + + + + +### Terminales de cuota incompletos + +Una respuesta directa nativa que termina con evidencia de cuota o límite de tasa en una terminal `incomplete` registra el fallo de la cuota de la cuenta y la salud de la reaparición. Estructurado `incomplete_details.reason` y códigos de error son aceptados sin un mensaje; ordinarios de límite de salida, filtrado, dirección y pérdida incompleta no enfrían una cuenta. La clasificación de la política cibernética mantiene su precedencia. El terminal no se reproduce después de la salida, y la selección de solicitud de cuenta fija permanece fija. + +Las solicitudes compactas remotas pueden almacenar su respuesta en búfer durante más tiempo que el tiempo de espera inactivo de la solicitud del servidor. Ese tiempo de espera del oyente se deshabilita después de que se acepte el cuerpo de la solicitud; aún se aplican los plazos de cancelación del cliente y de operación ascendente. + +La compactación enrutada amortiguada trata el texto no vacío y los deltas de razonamiento como progreso sin exponer texto de resumen parcial. Los comentarios, deltas vacíos y keepalives de la puerta de enlace no restablecen el regulador de pérdida de eventos del adaptador. El tiempo de espera por defecto permanece 300 segundos; el contenido de compactación encriptado se conserva sin cambios. + +El almacenamiento en búfer de respuesta compacta nativa también impone una fecha límite de inactividad de byte de cuerpo usando `stallTimeoutSec` (300 segundos para un flujo ascendente público, deshabilitado para uno local y deshabilitado en todas partes cuando se establece en `0`). Los fragmentos no vacíos restablecen esa fecha límite; un cuerpo estancado devuelve HTTP 504, la cancelación del cliente retiene HTTP 499 y la limpieza no espera una promesa de cancelación ascendente atascada. Se conservan el techo de respuesta de 32 MiB y los bytes originales del cuerpo. + +Un error canónico de creación rechazada WebSocket aguas arriba puede convertirse en un HTTP 4xx solo antes de que se confirme la respuesta y después de las comprobaciones de correlación de flujo. Las cabeceras de cuota permitidas se acotan y reconstruyen sin cabeceras de entramado ascendentes; la respuesta JSON no se puede almacenar en caché. Los errores posteriores al compromiso y 5xx mantienen la ruta sin reenvío. + +Cuando la recuperación de la tarea de agente encriptada rechaza una tarea enrutada, su error 400 existente puede incluir un `recovery_reason` limitado: `unsupported_envelope`, `admission_denied`, `recovery_unavailable`, `caller_cancelled`, `input_changed`, `recovery_http_rejected`, `recovery_timeout`, `recovery_aborted`, `recovery_transport_error` o `recovery_invalid_output`. El rechazo HTTP requiere una respuesta observada sin éxito. La salida no válida incluye UTF-8 no válido, cuerpos de gran tamaño, flujos de recuperación mal formados o incompletos y asignaciones inválidas o conflictivas. La cancelación de una persona que llama tiene prioridad sobre una fecha límite propia, que tiene prioridad sobre los fallos de decodificación/transporte. `recovery_aborted` describe una recuperación compartida cancelada independientemente de esa persona que llama. Los camareros de vuelos compartidos reciben el mismo error subyacente a menos que se cancele individualmente; solo se almacena en caché el texto sin formato correcto. Los diagnósticos no contienen ningún error de flujo ascendente o texto de carga útil. El campo se omite cuando no existe un resultado de recuperación clasificado, y las ramas de combo existentes que devuelven el error de destino original mantienen esa respuesta. `recovery_unavailable` incluye capacidad de caché/solamente vuelo y no prueba que se intentó una solicitud ascendente. No se permite reintento o aceptación de envolvente más amplia. diff --git a/docs-site/src/content/docs/es/reference/cli.md b/docs-site/src/content/docs/es/reference/cli.md new file mode 100644 index 00000000000..547b2995f95 --- /dev/null +++ b/docs-site/src/content/docs/es/reference/cli.md @@ -0,0 +1,232 @@ +--- +title: "CLI Referencia" +description: "Despacho de comandos, códigos de salida y enlaces a cada familia de comandos ocx." +--- + +La CLI de opencodex es `ocx`. El primer nombre determina qué comando se ejecuta. Los alias documentados `setup`/`init`, `restore`/`eject` y `models`/`model` realizan la misma operación. Los comandos desconocidos y las sintaxis no válidas producen errores. + +Ejecute `ocx`, `ocx help`, `ocx --help` o `ocx -h` para obtener el mismo índice de comandos compacto, agrupados en Inicio aquí, Tareas comunes, Explorar y Más ayuda. Utilice `ocx help --all` o `ocx --help --all` para la referencia completa de nivel superior, incluidas las variantes de comandos detalladas omitidas del índice compacto. Ejecutar `ocx help `, `ocx --help` o `ocx -h` para un comando registrado en la tabla de ayuda; `ocx help` también sigue siendo apoyado. Los comandos de ayuda y versión son de solo lectura: no inician, detienen, instalan, desinstalan o reescriben el estado Codex o opencodex. + + + +## Ayuda anidada + +La ayuda de una familia, como `ocx help models`, conserva su sintaxis y detalles y enumera los subcomandos declarados con sus resúmenes. Estas listas describen los subcomandos registrados; no garantizan que incluyan todas las variantes disponibles en ejecución. La ayuda de Alias conserva el propio uso y detalles del alias y apunta a su familia canónica: `ocx help model` conduce a `ocx help models`. Los modelos también ayudan a vincular el tema curado `models context` por separado de las capacidades declaradas. + +Ayuda acepta una ruta con más de una palabra de comando: + +```bash +ocx help models context +ocx models context --help +ocx model context --help +ocx help account list +ocx help account main +``` + +Las tres primeras formas muestran el mismo tema de contexto-cap, incluyendo el alias `model`: + +```text +ocx models context [--set-all]|provider on [--value ]|provider off|all > [--json] +``` + +`ocx models context status --json` lee la configuración actual. `value ` establece el valor predeterminado para los cambios futuros; agregar `--set-all` lo aplica a todos los proveedores enrutados. `provider on` permite una tapa de proveedor, opcionalmente con `--value `; `off` lo deshabilita. `all on|off` cambia todos los proveedores enrutados juntos. + +Temas de capacidad declarados tales como `account list` mostrar su resumen, banderas conocidas y detalles, con un puntero a la ayuda de los padres. Estos metadatos no cubren todos los operandos o tiempos de ejecución. subcomando, por lo que un tema puede mostrar `Command: ocx ...` Sin pretender una completa `Usage:` Gramática. Un prefijo como `account main` enumera a sus hijos declarados y marca esa cobertura como incompleta. Un tema explícito no declarado (`ocx help `) sale 1 con una ayuda detallada concisa no disponible mensaje y un puntero padre conocido o de referencia completa en el error estándar. Salida estándar vacío, y no se imprime ningún banner de ayuda completo. Falta detalle no establece si el comando runtime es válido. Anexado `--help`/`-h` preserva el comportamiento de ayuda de comandos existente: cuando los metadatos detallados no están disponibles, Muestra la ayuda de padre conocida con éxito, sin ejecutar el comando. + +En el cabezal Bun CLI, desnudo `help` se reconoce solo en la raíz o inmediatamente después de la raíz comando. Uso `--help` o `-h` para caminos anidados. Valores posteriores como el `help` en +`ocx alias set demo help` Siguen siendo argumentos de comando. Un exacto `--` termina la ayuda de la cabeza que explora, así que `ocx claude -- --help` conserva los argumentos para el despacho de comandos. + + + +## Recuperación de errores tipográficos de comando + +Comandos raíz desconocidos y rutas de ayuda explícitas no resueltas salen de 1 con una breve guía de diagnóstico y navegación sobre el error estándar, dejando la salida estándar vacía. Los errores tipográficos cercanos pueden recibir sugerencias conservadoras extraídas de los nombres de comandos visibles y de los hijos documentados de la familia de ayuda actual. Las sugerencias son solo de orientación: el CLI nunca las ejecuta ni vuelve a intentar el comando. + +| Entrada | Orientación | +| --- | --- | +| `ocx modles` o `ocx help modles` | Sugiere `ocx help models`. | +| `ocx help account lisst` | Sugiere `ocx help account list` dentro de la familia de cuentas. | +| `ocx help qzxv` | Ofrece `ocx help --all` sin adivinar un comando. | +| `ocx help models qzxv` | Indica que la ayuda detallada no está disponible y remite a la familia de comandos de modelos conocida. | + +El Bun CLI rechaza una raíz desconocida antes de la auto-restauración de la shim u otro comando previo al vuelo. Los comandos reconocidos conservan su prevuelo existente; los comandos ocultos y el corredor interno siguen siendo objetivos de despacho válidos, pero están excluidos del descubrimiento y las sugerencias. La opción alternativa de ayuda con bandera añadida, la capacidad JSON y el manejo de errores específicos del proveedor conservan su comportamiento existente. + + + +## Familias de mando + +### `ocx message` + +`ocx message sessions [--json]` descubre Codex sesiones locales cargadas. `ocx message send (--thread | --name ) --stdin [--json]` envía un mensaje de igual correlacionado, sin iniciar un demonio o reanudar un hilo. Sin `--host`, estas operaciones son locales. Consulta [Mensajería de Codex](/es/reference/cli/messaging/) para el contexto del remitente, los tipos, el entorno de ejecución probado y los recibos `not_sent` / `queued` / `unknown`. El [transporte remoto mediante SSH](/es/reference/cli/messaging/#explicit-remote-peers) requiere un host registrado y la opción `--host`; no inicia automáticamente el receptor ni reenvía mensajes de forma automática. + +### `ocx provider` + +`ocx provider`, `ocx help provider`, `ocx provider help`, `ocx provider --help` y `ocx provider -h` muestran la misma ayuda del proveedor, con sintaxis de comandos, ejemplos, orientación preestablecida / personalizada y punteros de temas declarados. La ayuda se imprime correctamente en la salida estándar y sale en 0. Bare `ocx provider` todavía sigue el prevuelo de comando ordinario; las formas explícitas de ayuda para la cabeza salen antes de ese prevuelo. Una acción de proveedor desconocido imprime su diagnóstico y ayuda del proveedor al error estándar, deja la salida estándar vacía y sale 1. + +### `ocx alias` + +`ocx alias list [--json]` muestra alias de usuario efectivos e integrados. Utilice `ocx alias set [/] ` y `ocx alias rm [/]` para editarlos. Los identificadores de modelo nativos pueden contener barras adicionales porque el selector se divide solo en la primera barra. Habilite los valores predeterminados enviados con `ocx alias defaults on|off [--provider ]`. + +### `ocx remote-workspace` + +`ocx remote-workspace pair --pairing-code-stdin --root ` inscribe el equipo local como un Ejecutor solo OCX. Repita `--root` para aprobar más carpetas y utilizar `--name` para anular el nombre de host. Repita `--toolchain-root ` para exponer un directorio de Node, Rust, Go u otra cadena de herramientas instalado por el usuario de solo lectura dentro del entorno de pruebas del comando. En las compilaciones internas de prueba para macOS y Windows, `bun run build:remote-workspace-helper` compila el helper de Rust que el comando de emparejamiento descubre automáticamente; `--executor-helper ` selecciona otra compilación revisada explícitamente y fija su resumen en el estado de Ejecutor local. `ocx remote-workspace agent` mantiene la conexión cifrada saliente; `ocx remote-workspace status [--json]` informa sobre el Hub, el dispositivo, las raíces y las capacidades anunciadas sin imprimir su portador o clave privada. Véase [Espacio de trabajo remoto](/es/guides/remote-workspace/). + +Familias de comandos adicionales: + +| Familia | Sintaxis y referencia | +| --- | --- | +| `ocx chatgpt` | `ocx chatgpt ` - macOS aplicación-servidor de calza experimental, por defecto apagado. Véase [ChatGPT Escritorio](/es/guides/chatgpt-desktop/). | +| `ocx hub` | `ocx hub invite [--json] [--data-url ] [--management-url ] [--clients codex,claude]`: crea un código de emparejamiento secreto de un solo uso en un concentrador en ejecución. Consulte [Hub remoto](/es/guides/remote-hub/); invite requiere autorización explícita y su código no debe ingresar una transcripción del agente. | +| `ocx inspect` | `ocx inspect ` - lea la configuración efectiva, el catálogo, el análisis de enrutamiento, el ritmo, el inventario del proveedor de claves, el indicador Codex, la configuración del cliente, el estado de estrella o el estado de la bandeja Windows. Ejecutar `ocx help inspect` para los enlaces del tema. | +| `ocx mcode` | `ocx mcode [mcode args...]` - inicie el código MiniMax después de que su integración de archivos administrados esté habilitada. Véase [MiniMax clientes](/es/guides/minimax/). | +| `ocx mmx` | `ocx mmx text [mmx args...]` - Lanzamiento MiniMax CLI texto a través del proxy; uso llano `mmx` para otras superficies. Véase [MiniMax clientes](/es/guides/minimax/). | +| `ocx zcode` | `ocx zcode [status\|enable\|disable\|history\|restore] [--json]` - Comandos de integración ZCode administrados. Véase [Tiendas ZCode](/es/guides/integrations/#zcode-314-and-later). | + +- [Ciclo de vida](/es/reference/cli/lifecycle/) - Configuración, proxy y ciclo de vida del servicio, estado, diagnóstico, sincronización del catálogo, el panel de control y actualizaciones. +- [Proveedores, cuentas y modelos](/es/reference/cli/providers-accounts/) - configuración de proveedores, autenticación, grupos de credenciales, cuota, modelos personalizados, visibilidad, modelos seleccionados y límites de contexto. +- [Agentes, enrutamiento e integraciones](/es/reference/cli/agents/) - controles multiagente, combos, observabilidad, claves de admisión, rutas de protocolo, integraciones de clientes, configuración en entorno de ejecución, configuración validada e inspección de actualización de solo lectura Codex CLI. + + + +## Comportamiento sin cabeza + +La administración ordena el viaje de ida y vuelta de la administración del proxy en vivo API, utilizando el puerto de entorno de ejecución registrado y las verificaciones de identidad en lugar de mantener una segunda ruta de configuración. Un proxy detenido o inalcanzable se representa como HTTP 503 y produce una salida no cero CLI. Los comandos explícitamente documentados como operaciones de configuración sin conexión pueden validar y editar el archivo de configuración sin un proxy en vivo. + +`ocx system codex-cli-update check` no necesita proxy en vivo y no hace ninguna solicitud de registro de paquetes. Inspecciona los metadatos de procedencia limitada para el candidato de instalación configurado, incluida su ubicación ejecutable redactada y la evidencia de propiedad. El contexto del lanzador publicado de confianza autentica esa instantánea candidata, no una ejecución exitosa de Codex. En POSIX, `selectionAttested` puede ser `true` cuando el solucionador en entorno de ejecución selecciona el mismo candidato de entorno canónico sin ejecutarlo. Un manifiesto de paquete global vinculado npm puede establecer `managed: true` cuando prueba la propiedad y, si se informa de una versión candidata, esa versión coincide con el manifiesto; los candidatos persistentes permanecen sin certificar. El informe JSON expone `candidateAvailable`, `candidateVersion`, `candidateSource` y `selectionAttested`. Inspeccionar el candidato configurado requiere un contexto de lanzador publicado de confianza; un lanzamiento directo Bun /source no tiene tal prueba, ignora el estado del candidato ambiental y persistente, y puede informar `candidate_unavailable` en POSIX o `windows_inspection_deferred` en Windows. En Windows este primer segmento no realiza ninguna E/S candidata o de sistema de archivos de configuración: solo un candidato de entorno absoluto capturado por prueba puede recibir etiquetas de paquete de aplicaciones léxicas o gestor de versiones; cada otro candidato Windows falla cerrado. El comando no instala ni repara software, ejecuta Codex o npm, controla un proceso en ejecución ni escribe el estado de configuración/caché. + +`ocx system codex-cli-update plan --json` agrega una decisión de actualización de solo lectura para una instalación POSIX npm -global certificada. Resuelve `latest` a través del registro oficial npm, valida la versión exacta y la integridad SHA-512, y rechaza sesiones activas u observación de procesos incompleta. Las consultas del registro utilizan configuración temporal aislada npm, caché y registros con la limpieza del mejor esfuerzo. No hay software instalado y ningún proceso está señalizado. Windows devuelve `windows_inspection_deferred`. Véase [detalles de planificación](/es/reference/cli/agents/#read-only-codex-cli-update-plan). + +Para la observación de la instalación de Windows x64, véase [El comando `attest`](/es/reference/cli/agents/#explicit-installation-observation-on-windows-x64). Sin rutas explícitas, observa el candidato seleccionado identificado a partir de la instantánea del lanzador de prueba; no otorga autoridad de actualización ni certifica la selección en entorno de ejecución. + +La lista o el estado es el valor predeterminado cuando no es ambiguo. Use `--json` solo en hojas que lo admitan, y `ocx observe logs --follow --jsonl` para la salida de fila modificada, o `ocx logs --follow --events` para instantáneas/agregados de ventana observada versionados. Tampoco es historia sin pérdida; [seguimiento, la línea de tiempo y el uso de key-scoped](/es/reference/cli/agents/#follow-request-windows-or-injection-sequences): Límites de cursor/reseteo/datos incompletos. [Modelo de clave seleccionada/comprobaciones de audio](/es/reference/cli/agents/#explicit-key-model-and-audio-checks) requieren el trabajo autorizado por el operador y la transferencia privada de datos; sus informes son observaciones, no certificados de alcance de clave. El tema, el idioma, la navegación y otros estados del navegador puramente visuales no tienen el equivalente CLI; La configuración de Cloudflare Tunnel está fuera de este conjunto de comandos. + +Para las tareas de lectura de estilo tablero, use [selección de registro limitado, búsqueda de modelo de uso y totales de compañeros guardados](/es/reference/cli/agents/#filter-a-bounded-log-snapshot). `logs filter` distingue la ventana escaneada de las coincidencias devueltas; `usage --search` cambia las filas del modelo sin recalcular los totales del informe; `companion usage` conserva la disponibilidad y la configuración de cada rango. [API - cuota de key pool](/es/reference/cli/providers-accounts/#accounts-and-key-pools) es una lectura explícita `account list --quota` y puede contactar a los proveedores. + + + +## Sonda Liveness techo override + +`ocx health`, `ocx status`, `ocx account *`, `ocx login codex` y `ocx ready` encuentran el proxy de ejecución a través de una sonda de vida corta: 750 ms por intento por defecto y 1500 ms con reintentos para detener y comenzar las decisiones. En los hosts donde una capa de seguridad (un filtro de contenido o una extensión de red de estilo EDR) agrega un costo fijo a cada conexión de bucle de retorno, esos límites pueden expirar antes de que un proxy saludable responda, por lo que estos comandos informan que el proxy está inactivo mientras `curl http://127.0.0.1:10100/healthz` tiene éxito. + +Establecer `OCX_PROBE_TIMEOUT_MS` para elevar los techos en tales hosts, por ejemplo `OCX_PROBE_TIMEOUT_MS=5000 ocx status`. El valor es milisegundos enteros de 1 a 30000. La anulación solo aumenta: los presupuestos predeterminados de 750 ms y 1500 ms de parada / inicio mantienen sus pisos, por lo que `1000` solo alarga la sonda predeterminada. Los valores indefinidos, vacíos, fraccionarios, negativos, cero o mayores se ignoran y se aplican los límites máximos enviados. + +En Windows, el proxy también eleva su propio proceso a la prioridad ABOVE_NORMAL cuando se inicia, lo que reduce los retrasos de programación en un host saturado por otro trabajo de prioridad NORMAL (exploraciones de antivirus, codificadores, emuladores) sin garantizar que la sonda permanezca bajo estos techos a carga extrema. El impulso se aplica solo al proceso proxy (el trabajo que genera aún se ejecuta en NORMAL) y un proxy con CPU pesada puede retrasar las aplicaciones con prioridad NORMAL. El cambio es de mejor esfuerzo; establece `OCX_DISABLE_PRIORITY_BOOST=1` en el entorno del proxy para dejar la prioridad sin cambios. + + + +## Códigos de salida y confirmación + +Los comandos exitosos terminan con código 0. Los argumentos no válidos, los comandos o recursos desconocidos, las operaciones de API fallidas y la falta de servicios necesarios producen un código distinto de cero. `ocx health` sale específicamente 0 solo cuando el proxy está sano y 1 cuando no se encuentra ningún proxy sano; los argumentos inválidos salen 2, por lo que se puede usar como una sonda de servicio. Los scripts deben probar el código de salida en lugar de raspar la salida legible por humanos. + +Muchos comandos de gestión comparten estas asignaciones; otras CLI familias conservan sus propios contratos de salida: + +| Código | Causa | +|---|---| +| 0 | éxito | +| 2 | rechazo de uso local en los controladores de gestión; también no compatible con `doctor --json` | +| 64 | argumentos inválidos a `capabilities`, `ready` o `resolve`, antes de su descubrimiento / solicitud de trabajo | +| 4 | HTTP 404 - la cuenta, el proveedor, la clave o la ruta con nombre no existe | +| 5 | HTTP 409 - conflicto; se mantiene una cerradura o se cambia el estado debajo | +| 1 | todo lo demás, incluyendo fallos de transporte y otros errores HTTP | + +Salida 0 significa que no se informó ningún error. Los verbos de vista previa (por ejemplo `ocx storage cleanup` sin `--yes`) también salen 0 sin mutar. Una configuración guardada todavía puede llevar un resultado de aplicación omitido o incompleto; lea las advertencias de recibo y stderr. + +Las operaciones de eliminación destructiva, importación, consumo de crédito y actualización que anuncian la confirmación requieren `--yes` en uso no interactivo. La bandera es un opt-in explícito; omitirla no debe confirmar silenciosamente la acción. + +`ocx storage cleanup` va más allá: sin `--yes` se ejecuta la vista previa e imprime lo que *se habría* se libera, luego sale 0 sin haber cambiado nada. No hay confirmación interactiva para ninguno de estos - una indicación de que un llamante automático puede responder no es un límite de seguridad, por lo que la bandera es el límite. + + + +## Conducir el CLI desde un agente + +Descubra progresivamente, sin iniciar un proxy: + +```bash +ocx help +ocx help models +ocx help models preset show +``` + +Lea el capítulo correspondiente en el `skills/ocx/references/01_management_surface.md` del repositorio o en una de las páginas de la familia de comandos públicas anteriores. Full `ocx help --all` es un escape a la referencia de nivel superior. Un amplio inventario de máquinas es opcional: + +```bash +ocx capabilities --json +ocx capabilities --mutating-only --json +ocx capabilities --route '/api/providers/{provider}/model-costs' --json +``` + +La búsqueda de ruta coincide con la plantilla declarada literal, no con los ID de proveedor concretos ni con un método HTTP. Un error sale 4 y no prueba que un comando runtime esté ausente. Las declaraciones incluyen comandos locales, así como comandos de gestión; solo estos últimos necesitan un objetivo en vivo. Antes de las operaciones en vivo, ejecute `ocx ready --json` y `ocx status --json`, inspeccione el objetivo y `versionSkew.relation`, y resuelva el desajuste de versión. `unknown` no confirma las compilaciones coincidentes. La ayuda sin conexión, la configuración local y la inspección local del laboratorio no requieren el inicio. + +`ocx status --json` incluye `cliCommand`: intent de escritorio configurado, el ejecutable esperado, candidatos de PATH observados, `pathFirst`, `desktopFirstOnPath`, códigos de emisión y `shellResolution: "unobserved"`. El informe de estado humano imprime una línea de selección de comandos. `ocx doctor` añade una sección de "selección de comandos ocx": los registros no válidos, inseguros (`record-unsafe`) o habilitados pendientes y los objetivos de escritorio faltantes/inutilizables fallan la comprobación, mientras que los registros deshabilitados pendientes de limpieza, los conflictos de orden de PATH y los escaneos incompletos advierten. `OCX_NO_DESKTOP_HANDOFF=1` suprime el traspaso de paquete-lanzador para una invocación; deja la configuración de la shim de escritorio y de PATH en su lugar. Estas observaciones de solo lectura no ejecutan candidatos, resuelven alias/funciones de parent-shell ni identifican al propietario del entorno de ejecución del proxy. En Windows, el traspaso de paquete-lanzador está desactivado; el pedido del usuario `Path` selecciona el escritorio `ocx.exe`. El estado y el médico aún leen el registro y reportan al primer candidato a PATH. Se informa de un posible candidato de directorio actual cmd por separado del orden PATH. + +`ocx status --json` también incluye `install`: cómo se instaló este `ocx`, según el mismo detector que usa `ocx update`. `install.method` es `bun`, `npm`, `pnpm`, `mise`, `source`, `standalone` (el binario compilado de escritorio) o `unknown` si la detección falló. `install.evidence.basis` indica qué evidencia decidió el resultado (`package-layout`, `mise-backend-record`, `standalone-binary` o `unavailable`); una instalación mise añade el alias de la herramienta y el backend de mise, y un fallo añade un código `error`. No se añade ninguna ruta. + +Los indicadores de salida son por comando. `doctor` rechaza `--json` con la salida 2; [`v2` (referencia de la familia)](/es/reference/cli/agents/) soporta `--json` para objetivos locales y `--live`. Incluso para los comandos de gestión con capacidad JSON, los fallos API normalmente usan prosa stderr con líneas opcionales `reason:` y `hint:`, no una envolvente de error JSON. Mantén separados el estado stdout, stderr y exit. + +La cobertura se mide por flujos de trabajo con nombre, no por prefijos de rutas compartidas. Los ajustes preestablecidos de modelo existentes, la visibilidad, los controles de cuenta y las lecturas de perfil de enrutamiento no implican soporte para ediciones de nombre de pantalla de modelo descubierto o escrituras de perfil de enrutamiento. Las acciones de consentimiento de solo sesión y la presentación del navegador siguen siendo límites separados. Creación de clave de acceso y credenciales de texto plano de retorno de inicio de rotación: los agentes deben entregar esos pasos a un terminal operado por humanos fuera de la sesión y aceptar solo ID y confirmación no secretas. Nunca pida credenciales en el chat ni omita una acción de solo sesión con otro cliente API. + + + +## Cambios de comportamiento recientes + +Estas son correcciones a comandos que previamente informaron mal sus propios resultados: + +- `doctor` y `sync-cache` ahora salen no cero en caso de fallo. Previamente imprimieron un fracaso y salieron 0, por lo que un guión no podía distinguir el éxito del fracaso. +- Los errores del cliente de `account` Mapa HTTP 404 a la salida 4 y HTTP 409 a la salida 5, en lugar de contraerse Todo en 1. +- `ocx restore back --json` ahora honra su bandera de salida, que previamente aceptó e ignoró. Esto no hace que `--json` sea una opción global para cada comando. +- `ocx logs --model` ahora en realidad filtros. Se aceptó y se ignoró silenciosamente, por lo que la salida parecía filtrada mientras mostraba cada fila. +- `ocx storage` ganó `cleanup`, `trash` y `policy` subcomandos. Un `ocx storage` desnudo todavía imprime el informe de almacenamiento, como lo hizo cuando era un alias de `ocx observe storage`. + + + +## Objetivos de versión y despacho interno + +`ocx --version`, `ocx -v`, y `ocx version` imprimen una línea de versión amigable para el script y salen. + +Dos destinos de envío se omiten intencionalmente de la ayuda normal: `__refresh-version [preview]` actualiza la caché de actualización-notificación en un proceso separado, y `__gui-update-worker [latest|preview] [restart]` ejecuta un trabajo de actualización del panel de control. Son detalles de implementación, no comandos estables orientados al usuario. El panel registra el PID del trabajador, recupera un trabajo activo cuyo trabajador murió, trata los registros activos sin PID más antiguos como obsoletos después de diez minutos y protege a un trabajador vivo de actualizaciones simultáneas. + + + +## Validación del argumento de capacidad + +`ocx capabilities` rechaza argumentos desconocidos, banderas repetidas y valores en blanco de `--route` con salida 64. Una ruta válida sin capacidad declarada sale 4. + + + +## Valores de opción enteros + +Las opciones enteras como `--limit` requieren números enteros decimales dentro de los límites de seguridad de JavaScript. Se aceptan separadores de dígitos tales como `1_000` y `1,000`. Los valores vacíos, hexadecimales, notación de exponente y fracciones son rechazados antes de que se envíe una solicitud. + + + +## Windows JSON archivos de configuración + +`ocx config validate ` y `ocx config import --yes` aceptan UTF-8 JSON con o sin una lista de materiales líder, incluyendo stdin (`-`). Esto soporta exportaciones UTF-8 desde Windows PowerShell y editores. No se acepta la entrada UTF-16. + + + +## Listado de alias predeterminado + +`ocx alias --json` es equivalente a `ocx alias list --json`. La bandera de salida puede preceder o seguir una acción de alias explícita. + + + +## Salida y validación de configuración local + +`ocx config validate [path|-] [--json]` sale de 1 cuando falla la validación. El modo JSON emite una carga útil `{ok:false,error}`; el modo humano nombra el fallo de validación. + +Cuando la configuración guardada no es válida o ilegible, `ocx config`, `ocx config show` y `ocx config get` advierten en stderr que los valores predeterminados se muestran para configuraciones inválidas y salen no cero. Stdout conserva su formato existente. Ejecute `ocx config validate` para inspeccionar el error, o `ocx config show --source` para los diagnósticos de configuración y fuente. La inspección explícita `--source` sale de 0 cuando informa con éxito una reserva y aún emite la advertencia. + +`ocx config export --json` escribe la configuración raw en el archivo y emite solo `{ok:true,path}` en stdout. Exportar a `-` siempre emite el documento de configuración en bruto, incluidas las credenciales; manténgalo fuera de las transcripciones del agente. + +Local `ocx provider add` valida la configuración completa del candidato antes de guardar. Un error de validación deja el archivo guardado sin cambios. intencionalmente proveedores locales requieren `--allow-private-network` a menos que su entrada de registro ya permita destinos privados. El indicador no permite los puntos finales de metadatos bloqueados. + +`ocx health` solo acepta una bandera opcional `--json`. Los argumentos desconocidos o los indicadores repetidos devuelven la salida 2 antes de sondear. Los errores de uso de Alias también devuelven la salida 2 con un error legible; las acciones desconocidas nombran `ocx help alias`. + + + +### Selectores de modelo de registro + +`ocx logs --model` acepta un ID de modelo desnudo o la etiqueta completa `provider/model` impresa en filas humanas, incluidos los modelos cuyos ID desnudos contienen barras. Los intentos de conmutación por error se comparan como destinos completos. El filtrado se produce antes de `--limit`, y `--follow` utiliza el mismo filtro de servidor. Un resultado humano filtrado vacío dice que no hay entrada de registro coincidente; `--json` y `--jsonl` mantienen su salida legible por máquina. + +`ocx hub disable [--revoke-clients --client-key ...] [--json]` devuelve un concentrador a autónomo en una escritura de configuración validada. La revocación de la clave del cliente requiere identificadores explícitos porque los nombres de clave no prueban el origen. Véase [Devolver un concentrador a autónomo](/es/guides/remote-hub/#return-a-hub-to-standalone). diff --git a/docs-site/src/content/docs/es/reference/cli/agents.md b/docs-site/src/content/docs/es/reference/cli/agents.md new file mode 100644 index 00000000000..33a163d1a9d --- /dev/null +++ b/docs-site/src/content/docs/es/reference/cli/agents.md @@ -0,0 +1,809 @@ +--- +title: "Agentes, enrutamiento e integraciones de CLI" +description: "Comandos multiagente, combo, observabilidad, acceso, ruta de protocolo, integración, sistema y configuración." +--- + +Estos comandos controlan la política del agente y el enrutamiento, inspeccionan el proxy en vivo y conectan los clientes compatibles con opencodex. + + + +## Política del agente + +### `ocx agent ...` + +Administre la lista de agentes múltiples sin cabeza, los límites de esfuerzo, la inyección rápida, la reserva y la configuración del sidecar. Utilice `status` para la política actual. Vea [Superficies de los subagentes](/es/guides/sub-agent-surface/) para ver cómo encajan entre sí los modos de superficie, la delegación, el esfuerzo y el comportamiento alternativo. + +```bash +ocx agent subagents set ark/model-a,openai/gpt-5.5 +``` + +`ocx agent roles` es para omo (Codex / LazyCodex). Enumera cada rol de agente Codex en `$CODEX_HOME/agents` con su pin de modelo y si `~/.omo/omo.jsonc` se puede actualizar, o dice que LazyCodex no está instalado, en cuyo caso `set` es rechazado. `ocx agent roles set [--effort ]` reescribe solo la línea de la raíz `model` de ese rol, y su línea `model_reasoning_effort` con `--effort`, y refleja tanto en omo.jsonc como `[codex].agents.` como `model` y `reasoning`. Un esfuerzo para el que LazyCodex no tiene nivel, como `ultra`, se escribe solo en el archivo de rol. Una falta omo.jsonc, o uno que contiene comentarios, se deja sin cambios y el comando lo dice. Véase [omo ( Codex / LazyCodex) modelos de rol](/es/guides/integrations/#omo-codex--lazycodex-role-models). + +```bash +ocx agent roles set explorer xai/grok-4.5 --effort medium +``` + +`ocx agent roles suggest` es omo (Codex / LazyCodex) solamente, rechazado como `set` cuando LazyCodex no está instalado. Dimensiona cada rol con una llamada al modelo predeterminado Codex (o `--model`) e imprime un modelo propuesto y un esfuerzo por rol sin escribir nada. `--apply` escribe cada propuesta a través de la misma escritura que `set`, saltándose y nombrando los roles cuyo modelo y esfuerzo ya coinciden. Véase [Asignación automática](/es/guides/integrations/#auto-assign). + +La salida de sugerencias legible por humanos muestra caracteres de control de terminal como escapes visibles. Utilice `--json` cuando necesite los valores de sugerencia originales sin que se escape la presentación. + +`ocx agent injection suggest ` hace lo mismo para el modelo de delegación: mide el trabajo descrito, propone el modelo suficiente más barato y un esfuerzo de la lista del seleccionador de delegación, y no escribe nada a menos que se dé `--apply`, lo que ahorra a través de la misma escritura que `injection set`. Véase [Modelo de delegación y esfuerzo](/es/guides/sub-agent-surface/#delegation-model-and-effort). + +`ocx agent sidecar web --list` y `ocx agent sidecar vision --list` imprimen los modelos que el servidor ofrece actualmente para cada sidecar: el conjunto filtrado exacto que muestra el selector de tablero (filas visibles para el selector más las ranuras de autenticación Luna/Haiku con nombre de inicio de sesión, intersectadas con la disponibilidad del ejecutor para la búsqueda web, menos los modelos de solo texto para la visión). Las listas legibles por humanos muestran el backend de cada modelo entre paréntesis. Una escritura de búsqueda web `--model` resuelve esa fila ofrecida por el servidor y persiste su backend y modelo juntos, por lo que cambiar a una opción Anthropic no puede mantener un backend OpenAI (o viceversa). Las escrituras van a la misma ruta de administración que la GUI y están sujetas a la misma puerta por sidecar: la búsqueda web rechaza un par backend / modelo fuera del conjunto de la lista (miembro cerrado), mientras que la visión rechaza solo un modelo que probablemente no pueda ver (ids desconocidos permanecen escribibles). + +```bash +ocx agent sidecar web --list +ocx agent sidecar web --model gpt-5.6-luna +ocx agent sidecar web --enabled off +``` + +`--enabled off` es el mismo switch que la fila Off del Dashboard: OpenCodex deja de ejecutar el sidecar y la integración Codex escribe `web_search = "disabled"` en `~/.codex/config.toml`, que es lo que permite que un servidor de búsqueda MCP sea la única ruta de búsqueda. `--enabled on` elimina esa línea de propiedad del marcador de nuevo. Cuando el guardar mueve realmente el interruptor, el comando informa que el Codex -side escribe que se activó (`codexWebSearch` en `--json`, una línea `Codex config:` posterior de lo contrario) y apunta a `ocx sync` cuando no podía suceder; un guardar que deja el interruptor donde estaba no tiene nada que informar e imprime ninguna línea `Codex config:`. La bandera funciona para `vision` también. + + + +### Configuración predeterminados de inyección y entorno de ejecución del sidecar + +```bash +ocx agent injection status --json +ocx agent injection set --sync-codex-defaults off --json +ocx agent injection status --json +ocx agent sidecar web --stream-routed-output on --json +ocx agent sidecar vision --timeout-ms 30000 --json +ocx agent sidecar status --json +``` + +Ejecutar escribe solo para el cambio solicitado. La inyección `--sync-codex-defaults on|off` actualiza `syncCodexSubagentDefaults`; modelo/esfuerzo/pronta/orientación omitido permanece intacto, y `-` borra modelo/esfuerzo/pronta. El recibo ha normalizado realmente `model`, `effort`, `prompt`, `multiAgentGuidanceEnabled` y `syncCodexSubagentDefaults`, no un resultado de catálogo fabricado. + +Web `--reasoning` sigue siendo compatible. `--max-descriptions` y `--timeout-ms` son solo de visión; el tiempo de espera acepta enteros de 1 a 2147483647 milisegundos. `--stream-routed-output` es solo web. Las escrituras parciales conservan la configuración de hermanos. El recibo de nueva opción expone solo el estado público seleccionado `webSearch` o `vision` y `codexWebSearch` aplica el informe. `{applied:false, reason, retryable}` distingue el aplazamiento/rechazo de aplicación nativa de una configuración guardada; una nueva configuración faltante o no coincidente no está verificada y no es cero. Lee el estado para ver los ajustes completos observados, incluido el razonamiento web. No vuelvas a intentar ciegamente el rechazo de la propiedad. + + + +### Anulaciones de enrutamiento de memoria y compactación + +```bash +ocx agent memory-models show --json +ocx agent memory-models set --extract-model --extract-effort high --consolidation-model --json +ocx agent memory-models show --json +ocx agent compaction-routing show --json +ocx agent compaction-routing set --model --effort high --triggers manual,auto --sources ',/*' --json +ocx agent compaction-routing show --json +``` + +Cada conjunto reemplaza el bloque entero. La memoria acepta el modelo de extracción/consolidación y los pares de esfuerzo opcionales; se rechaza un esfuerzo sin el modelo de esa fase. Las fases omitidas usan su ruta existente/predeterminada, no una canalización detenida. `--file memory.json` en cambio lee el bloque en sí: + +```json +{"extract":{"model":"example/model","reasoningEffort":"high"}} +``` + +Un archivo de memoria explícito `{}` es válido y sigue siendo un bloque de anulación vacío; `ocx agent memory-models clear --json` escribe null. Ambos significan que no hay una anulación personalizada, no un procesamiento de memoria deshabilitado. El modo de archivo es exclusivo con opciones escalares. Los archivos UTF-8 regulares o `--file -` canalizados utilizan el contrato de entrada limitada de 4 MiB/30 segundos, incluido un límite de solicitud seriado de 4 MiB. + +Los archivos de compactación contienen `model`, `reasoningEffort` opcional, `triggers` y `sourceModels`. Los disparadores son únicos `manual` / `auto`; los selectores de fuente deben ser exactos y únicos, o patrones de proveedor /. Los disparadores omitidos usan los valores predeterminados del servidor; las fuentes omitidas seleccionan todas las fuentes, no el alcance personalizado anterior. `ocx agent compaction-routing clear --json` escribe null y restaura el enrutamiento de compactación ordinario sin deshabilitar la compactación. Ninguna llamada de modelo sintético verifica estos ahorros. + +Las lecturas devuelven solo `{memoryModels: blockOrNull}` o `{compactionRouting: blockOrNull}`. Escribe agrega `catalogRefreshPending`: salidas falsas 0 sin prometer a cada cliente aplicado, salidas verdaderas 1 después de guardar. La evidencia pendiente faltante/malformada es nula con `verification:"unverified"` y salida 1. Lee antes de la recuperación. + +### `ocx effort [status|set|clear]` + +Inspeccione o cambie los límites del esfuerzo de razonamiento del agente principal y del subagente a través del proxy en vivo o la configuración local cuando no haya proxy disponible. Los valores máximos son `low`, `medium`, `high`, `xhigh`, `max` y `ultra`; `-` borra la tapa seleccionada. `none` y `minimal` no son niveles de límite y se rechazan antes de probar el proxy o enviar una actualización, incluso cuando otra opción en el mismo comando es válida. Siguen siendo válidos para `--injection`, que establece el esfuerzo de inyección por separado en lugar de una tapa. + +```bash +ocx effort status --json +ocx effort set --main high --subagent low +ocx effort set --subagent - +``` + +Status conserva los valores de límite de entorno de ejecución/almacenados existentes e informa de los valores no admitidos en `warnings` (una matriz vacía cuando no se admite ninguna). Las mismas advertencias aparecen en la salida humana y nombran el campo que se ignora con un comando de corrección. El estado nunca repara o reescribe esos valores. Un campo de subagente ignorado no elimina un límite principal válido. `ocx effort clear` limpia ambas tapas mientras retiene la configuración de esfuerzo de inyección separada. Véase [Superficies de los subagentes](/es/guides/sub-agent-surface/) para las superficies de solicitud donde se aplican tapas. + +### `ocx v2 |keep-native-v1 |threads |mode-hint >` + +Administre el indicador de características Codex `multi_agent_v2` y el modo de superficie multiagente de tres estados. Estos funcionan localmente por defecto. `--live` utiliza el proxy de ejecución seleccionado sin respaldo local; ambos objetivos admiten `--json`. Vuelva a leer el estado en el mismo objetivo después de un cambio y distinga la configuración almacenada del comportamiento de la nueva sesión. + +| Subcomando | Medidas adoptadas | +| --- | --- | +| `status` (por defecto) | Reportar el indicador v2 actual, el modo multiagente y la concurrencia de subprocesos. | +| `on` | Habilite la función global `multi_agent_v2`; los cambios locales vuelven a sincronizar el catálogo. Rechazado mientras el pin híbrido v2 está activo porque la anulación global lo derrotaría. | +| `off` | Desactive la función `multi_agent_v2` y vuelva a sincronizar el catálogo. | +| `mode v1` | Forzar a todos los modelos a v1, deshabilitar v2 nativo y preservar el límite de subproceso activo. | +| `mode default` | Respete los pines de superficie del modelo aguas arriba. | +| `mode v2` | Forzar los modelos a v2 y preservar el límite de rosca activa. Con `keep-native-v1` desactivado, habilite la v2 nativa global; con ella, deshabilite la anulación global y use pines de catálogo. | +| `keep-native-v1 on\|off` | Bajo `mode v2`, mantenga los modelos nativos ChatGPT en v1 y los modelos enrutados en v2. Habilitarlo desactiva la anulación global de V2 antes de la sincronización del catálogo. | +| `threads ` | Establezca el límite de hilo v1/v2 activo en un número entero de al menos 1. | +| `mode-hint ` | Establezca la sugerencia de delegación proactiva (modo Ultra) para cada modelo y esfuerzo. | +| `mode-hint --clear` | Elimine la sugerencia para que se reanude la política derivada del esfuerzo (ultra + proactiva). | + +```bash +ocx v2 status +ocx v2 mode v1 +ocx v2 mode default +ocx v2 on +ocx v2 threads 16 +ocx v2 mode-hint "Proactive multi-agent delegation is active." +ocx v2 mode-hint --clear +``` + +El subcomando `mode` escribe `multiAgentMode` a la configuración opencodex y vuelve a sincronizar el catálogo Codex. Las transiciones de modo y bandera mueven el límite de subproceso numérico actual entre las teclas v1/v2 Codex válidas; una transición fallida restaura el `config.toml` original. Los cambios se aplican a las nuevas Codex sesiones, mientras que las sesiones en ejecución mantienen su superficie fija. + +Codex resuelve una anulación global habilitada de `multi_agent_v2` antes del pin de catálogo del modelo seleccionado. Por lo tanto, el contrato híbrido `keep-native-v1` mantiene esa anulación global apagada; de lo contrario, una fila nativa estampada `v1` aún comenzaría en V2 y produciría tareas secundarias cifradas en el backend. + +`mode-hint` escribe `features.multi_agent_v2.multi_agent_mode_hint_text` en Codex 's `$CODEX_HOME/config.toml` incluso cuando `multi_agent_v2` está actualmente deshabilitado. El comando solo persiste la anulación; no habilita ni deshabilita la función, por lo que la sugerencia tiene efecto cuando una superficie coincidente Codex está activa. La sugerencia anula la política multiagente derivada de esfuerzo de codex-rs, por lo que cualquier modelo y cualquier esfuerzo de razonamiento recibe el mensaje de delegación proactiva. **no** cambia el esfuerzo de razonamiento en sí. Se rechaza un argumento faltante o un valor de solo espacio en blanco; solo `--clear` elimina la sugerencia. El modo Ultra **on** del panel de Subagents tiene una puerta más estricta: requiere que la función nativa esté habilitada con una superficie v2 explícita ( `ocx v2 mode v2` ); `ocx v2 on` por sí solo no satisface esa puerta del tablero. + + + +#### Objetivo y resultado explícitos de la versión 2 + +```bash +ocx v2 status --json +ocx v2 status --live --json +ocx v2 mode v1 --live --json +ocx v2 status --live --json +``` + +La escritura en vivo utiliza la ruta de gestión existente. Sólo explícito en vivo `mode` acepta `--acknowledge-surface-advisory`; añadirlo sólo cuando se reconoce que se solicita asesoramiento. Modo local y estado/encendido/apagado/mantenimiento nativo/hilos/pista rechazarlo. No hay reconocimiento automático. + +Para el texto literal reservado, pase un operando citado después de `--`: + +```bash +ocx v2 mode-hint --live --json -- '--clear' +``` + +Esto almacena literal `--clear`; sin `--`, `mode-hint --clear` elimina la pista. El sufijo no se escanea en busca de ayuda, en vivo, JSON o controles claros; los controles pertenecen antes de `--`. Los operandos adicionales y las banderas duplicadas se niegan antes de la mutación. + +El local JSON es `{ok, target:"local", action, changed, state, sync}` usando el estado post-escritura real. Modo/mantenimiento-nativo y modificado on/off mantienen su intento de sincronización real incluso sin un puerto descubierto; hilos/sugerencias y on/off sin cambios no agregan sincronización. Un resultado de sincronización ausente/malformado no se verifica con la salida 1, no con éxito. `changed` o estado puede ser desconocido después de la falla; no reclame la reversión. Los informes de estado en vivo validaron el estado/asesor/recomendación con `target:"live"`; escribe añadir `ok:true` y `catalogRefresh`. Solo la actualización comprometida y no degradada sale 0. HTTP 502 puede significar un estado nativo parcialmente aplicado: inspeccionar antes de volver a intentarlo. Los errores de uso local retienen la salida 1; los nuevos errores de uso en vivo usan la salida 2. + + + +## Ruteo combinado + +### `ocx combo ...` · `ocx route combo ...` + +Gestione la conmutación por error combinada y los modelos virtuales round-robin. `ocx route combo` es el alias jerárquico; combos y perfiles de enrutamiento son recursos distintos. Los objetivos combinados usan `provider/model[:weight],provider/model[:weight]`. + +```bash +ocx combo list +ocx route combo set reliable --targets ark/model-a:2,openai/gpt-5.5 +``` + +`set` acepta `--strategy`, `--sticky`, `--effort`, `--alias`, `--rename-from`, `--native-alias` y `--display-name ` (`-` borra la etiqueta). Un alias nativo captura solo un identificador de modelo OpenAI no calificado actualmente soportado. Bare `gpt-5.6-*` alias nativos utilizan Codex Pool / Direct credenciales. Las rutas con calificación de cuenta OpenAI siguen siendo distintas, mientras que las rutas con calificación de proveedor como `openai-apikey/gpt-5.6-*` usan su clave configurada API y nunca caen a través del alias nativo. Lea el contrato de seguridad y visibilidad en la guía antes de habilitar el par de compatibilidad. El método de decisión se elige mediante dos opciones mutuamente excluyentes únicamente cuando la estrategia efectiva es JEV: al indicar `--strategy jev` o al omitir `--strategy` en un combo JEV existente. `--decision-provider ` nombra una fila `jev-decision` configurada (por ejemplo, una Ollama `tev1` autoalojada) como un servidor compatible con System One. `--decision-model ` nombra una ruta opencodex ordinaria (por ejemplo `ollama/qwen3:4b`) que responde a la misma opción que JSON; no puede ser este combo o cualquier combo JEV. Un combo JEV nuevo usa TypeSafe si se omiten ambas opciones; uno existente conserva su método de decisión hasta cambiarlo mediante una de ellas. `--decision-timeout ` establece el plazo de decisión (1000-120000, por defecto 4000); `-` elimina cualquiera de los tres. + +`ocx combo set --decision-quota-signals on|off|-` controla la evidencia consultiva por combo. `--decision-quota-tiers '{"limited":80}'` configura umbrales parciales; `-` los borra. Ambas opciones son exclusivas de JEV. Si se omiten, se conservan al sustituir destinos con `--targets-file` o `--targets` y al renombrar. Si no se indica `--strategy`, un combo existente conserva su estrategia: JEV mantiene su método, cuotas y fijación de sesión; un combo nuevo usa failover por defecto. Si una política JEV conservada rechaza los destinos nuevos, el comando identifica esa política y no guarda nada. Desactivar las señales conserva los umbrales; salir de JEV elimina ambos ajustes. Esto aporta datos de cuota al backend elegido, sin añadir consultas a proveedores, selección de cuentas ni exclusiones obligatorias. Véase [valores predeterminados, vigencia y privacidad](/es/guides/combos/#advisory-quota-signals-for-jev). + +`ocx combo set --session-pin `, exclusivo de JEV, mantiene la sesión en el destino que JEV eligió mientras siga activa, permitiendo reutilizar la caché del proveedor. La duración es un plazo de inactividad: `90s`, `20m`, `1h` o milisegundos, entre un minuto y 24 horas. `-` lo desactiva. Véase [Fijación de sesión para JEV](/es/guides/combos/#session-pin-for-jev). + +`ocx combo test [--combo ] [--decision-provider | --decision-model ] +[--decision-timeout ]` envía una sonda de decisión sintética a través de un método combinado guardado o una selección no guardada e informa de la puerta, el backend y la latencia; puede pasar una llamada de decisión. `ocx combo discover [--query ]` enumera las filas configuradas de System One y los modelos de catálogo que parecen modelos de decisión, con el punto final derivado. + +Para metadatos de destino estructurados, inspeccione la ayuda sin conexión y el combo actual: + +```bash +ocx combo set --help +ocx combo list --json +ocx combo show reliable --json +``` + +Un documento `--targets-file` es una matriz ordenada no vacía, por ejemplo, esta forma con valores de proveedor/modelo reemplazados por candidatos configurados reales: + +```json +[{"provider":"example","model":"raw/model","weight":1,"reasoningEfforts":["high"],"modelProfile":"Reasoning tasks","lastResort":false}] +``` + +Los campos opcionales son `weight`, `reasoningEfforts`, `modelProfile` y `lastResort`. Esfuerzos son una lista única no vacía de `low`, `medium`, `high`, `xhigh`, `max`, `ultra`; vacío/ninguno/mínimo modelo personalizado semántica no se aplican. Los archivos o `-` canalizados explícitamente tienen un límite de 4 MiB y un plazo de lectura de 30 segundos; el cuerpo de administración serializado también debe ajustarse a 4 MiB. Los campos desconocidos se niegan antes de la escritura. + +```bash +ocx combo set reliable --targets-file targets.json --image-input auto --reasoning-effort-mode strict --json +ocx combo show reliable --json +``` + +`--targets-file` y `--targets` son mutuamente excluyentes. Omitir ambos preserva metadatos de destino completos para ediciones parciales; los archivos de reemplazo preservan el orden y el `lastResort: false` explícito. `--image-input auto|disabled` y `--reasoning-effort-mode strict|adaptive` preservan la omisión, mientras que `auto` y `strict` explícitos anulan los valores deshabilitados/adaptativos guardados. El modo Razonamiento-esfuerzo está separado del `--effort-mode fallback|force`, que gobierna el esfuerzo predeterminado. `--allow-metered-targets on|off` otorga o borra el consentimiento del operador para los objetivos combinados marcados en un proxy de solo loopback; las personas que llaman públicas y vinculadas aún necesitan el consentimiento de clave configurada. `--native-alias on|off` conserva explícito falso; la bandera desnuda legado significa verdadero. Desactivarlo puede requerir el alias claro previsto, `--native-alias off --alias -`, para evitar retener un alias nativo incompatible. Establecer/renombrar es un upsert sin CAS, así que vuelve a leerlo después de los cambios. El recibo es `{success, id, model, combo, catalogRefresh}`; la actualización del catálogo omitida, fallida o degradada devuelve un valor distinto de cero después de guardar. + + + +### Observar las estadísticas de decisiones combinadas + +```bash +ocx combo stats reliable --range 30d --json +``` + +Utilice el ID combinado almacenado exacto de list/show, no su modelo público o alias. Los rangos son `7d`, `30d` (predeterminado) y `all`. Esto lee observaciones JEV registradas sin ejecutar una sonda de decisión pagada. Inspeccione las decisiones, los intentos de modelo, los intentos medidos, los tokens de modelo y los tokens de decisión por separado. Mantenga las proporciones de cobertura `measuredModelAttempts/modelAttempts` y `decisionUsageReported/decisions` con los totales. Los promedios nulos no están disponibles, no son cero. Conservar `usageIncomplete`, `historyTruncated`, `entriesTruncated`, recuentos de entrada caída y límites de ventana instantánea. Cero observaciones no prueban el éxito. No hay costos monetarios ni ahorros comparativos en este informe. + +Consulte [Combos](/es/guides/combos/) para obtener orientación sobre el comportamiento de enrutamiento y la configuración. + + + +## Desactivar el fallback + +### `ocx fallback ...` + +```bash +ocx fallback status --json +ocx fallback off --kind provider +ocx fallback on --route combo/coding +ocx fallback clear --provider anthropic --kind model +ocx fallback local on --device mac-studio +``` + +`off`, `on` y `clear` aceptan `--kind model|provider|all` (por defecto, `all`) y como máximo un alcance: `--provider `, `--route ` o `--device `. Sin alcance explícito, modifican el ajuste global. Un dispositivo configurado en off siempre rechaza el fallback; en los demás casos, la ruta tiene prioridad sobre el proveedor y este sobre el ajuste global. `local` guarda si un dispositivo puede usar sus propios proveedores mientras el Home no esté disponible, un permiso que consulta GOAT; OpenCodex sigue devolviendo `home_unreachable` en ese caso. Los comandos se comunican con el proxy en ejecución; en un Remote Link Child, `status` consulta el Home y las escrituras se rechazan. Consulta [Desactivar el fallback](/es/guides/fallback-off/). + + + +## Perfiles de enrutamiento + +Los perfiles existentes apoyan la inspección y evaluación a través del API en vivo: + +```bash +ocx route policy list --json +ocx route policy show reliable --json +ocx route policy dry-run reliable --model-context 128000 --tools --image --structured-output --json +``` + +Solo ejecute esta evaluación con autoridad para activar Lab en el destino. La administración POST puede activar Lab e iniciar la automatización que ya está habilitada allí, incluidas las sondas ascendentes. Use list/show para la observación sin ese efecto de activación. + +Reemplazar `reliable` con un ID listado. `evaluate` es un alias para `dry-run`; ambos envían requisitos al evaluador del perfil guardado sin una solicitud de inferencia. La creación, actualización y eliminación utilizan el flujo de trabajo explícito de archivo/revisión a continuación. Combo escribe editar un recurso separado. Los perfiles faltantes devuelven la salida 4 y los operandos faltantes devuelven 2. + + + +### Editar un perfil de enrutamiento con su revisión observada + +Crear/actualizar puede activar la automatización de Lab y ya habilitada, incluidas las sondas ascendentes. Sólo guárdalos con esa autoridad. La lista/presentación son observacionales; primero lea la ayuda fuera de línea y guarde el perfil previsto: + +```bash +ocx route policy update --help +ocx route policy show reliable --json > profile.observed.json +jq 'del(.id, .model, .revision) | if .alias == null then del(.alias) else . end' profile.observed.json > profile.next.json +``` + +Editar y revisar el siguiente archivo; mantener el archivo observado sin cambios. La entrada contiene solo `alias`, `candidates`, `require`, `optimize`, `limits`, `unknownEvidence` y `compatibility` editables con campos anidados admitidos. `id`, `model`, `revision`, las claves desconocidas y el alias nulo no son entradas editables. El servidor sigue validando la semántica de proveedor, alias y políticas. `--file -` acepta stdin canalizado; los archivos/stdin UTF-8 regulares tienen el contrato de lectura de 4 MiB y de 30 segundos acotado. + +```bash +ocx route policy update reliable --file profile.next.json --expected-revision '' --json +ocx route policy show reliable --json +``` + +Utilice la revisión opaca original explícitamente. HTTP 409 / exit 5 significa volver a leer show, revisar los cambios concurrentes y reconstruir la edición. Nunca busque silenciosamente una revisión de reemplazo, vuelva a intentar o convierta la actualización en crear. Para un nuevo ID autorizado, utilice `ocx route policy create --file profile.next.json --json` sin revisión. La eliminación autorizada es `ocx route policy remove --yes --json` y no tiene guardia de revisión. + +Create/update devuelve `{success, id, model, profile, catalogRefresh}` con el nuevo `profile.revision`; quita `{success, id, catalogRefresh}`. Solo la actualización comprometida y no degradada sale 0. Un recibo guardado con salidas de actualización saltadas/fallidas/degradadas 1: inspeccione antes de la recuperación en lugar de repetir la escritura de configuración. + + + +## Laboratorio de compatibilidad + +Lab es la inspección local **y** explícita de pruebas / automatización de gestión. Las lecturas usan la proyección local y no requieren una administración en ejecución API: + +```bash +ocx lab status --json +ocx lab catalog --json +ocx lab subjects --limit 10 --json +ocx lab automation status --json +ocx lab automation runs --limit 10 --json +ocx lab public community --json +``` + +`subject`, `observations`, `event`, `artifact` y `production-signals` siguen el linaje de evidencia local. La familia pública ofrece vista previa/exportación por `--event ` repetido, verificación/importación a través de `--file `, y contexto comunitario. Exportar e importar escribe evidencia local. La verificación puede imprimir su resultado y aún salir de no cero cuando el paquete no es criptográficamente válido. + +El manual `lab run` selecciona una capa y un escenario y puede gastar la cuota ascendente. Lea `ocx help lab` y la hoja correspondiente antes de estas operaciones autorizadas. Una política local guardada no prueba que un programador de proxy que ejecuta por separado la haya adoptado. Estos controles CLI no exponen la edición de políticas de automatización completa ni la cancelación de ejecución. + + + +## Observabilidad y depuración + +### `ocx observe ...` + +Inspeccione las solicitudes de proxy, el uso, el almacenamiento, la memoria y los datos de depuración. Los alias directos son: + +| Alias | Recursos equivalentes | +| --- | --- | +| `ocx logs [filters] [--follow] [--json\|--jsonl\|--events]` | `ocx observe logs` | +| `ocx usage [--range ] [--since --until ] [--surface ] [--provider ] [--model ] [--api-key-id ] [--search ] [--top <1-1000>] [--json]` | `ocx observe usage` | +| `ocx usage compare [--range ] [--json]` | `ocx observe usage compare` | +| `ocx storage [--json]` | `ocx observe storage` | +| `ocx memory [--json]` | `ocx observe memory` | + +```bash +ocx observe usage --range 30d --json +ocx usage --since 2026-09-01T09:00:00Z --until 2026-09-01T10:59:59.999Z --json +``` + +`--since` y `--until` deben suministrarse juntos. Aceptan milisegundos de época enteros o fechas ISO completas con una zona horaria explícita, incluyen ambos puntos finales y anulan `--range`. Los límites no válidos o invertidos fallan antes de la solicitud. La salida humana imprime el intervalo solicitado; `--json` incluye `customWindow`, `since` y `until`. Todavía se aplican los filtros de superficie/proveedor/modelo existentes. Estos comandos consultan el proxy en ejecución; no proporcionan informes sin conexión. + +`--range today` (alias `1d` ) informa el día local actual. `--provider` y `--model` reducen el informe a un objetivo ascendente, distinto del `--surface`, que selecciona el cliente llamante (Codex, Claude Code, Grok) en lugar del proveedor que atiende la solicitud. + +La vista predeterminada imprime la solicitud, el token y los totales de costos estimados, además de los desgloses por proveedor y por modelo. Los costos son equivalentes al precio de lista de API, no un recibo de facturación: los planes de suscripción y los créditos del proveedor se facturan por separado, y las solicitudes sin fila de precios coincidentes se cuentan como `unpriced` / `unmetered` en lugar de doblar como cero. + +```bash +ocx usage --range today --provider xai +``` + +Cuando no se pueden incluir algunos registros de uso, la salida humana advierte, incluso cuando hay cero filas legibles. Los totales mostrados reflejan solamente registros legibles. Si un filtro no tiene coincidencias legibles, la salida muestra la advertencia y la guía en lugar de las líneas totales; los registros omitidos pueden contener coincidencias. `--json` preserva el diagnóstico y la razón del nivel de respuesta `usageIncomplete`. + + + +### Comparar un rango con la ventana igual anterior + +```bash +ocx usage compare --range today --json +ocx usage compare --range 7d --provider xai +``` + +`ocx observe usage compare` es la forma familiar equivalente. El comando lee `GET /api/usage` dos veces: el rango nombrado termina ahora, luego el mismo rango evaluó una ventana igual antes (un día local para `today` / `1d`, siete para `7d`, treinta para `30d`). El rango predeterminado es `30d`. `--range all` se rechaza porque el historial abierto no tiene una ventana igual anterior. `--since` y `--until` no son aceptados; las ventanas se derivan. Los filtros de superficie, proveedor, modelo y API teclas se aplican a ambas lecturas. La salida humana imprime el cambio actual, anterior, firmado delta y porcentual. `--json` es `{schemaVersion,range,current,previous,delta,change,incomplete}`. Las dos lecturas son secuenciales, no una instantánea atómica. La opción personalizada `since` / `until` en cada respuesta debe coincidir con la ventana solicitada. Ambas lecturas usan la misma conexión y credencial. Si la conexión, la cuenta o la credencial cambian durante el comando, se informa de un desajuste del propietario y se le pide que vuelva a intentar en lugar de imprimir una comparación. + + + +### Historial de solicitudes indexadas de página + +```bash +ocx logs history --provider xai --status 200 --limit 50 --json +ocx logs history --cursor '' --json +ocx logs get --json +``` + +`ocx observe logs history` y `ocx observe logs get` son las formas familiares equivalentes. Estos leen el índice de historial de solicitudes derivado, no el reciente anillo `ocx logs`. `--limit` es 1-100 (por defecto 50). `--from` y `--to` aceptan milisegundos de época o fechas ISO completas con una zona horaria y son inclusivos. `--json` devuelve `{entries,hasMore,nextCursor,index}`. `--jsonl` emite filas solamente; cuando existen más páginas, `nextCursor=…` se imprime en stderr para que un llamante pueda reanudar sin mezclar el token en el flujo de filas. Los partidos vacíos tienen éxito. `get` devuelve una fila canónica por ID de solicitud; `ocx logs explain` sigue siendo la vista de decisión de ruta para ese mismo ID. + + + +### Filtrar una instantánea de registro limitado + +```bash +ocx logs filter --surface claude --status errors --time-window 1h --scan-limit 2000 --limit 50 --json +``` + +`ocx observe logs filter` es la forma familiar equivalente. Esto lee una ventana reciente, filtra localmente y luego mantiene las coincidencias más recientes en su orden original. `--scan-limit` controles obtenidos filas (1-2000, por defecto 2000); `--limit` controles filas devueltas (1-2000, por defecto 200). JSON informa `{schemaVersion:1,logs,cursor,filters,window:{scanLimit,loaded,matched,returned,limit}}`. Los recuentos describen esta ventana observada, no toda la historia. JSONL solo emite filas; las coincidencias vacías tienen éxito. Cursor metadatos no es un token de búsqueda reanudable. + +Los selectores incluyen `--surface all|codex|claude|grok`, `--status all|success|errors`, `--time-window all|15m|1h|24h`, `--model`, `--provider`, `--conversation` (alias `--conversationId`), `--intercepted-only`, `--min-tok-per-sec`, `--max-tok-per-sec` y `--protocol-mode all|native|translated|legacy-bridge|blocked|none`. La igualdad de modelo/proveedor se recorta y no distingue entre mayúsculas y minúsculas, incluidos los modelos resueltos/servidos y los intentos. Claude incluye Desktop; Codex significa superficie ausente. El éxito es HTTP 200-299, errores 400-599. Los límites inferiores de tiempo son inclusivos. La velocidad utiliza tok/s de valor-bueno observado, con valores mínimos y máximos inclusivos; los valores no disponibles fallan los filtros de velocidad activos. El protocolo ninguno incluye trazas ausentes o no válidas. La coincidencia de conversaciones utiliza los mismos ID de hash que los registros ordinarios. La interceptación selecciona marcadores de reescritura con valor de cadena. + +Banderas desconocidas/repetidas/conflictivas, límites inválidos y eventos siguientes/fallos antes del descubrimiento. Las lecturas malformadas, de gran tamaño o fallidas no son cero, no son resultados vacíos. Para reducir el tamaño de la respuesta, reduzca el límite de exploración; reducir el límite de salida no cambia la búsqueda. Para la transmisión, use los formularios de seguimiento separados a continuación. + + + +### Buscar filas de modelo de uso + +```bash +ocx usage --range 7d --search 'model-a' --json +``` + +`--search` coincide con una subcadena recortada que no distingue entre mayúsculas y minúsculas en el modelo, proveedor o modelo resuelto después de leer el informe. Ordena las filas del modelo descendiendo tokens totales con lazos estables y mantiene hasta 100 por defecto. JSON agrega `modelView:{query,matchedModelCount,returnedModelCount,limit:100,truncated}`; la salida humana etiqueta la vista y muestra las filas de modelos seleccionadas. Los totales de los informes, las filas proveedor/día/cuenta, los filtros exactos y los metadatos incompletos/ventana permanecen sin cambios. Ninguna coincidencia de modelo no significa que no se utilice el informe. + +Una consulta en blanco explícita (`--search=`) selecciona la vista top-100; la omisión de la búsqueda conserva el resultado existente. Exacto `--provider` / `--model` todavía alcance el informe subyacente. La búsqueda no amplía el auto alcance de la clave seleccionada o del cliente conectado y nunca se envía como un nuevo parámetro de consulta de Hub API. + +`ocx usage --top 25` (también `ocx observe usage --top 25`) establece el límite de la tabla del modelo humano a un número entero de 1 a 1000. El valor predeterminado es 10, o 100 con `--search`; el límite se aplica después del filtrado de búsqueda. Solo cambia la visualización local: los totales de los informes, las filas de proveedores/cuentas y los parámetros API permanecen sin cambios. Con `--json`, se ignora un `--top` válido; JSON conserva su informe completo existente o vista de búsqueda de 100 filas. Límites no válidos devuelven la salida 2 antes de buscar. + + + +### Totales de uso de compañeros guardados + +```bash +ocx companion show --json +ocx companion usage --json +``` + +El segundo comando lee los ajustes complementarios guardados, luego hoy y el uso de 30d secuencialmente en el mismo entorno de ejecución de administración. Aplica las preferencias guardadas `models` y `hiddenProviders` y conserva los costos y tokens desconocidos / no medidos. La selección de modelo nulo significa todo; una selección vacía significa nada. No cambia la configuración, opera ventanas nativas o retransmite a través de un cliente conectado. + +JSON devuelve `schemaVersion:1`, `filters`, `settingsUpdatedAt`, `settingsCorrupt`, `settingsFallback`, `ranges` y `partial`. Cada rango tiene `status:"available"` con `data` filtrado, o `status:"unavailable"`. Un rango no disponible establece el parcial y la salida 1 mientras que retiene el otro rango. Los datos incompletos disponibles conservan sus propios metadatos; no se mide en cero. Los valores predeterminados válidos del servidor retienen una marca de tiempo de configuración nula y establecen un retroceso; los valores predeterminados del archivo corrupto también establecen corruptos y advierten en la salida humana. Los ajustes incorrectos se detienen antes de que se lea el uso. Estas lecturas no son una instantánea atómica. Cada GET tiene una fecha límite de búsqueda/cuerpo de 10 segundos después del descubrimiento y un límite de respuesta de 32 MiB; esta no es una fecha límite de comando completo. Las señales salen 130/143 sin resultados tardíos. + + + +### Siga las ventanas de solicitud o secuencias de inyección + +```bash +ocx logs --help +ocx logs --limit 200 --json +ocx logs --follow --events --limit 200 +``` + +`--events` requiere seguir e implica JSONL; se acepta la redundancia `--jsonl`. `--json` sigue siendo de un solo disparo y entra en conflicto con los siguientes / eventos. Cada línea events-v1 es `{schemaVersion:1,type:"snapshot"|"append",rows,cursor,limit}`. Reemplace la ventana del consumidor en la instantánea, agregue/recortar en el agregado, preservando el orden y los ID repetidos. Se emiten instantáneas iniciales vacías y de reinicio/eliminación; las encuestas vacías estables permanecen en silencio. Las matrices heredadas son instantáneas con cursor nulo, no con cursores inventados. Estas son ventanas observadas, no una repetición sin pérdidas del tráfico que se pierde entre las urnas o después del desalojo del anillo. + +`ocx logs --follow --jsonl --limit 200` conserva la salida en forma de fila. Vuelve a emitir eventos modificados, incluyendo el mismo estado de ID / enmiendas de token y ID repetidos. No colapse todo por ID de solicitud. Esta salida heredada no puede codificar eliminaciones, reinicios u orden de ventana exacto; elija eventos cuando esas distinciones importan. El límite de seguimiento de registro es 1-2000, por defecto 200. + +```bash +ocx observe injection --limit 500 --json +ocx observe injection --follow --jsonl --limit 500 +``` + +La inyección emite `{seq,at,line}` filas ordenadas, donde `at` es milisegundos de época; el `after` interno avanza con seq. El límite de seguimiento es 1-2000, por defecto 500. JSON es one-shot y JSONL requiere seguir. La observación no permite la captura. Las encuestas vacías no identifican la captura de desactivados ni prueban la ausencia de brechas. La deriva en entorno de ejecución detectable se detiene; no se pueden excluir intervalos de reinicio/última N indetectables sin un marcador de época/intervalo API. + +Ambos bucles de seguimiento utilizan esperas de un segundo en serie, fechas límite de búsqueda/cuerpo de 10 segundos y límites de respuesta de 32 MiB. Errores de malformado/sobredimensionado/transporte se detienen con stderr y salida 1, sin reintento/reconexión automática. Reducir el límite para ventanas de gran tamaño. SIGINT/Ctrl-C sale 130, SIGTERM 143, sin encuestas/salida posteriores. Inspeccione el estado de salida y las filas retenidas en lugar de tratar la cancelación como un historial completo. + + + +### Línea de tiempo complementaria y uso de key-scoped + +```bash +ocx companion timeline --help +ocx companion timeline --hours 24 --bucket-minutes 60 --metric total --aggregation sum --grouping model --model example/model-a --hide-provider excluded-provider --json +``` + +Reemplace los ID ficticios con los filtros seleccionados. Repita `--model` para los ID de proveedor/modelo individuales (se permiten las barras anidadas; no CSV); repita `--hide-provider` para excluir a los proveedores. Positivo `--provider` no está soportado. Las horas son 6/24/72/168, los minutos del cubo 1-1440 con un máximo de 2000 cubos, métrico total/entrada/salida/caché, suma de agregación/promedio/máx, modelo de agrupación/modelAccount. El API limita las entradas de filtro a 100 elementos. Esto lee el uso sin cambiar la configuración del compañero. + +Compruebe `appliedFilters.models/hiddenProviders`. Los límites de la línea de tiempo son segundos de época, con final exclusivo, a diferencia de la ventana personalizada de milisegundos del uso ordinario. El final debe coincidir con el depósito de tiempo de solicitud, o su sucesor inmediato si la solicitud cruza un límite de depósito; se rechaza una ventana alineada más antigua. Las series vacías retienen los metadatos del bucket/filtro. `missingMeasurements` y `truncated` deben permanecer visibles: los puntos sin relleno no demuestran un uso cero completo. + +En un host de gestión no cliente: + +```bash +ocx access key list --json +ocx usage --api-key-id key-example --range 7d --json +``` + +Utilice un identificador de clave real no secreto. El CLI requiere un acuse de recibo de respuesta exacto en `filter.apiKeyId`; los filtros ignorados fallan en lugar de mostrar totales no explorados. Un ID desconocido reconocido puede devolver `matched:false` y vaciar el tráfico, no 404. Mantenga los datos incompletos/de ventana personalizada. Los clientes conectados rechazan `--api-key-id` antes del acceso o transporte de clave inscrita; lo omiten para el uso de Hub auto-solamente existente o realizan la vista de clave seleccionada en el Hub. Ninguna autoridad de gestión de concesiones de claves de datos. + +### `ocx debug ` + +Lea o cambie las anulaciones de depuración en entorno de ejecución a través de la administración del proxy en ejecución API. + +```bash +ocx debug provider on|off|status|reset +ocx debug provider logs [-f|--follow] +ocx debug usage on|off|status|reset +ocx debug usage logs [-f|--follow] +``` + +Sin alcance, `ocx debug` imprime el uso y, cuando se detiene el proxy, el entorno de siguiente inicio predeterminado. Depuración de proveedores por defecto desde `OCX_DEBUG=1` (también funciona el legado `OCX_DEBUG_FRAMES=1`); depuración de uso por defecto desde `OPENCODEX_USAGE_DEBUG=1`. + + + +## Acceso API + +### `ocx access ...` + +Inspeccione las claves de admisión, los puntos finales externos y los modelos con la familia de acceso. `ocx api-key` alias la familia de claves de acceso. La creación y el inicio de rotación devuelven una credencial de texto sin formato de una sola vez en el texto y la salida JSON. Los agentes deben dejar esos pasos a un terminal operado por humanos fuera de la sesión de agente; solicite solo confirmación y claves no secretas / ID de rotación, nunca la credencial. + +```bash +ocx access key list --json +``` + +Después de que el humano configure y verifique el reemplazo, realizar su rotación o eliminar la clave antigua requiere una autoridad de revocación explícita separada. Los seguimientos no secretos seguros son `ocx access key rotate commit --json` y `ocx access key rotate abort --json`, con autoridad para la acción elegida. Volver a la lista después. El estado pendiente ausente por sí solo no prueba la confirmación: la expiración o el aborto también pueden borrarlo. No envíe el consentimiento emitiendo directamente la solicitud de gestión de devolución secreta. + + + +### Cambiar el nombre de una clave sin cambiar su política de acceso + +```bash +ocx access key rename key-example 'Research client' --json +ocx access key list --json +``` + +Utilice un ID único real o un nombre inequívoco. Renombrar envía solo `{id,name}` y conserva los alcances del proveedor/modelo; no rota/elimina una clave. La respuesta contiene id/name/createdAt y allowedProviders / allowedModels opcional, nunca texto sin formato o un prefijo. La lista sigue enmascarada. Los nombres están libres de control, recortados, no vacíos y como máximo 64 unidades de cadena JavaScript. La secuencia de lectura/cambio de nombre no es CAS; inspeccione la lista enmascarada después de un resultado desconocido antes de volver a intentarlo. El alias raíz `api-key rename` utiliza el mismo comando. + + + +### Modelo de clave explícita y comprobaciones de audio + +Descubre la sintaxis instalada sin contactar con upstream: + +```bash +ocx access test --help +ocx access audio transcribe --help +ocx access audio live-check --help +``` + +Las solicitudes de modelos, las cargas de audio y las verificaciones de sesiones en vivo requieren una autorización explícita del operador para esa operación ascendente en particular y una posible cuota/costo. El operador suministra la clave seleccionada desde una fuente privada aprobada en un terminal operado por humanos fuera de la sesión de agente. Los agentes no deben capturarlo o pedirlo en el chat. Nunca lo ponga en argv / medio ambiente. Estos son el lado ocx de esa tubería privada, no las indicaciones de teclas interactivas directas o un lote de agente: + +```bash +ocx access test example/model --protocol responses --api-key-stdin --json +ocx access audio transcribe sample.wav --model gpt-4o-mini-transcribe --api-key-stdin --json +ocx access audio live-check --model gpt-live-1-codex --api-key-stdin --json +``` + +Elija solo la tarea autorizada y el modelo/archivo real. Se rechaza la entrada TTY. La entrada está limitada a 4096 bytes/30 segundos, ASCII imprimible UTF-8 válido, sin espacios en blanco externos, controles o líneas adicionales; se permite un LF/CRLF final. Esto cubre deliberadamente las claves emitidas actualmente, no todos los valores Unicode que la configuración del servidor podría aceptar. Las ocurrencias exactas de la clave suministrada en el texto permitido se convierten en `[redacted]`; las codificaciones arbitrarias no se garantizan detectadas. No se imprime ningún portador de claves codificado. + +Los objetivos son el origen de servicio local comprobado o el origen de concentrador inscrito normalizado existente, con la identidad comprobada alrededor del trabajo asíncrono. No hay un origen personalizado, administración o reserva de clave inscrita, seguimiento de redireccionamiento, caché de credenciales o reintento automático. El operador solo informa al agente sobre el resultado no secreto. + + + +#### Control del modelo y límites de respuesta + +Los protocolos son chat (predeterminado), respuestas o mensajes. El modo de clave seleccionada primero envía un control mal formado sin credenciales: JSON a ese punto final. Solo la clave nativa requerida 401 avanza a una solicitud de modelo de 16 tokens fija usando la clave suministrada. El control tiene un presupuesto de respuesta de 5 segundos/4096 bytes; la solicitud tiene un presupuesto de respuesta de 60 segundos/2 MiB que incluye lecturas del cuerpo. Los controles sin autorización/no reconocidos se detienen antes de la inferencia. La contabilidad de registro/admisión local puede seguir ocurriendo. + +JSON es `{schemaVersion:1,control:{outcome,status?},request:{outcome,status?},response?}`. La respuesta segura contiene el protocolo, el texto ordenado, la finalización completa/limitada y los recuentos de tokens medidos opcionales. Una respuesta de longitud limitada utilizable es `limited`; las respuestas de rechazo / filtro de contenido / herramienta o mal formadas no son compatibles, incluso con HTTP 2xx. Los metadatos de error, ID, herramientas y razonamiento no se imprimen. El fallo operativo retiene un informe versionado más stderr/salida 1 fijo; salidas de entrada de gramática/clave no válidas 2 sin un informe fabricado. + +El éxito solo dice: "La solicitud sin credenciales fue rechazada; la solicitud del modelo que usa la clave suministrada tuvo éxito". Los cambios de política del oyente entre las llamadas siguen siendo posibles; esto no certifica el alcance de la clave, la admisión atómica o la identidad de facturación. Sin `--api-key-stdin`, la prueba heredada JSON sigue siendo su carga útil original y no dice nada sobre una clave recién seleccionada. + + + +#### Transcripción y preparación en vivo + +La transcripción requiere un archivo regular no vacío de hasta 25.000.000 bytes, con un límite de lectura local de 30 segundos y un cuerpo multipart de hasta 32 MiB. Admite `gpt-4o-transcribe`, `gpt-4o-mini-transcribe` o `whisper-1`, según el destino. La carga y la respuesta comparten un único límite de 130 segundos; la respuesta no puede superar 2 MiB. Si tiene éxito, devuelve solo `{text}`, incluso si está vacío, y oculta la clave exacta. Si falla, deja stdout vacío, escribe un diagnóstico fijo en stderr y termina con un código distinto de cero; no devuelve un objeto JSON de error ni el cuerpo sin procesar. + +El audio utiliza la admisión de clave explícita sin el control del modelo. La verificación en vivo envía solo session.update y session.close fijas. La preparación requiere session.started o session.updated con ID de sesión nativa no en blanco en 15 segundos; el socket abierto o session.created solo es insuficiente. Después de la preparación, espera como máximo 2 segundos para el cierre normal del código-1000. Cada cuadro UTF-8 tiene un límite de 64 KiB, suma 2 MiB; no hay un historial de cuadros retenidos. + +En vivo JSON es `{schemaVersion:1,ready,close:"confirmed"|"unverified",check:"session-readiness",event?}`. El fallo operacional preserva esa observación sin marcos en bruto. Disposición parcial con salidas cerradas no verificadas 1; un cierre normal posterior no puede borrar un error anterior. Salida de señales 130/143. Esto comprueba la disponibilidad/cierre solamente, no el micrófono, la carga, la ejecución de la herramienta, la liberación de ida y vuelta de voz completa o el arrendamiento del servidor. La apertura de la sesión previa no está garantizada gratis. Ninguna reconexión o reintento es automático. + +### `ocx api ...` + +Inspeccione y establezca cómo viajan las solicitudes entre las API del cliente y los cables del proveedor. Vea [Rutas de protocolo](/es/guides/protocol-paths/) para el vocabulario. + +| Comando | Ruta | Cambia el estado | +| --- | --- | --- | +| `ocx api protocols [--provider ] [--json]` | `GET /api/protocols` | No | +| `ocx api explain --model --inbound [--feature ]... [--json]` | `POST /api/protocols/plan` | No | +| `ocx api policy [--json]` | `GET /api/protocols` | No | +| `ocx api policy [--messages ] [--unrepresentable ] [--rollout =]... [--json]` | `PATCH /api/protocols/settings` | Sí | + +- `protocols` imprime la versión del contrato, si cada cliente API está atendido y por qué, la política no representable, cada interruptor de implementación y la revisión de la política. `--provider` agrega el cable ascendente que recibe el proveedor, quién lo decidió y los modelos en otro cable. +- `explain` previsualiza la ruta que tomaría un modelo de un cliente API. `--feature` es repetible y acepta una lista separada por comas; `ocx api protocols --json` enumera las claves de características conocidas. La vista previa se calcula a partir de la configuración: no se envía nada aguas arriba, no se avanza en la rotación combinada y la entrada no se registra. +- `policy` sin una bandera de configuración solo se lee. Con uno, envía un solo cambio al proxy en ejecución, que lo valida, guarda la configuración y responde con la nueva política. `--messages off` también desactiva la integración Claude, como lo hace el conmutador del tablero de instrumentos. Los nombres y las combinaciones de conmutación son validados por el proxy; por ejemplo, se rechaza `--rollout managedMessagesNativeOAuth=on` a menos que `managedMessagesNative` ya esté activado o activado en el mismo commando. + +```bash +ocx api explain --model combo/main --inbound chat --feature request.seed,request.tools +ocx api policy --rollout shadowPlan=on +``` + +Los errores de uso salen 2 antes de que se envíe cualquier solicitud. `--json` imprime el cuerpo de gestión API tal cual. + + + +## Integraciones de clientes + + + +### Comandos básicos de integración + +| Comando | Medidas adoptadas | +| --- | --- | +| `ocx integration client status [--client ] [--profile ] [--json]` | Lea todas las integraciones de archivos administrados, un cliente o perfiles de Aside. `show` y `list` alias `status`. | +| `ocx integration client history [--client ] [--profile ] [--json]` | Lea las operaciones de reversión y la disponibilidad de instantáneas. `journal` alias `history`. | +| `ocx integration client enable --client [--profile ] [--overwrite-conflict] [--json]` | Aplicar la integración de archivos administrados. Sobrescribir un bloque en conflicto requiere la bandera explícita. | +| `ocx integration client disable --client [--profile ] [--json]` | Elimine la integración administrada seleccionada a través de su propietario de tiempo de ejecución. | +| `ocx integration client restore --op [--client aside --profile ] [--confirm-drift] [--json]` | Restaurar una operación registrada; reemplazar ediciones posteriores requiere confirmación explícita de deriva. | +| `ocx integration native [list] [--json]` | Leer estado de integración nativa. | +| `ocx integration native [--json]` | Escriba la configuración del cliente nativo seleccionado a través de su propietario en tiempo de ejecución. | + +Estos comandos requieren un proxy en ejecución. `--profile` selecciona un ID de cuenta de Aside no negativo y requiere `--client aside`; perfiles omitidos seleccionan el agregado para lecturas y todos los perfiles para habilitación/desactivación sin atar. Conmutaciones nativas cambian la configuración del cliente; Cursor tiene comandos de inspección de solo lectura separados a continuación. Para obtener una vista previa y opciones de escritura limitada, continúe con las recetas a continuación. + + + +### Vista previa y recuperación de integraciones de archivos administrados + +```bash +ocx integration client preview --client hermes --operation apply --json +ocx integration client restore --op op-example --preview --json +``` + +`op-example` es ficticio; use una identificación de la historia. Las operaciones de vista previa se aplican, sobrescriben y desactivan; la restauración utiliza `--preview` en su comando existente. Revise los cambios estructurales y `canApply` / `willChange`; rechazo válido / salidas no opcionales 0 sin aplicar. Habilitar/deshabilitar/restaurar acepta la opción `--plan-fingerprint` para un compromiso vinculado explícito. Direct escrituras de legado permanecen disponibles. Para previsualizar o escribir vinculado se requiere `--client aside --profile N`. La confirmación de deriva y la sobreescritura nunca son automáticas; las salidas de enlace obsoletas 5 con stdout vacío y una instrucción de revisualización en stderr. Siga el [recetas completas de vista previa/compromiso y deriva](/es/guides/integrations/#preview-and-bind-a-terminal-write). + +Droid aplica/sobrescribe los soportes repetidos `--reasoning-default MODEL=EFFORT` para el reemplazo completo del mapa, o el exclusivo `--clear-reasoning-defaults` para `{}`. La omisión preserva el mapa. Repita el mapa exacto en vista previa y confirmación; ver [Droid valores predeterminados](/es/guides/integrations/#factory-droid). + +La eliminación de historial es irreversible y requiere un opId exacto más `--yes`: `ocx integration client history remove --op op-example --yes --json` aborda la revista global. Sólo `--client aside` y opcional `--profile N` proporcionan alcances de eliminación más estrechos. La última fila está protegida. `snapshotRemoved:false` sale 1 después de la jubilación con la limpieza incompleta; no vuelva a intentar la eliminación o la reversión de la reclamación. + +`ocx integration client sync --client aside --json` actualiza los perfiles elegibles a través del propietario certificado, sin selector de perfil o reserva local. El vacío `results` es una observación exitosa de perfiles no elegibles; una fila fallida hace que el agregado sea distinto de cero mientras conserva otros éxitos. Lea los hechos de estado y recuperación antes de volver a intentarlo; [Los controles de Aside](/es/guides/integrations/#aside-profile-controls) explican la intención del perfil versus el estado del archivo. + + + +### Inspeccione Cursor sin instalarlo + +```bash +ocx integration native cursor status --json +ocx integration native cursor local-installer --json +``` + +El estado puede recopilar el inventario del modelo; la búsqueda del instalador puede obtener un manifiesto público. No se descargan/instalan ni cambian el Cursor. El estado distingue la credencial del modo de puerta de enlace de marcador de posición; el marcador de posición no es una credencial de acceso. El instalador `{available:false,url:null,version:null,reason:null}` es válido, incluso cuando Private Inference ya está instalado. Una lectura no disponible válida sale de 0. + +### `ocx integration ...` + +Administre las integraciones Claude y Grok compatibles. Las familias de comandos directos a continuación exponen sus controles específicos del cliente. + +### `ocx claude [claude args...]` + +Asegúrese de que el proxy se está ejecutando, luego inicie Claude Code con `ANTHROPIC_BASE_URL`, `ANTHROPIC_AUTH_TOKEN`, `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1` y las ranuras del modelo de `config.claudeCode`. Los modelos encaminados aparecen en el selector nativo `/model` a través de alias de ranura estables con Claude Code 2.1.129 o más reciente. En versiones anteriores, seleccione con `ANTHROPIC_MODEL` o `/model `. Las variables `ANTHROPIC_*` exportadas por el usuario siempre tienen prioridad. + +Los comandos de perfil Claude Desktop son: + +```text +ocx claude desktop [apply] Save and apply the four-family profile +ocx claude desktop show [--json] Show routes, families, and defaults +ocx claude desktop status [--json] Show applied state, drift, and health +ocx claude desktop move [--default] +ocx claude desktop default +ocx claude desktop export Export versioned JSON (`-` = stdout) +ocx claude desktop import [--apply] Validate and import JSON +``` + +Las familias son `opus`, `fable`, `sonnet`, y `haiku`; nuevas rutas comienzan en `opus`. `none` es válido Sólo cuando la familia está vacía. Legado aplicar banderas `--static`, `--hybrid`, y `--discovery-only` +seguir siendo apoyados. Uso `ocx claude config ...` para la configuración de Claude Code. + + + +#### Leer o guardar el perfil de escritorio del entorno de ejecución seleccionado + +Los comandos show/import existentes son locales. La familia `profile` se dirige al entorno de ejecución de la administración en ejecución y puede recopilar el inventario del modelo: + +```bash +ocx claude desktop profile show --json > desktop-observed.json +jq '.profile' desktop-observed.json > desktop-profile.json +``` + +Editar/revisar el perfil versionado, preservando los marcadores aplicados propiedad del servidor. Para un guardado autorizado, lea de nuevo: + +```bash +ocx claude desktop profile import desktop-profile.json --json +ocx claude desktop profile show --json +``` + +Import acepta el perfil en sí, no la respuesta externa `{profile,models,rendered,port}`, utilizando archivos JSON regulares limitados o stdin explícito `-` (4 MiB / 30 segundos). Devuelve esos campos observados más `ok:true`, es decir, guardados solo. `--apply` y se rechazan las banderas en modo nativo; la función de guardado en entorno de ejecución no tiene respaldo local. Apply es una acción de escritorio existente separada en su máquina, así que verifique el host/contexto antes de elegirlo. Los modelos renderizados no son prueba de aplicación nativa. + +### `ocx opencode [opencode args...]` + +Asegúrese de que el proxy se está ejecutando, después inicia OpenCode con los bloques `provider.opencodex` y `providers.opencodex` generados en la capa de entorno de ejecución en línea de OpenCode (`OPENCODE_CONFIG_CONTENT`). El bloque heredado mantiene a los clientes V1 trabajando con mapas variantes; el bloque V2 lleva matrices nativas para las mismas opciones de esfuerzo de razonamiento y valores predeterminados. La configuración en línea existente se conserva y solo se reemplazan esas dos claves para este lanzamiento. Los archivos globales o de proyecto `opencode.json` se pueden leer para advertir sobre una anulación existente, pero los archivos en el disco nunca se modifican. Los modelos enrutados aparecen como `opencodex//`. El lanzamiento del plain `opencode` más tarde se comporta exactamente como antes. + +### `ocx grok ...` + +Administre y aplique la valla modelo Grok Build. + + + +## Exportación de configuración de cliente + +### `ocx export --client ` + +Imprima una configuración de cliente conectada al proxy en ejecución. El comando serializa el bloque del proveedor `opencodex` (URL base, lista de modelos y el marcador de posición de referencia de credenciales o loopback del cliente) en el formato nativo del cliente seleccionado. + +El proxy debe estar ejecutándose; el comando resuelve su puerto activo, lee `/api/models` y emite solo los modelos Codex que puede ver actualmente. + +Las exportaciones de OpenCode y Kilo preservan los límites efectivos del modelo, las capacidades conocidas, las opciones de razonamiento declaradas y los valores predeterminados, incluidos los metadatos heredados por las filas personalizadas. Las anulaciones explícitas aún ganan; no se inventan capacidades desconocidas y valores predeterminados. El lanzador de OpenCode utiliza los mismos metadatos. Consulte [Integraciones de clientes](/es/guides/integrations/) para conocer el comportamiento de actualización y actualización administrados. + +| Bandera | Medidas adoptadas | +| --- | --- | +| `--client ` | Requerido. Selecciona el dialecto de configuración del cliente. | +| `--json` | Imprima el documento generado como JSON en stdout para scripts. Esto es JSON incluso cuando el formato nativo del cliente seleccionado es YAML, TOML o JSON5. | +| `--out ` | Escriba el formato de configuración nativo del cliente en ``. Se niega a reemplazar un archivo existente. | +| `--force` | Permite que `--out` reemplace un archivo existente. | + +```bash +ocx export --client opencode # config plus destination, merge warning, and counts +ocx export --client pi --json > pi-models.json # JSON document for a pipe or a diff +ocx export --client omp --out ./omp-models.yml # native OMP YAML +ocx export --client opencode --out ~/opencodex-opencode.json +``` + +Sin `--json`, la configuración generada conduce, luego la ruta de destino canónica, la advertencia de fusión, la línea de exportación env donde el cliente tiene uno y un recuento de modelos con cuántas filas omite los límites de contexto (el cliente aplica sus propios valores predeterminados para esos). + +| Cliente | Destino canónico | Descargar nombre de archivo | Env var | +| --- | --- | --- | --- | +| `opencode` | `~/.config/opencode/opencode.json` (`XDG_CONFIG_HOME` gana cuando se establece) | `opencode.json` | `OPENCODEX_OPENCODE_API_KEY` | +| `pi` | `~/.pi/agent/models.json` (`PI_CODING_AGENT_DIR` gana cuando se establece; se rechaza un valor relativo) | `pi-models.json` | ninguno - el bloque lleva el literal `opencodex-loopback` | +| `omp` | `~/.omp/agent/models.yml` (`OMP_PROFILE` gana sobre `PI_PROFILE`, incluso cuando está vacío; los perfiles con nombre usan el nombre de directorio `PI_CONFIG_DIR` relativo a la casa e ignoran `PI_CODING_AGENT_DIR`, mientras que el perfil predeterminado permite que `PI_CODING_AGENT_DIR` gane) | `omp-models.yaml` | Ninguno - Loopback placeholder | +| `hermes` | `~/.hermes/config.yaml` | `hermes-config.yaml` | `OPENCODEX_HERMES_API_KEY` | +| `openclaw` | `~/.openclaw/openclaw.json` | `openclaw.json5` | `OPENCODEX_OPENCLAW_API_KEY` | +| `kimi` | `~/.kimi-code/config.toml` | `kimi-config.toml` | Ninguno - Loopback placeholder | +| `gajae` | `~/.gjc/agent/models.yml` | `gajae-models.yaml` | marcador de posición de bucle de retroceso no secreto | +| `dsh` | `$DSH_HOME/settings.yaml` (por defecto `~/.dsh/settings.yaml` ) | `settings.yaml` | ninguno - marcador de posición de portador de bucle de retorno no secreto | +| `mcode` | `~/.minimax/config.yaml` (`MINIMAX_DATA_DIR`, luego el legado `MAVIS_DATA_DIR`, gana cuando se establece; se rechaza un valor relativo) | `mcode-config.yaml` | Ninguno - Loopback placeholder | +| `zcode` | `~/.zcode/v2/config.json` (`dataBaseDir` en la página de inicio predeterminada `setting.json` reubica la raíz; `ZCODE_DATA_DIR` gana cuando se establece; se rechazan los valores relativos) | `config.json` | Ninguno - Loopback placeholder | +| `prime` | `~/.prime/agent/models.json` (`PRIME_AGENT_CODING_AGENT_DIR` gana cuando se establece; se rechaza un valor relativo) | `prime-models.json` | Ninguno - Loopback placeholder | +| `aside` | `~/.aside/u//models.json` para la cuenta de Aside `accounts.json` nombres como actual; un manifiesto ilegible se rechaza en lugar de por defecto a una cuenta | `aside-models.json` | Ninguno - Loopback placeholder | +| `raycast` | `~/.config/raycast/ai/providers.yaml` en macOS y Windows por igual (Raycast no honra `XDG_CONFIG_HOME`) | `raycast-providers.yaml` | ninguno - solo loopback, no se escribe ninguna entrada `api_keys` | +| `omo` | `~/.omo/agent/models.json` (`OMO_CODING_AGENT_DIR`, luego `SENPI_CODING_AGENT_DIR`, luego `PI_CODING_AGENT_DIR` gana en ese orden cuando se establece; se rechaza un valor relativo) | `omo-models.json` | Ninguno - Loopback placeholder | +| `kilo` | primero existente `kilo.jsonc`, `kilo.json`, `opencode.jsonc`, `opencode.json`, o `config.json` bajo `~/.config/kilo` (`XDG_CONFIG_HOME` reubica ese directorio); utiliza `kilo.jsonc` cuando no existe ninguno | `kilo.jsonc` | `OPENCODEX_KILO_API_KEY` | +| `commandcode` | `~/.commandcode/providers.json` (en Windows con el inicio predeterminado: usar `HOME ?? USERPROFILE` solo si no está en blanco y Windows-absoluto, de lo contrario `homedir()`; se conserva una vivienda suministrada por separado; adjuntar `.commandcode\providers.json`) | `providers.json` | solo loopback; `apiKey: false`; no hay variable de entorno | +| `droid` | `~/.factory/settings.json` ( `%USERPROFILE%\.factory\settings.json` en Windows) | `factory-settings.json` | loopback solamente; no hay variable de entorno | + +La exportación DSH administrada requiere DSH 0.1.0-rc.6 o más reciente y solo posee `llm-pi-ai.providers.opencodex`. DSH recarga ese proveedor; el modelo predeterminado del usuario y `deepseek-official` permanecen intactos. Esta exportación es solo loopback y no tiene credenciales reales. La importación de DSH 0.1.7 y más reciente `settings.yaml` una vez en el primer perfil que arranca y luego lo cambia el nombre, por lo que la integración del panel escribe el mismo proveedor en la fila `llm-pi-ai` del perfil de escritorio `$DSH_HOME/profiles/desktop/cordis.patch.yml` una vez que existe ese perfil. + +OpenCode interpola `{env:OPENCODEX_OPENCODE_API_KEY}`. Las exportaciones de Pi y OMP generadas no requieren una variable de entorno: cada una lleva el marcador de posición literal `opencodex-loopback`. Esto es soportante porque ambos clientes resuelven `apiKey` mientras construyen sus listas de modelos y ocultan a todo el proveedor cuando una configuración existente contiene una referencia env no establecida. El proxy nunca comprueba el marcador de posición generado en loopback. OMP admite encabezados a nivel de proveedor, pero esta integración inicial permanece deliberadamente solo en bucle; se aplaza el cableado remoto `x-opencodex-api-key`. + +La exportación de Raycast es un documento independiente `providers.yaml` con un elemento `id: opencodex` en la secuencia `providers`: `name: OpenCodex`, el proxy `/v1` URL base, y cada modelo encaminado con su `abilities` (`tools` y `system_message` siempre soportado, `vision` de las modalidades de entrada del catálogo, `reasoning_effort` cuando el modelo tiene una escalera de esfuerzo, `temperature` para los modelos de razonamiento). Custom Providers es una función de Raycast Pro, y Raycast observa el archivo, por lo que un cambio guardado entra en vigencia sin reiniciarlo. El formato está documentado en [manual.raycast.com/ai/proveedores personalizados](https://manual.raycast.com/ai/custom-providers). No se escribe la entrada `api_keys`, por lo que esta exportación es solo loopback y se rechaza un enlace que no sea loopback. + +Las exportaciones de MCode, ZCode y Prime son solo loop-back por la misma razón y también llevan el marcador de posición `opencodex-loopback` en lugar de una credencial real. El agente principal lee el mismo contrato de `models.json` que Pi, por lo que las dos exportaciones producen el mismo documento; solo el destino difiere. Se rechaza una ruta relativa en cualquiera de esas tres anulaciones de entorno, porque el proxy y el cliente pueden tener directorios de trabajo diferentes y de lo contrario no estarían de acuerdo sobre qué archivo se quiere decir. + +ZCode 3.8.1 puede guardar los metadatos de contexto por defecto y derivados del entorno de ejecución `reasoning`, `limit.output` en las entradas generadas `provider.opencodex.models`. El estado de integración administrado trata solo aquellas adiciones documentadas como deriva actualizable. La identidad del proveedor y la configuración de conexión, incluyendo `options.baseURL`, la membresía del modelo, los nombres, las modalidades y cualquier límite de contexto OpenCodex emitido con autoridad permanecen protegidos; editándolos informa `conflict / foreign-edit` en lugar de sobrescribir el archivo. Un registro de propiedad creado por una versión anterior de OpenCodex puede recuperarse automáticamente cuando el catálogo generado no cambia. Si tanto el catálogo como el bloque cambiaron, vuelva a aplicar solo después de revisar el archivo porque el registro anterior no puede probar qué cambio fue derivado de ZCode. + +:::caution[Combina la configuración; no la reemplaces] +`ocx export` nunca escribe su configuración de cliente real. El destino está impreso para que usted se fusione con mano, y `--out` se niega a sobrescribir un archivo existente sin `--force`, porque reemplazando a config destruye los otros proveedores, agentes y entradas MCP que ya están en él. +::: + +Ninguna llave se serializa nunca. Los Configs llevan una referencia de entorno documentada o un marcador de posición de bucle de retroceso no secreto. Una dirección de loopback (`127.0.0.1`) sola no establece la admisión sin llave: compruebe la política de destino y el punto final. Los comandos de modelo/audio de clave seleccionada aún requieren una entrada de clave explícita en loopback. Establezca una variable referenciada solo cuando el esquema del cliente la admita y el proxy se vincule más allá del bucle de retorno; consulte [Acceso remoto](/es/reference/configuration/server/#remote-access) para conocer cómo se emiten las claves de admisión. Las claves para los propios proveedores ascendentes son una cosa completamente separada, configuradas por [Proveedores](/es/guides/providers/). La integración gjc generada utiliza un marcador de posición de bucle de retroceso no secreto y no necesita ninguna variable de entorno. Sigue siendo solo loopback; no configura las credenciales de admisión remotas. + +La misma carga útil es servida por `GET /api/client-config` y renderizada en la pestaña API del tablero de instrumentos, por lo que el CLI, el API y la GUI usan los mismos bytes. + + + +## Tiempo de ejecución y configuración + +### `ocx system ...` + +Gestione la configuración, el inicio, la sincronización, los diagnósticos y las actualizaciones en entorno de ejecución sin cabeza. + +`ocx system codex-restart --yes` reinicia Codex servidores de aplicaciones a través del mismo módulo que `ocx sync --restart-codex`. Se cierra y vuelve a lanzar la aplicación de escritorio Codex cuando la aplicación se lanzó antes de que se escribiera el catálogo de modelos actual o esta solicitud cambió su vinculación `model_catalog_json`, porque el selector de modelos se creó en el lanzamiento. De lo contrario, la aplicación permanece abierta, reaparece su propio servidor de aplicaciones y mantiene los borradores no guardados y las aprobaciones pendientes. Si no se puede leer el estado de la aplicación o del catálogo, se reinicia por completo. Cuando el proxy se está ejecutando dentro de la aplicación Codex, el reinicio del escritorio se niega con un mensaje procesable en lugar de prometer un traspaso que no puede completar. + +Un enlace `model_catalog_json` modificado por esta solicitud también fuerza el reinicio del escritorio, incluso cuando el shell se inició después de que se escribió el archivo de catálogo. + +```bash +ocx system settings --stream-mode eager-relay +``` + +Otros booleanos del sistema toman encendido/apagado: `--show-codex-credits`, `--account-picker`, `--main-account-hard-lock`, `--ultra-fast-tier` y `--fast-rows`. Escriben solo campos explícitos y pueden combinarse con las opciones del sistema existentes. Mostrar créditos es una preferencia de visualización, no una opción de crédito pagado; el sistema Ultra Fast está separado del proveedor Fast. + +Ultra Fast es una configuración opt-in, por defecto desactivado. Con `--ultra-fast-tier on`, el catálogo generado agrega la opción de velocidad ultrarrápida a `gpt-6-astra` y `gpt-6.1-sol` nativos (incluidas las filas vinculadas a la cuenta), por lo que el selector Codex lo ofrece junto a Fast. Ultrafast requiere un plan ChatGPT elegible; el catálogo no puede verificar eso, así que active la configuración solo si su plan lo incluye. Otros modelos y la velocidad predeterminada no se modifican. + +Para los modelos enrutados, la convergencia de sincronización y catálogo retiene las entradas `ultrafast` suministradas por el operador de una fila enrutada existente en `service_tiers` y `additional_speed_tiers` junto con su capacidad Fast actual. Las declaraciones pertenecen a la pieza exacta del proveedor/modelo; no se copian a otros modelos. La configuración no crea declaraciones faltantes ni restaura modelos eliminados. Apagarlo elimina Ultra Fast de las filas enrutadas ordinarias y la opción nativa generada en la siguiente regeneración del catálogo. + +El modo Fast del proxy decide lo que llega al backend: cuando no está configurado, una solicitud Ultrafast seleccionada se reenvía como `service_tier: "ultrafast"`; `fastMode: true` reemplaza cualquier nivel con Fast (`priority`), y `fastMode: false` elimina el nivel. Deje el modo Rápido sin configurar para usar Ultrarápido. + +```bash +ocx system settings --json +ocx system settings --show-codex-credits on --json +ocx system settings --json +``` + +Nueva opción escribe informe `{ok:true, settings: observedFields, catalogRefreshPending}`. Ultra Fast realiza la lectura GET del mismo objetivo porque PUT omite ese valor. Una observación faltante/incompatible/leída permanece `verification:"unverified"` con `unverifiedFields` y una salida distinta de cero después de la aceptación; los valores solicitados nunca se sustituyen por observaciones. Los switches de escritorio combinados conservan datos almacenados/efectivos y los aplican. El catálogo pendiente o la aplicación nativa diferida/rechazada es distinta de una configuración guardada. Falsa pendiente no es prueba de que cada cliente ha recargado. + +`ocx system update` actualiza el propio OpenCodex. La superficie de inspección separada Codex CLI es: + +```bash +ocx system codex-cli-update check --json +``` + +`check` no realiza ninguna solicitud de registro de paquetes e inspecciona la evidencia de procedencia de candidatos configurados limitada, incluida una evidencia de ubicación y propiedad ejecutable redactada. El contexto de lanzador publicado de confianza autentica la instantánea candidata, no la ejecución exitosa de Codex. En POSIX, la selección se certifica solo cuando el solucionador en entorno de ejecución selecciona el mismo candidato de entorno canónico sin ejecutarlo. Un manifiesto vinculado npm-global puede establecer `managed: true` cuando prueba la propiedad y, si se informa de una versión candidata, esa versión coincide con el manifiesto; los candidatos persistentes permanecen sin certificar. El informe JSON expone `candidateAvailable`, `candidateVersion`, `candidateSource` y `selectionAttested`. Inspeccionar el candidato configurado requiere un contexto de lanzador publicado de confianza; un lanzamiento Bun /source directo no tiene tal prueba, ignora el estado del candidato ambiental y persistente, y puede informar `candidate_unavailable` en POSIX. En Windows este primer segmento no realiza ninguna E/S candidata o de sistema de archivos de configuración: solo un candidato de entorno absoluto capturado por prueba puede recibir etiquetas de paquete de aplicaciones o gestor de versiones léxicas; cada otro candidato Windows falla cerrado. Debido a que ese segmento nunca consulta el estado persistente, una ejecución Windows sin informes de candidatos de entorno capturados `windows_inspection_deferred` en lugar de `candidate_unavailable`: el comando no puede observar si está instalado un Codex CLI, por lo que informa el aplazamiento en lugar de afirmar que no existe ningún candidato. El comando no ejecuta Codex o un administrador de paquetes, reparar una shim, escribir configuración o estado de caché, detener un proceso o instalar nada. Los estados de shim independientes, ambiguos y no verificados, reconocidos y agrupados en aplicaciones se informan como no administrados o desconocidos y nunca se clasifican como administrados. + +En Windows, un comando desnudo capturado como `CODEX_CLI_PATH=codex`, una ruta remota o una ruta de dispositivo informa `candidate_path_unavailable` en su lugar. Esos casos tienen un candidato capturado; su trayectoria no es elegible para esta inspección. + + + +#### Plan de actualización de solo lectura Codex CLI + +```bash +ocx system codex-cli-update plan --channel latest --json +``` + +Ejecute a través del lanzador de nodos publicado con el `CODEX_CLI_PATH` previsto en el entorno de shell. El plan requiere una instalación global certificada de POSIX npm y una versión de manifiesto de paquete vinculada. Consulta el registro oficial npm para una versión exacta, integridad SHA-512 y tarball del mismo origen, utilizando el PATH capturado del lanzador y la configuración, caché y registros temporales aislados npm. La configuración del proxy y `NODE_EXTRA_CA_CERTS` siguen siendo compatibles; la limpieza es el mejor esfuerzo. No se ejecuta el comando Codex. + +Un plan aplicable reporta `applicable: true` y una plataforma de enlace determinista `planId`, resumen de la raíz de la instalación, versión instalada, versión / integridad del canal y destino. El plan nunca se mantiene. Rechaza rebajas, versiones ya actuales, Codex sesiones activas y observación de procesos incompletos. Windows devuelve `windows_inspection_deferred` antes de las consultas de registro/proceso. Una denegación sale 0: inspeccionar `applicable` y `refusal`. El argv de instalación impreso es indicativo; este comando no instala nada, no cambia el estado de la aplicación y nunca señala una sesión. No se expone ningún comando apply y un ID de plan no es una autorización de instalación. + + + +#### Observación explícita de la instalación en Windows x64 + +```text +ocx system codex-cli-update attest [--json] +ocx system codex-cli-update attest --candidate --npm-prefix --npm-cli --node [--json] +``` + +`attest` es un opt-in, observación de solo lectura de una instalación Windows x64 npm. Sin opciones, identifica el candidato seleccionado a partir de la instantánea del lanzador de prueba: el `CODEX_CLI_PATH` configurado o el primer `codex` en el PATH capturado, con un envoltorio OpenCodex que resuelve su respaldo `codex.opencodex-real.cmd` npm renombrado. Suministrar los cuatro caminos absolutos anula el descubrimiento; el descubrimiento solo propone caminos y la observación manual sigue siendo la autoridad. `--candidate` debe nombrar el estándar npm `/codex.cmd` o `/node_modules/@openai/codex/bin/codex.js`. `--npm-cli` debe terminar en `node_modules/npm/bin/npm-cli.js`; `--node` nombra un `node.exe` explícito. Los paquetes de aplicaciones, los diseños de administradores de versiones reconocidos, las shims opencodex sin su respaldo npm y los envoltorios personalizados son rechazados. + +Los controladores nativos mantienen los directorios y archivos antecesores durante las lecturas limitadas. Las plataformas no soportadas, los puntos/secciones de análisis, los escritores en conflicto, las rutas inseguras y los archivos de gran tamaño son rechazados. El informe fijo no contiene rutas: `status` es `observed` o `refused`, con `installationIdentityObserved`; `selectionAttested`, `managed` y `applyAllowed` permanecen `false`. Compruebe `status`, no solo el código de salida del proceso: un rechazo informado puede salir 0. + +Una identidad o resumen observado describe esos archivos durante esta observación. No es un permiso de actualización duradero y no prueba el entorno de ejecución seleccionado, el instalador anterior, la configuración efectiva del npm o la autenticidad de la herramienta. El ejecutable Node suministrado solo se observa; no se ha demostrado que sea el que seleccionaría un lanzador. No se ejecuta ningún destino; no se produce ninguna solicitud de registro, instalación, escritura de configuración o control de procesos. El comando existente Windows `check` todavía no realiza ninguna E/S del sistema de archivos candidato/configuración. + +### `ocx config [show|get|set|unset|validate|export|import] ...` + +`ocx config [show] [--json] [--source]` muestra la configuración local sin un proxy en ejecución. Omitir `show` también funciona con cualquiera de las banderas o ambas, en cualquier orden. `--source` incluye campos de fuente de diagnóstico, error y advertencia y solo se acepta para su visualización. `--json` puede preceder a una acción explícita; no cambia qué acción se ejecuta. Se rechazan las banderas `--json` o `--source` repetidas y los argumentos desconocidos. + +Inspeccione y modifique de forma segura la configuración validada del OpenCodex. `show` y `get` secretos de máscaras. Importar valida antes de escribir y requiere `--yes`. + +La visualización y la mutación eliminan las credenciales de las URL proxy al tiempo que retienen el host y el puerto. `direct` y los valores de proxy sin credenciales se mantienen legibles. `export` conserva las credenciales para que la copia de seguridad pueda restaurar la configuración; almacenar los archivos exportados como secretos. + + + +### Uso desde un cliente conectado + +`ocx usage` lee el concentrador conectado con la clave de datos registrada de este cliente. La salida humana identifica la fuente del concentrador y el alcance de la clave del cliente; `--json` devuelve los mismos datos de alcance. Los filtros de rango, superficie, proveedor / modelo y los límites personalizados `--since` / `--until` permanecen disponibles. Los desgloses de cuentas y los registros de otros clientes no se comparten. Un concentrador antiguo o no disponible produce un error explícito en lugar de sustituir el uso local; actualice el concentrador si no admite esta lectura. + +El punto final del plano de datos de solo lectura es `GET /v1/usage`, usando `x-opencodex-api-key` con una clave de cliente configurada. En todo el entorno y las claves de administración son rechazadas. Acepta `range`, `surface`, `provider`, `model`, `since` y `until`; se rechazan las opciones desconocidas / repetidas y los identificadores de clave seleccionados por el llamante. Las filas sobredimensionadas omitidas retienen la advertencia explícita de historial incompleto. + + + +## Explicar una solicitud listada + +La salida `ocx logs` humana incluye `id=`. Pase ese valor a `ocx logs explain ` para inspeccionar las decisiones de enrutamiento. Las filas sin ID o con caracteres de control en su ID omiten el campo en lugar de mostrar una clave de búsqueda diferente. JSON y la salida JSONL conservan su esquema existente. + + + +## Estado de búsqueda del perfil de enrutamiento + +`ocx route policy show ` sale 4 cuando el perfil no existe. Faltan o no son válidos los argumentos de comando. Los scripts pueden distinguir un perfil que falta del uso incorrecto. + + + +## Detalles de error ascendentes + +Cuando una envolvente de error ascendente contiene varios campos de mensaje, OpenCodex usa la primera cadena no en blanco en su orden de prioridad establecido. Los campos vacíos o mal formados ya no ocultan un diagnóstico alternativo válido. + + + +### Modelo de subagente forzado Claude Code + +La página Subagentes ofrece **Forzar un modelo para todos los subagentes**, una opción **desactivada de forma predeterminada**. Selecciona un identificador disponible en la lista, como `combo/tev-auto`, y después activa la opción. Primero se ofrece la lista de modelos; las entradas guardadas que ya no estén disponibles no se pueden usar como destino forzado. + +`ocx agent subagents force combo/tev-auto` conjuntos `claudeCode.subagentModelForce`; `ocx agent subagents force -` lo aclara. `ocx agent status` informa de la configuración. `GET /api/subagent-models` devuelve `force`, `forceAvailable` y `forceStatus`; `PUT` acepta `{ "force": "combo/tev-auto" }` o `{ "force": null }` sin cambiar la lista. Omitir `force` lo deja sin cambios. Los objetivos inválidos o no expuestos son rechazados en la escritura; los objetivos obsoletos son reportados y omitidos en el lanzamiento. + +Esto tiene efecto en el **siguiente inicio enrutado de `ocx claude`**, inyectando `CLAUDE_CODE_SUBAGENT_MODEL` como un alias proxy explícito (con `[1m]` solo para una ventana autorizada de un millón de tokens; los objetivos nativos Claude usan un alias nativo reversible) y `CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1`. Cada variable no vacía exportada por el shell gana independientemente. Los lanzamientos nativos no inyectan ninguna variable; el plano `claude` no se ve afectado. No hay archivos de plugin o `settings.json` se modifican por esta configuración. + +Claude Code **2.1.257 o más reciente** es necesario para la fuerza. Los argumentos de modelo de complemento y agentes incorporados (incluyendo Explorar/Planear) y por llamada se anulan. Las bifurcaciones y las habilidades de subagente con `model: inherit` mantienen el modelo de conversación principal. El bucle principal y los sidecars de pequeño-rápido no se ven afectados. Los archivos de la lista existentes permanecen disponibles. + +El panel de control advierte sobre versiones antiguas o desconocidas de CLI, objetivos no disponibles y cualquiera de las variables ya presentes en `settings.json` → `env` (que anula env de lanzamiento). La detección es de solo lectura y local en el servidor: no puede inspeccionar otro shell de lanzamiento, otra máquina o la configuración local del proyecto. Un resultado desconocido no es prueba de apoyo a la fuerza. diff --git a/docs-site/src/content/docs/es/reference/cli/lifecycle.md b/docs-site/src/content/docs/es/reference/cli/lifecycle.md new file mode 100644 index 00000000000..97013b00971 --- /dev/null +++ b/docs-site/src/content/docs/es/reference/cli/lifecycle.md @@ -0,0 +1,665 @@ +--- +title: "Ciclo de vida CLI" +description: "Comandos de instalación, inicio, parada, servicio, diagnóstico, sincronización y actualización." +--- + +Estos comandos instalan, ejecutan, inspeccionan, reparan y actualizan el proxy local opencodex y su integración Codex. + + + +## Descubre antes de comenzar los servicios + +`ocx help`, `ocx help ` y `ocx help ` están fuera de línea. Utilice `ocx help --all` cuando la raíz compacta es insuficiente. La ayuda, la validación de configuración local y la inspección local de laboratorio no requieren iniciar un proxy. + +Antes de un flujo de trabajo de administración en vivo, ejecute `ocx ready --json` y `ocx status --json`. La preparación distingue `pending`, `failed` y `unreachable`; solo `ready: true` confirma la preparación. Compruebe el objetivo y `versionSkew.relation`: `unknown` no es prueba de versiones coincidentes. Un desajuste de versión requiere resolver la instalación prevista, no intentar repetidamente una bandera más nueva contra un servidor más antiguo. + +Las convenciones de salida y salida son específicas de los comandos. `ready` y `resolve` rechazan argumentos inválidos con 64, mientras que `doctor --json` no está soportado y sale de 2. Una solicitud de guardado local o de reinicio aceptado satisfactoriamente no prueba convergencia; lea el recibo del comando y vuelva a verificar el estado después de la operación solicitada. + +Cuando el descubrimiento de destino en vivo no encuentra proxy, comandos de directiva/catálogo, uso de alcance de clave e informe de sincronización de perfil de Aside: "Proxy no se está ejecutando. Inicie el proxy deseado con: ocx start. No se envió ninguna solicitud." Una solicitud de administración que se envió puede tener un resultado de escritura incierto; leer de nuevo desde el objetivo previsto antes de volver a intentar. Los rechazos de integración de cliente heredados agregan una guía de recuperación fija basada en la razón del rechazo (nunca el propio texto del escritor); los avisos de respaldo y recuperación residual permanecen disponibles. + +`ocx system update run --yes` imprime el ID de trabajo aceptado y el estado del trabajo observado. Síguelo con `ocx system update status `; la aceptación no establece una instalación o reinicio exitosos. `--json` conserva la respuesta completa del servidor. + + + +## Configuración + +### `ocx init` · `ocx setup` + +Asistente de configuración interactiva (`setup` es un alias de `init`). Indica un proveedor (preestablecido o personalizado), una clave API (literal o `${ENV}`), un modelo predeterminado y un puerto proxy; guarda `~/.opencodex/config.json`; opcionalmente inyecta el proxy en `$CODEX_HOME/config.toml` (predeterminado `~/.codex/config.toml`); y opcionalmente instala la shim de inicio automático Codex. + + + +## Ciclo de vida del proxy + +### `ocx start [--port ] [--socks5 [host:port] | --socks5-off]` + +Inicie el servidor proxy (puerto preferido `10100`). Escribe el estado PID / runtime-port y se niega a iniciar una segunda instancia en vivo. Cuando el puerto preferido está ocupado, `start` pregunta al titular quién es y se detiene en cualquier sentido: se niega rotundamente cuando un opencodex responde allí, e informa a un titular no identificado de lo contrario. Nunca mueve al oyente a otro puerto por sí mismo, porque eso dejaría el primer proxy en funcionamiento y volvería a apuntar al Codex en el segundo. Todavía se rechaza un `--port` explícito diferente cuando el proxy en vivo comparte este `OPENCODEX_HOME`, porque tanto la contabilidad de gastos solo observada como forzada escriben el mismo diario. Use un `OPENCODEX_HOME` separado para un hermano independiente; `port: 0` solo pide al sistema operativo el puerto de esa instancia y no separa su estado. Al inicio, sincroniza los modelos de cada proveedor en el catálogo de Codex. Al apagarlo, restaura el Codex nativo, a menos que se haya lanzado como un servicio administrado (`OCX_SERVICE=1`). Un hermano iniciado junto a un proxy en ejecución no hace ninguna de las dos cosas: sirve solicitudes directas solo en su propio puerto, y Codex, Grok y Claude permanecen apuntando al proxy que ya se estaba ejecutando. Con un `OPENCODEX_HOME` separado, el inicio comprueba el registro de entorno de ejecución del hogar predeterminado y administra Grok y Codex destinos de bucle de retorno para un propietario de opencodex en vivo antes de la sincronización. Una casa personalizada sin propietario en vivo todavía se sincroniza normalmente; `ocx sync` y `ocx grok apply` explícitos permanecen disponibles. Detener a ese hermano con `ocx stop` o una señal también deja su configuración sola. Mientras se ejecuta, el proxy también mantiene Codex apuntado a sí mismo: cuando el enrutamiento opencodex en `~/.codex/config.toml` nombra otro puerto local donde no opencodex ha respondido durante aproximadamente 20 segundos (una instancia que lo volvió a apuntar y luego murió, por ejemplo), el proxy vuelve a apuntar Codex en su propio puerto e imprime una advertencia. Codex hilos abiertos mientras tanto, mantenga la dirección muerta hasta que los vuelva a abrir. + +`--socks5` (por defecto `127.0.0.1:10808`) guarda `config.proxy` como una URL de SOCKS5 y las rutas de salida HTTP (S) a través de un túnel real SOCKS5. `--socks5-off` borra solo ese proxy SOCKS5 guardado; no elimina un proxy HTTP. El valor sobrevive `ocx update` porque vive en config, no en el paquete instalado. Se puede incluir un nombre de usuario y una contraseña proxy en la URL, pero los registros de inicio los redactan. + +```bash +ocx start +ocx start --port 8080 +ocx start --port 10100 --socks5 +ocx start --socks5-off +``` + +### `ocx stop [--json]` + +Detenga el proxy en ejecución (por PID), elimine el archivo PID y restaure el Codex nativo. Si se instala un servicio administrado en segundo plano, `ocx stop` también lo detiene primero para que no pueda reaparecer el proxy. Mientras que la aplicación de escritorio OpenCodex se está ejecutando, `ocx stop` no mantiene el proxy abajo: la aplicación lo trata como una salida inesperada y comienza un proxy de nuevo, en cuestión de segundos para uno que comenzó y después de aproximadamente un minuto para uno que sólo había unido. Utilice la bandeja de la aplicación **Detener proxy** (para un proxy que inició la aplicación) o **Salir** para mantenerla detenida. Por la misma razón, el botón **Detener** del panel de control se niega con `desktop_supervised`, y no cambia nada, para un proxy la aplicación comenzó. El botón **Detener** del panel de control web ejecuta la misma acción ( `POST /api/stop` ) en cada backend, excepto en el Programador de tareas Windows. Allí, el contenedor puede volver a enviar el proxy después de que finalice la tarea, y solo una parada que se ejecute fuera del proxy puede verificar que la ventana de reinicio antes de restaurar la configuración del cliente, por lo que el panel de control se niega con `respawnable_service`, no cambia nada y le pide que ejecute `ocx stop`. + +El panel de control también se niega cuando el proxy está ejecutando *como* el servicio launchd o systemd instalado. Detener ese administrador desde el interior del proxy terminaría el proceso antes de que se restaure el Codex nativo, dejando la configuración del cliente apuntando a un proxy que se ha ido, por lo que el panel de control devuelve `self_unload_service`, no cambia nada y le pide que ejecute `ocx stop`, lo que detiene el servicio desde el exterior y completa la restauración. + +Una salida proxy sola no confirma que la restauración compartida Codex / Grok tuvo éxito. Si la respuesta de parada informa de un fallo, es ilegible o no confirma el modo de desmontaje asignado, el CLI mantiene la restauración con el padre de parada después de las comprobaciones de propiedad y reaparición existentes. No entra en el repliegue forzado para un proceso que ya se ha observado que ha salido. Un aplazamiento respaldado por recibos aún deja la restauración final y la limpieza de recibos con el padre; el fracaso en restaurar la configuración del cliente compartido mantiene la parada fallida y su recibo pendiente. + +`ocx stop --json` ejecuta exactamente la misma ruta de parada e imprime un documento de resumen versionado (`schema: "ocx-stop/1"`) en stdout, mientras que las líneas de progreso humano se mueven a stderr. El resumen lleva la clase de resultado (`stopped`, `not-running`, `history-incomplete`, `history-deferred` o `failed`), las clasificaciones de servicio y proxy, si el entorno de ejecución está inactivo y un mensaje de una línea estable. Los códigos de salida son idénticos con y sin `--json`: 0 en caso de éxito, 1 en caso de fracaso, 79 cuando no se completó la limpieza de la historia de Codex y 80 cuando el desmontaje compartido se aplazó y todavía se debe. + +Para una adquisición aprobada por el escritorio, `ocx stop --json` también acepta el conjunto completo de `--expect-*` valores suministrados por `ocx resolve --json`. En Windows, esta parada vigilada puede detener una tarea del Programador de tareas solo cuando su definición registrada, el estado de ejecución y el antepasado de la envoltura demuestren que posee el proxy aprobado. Un servicio WinSW debe probar su ruta binaria instalada y la ascendencia PID del servicio. Después de detener cualquiera de los administradores, el CLI señala el proxy aprobado por separado y verifica que la tarea ya no se esté ejecutando, que no sobreviva ningún envoltorio y que se detenga WinSW. Un proceso `wscript.exe`, `cscript.exe` o `cmd.exe` con una línea de comandos ilegible en la cadena de supervisión del proxy aprobado (o sobrevivir bajo el administrador detenido) deja desconocida la propiedad del envoltorio, por lo que el stop vigilado no puede informar el éxito. La evidencia faltante o ilegible bloquea la parada vigilada. + +### `ocx restart` + +Cuando este CLI es más nuevo que un proxy POSIX independiente certificado, el reinicio puede detener la instalación anterior y ejecutar esta. Esta actualización vigilada requiere un hogar físico no reclamado, un proxy separado cuyo padre es PID 1, supervisión de servicio positivamente inactiva y una versión conocida CLI. Un registro de servicio launchd instalado pero descargado o systemd inactivo solo es elegible cuando no conlleva ningún reclamo de propiedad. Ambos dominios launchd deben estar ausentes; systemd debe informar inactivo con MainPID cero. La evidencia de un gerente ilegible o incierto se niega. El comando congela todos los registros de servicio y la definición de la plataforma y los verifica a través de stop, lanzamiento y publicación secundaria. Cualquier reescritura, reemplazo, cambio de permiso o creación / eliminación de registros se niega; reintente después de inspeccionar `ocx status`. El stop usa la misma conexión que probó la identidad del viejo proxy. El comando se inicia una sola vez después del apagado confirmado, luego requiere el PID hijo exacto, el punto final, la prueba de identidad nueva y la versión coincidente. La versión que falta, la parada incierta, el tiempo de espera o un reemplazo inesperado informa de un fallo sin otra parada o inicio. Si el entorno de ejecución este CLI se lanzaría sigue siendo el pequeño marcador de posición, una instalación npm en el lugar deja antes de su postinstalación, el reinicio se niega antes de detener cualquier cosa; después de una parada confirmada, espera el entorno de ejecución dentro de la misma fecha límite y no lanza nada si no llega. Windows, en primer plano, supervisado por el escritorio, servicio activo, cliente conectado y tiempos de ejecución hermanos no utilizan esta ruta de actualización; utilizar sus controles de ciclo de vida de posesión. Un proxy más nuevo o una versión incomparable aún rechaza una degradación in situ. Utilice el `ocx` de la instalación más reciente para reiniciar; inspeccione `which -a ocx` y `ocx status` para identificarlo. Los rechazos de elegibilidad nombran la razón y la siguiente acción: use el `ocx service restart` de la instalación propietaria para un servicio, el terminal propietario para un proxy en primer plano o la aplicación de servicio / escritorio propietario en Windows. La ascendencia desconocida o un objetivo cambiado requiere `ocx status` antes de cualquier reinicio. + +En un entorno cliente conectado (Remote Link Child o cliente Hub), `ocx restart` pide al propio entorno iniciar su reemplazo en el mismo puerto. Si el reemplazo no responde dentro del plazo, se detiene y el entorno anterior vuelve a ocupar el puerto y sigue atendiendo; el comando informa que el reinicio no se completó. Un entorno cliente administrado por un servicio o la aplicación Desktop rechaza la solicitud y sigue funcionando ("Restart not performed; the running client runtime was kept"); reinícialo con `ocx service restart` o desde la aplicación. Consulta [Paridad de aplicación de Remote Link](#remote-link-apply-parity). + +Si los archivos de paquete o el entorno de ejecución del Bun permanecen incompletos después de que el instalador haya salido o haya fallado, ejecute `ocx status`, detenga cualquier proxy que se ejecute a través de su propietario (`ocx stop`, o su servicio o aplicación de escritorio), luego vuelva a instalar con el mismo administrador de paquetes y vuelva a iniciarlo. Véase [Fallo de actualización](/es/troubleshooting/update-failed). + +Cuando un proxy se está ejecutando, pida que PID y puerto certificados exactos se reinicien en su lugar, espere a que su normal, y verificar un entorno de ejecución diferente PID en el mismo puerto. Enrutamiento y servicio gestionados La supervisión permanece instalada en todas partes; una petición incierta se observa más bien que se repite como un problema. Parada/Inicio por separado. Si no se está ejecutando ningún proxy, el comando vuelve a la posición normal. `ensure` Inicio. Si un reinicio aceptado pierde su reemplazo, el comando intenta un inicio de recuperación limitado incluso cuando el inicio automático Codex está deshabilitado, e informa de un error si no se inicia ningún proxy. Cuando el proxy inicia su propio reemplazo (ningún servicio en segundo plano lo supervisa) después del drenaje terminado normalmente, un reemplazo que sale antes de que responda se inicia de nuevo hasta dos veces. ¿Qué Las impresiones de reemplazo van a `~/.opencodex/restart-handoff.log`, que se mantiene cerca de 256 KiB: a El reinicio lo vacía una vez que alcanza ese tamaño, y el reemplazo en ejecución lo verifica una vez por minuto. Un proxy que la aplicación de escritorio OpenCodex inició no inicia su propio reemplazo: sale y la aplicación inicia el nuevo proxy en el mismo puerto. Si no se puede certificar un oyente en vivo a un PID en entorno de ejecución (incluido un proxy de actualización previa), se produce un error de reinicio Cerrado sin un `ensure` o detener/iniciar el retroceso. Después de confirmar la propiedad, el uso `ocx stop` entonces +`ocx start` para un proxy independiente. Para un proxy administrado por servicio, use `ocx stop` seguido por +`ocx service start` Se restablece la supervisión. Una invocación vuelve a observar las razas de descubrimiento transitorias. Un inicio fallido se vuelve a intentar solo cuando el intento anterior nunca lanzó un niño o se sabe que el niño lanzado ha salido. Si un inicio aún puede estar en ejecución, reinicie los informes del error original sin iniciar un segundo proxy, incluso cuando una investigación de salud no encuentra nada. Cuando un reinicio aceptado nunca publica un reemplazo, el comando vuelve a observar una vez antes de renunciar a — un proxy que se estrelló a mitad de reinicio lee ausente y se inicia fresco, mientras que un reemplazo que aterrizó justo después de la espera de reemplazo acortada todavía demuestra el éxito dentro del plazo general de observación. Fuera de la ruta de actualización CLI más reciente, un destino en vivo es nunca se detuvo para hacer espacio, por lo que un proceso de escucha rancio no puede ser reemplazado por un segundo Para el puerto. Cada intento fallido de inicio es seguido por un ritmo y una fuerte re-observación antes de la siguiente intento: un niño que acaba de ser lanzado puede seguir siendo vinculante, y los pasos posteriores a la salud puede haber lanzado en un proxy que ya sirve. Una lectura en vivo significa no se genera un segundo comienzo: un rechazo limpio luego da fe del éxito, mientras que un tiro se propaga como un fallo de inicio porque el trabajo posterior a la salud falló en un proceso de servicio. Durante la recuperación de un accidente después de un reinicio en vivo aceptado, el éxito requiere una entorno de ejecución PID en el puerto original: si el PID original se vuelve a leer en vivo, el reinicio falla como un reemplazo perdido en lugar de informar el éxito. Pruebas de ausencia y lanzamiento-salida confirmadas juntas permiten otro intento de inicio. Mientras que el PID anterior todavía está activo, o una sonda es incierta, la La ventana de confirmación mantiene la votación para un reemplazo dentro de la reserva en lugar de Fracasó de inmediato. Un segundo proxy nunca se genera junto a uno vivo. La espera de reemplazo termina lo suficientemente temprano como para que la ventana de confirmación aún se ajuste dentro del plazo de observación general. + +La recuperación del puerto después de la parada o actualización respeta una comprobación de proceso OCX fallido incluso cuando el PID se registró antes del apagado. Un soporte en vivo rechazado se deja en funcionamiento y evita la limpieza de la fila TCP. Si no se verifica, la espera de recuperación limitada puede caducar con el puerto todavía ocupado. Compruebe el titular del puerto actual y vuelva a intentar el reinicio después de que se resuelva el conflicto. + +### `ocx ensure` + +Asegúrese de que se está ejecutando un proxy en segundo plano y, a continuación, sincronice su catálogo de modelos en vivo. Si `codexAutoStart` es `false`, se imprime que el inicio automático está deshabilitado y no hace nada. + +Con una configuración de cliente conectado validada, `ensure` tiene éxito sin iniciar un proxy de proveedor local después de conciliar el diario del cliente. Esto no prueba ni certifica la disponibilidad del concentrador remoto. El estado del cliente no válido o no coincidente sigue fallando. + +### `ocx restore [back]` · `ocx eject [back]` + +Restaurar nativo Codex **sin** detener el proxy - tiras de las líneas de configuración inyectadas y entradas de catálogo enrutado para llanura `codex` funciona de forma nativa de nuevo. `eject` es un alias de `restore`. + +La salida del catálogo restaurado excluye los modelos nativos retirados, incluidos los `gpt-5.3-codex-spark`, ya sean almacenados como ID desnudos o filas calificadas para cuentas de confianza. Esto se aplica con o sin una copia de seguridad del catálogo; se conservan la copia de seguridad original y la configuración histórica seleccionada por el usuario. + +La restauración informa de un fallo en lugar de reemplazar los archivos de configuración modificados cuando un diario guardado carece de los hashes de inyección correspondientes. Los archivos actuales y el diario permanecen disponibles para su revisión; ver [recuperación sin hashes de inyección](/es/guides/codex-integration/#recovery-without-injection-hashes). + +Pase `back` para volver a señalar el plano `codex` en un proxy que ya se esté ejecutando sin cambiar el ciclo de vida del proxy: + +```bash +ocx restore back +ocx eject back +``` + +### `ocx recover-history --legacy-openai --yes` + +Recuperación explícita para versiones de desarrollo anteriores que volvieron a mapear el historial de la aplicación Codex antes de que existiera el soporte de copia de seguridad reversible. Cierre primero Codex si su base de datos de historial está bloqueada. + +Este es un reetiquetado amplio y destructivo: cada hilo de mensaje de usuario etiquetado actualmente `opencodex` se cambia a `openai`, `exec` se normaliza a `cli` y se establece el marcador de evento. Eso incluye la historia legítima de proveedores dedicados. Realice una copia de seguridad del estado y ejecútelo solo cuando se pretenda ese alcance completo. + +### `ocx recover-history --ocx-compaction --yes` + +Repare un hilo que se compactó a través de un proveedor enrutado antes de reanudarlo a través del Codex nativo. El comando lee el subproceso exacto seleccionado por UUID, guarda una copia de seguridad privada de byte por byte y, a continuación, convierte solo el estado de compactación `ocx1:` / `ocx2:` propiedad de OpenCodeX en un resumen sencillo que el Codex nativo puede reproducir. El contenido cifrado nativo y otros hilos se dejan sin cambios. Cierre el subproceso seleccionado antes de ejecutar el comando; un cambio de implementación concurrente hace que la recuperación se detenga sin reemplazar el archivo. + +### `ocx uninstall` · `ocx remove` + +Detenga el servicio y el proxy, elimine el servicio y la compensación Codex, restaure el Codex nativo y, a continuación, elimine la configuración local opencodex solo si todos los pasos de restauración tuvieron éxito. `remove` es un alias de `uninstall`. La limpieza de configuración requiere metadatos de propiedad creados por una instalación nueva; los directorios heredados o compartidos se dejan en su lugar. + +Ambos comandos no aceptan argumentos. Las banderas no soportadas (incluyendo `--dry-run` y `--yes`) salen con el estado de uso 2 antes del prevuelo o desmontaje; no se realizan cambios. Para obtener ayuda, ejecute `ocx help uninstall` o `ocx help remove`. + + + +## Situación y salud + +### `ocx status [--json]` + +Estado y `ocx doctor` comparan esta versión CLI 's con el proxy en ejecución. Si el CLI es más nuevo, reinicie el proxy utilizando la instalación actual prevista; para un servicio en segundo plano, ejecute `ocx service restart`. En macOS, un sesgo de versión deja la definición de servicio byte-idéntica, por lo que `ocx service repair` no recargaría nada y mantendría el antiguo proceso en servicio. Si el proxy es más nuevo, actualice el CLI o resuelva `PATH` a la instalación prevista. Estos diagnósticos no reparan el servicio ni cambian si se permiten solicitudes. + +Las cadenas de versión idénticas y los marcadores de posición `unknown` / `0.0.0` suprimen la advertencia, al igual que una versión proxy ausente. El doctor no reporta marcadores de posición como un partido confirmado. Las diferentes cadenas aún producen una advertencia neutral cuando no pueden analizarse estrictamente como SemVer o difieren solo en los metadatos de compilación; ninguno de los lados se llama más antiguo. Las versiones no se recortan y no se normaliza un `v` principal. JSON expone el mismo consejo en `versionSkew`, cuyos campos permanecen `cliVersion`, `proxyVersion`, `skewed` y `warning`. + +En un Remote Link Child y su Home, `--json` también informa `appliedCodexSettingsDigest`, `lastApplyAt` y `runtimeStartedAt`; consulta [Paridad de aplicación de Remote Link](#remote-link-apply-parity). + +Imprima un resumen de diagnóstico de solo lectura: PID proxy, accesibilidad `/healthz`, URL del panel de control, ruta de configuración, proveedor predeterminado, configuración de inicio automático Codex, estado del servicio, estado de compensación y la casa Codex efectiva redactada. Solo la firma de inicio de ejecución Windows explícita y de alta confianza de Orca agrega una advertencia procesable de desajuste de App-home; nunca cambia `CODEX_HOME` automáticamente. También advierte cuando el Codex enrutamiento opencodex escribió nombres de un puerto local que el proxy en ejecución no sirve. `ocx sync` lo repara inmediatamente, y un proxy de propietario en ejecución también puede volver a apuntarlo por su cuenta una vez que nada responde en ese puerto. El estado de un hermano no lo informa, porque su enrutamiento nombra el proxy al lado del cual se ejecuta. + +Cuando un proxy en vivo ya ha pasado la verificación de identidad / vitalidad, `ocx status` prefiere el informe de salud de inicio certificado de ese proceso para reiniciar la seguridad y la viabilidad del servicio. Esto evita falsos negativos de una prueba de administrador de servicio local de shell que carece del entorno de administrador del servicio en ejecución. El informe en vivo se valida por esquema; si no está disponible o está mal formado, el estado vuelve al servicio local y a los diagnósticos de shim. `ocx doctor` utiliza la misma regla de live-first para su sección **Seguridad de reinicio Codex**, por lo que los dos comandos deben acordar la protección de reinicio. Si está diagnosticando una discrepancia, compare el veredicto de inicio en vivo reportado con los detalles del servicio local en lugar de tratar la sonda de shell como más autorizada. + +La lectura en vivo permite que la sonda de servicio limitada termine: hasta 6,5 segundos en macOS / Linux y 16,5 segundos en Windows cuando la caché de diagnóstico está fría o caducada. Cached lee el regreso rápidamente. Un tiempo de espera todavía vuelve a los diagnósticos locales; un `/healthz` saludable solo no establece protección de reinicio. + +El diagnóstico `clients=pending-restart(...)` enumera Codex CLI clientes que son anteriores a la inyección de enrutamiento. En macOS, los renderizadores de electrones, la utilidad y los ayudantes de crashpad bajo el marco Codex.app están excluidos de esa lista de clientes, incluidos los ayudantes cuyas rutas ejecutables contienen espacios. + +La salida humana también incluye un bloque **OAuth salud** después del resumen de inicios de sesión OAuth: `OAuth health: +ok` cuando cada cuenta conocida está sana, o `OAuth health: warning` con una línea redactada por cuenta no saludable (proveedor, ID de cuenta enmascarada, estado tal como reautenticación requerida, tasa o cuota limitada o conflicto de actualización) más una sugerencia opcional `Action:`. Los identificadores de la cuenta se redactan; los tokens y los correos electrónicos nunca se imprimen. El contrato `--json` no incluye actualmente este bloque de salud. + +```bash +ocx status +ocx status --json +``` + +Forma de ejemplo abreviada: + +```json +{ + "schemaVersion": 1, + "proxy": { + "running": false, + "pid": null, + "health": { + "ok": false, + "url": "http://127.0.0.1:10100/healthz", + "message": "unreachable" + } + }, + "dashboard": { + "url": "http://localhost:10100/" + }, + "paths": { + "config": "/Users/example/.opencodex/config.json", + "pid": "/Users/example/.opencodex/ocx.pid", + "runtime": "/path/to/bun" + }, + "runtime": { + "source": "bundled" + }, + "codexHome": { + "effectiveCodexHome": "C:\\Users\\[USER]\\.codex", + "appCodexHome": "C:\\Users\\[USER]\\.codex", + "mismatch": false, + "warning": null, + "action": null + }, + "codexAutostart": true, + "defaultProvider": "openai", + "service": { + "summary": "not installed (logs: /Users/example/.opencodex/service.log)" + }, + "codexShim": { + "summary": "Codex autostart shim: not installed" + } +} +``` + +El objeto real también incluye `listen` (puerto, nombre de host, entorno de ejecución/fuente de configuración), carga de configuración diagnósticos y diagnósticos de complementos Codex incluidos. El esquema JSON es solo aditivo: versiones futuras puede agregar campos, pero los campos existentes deben permanecer estables. Excluye intencionadamente las claves API, OAuth tokens, encabezados de autorización, contenido de solicitud, correos electrónicos e identidades de cuenta. + +### `ocx health [--json]` + +Verifique la identidad del proxy en vivo. Informes de producción humana PID/puerto; `--json` emite `{ok, pid, port}`. El comando sale 0 solo cuando está sano y 1 de lo contrario, lo que lo hace adecuado para sondas de servicio. + +### `ocx system health [--json]` + +```bash +ocx health --json +ocx system health --json +``` + +La salud de la raíz es la sonda de vitalidad. La salud del sistema es una observación de gestión separada: `{status:"ok",service:"opencodex",version,uptime,pid,spendLedger}`, con tiempo de actividad en segundos. `system status` sigue siendo su configuración / inicio / memoria agregada. Una observación válida de la salud del sistema sale 0 incluso si el libro mayor de gastos se degrada. La propiedad de lectura mantenida / no mantenida, inicializada, configurada, degradada, persistFailures y corruptRecords; el estado ok no certifica que todos los subsistemas estén sanos. Las lecturas fallidas/malformadas permanecen distintas de cero con datos sanos seguros, no fabricados. + +Para diagnósticos limitados, [solicitud/inyección seguir](/es/reference/cli/agents/#follow-request-windows-or-injection-sequences) se detiene en caso de error o cambio de objetivo detectado en lugar de volver a conectarse automáticamente. SIGINT sale por 130 y SIGTERM 143. Los eventos de registro con versiones reconstruyen las ventanas observadas, no el tráfico perdido entre sondeos; la secuencia de inyección no puede excluir las brechas de reinicio / desalojo. + +### `ocx ready [--json] [--wait [--timeout ]]` + +Comprueba si el proxy está listo después de la sincronización mediante el endpoint no autenticado `GET /readyz`. Devuelve `200` cuando está listo, o `503` con `Retry-After: 1` para `pending` y el estado terminal `failed`. Su identidad HTTP depurada es `{service, version, uptime, pid, port, status}`, junto con los campos del protocolo del hub remoto `{protocol, minimumClientProtocol, managementUrl, features}`. `protocol` identifica el protocolo del hub y `minimumClientProtocol` el cliente más antiguo aceptado, para rechazar un emparejamiento incompatible antes de enviar otros datos. `managementUrl` indica el origen del plano de administración: `hub.managementPublicOrigin` cuando `runtimeRole` es `hub`; en los demás casos, el origen por el que llegó la solicitud. Se rechazan las solicitudes sin un origen HTTP(S) en lugar de adivinar uno. + +`features` enumera las capacidades que ofrece esta compilación para que otro nodo pueda comprobarlas sin comparar versiones: `relay-auth/` identifica la versión de autenticación del relé Remote Link; `link-management-relay`, su relé de administración de solo lectura; `link-peer-report/`, el informe de versión y compatibilidad de cada Child que el Home muestra en `ocx link status`; `quota-pool/1`, la consulta de administración `GET /api/quota-pool`; y `served-by-header`, el encabezado de respuesta `x-opencodex-served-by`. Las capacidades no disponibles se omiten. La lista contiene únicamente nombres fijos, nunca datos de cuentas o configuración. + +Los proxies antiguos sin `/readyz` se consideran `unreachable` y no se aceptan como listos; `/healthz` comprueba por separado si el proceso responde. El comando realiza una comprobación por defecto. `--wait` repite la consulta hasta que el proxy esté listo o se agote el plazo, pero termina inmediatamente al observar `failed`. El plazo predeterminado es de 45 segundos; `--timeout ` requiere `--wait` y acepta enteros de 1–300. La salida `--json` de la CLI contiene menos campos que la respuesta HTTP: `{ready, status, pid, port}`, donde `status` es `ready`, `pending`, `failed` o `unreachable`. Los códigos de salida son 0 si está listo; 1 si no está listo, sigue pendiente, falla, se agota el plazo o no es accesible; y 64 si los argumentos no son válidos. + +En un Child de Remote Link, la disponibilidad también incluye el enlace. Si no puede transportar solicitudes, `/readyz` devuelve `503` con `status: "pending"` y `link: {state: "unavailable", reason}`; `ocx ready --wait` sigue esperando a que se recupere. Un enlace operativo añade `link: {state: "available"}` a la respuesta `200`. En un Child, `/healthz` sigue indicando únicamente que el proceso responde. Los motivos se enumeran en [Remote Link](/es/guides/remote-link/#link-status). + +### `ocx resolve [--json]` + +Resolver los hechos de entorno de ejecución que un shell necesita sin volver a implementarlos: la configuración de inicio, el puerto efectivo y el veredicto de vivacidad verificado de identidad. `--json` emite un documento versionado (`schema: "ocx-resolve/1"`) con `cliVersion`, `configHome`, `port` (`effective`, `configured` y `source`), y `liveness` (`status`, `pid`, `port`, `source`, más `version`, `role` y `hostname` cuando el proxy en vivo los informa). Cuando un proxy está activo, el documento también lleva `versionSkew` - la misma superficie de comparación `ocx status` y `ocx doctor` - con `cliVersion`, `proxyVersion`, `skewed`, `relation` de `match`, `cli-newer`, `proxy-newer`, `incomparable` o `unknown`, y el `warning` orientado al operador. Los shells leen `relation` en lugar de reformular la advertencia; el escritorio usa `proxy-newer` para evitar que una toma de control disminuya el oyente. Liveness tiene tres respuestas: `live`, `absent-proven` (cada punto final registrado y configurado rechazó o respondió definitivamente no opencodex), y desconocido - una sonda de temporización o un oyente que retiene `/healthz` salidas 1 en lugar de leer como ausente, por lo que solo `absent-proven` puede autorizar el inicio de un nuevo entorno de ejecución. El puerto es el puerto del oyente en vivo cuando un proxy responde, de lo contrario, el puerto configurado (por defecto 10100). La salida 0 lleva un veredicto digno de confianza; la salida 1 significa que el CLI no se pudo resolver, incluido un `config.json` inválido, que nunca se repara aquí, y la persona que llama debe negarse a adivinar; cualquier argumento desconocido sale 64. Discovery utiliza el mismo presupuesto de sondeo seguro para la propiedad que `ocx start`, porque una respuesta falsa de "no escuchar nada" es cómo suceden los proxies duplicados. El verbo es de solo lectura y omite la función de restauración automática previa. + +### `ocx doctor` + +El informe predeterminado incluye el estado del coordinador de escritura nativa y la ruta exacta utilizando la inspección de solo lectura inmutable SQLite. Los estados de cero bytes, vacío-sin versionar y sin filas se muestran por separado del estado del catálogo/servidor de aplicaciones, por lo que una actualización de catálogo exitosa no se confunde con una inyección de configuración Codex exitosa. + +La comprobación de historial pendiente lee un WAL-mode `state_5.sqlite` con puntos de control incluso cuando Codex está cerrado y sus archivos `-wal` / `-shm` están ausentes. Los sidecares que faltan por sí solos no indican un fallo de integridad de la historia. Los manifiestos de copia de seguridad y los objetivos de restauración aún se someten a validación de integridad. + +Después de detener el servicio/proxy OpenCodex, conserve y mueva explícitamente un coordinador no autorizado probado, luego vuelva a intentar la sincronización: + +```bash +ocx doctor --recover-zero-byte-coordinator --yes +ocx sync +``` + +La recuperación solo acepta un remanente probado de cero bytes. Rechaza todas las bases de datos no vacías, válidas, desconocidas, cambiadas, inseguras u ocupadas y crea un archivo del mismo directorio `.zero-byte-backup-*` en lugar de eliminar nada. + +Ejecute diagnósticos de conectividad y entorno de solo lectura: rutas de estado y tipo de sistema de archivos, instalaciones duales WSL, entorno/configuración proxy, accesibilidad ChatGPT, advertencias de plugin y configuración de proyecto Codex y migración de historial pendiente. La sección de orientación de la aplicación Codex también detecta la estrecha falta de coincidencia del entorno de ejecución de Windows Orca y explica la migración del servicio cuando corresponde. Las rutas mostradas por este diagnóstico redactan el nombre de usuario del sistema operativo. El médico imprime pistas de reparación, pero no las aplica. + +Los diagnósticos de Project-config ignoran los ejemplos de proveedores dentro de cadenas multilínea TOML, incluyendo `developer_instructions`. La configuración real del proveedor y del perfil después del delimitador de cierre sigue estando marcada, incluso cuando una cita escapada precede inmediatamente a ese delimitador. + +La sección **OAuth fiabilidad** informa si el almacenamiento de credenciales es escribible, si se pueden crear archivos de actualización de un solo vuelo/bloqueo bajo `OPENCODEX_HOME`, OAuth o Codex cuentas de grupo no saludables (ids redactados) con una recuperación `Action:`, y un OK estático de que la ruta de reenvío Codex no fabrica metadatos de cliente oficial. El médico nunca muta las credenciales ni aplica reparaciones. + + + +## Sincronización de catálogo + + + +### Leer el estado guardado por separado de la sincronización + +El modelo, el proveedor, la configuración y los recibos v2 tienen diferentes contratos de finalización. Los cambios de modelo personalizado local se sincronizan de manera oportunista: ningún proxy significa un guardado exitoso, `needsSync:true`, `sync.status:"not-attempted"` y salida 0. Un proveedor local explícito `--sync` sin un proxy en su lugar devuelve un valor distinto de cero después de guardar. + +Las escrituras de configuración usan `catalogRefreshPending`, mientras que las escrituras de catálogos en vivo usan una disposición completa de `catalogRefresh`. El modo local v2/keep-native y el modificado on/off siguen intentando su sincronización establecida incluso cuando no se descubrió ningún puerto. JSON informa sobre el estado real cambiado y las pruebas de sincronización; la sincronización no verificada/no verificada no es cero. Hilos/sugerencias y encendido/apagado sin cambios no introducen un nuevo intento de sincronización. + +Inspeccione el mismo objetivo con `ocx v2 status --json` o `ocx v2 status --live --json` y utilice `ocx system settings --json` para la lectura de la configuración. Un resultado guardado pero pendiente o desconocido no prueba retroceso y no es permiso para reproducir una escritura. Consulte [v2 resultados](/es/reference/cli/agents/#explicit-v2-target-and-outcome) y [política de cuenta](/es/reference/cli/providers-accounts/#pool-policy-account-thresholds-and-paid-credit-intent) para conocer los límites de gasto, alcance y destino. Una lectura de estado de reset-grant puede contactar con el estado de upstream pero nunca consume o reanuda una subvención. + +### `ocx sync [--restart-codex] [--restart-app-server-only]` + +Un reinicio solicitado explícitamente también se ejecuta después de un cambio realizado con éxito de `config.toml`, incluso si los bytes de catálogo y caché no cambian. Una escritura de solo configuración sin opción, de rechazo, previa o de retroceso no la activa. Sin un indicador de reinicio, la sincronización nunca se reinicia automáticamente Codex. + +En un Remote Link Child, `ocx sync` también aplica la configuración de Codex del Home y reinicia el entorno cliente si este arrancó antes de esa aplicación; consulta [Paridad de aplicación de Remote Link](#remote-link-apply-parity). + +Obtenga la lista de modelos en vivo de cada proveedor configurado y vuelva a inyectar el catálogo combinado en Codex. Ejecutarlo después de agregar un proveedor o para actualizar los modelos disponibles. + +Antes de la detección de proveedores o el reemplazo de catálogo/caché, `ocx sync` valida que se puede inyectar la configuración administrada Codex. Si esa validación rechaza la configuración, el comando sale de no cero, imprime la razón concreta en stderr y deja el catálogo y la caché existentes sin cambios. `ocx restore back` usa el mismo prevuelo sin escritura antes de volver a habilitar el enrutamiento. + +Si los procesos de larga vida Codex `app-server` todavía se están ejecutando, `ocx sync` advierte que pueden seguir sirviendo la lista de modelos en memoria anterior a pesar de que `opencodex-catalog.json` / `models_cache.json` se actualizaron. Pase `--restart-codex` para reiniciar los procesos `codex … app-server` y `codex-code-mode-host` que coinciden con **y** y reinicie completamente la aplicación de escritorio Codex, en macOS, Linux y Windows, por lo que el selector de modelos vuelve a leer el catálogo. Las conversaciones en vivo terminan. La coincidencia amplia `pkill -f codex` se evita intencionadamente. + +`--restart-desktop-app` es un alias obsoleto de `--restart-codex`. Todavía funciona, imprime un aviso de censura, y no es Windows -solo. + +`--restart-app-server-only` restaura el comportamiento más antiguo y más estrecho: `SIGTERM` solo a los procesos de host de modo de código y de servidor de aplicaciones correspondientes propiedad del usuario actual, con la aplicación de escritorio en ejecución. Los giros activos aún pueden interrumpirse. Si se combina con `--restart-codex` o `--restart-desktop-app`, el alcance estrecho gana, porque perder conversaciones en vivo es irrecuperable y un selector obsoleto no lo es. + +Cuando el comando se ejecuta desde dentro de la aplicación Codex, el reinicio se transfiere a un ayudante separado y esta sesión finaliza con la aplicación. + +### `ocx sync-cache [--restart-codex] [--restart-app-server-only]` + +Invalide la caché local del selector de modelos de Codex para que se reconstruya a partir del catálogo activo de opencodex. Se aplican las mismas advertencias obsoletas `app-server` y los indicadores de reinicio opcionales que `ocx sync`. + +Si la caché derivada ya tiene bytes idénticos, el comando se ejecuta correctamente sin reescribirlo ni reiniciar Codex. Con `--json`, esto se informa como `ok: true`, `wrote: false`, `skipped: true` y `skippedReason: "unchanged"`; un catálogo no válido o una escritura en caché fallida sigue saliendo no cero. + + + +### Diagnósticos de escritura de catálogo + +Catalog write auditing records diagnostics en `opencodex-catalog-audit.jsonl` bajo `CODEX_HOME`. Un catálogo o caché sin cambios no produce ningún evento; un error de auditoría no falla la publicación del catálogo. + +En Windows, **como máximo se registra el evento de creación de nuevo archivo exitoso**. El archivo se crea vacío y endurecido antes de que se escriban los datos de diagnóstico. Todos los eventos posteriores omiten el archivo existente, tanto en el mismo proceso como después de reiniciar. Un fallo de endurecimiento puede dejar un archivo vacío, que eventos posteriores también omiten. Los archivos existentes y sus ACL no se cambian para la auditoría, incluso cuando otra casa OpenCodex posee el catálogo. Este es un retroceso de la privacidad, no un flujo de auditoría Windows completo; el comportamiento NTFS nativo para esta ruta de auditoría aún no se ha validado. + +La auditoría POSIX continúa agregando y conservando registros limitados. La limitación Windows no deshabilita la protección del catálogo o la curación del propietario. Los archivos de auditoría en un `CODEX_HOME` separado permanecen como residuos de limpieza porque el manifiesto de desinstalación de configuración no puede reclamar rutas fuera de su propia raíz. + +### `ocx catalog pull [--auth-env ] [--json] [--restart-codex] [--restart-app-server-only]` + +Instale un catálogo completo servido por el punto final `/v1/catalog` de otra instancia OpenCodex y, a continuación, sincronice `models_cache.json`. A diferencia de `ocx sync`, este comando no descubre proveedores configurados ni inyecta la configuración Codex. A diferencia de `ocx sync-cache`, reemplaza el catálogo activo antes de reconstruir la caché. Funciona incluso cuando el estado deseado de la integración local Codex está desactivado. + +La URL debe ser HTTPS; se acepta loopback HTTP para pruebas locales. Las credenciales de URL incrustadas, consultas, fragmentos, redirecciones, respuestas de gran tamaño, JSON malformadas, identificadores duplicadas o inseguras y desconocidas `input_modalities` se rechazan antes de cualquier escritura local. + +Las solicitudes de Loopback HTTP son rechazadas antes de que se adjunten las cabeceras de autenticación o se envíe cualquier solicitud cuando se aplica `HTTP_PROXY` o `http_proxy` sin una derivación `NO_PROXY` o `no_proxy` coincidente. `ALL_PROXY` / `all_proxy` y la configuración limitada a `HTTPS_PROXY` / `https_proxy` no activan esta restricción HTTP; La adquisición del catálogo HTTPS permanece permitida. El mensaje de denegación no incluye ni la dirección proxy ni el testigo de autenticación. `http_proxy` y `no_proxy` tienen prioridad sobre `HTTP_PROXY` y `NO_PROXY`, respectivamente. Para reglas de omisión compatibles con Bun, use nombres de host, entradas coincidentes `host:port`, direcciones IPv6 entre corchetes como `[::1]` o `*`; no use URL, rutas o prefijos `*.`. + +La autenticación es opcional y solo se lee mediante referencia de entorno variable: + +```bash +export OPENCODEX_CATALOG_AUTH_TOKEN='...' +ocx catalog pull https://proxy.example.com/v1/catalog \ + --auth-env OPENCODEX_CATALOG_AUTH_TOKEN +``` + +El valor se envía como un token de portador, pero nunca se acepta como un valor de argv. Las redirecciones son rechazadas, por lo que la autorización no puede cruzar orígenes. Las escrituras de catálogo y caché utilizan el bloqueo de catálogo Codex compartido y el escritor atómico. Una recuperación, validación, adquisición de bloqueos, escritura de catálogo o reconstrucción de caché fallida conserva los últimos archivos buenos conocidos. Idénticos bytes de catálogo son una opción prohibida que conserva mtimes y nunca toca los procesos. `--restart-codex`, `--restart-app-server-only` y el alias `--restart-desktop-app` en desuso significan lo mismo aquí que en `ocx sync` y `ocx sync-cache`, y se aplican solo después de una escritura real. + +La URL debe nombrar `/v1/catalog` en la raíz del host. Este comando no admite un proxy inverso que sirva el punto final bajo un prefijo de ruta. + +El comando descarga el catálogo completo y compara bytes localmente en lugar de emitir un `ETag` / +`If-None-Match` Solicitud condicional. Los bytes idénticos se tratan como un no-op completo, por lo que Codex casa cuyo catálogo es correcto, pero cuya `models_cache.json` falta o es rancio no reparado por este comando; usar `ocx sync-cache` Por eso. + +`--json` emite un sobre estable en stdout. `schemaVersion`, `ok`, `status`, `catalogWritten`, `cacheSynced` y `codexRestarted` están siempre presentes. `codexRestarted` todavía significa solo servidores de aplicaciones. `desktopAppRestarted` está presente solo cuando se solicitó un reinicio del escritorio, y es `true` solo cuando se inició el relanzamiento; un traspaso no es un éxito. `status` es `updated`, `unchanged`, o `failed`. Un tirón exitoso agrega `modelCount`; un fallo agrega `code`, que es el campo en el que se ramifica un script: + +| `code` | Descripción | Salir | +| --- | --- | --- | +| `usage` | Los argumentos no eran una invocación `catalog pull` válida. | 2 | +| `auth_env_missing` | `--auth-env` nombró una variable que no está establecida | 1 | +| `url_invalid`, `insecure_http_refused` | La URL fue rechazada antes de cualquier solicitud | 1 | +| `request_failed`, `redirect_refused`, `http_error` | La solicitud no produjo una respuesta utilizable | 1 | +| `body_too_large`, `body_invalid`, `catalog_invalid` | La respuesta fue rechazada antes de cualquier escritura local. | 1 | +| `write_failed`, `lock_database`, `unsafe_path` | La escritura coordinada no se completó; los archivos no han cambiado | 1 | +| `lock_busy` | Otro escritor tiene el bloqueo de catálogo Codex | 3 | +| `restart_incomplete` | El catálogo y la caché aterrizaron, pero un Codex app-server sobrevivió `--restart-codex` o `--restart-app-server-only` | 1 | + +`restart_incomplete` es el único fallo que reporta escrituras reales: `catalogWritten` y `cacheSynced` permanecen verdaderas y `ok` es falsa, porque un servidor de aplicaciones sobreviviente todavía sirve el catálogo anterior de memoria. + + + +## Servicio en segundo plano + +Un servicio administrado puede iniciar una instalación más nueva que anteriormente servía a la misma casa OpenCodex, incluso cuando su definición de servicio aún apunta a una instalación más antigua. Si ese hijo más nuevo sale antes de vincularse, con cualquier código de salida, el servicio original se inicia en su lugar y aplica sus propias comprobaciones antes de servir. Los inicios de primer plano y los proxies lanzados por el cliente mantienen su ejecutable seleccionado. En Windows, esto se aplica al Programador de tareas y a los servicios nativos WinSW recién instalados o reparados. Una definición nativa de WinSW creada antes de este comportamiento necesita `ocx service repair` para actualizar su XML antes de que pueda pasar a una instalación más reciente. + +### `ocx service [install|repair|restart|start|stop|status|uninstall|remove]` + +En Windows Task Scheduler, el envoltorio de servicio reinicia el proxy después de cinco segundos, incluso cuando una herramienta externa lo termina con el código de salida 0. Si otro proxy opencodex ya posee el puerto, el contenedor sale deliberadamente. Utilice `ocx stop` o `ocx service stop` para detener el servicio y su bucle de reinicio. Después de actualizar una instalación existente, ejecute `ocx service repair` para actualizar el envoltorio generado. + +Ejecute opencodex como un servicio en segundo plano administrado por inicio de sesión (macOS **launchd**, Linux **Unidad de usuario systemd**, Windows **Programador de tareas**) que se inicia automáticamente al iniciar sesión y se reinicia automáticamente al bloquearse. El servicio ejecuta el conjunto `OCX_SERVICE=1` para que un reinicio no cambie la configuración Codex. + +Windows Las instalaciones del Programador de tareas usan la prioridad de proceso normal (`Priority=4`). La prioridad de fondo más antigua (`7`, también el planificador predeterminado cuando se omite) puede retrasar las respuestas de estado del proxy en la contención de la CPU, haciendo que la bandeja informe Desconectado incluso mientras el proceso está activo. Después de actualizar, ejecute `ocx service repair` para migrar esa prioridad registrada y reinicie el servicio. Esta migración puede solicitar la aprobación de UAC; una prioridad ya establecida a normal o alta no desencadena la sustitución. + +El envoltorio Windows admite fechas de configuración regional que contienen paréntesis, incluidos los formatos de fecha coreano y japonés. Después de actualizar, ejecute `ocx service repair` para reemplazar un envoltorio generado más antiguo que sale antes de lanzar Bun en esas configuraciones regionales. + +El envoltorio Windows verifica su entorno de ejecución Bun horneado y su entrada CLI antes de cada intento de inicio. Si una actualización de paquete interrumpida elimina cualquiera de los archivos, registra un mensaje `installation is incomplete` y se detiene en lugar de volver a intentar el mismo ejecutable que falta cada cinco segundos. Vuelva a instalar opencodex y, a continuación, ejecute `ocx service repair` para actualizar la tarea con las rutas de paquetes restauradas. + +Las definiciones de servicio omiten los directorios multishell version-manager locales de sus `PATH` guardados. Esto incluye el servicio nativo Windows instalado con `ocx service install --native`; ejecute `ocx service repair` para regenerar una definición de WinSW anterior con un `PATH` duradero. + +En Linux, la unidad systemd invoca el primer ejecutable normal `ocx` archivo encontrado en `PATH` en tiempo de instalación en lugar de las rutas Bun y CLI dentro del árbol de paquetes instalado. Administradores de versiones como el **mise** y **asdf** instalar en un directorio versionado y eliminar el antiguo en la actualización; su shim estable mantiene la unidad resolviendo. Fuente checkouts sin un `ocx` lanzador mantener el forma directa Bun + CLI. Un confiable `OPENCODEX_BUN_PATH` seleccionado antes de Bun se inicia se conserva a través de la shim; las rutas de paquetes locales Bun se redescubren después de las actualizaciones. + +En macOS, launchd en su lugar utiliza el paquete local Bun y CLI rutas seleccionadas durante la instalación o reparación. Esto evita que una shim PATH mutable reciba el token de servicio API y el entorno proxy configurado en un reinicio posterior. Después de actualizar una instalación del administrador de versiones, ejecute `ocx service repair` para actualizar esas rutas antes de reiniciar el servicio. Lanzado reinicia el proxy después de un fallo o un traspaso de reinicio fallido, pero lo deja detenido cuando el servicio sale deliberadamente de forma limpia porque la aplicación de escritorio es propietaria del entorno de ejecución. Ejecute `ocx service repair` una vez para aplicar este comportamiento a un servicio instalado por una versión anterior. + +Las definiciones instaladas antes de este cambio todavía llevan las antiguas rutas versionadas y no pueden migrar por sí mismas: una vez que se elimina el ejecutable antiguo, no se ejecuta ningún código opencodex para solucionarlo. Ejecutar `ocx service repair` una vez después de la actualización. Linux el servicio comienza entonces sigue el lanzador; macOS repair escribe las nuevas rutas de paquetes en la definición launchd. Un proxy ya en ejecución no se sustituye por una actualización externa: cuando el CLI instalado es más nuevo que el proxy en ejecución, ejecute `ocx service restart` para que sirva la nueva compilación. En macOS, `repair` no es suficiente allí: la definición no cambió, y una reparación que no cambia nada no recarga nada. Si el proxy es más nuevo en su lugar, compruebe la instalación CLI y `PATH` como se describe en [`ocx status`](#ocx-status---json). + +| Subcomando | Medidas adoptadas | +| --- | --- | +| Ninguno | Instale e inicie cuando esté ausente; de lo contrario, `repair` el servicio existente. Se reutiliza una definición saludable del planificador Windows; una definición obsoleta puede volver a registrarse y requerir elevación. | +| `install` | Crear e iniciar el servicio. Lo registra, que en Windows necesita elevación. | +| `repair` | Actualizar un servicio instalado en su lugar. En macOS, el administrador se recarga solo cuando algo cambia, por lo que un trabajo saludable y sin cambios sigue funcionando y la reparación no es una interrupción. En Linux y Windows, el servicio se reinicia; se reutiliza una definición de planificador de Windows saludable, mientras que una definición obsoleta puede volver a registrarse y requerir elevación. | +| `restart` | La misma actualización y un reinicio garantizado en todas las plataformas. En el macOS se inicia un trabajo sin cambios y ya cargado. No es un alias de `repair`. | +| `start` | Iniciar un servicio instalado. | +| `stop` | Detener el servicio y restaurar nativo Codex. | +| `status` | Informar los diagnósticos del servicio y del proxy, y las rutas de registros. `--json` muestra el documento pasivo descrito a continuación. | +| `uninstall` | Retire el servicio y restaurar nativo Codex. | +| `remove` | Alias de `uninstall`. | + +En `ocx service`, un Windows ejecuta la ruta de instalación solo después de que se demuestre que está ausente el Programador de tareas y WinSW. Si cualquiera de las consultas de estado no es concluyente, se niega a registrar nada y le pide que ejecute `ocx service status`; use `ocx service install` explícito solo después de confirmar la ausencia. + +`ocx service status --json` muestra un documento pasivo para scripts y otros clientes, como el inventario de dispositivos de GOAT. Realiza las mismas lecturas que el informe de texto y nunca instala, inicia, detiene ni repara nada; cualquier otro verbo `service` rechaza `--json`. Campos: `schemaVersion` (1), `platform`, `supported`, `backend` (`launchd`, `systemd`, `schtasks`, `winsw` o `none` si no hay ningún registro), `label` (nombre del trabajo, unidad, tarea o servicio WinSW), `installed`, `enabled`, `running` (veredicto del administrador de servicios), `viable`, `stale`, `conflict`, `serving` (`probed`, `ok`, `port`; solo se sondea cuando hay un registro), `summary`, `logPath`, `ownershipLease` y `desktopLogin`. Una plataforma no admitida o un contenedor Docker también recibe el documento, con `supported: false`. + + + +### Propiedad en entorno de ejecución + +La aplicación de escritorio OpenCodex puede tomar el proxy de fondo de una instalación CLI. Cuando lo hace, registra el traspaso en el estado de instalación del servicio compartido, y ese registro es lo que hace que la adquisición sobreviva a un reinicio. Su registro de servicio es **mantenido, nunca eliminado** - el registro lo reemplaza en lugar de reemplazarlo. + +Un archivo de estado sin registro de propiedad significa que la instalación CLI es propietaria del entorno de ejecución, que es en lo que se realiza cada instalación antes de que se encuentre esta función. Nada cambia para ti hasta que una aplicación se hace cargo. + +Los hijos de servicio supervisados también verifican al propietario registrado antes del inicio y una vez más mientras mantienen el contrato de arrendamiento de propiedad de inicio, antes de elegir un puerto o publicar un PID. Si la aplicación de escritorio reclama el entorno de ejecución durante el inicio, el hijo de servicio se desactiva incluso si el proxy de escritorio aún no ha comenzado a escuchar. Un registro de propiedad ilegible tiene el mismo comportamiento de stand-down. + +Home rutas dentro de un registro de estado se comparan con la casa actual por el directorio físico que resuelven, no solo su ortografía. Un cruce o enlace simbólico registrado bajo una instalación anterior todavía nombra la misma casa y sigue funcionando después de la mudanza; un alias que ya no se resuelve solo se trata como una casa diferente cuando su ortografía registrada también difiere de la actual, por lo que un montaje obsoleto aún produce la negativa del propietario extranjero en lugar de reclamar silenciosamente el entorno de ejecución. + +Mientras que algo más que este CLI posee el entorno de ejecución, los subcomandos que **activar** su registro se niegan en su lugar: + +| Subcomando | Comportamiento bajo un propietario extranjero | +| --- | --- | +| `repair`, `restart` | Rechazar antes de cambiar nada. El registro no se vuelve a habilitar, reescribe o reinicia. | +| `start` | Se niega por la misma razón, por lo que un inicio automático de bandeja no puede poner un segundo proxy al lado de la aplicación. | +| `stop`, `uninstall` | Sin cambios. Se desactivan, por lo que nunca están cerradas. | +| `install` | Devuelve el tiempo de ejecución. Limpia el registro de propiedad después de que el registro tenga éxito, e informa de quién fue. | + +`ocx update` se comporta de la misma manera: ni detiene el proxy en ejecución ni actualiza el servicio mientras la aplicación posee el entorno de ejecución, porque el servidor en ejecución es el propio binario incluido de la aplicación y la actualización volvería a habilitar el lanzador que reemplazó la adquisición. La aplicación actualiza su propio entorno de ejecución. + +La denegación nombra la instalación propietaria y la generación de consentimiento, por ejemplo: + +```text +Background service repair stopped: the desktop app owns the runtime (install , consent generation 2). +The service registration was left exactly as it is — not re-enabled, not rewritten and not restarted. +Quit the desktop app and run 'ocx service install' to hand the runtime back to this CLI. +``` + +Un registro que no se puede leer o no analiza produce el mismo rechazo con una primera línea diferente, porque una reclamación ilegible no es lo mismo que ninguna reclamación - tratándolo como "nadie es dueño de esto" es como un error de permisos reactivaría silenciosamente su servicio. + +**La recuperación en todos los casos es `ocx service install`.** Es deliberadamente el único verbo que nunca está cerrado, por lo que eliminar la aplicación sin devolver el entorno de ejecución, o un archivo de estado dañado, aún le deja una forma de recuperar el servicio: + +```bash +ocx service install +``` + +```bash +ocx service +ocx service install +ocx service repair +ocx service restart +ocx service status +ocx service uninstall +``` + +`install`, `start` y `repair` confirman que un proxy realmente responde en el puerto instalado antes de informar el éxito en las tres plataformas. Esperan hasta 20 segundos y luego imprimen el puerto de servicio: + +``` +✅ opencodex service installed and serving on port 10100. +``` + +Si nada responde, advierten y **Salida no cero**: + +``` +⚠️ Service installed, but no proxy answered on port 10100 within 20s. + The manager registered the job; that is not the same as serving. + Log: ~/.opencodex/service.log + Meanwhile: ocx start (serves in the foreground) +``` + +Una salida distinta de cero significa aquí *Registrados pero sin servicio*, no *no instalado*. El gerente de servicio aceptó el trabajo; el proxy detrás de él nunca conectó el puerto. Lea el registro nombrado en el mensaje y use `ocx start` para servir en primer plano. + +`ocx service status` informa los mismos tres estados en lugar de la salida del administrador en bruto: + +``` +✅ installed and loaded (launchd; logs: …) + Serving on port 10100. +``` + +``` +⚠️ installed and loaded (launchd; logs: …) + Registered, but no proxy is answering on port 10100. + launchd is running an OLDER plist than the one on disk. + Fix: launchctl bootout gui/$(id -u)/com.opencodex.proxy && ocx service repair + Log: ~/.opencodex/service.log + Repair: ocx service repair + Meanwhile: ocx start (serves in the foreground) +``` + +Ya no imprime la línea sin procesar `launchctl list` / `systemctl status`, que informaba de un trabajo registrado de manera idéntica si estaba sirviendo, vinculado a nada o ejecutando una definición anterior. La línea `Diagnostics:` todavía lleva la trayectoria logarítmica y cualquier hallazgo de trayectoria anticuada. + +En Windows, el backend del programador mantiene su propia salida de estado más rica, que ya informó el registro del Programador de tareas por separado de la accesibilidad del proxy. + + + +### Registros de servicio + +El proxy administrado escribe stdout y stderr a `~/.opencodex/service.log` (o `$OPENCODEX_HOME/service.log` con un hogar personalizado). Cuando se establece `OCX_SERVICE`, `ocx start` prefija cada línea de registro de consola, incluidos los diagnósticos multilínea, con una marca de tiempo UTC ISO-8601 como `2026-10-14T03:04:05.678Z`. La salida en primer plano y otros comandos CLI mantienen su formato existente. + +El servicio comprueba el tamaño del registro en el inicio y una vez por minuto. Por encima de 20 MiB copia los 20 MiB más nuevos en `service.log.1`, mueve el archivo anterior a `service.log.2` y trunca el archivo activo en su lugar para que los identificadores de apéndice abierto del administrador de servicios sigan siendo utilizables. El archivo activo puede superar el umbral entre comprobaciones; cada archivo está limitado a 20 MiB. Las fallas de rotación no detienen el servicio. Copy-truncate puede perder líneas escritas durante la copia, y un archivo puede comenzar a mitad de camino a través de una línea. Los mensajes de envoltura Windows existentes mantienen su formato de envoltura. + +En macOS esto también cubre un fallo más sutil: `launchctl load` informa de un fallo en stderr mientras sale 0, por lo que una carga que no se usó para dejar launchd ejecutando una versión **anterior** de la definición de servicio mientras el comando imprimió una marca de verificación. `install` ahora falla ruidosamente en ese caso y nombra el comando `launchctl bootout` que limpia el trabajo obsoleto. + +En Windows, `ocx service status` informa el registro del Programador de tareas por separado de la accesibilidad del proxy OpenCodex verificado por identidad. No imprime la tabla localizada `schtasks`, por lo que el resumen sigue siendo legible en Windows páginas de código. La recuperación de copia de seguridad transaccional registra un mensaje de éxito fijo en lugar del nombre del directorio de copia de seguridad; los nombres de copia de seguridad que contienen metacaracteres de shell no se convierten en comandos en ese mensaje de registro. + +En Windows, la creación de la entrada del Programador de tareas requiere elevación. El texto denegado de acceso localizado reconocido mantiene la ruta de guía existente. Si ese texto es ilegible, el recurso alternativo requiere la forma de comando propia `/create /tn opencodex-proxy /xml /f`, estado 1, y un token no elevado confirmado; la acción de seguridad de inicio del panel de control puede solicitar UAC automáticamente. Si esa reserva no puede determinar el estado del token, retiene el error del programador original. Las tareas y operaciones en el extranjero nunca pueden emitir el marcador de elevación automática. Aprobar el indicador UAC del panel de control o volver a ejecutar `ocx service install` en una ventana de PowerShell elevada. + +Para una instalación nueva en la que la tarea del planificador OpenCodex se confirma ausente, la aprobación de UAC ahora ocurre antes de que el instalador detenga cualquier proxy existente. Su XML de registro único se organiza en un directorio privado endurecido por ACL fuera de la raíz de configuración OpenCodex, y la tarea se registra sin ejecutarse. Solo después de que el registro tenga éxito, OpenCodex elimina ese XML, requiere metadatos de propiedad para una raíz de configuración genuinamente nueva, detiene el antiguo oyente, elimina y vuelve a verificar de manera limitada cualquier registro nativo de WinSW, publica los activos de servicio e inicia la tarea programada. La cancelación o denegación de UAC, o no reclamar una nueva raíz de forma segura, por lo tanto, deja el proxy de trabajo y su enrutamiento Codex en su lugar. Los registros de planificador existentes o conflictivos continúan fallando en lugar de ser eliminados como un retroceso inseguro del mejor esfuerzo. + +Si los informes de inicio `another process owns the runtime mutation lease` o `ocx service status` muestran `Runtime mutation lease busy`, el contrato de arrendamiento bloquea el inicio o los cambios de servicio incluso si el proxy no se está ejecutando. El mensaje incluye la ruta de bloqueo, el PID registrado, la vida actual, el nombre ejecutable cuando esté disponible y la edad de arrendamiento. La identidad del proceso no está verificada: el PID puede haber sido reutilizado, por lo que la vitalidad y el nombre ejecutable describen el proceso que ocupa ese PID ahora. Espere a que la operación termine y vuelva a intentarlo; no elimine el bloqueo ni detenga un proceso basado solo en este PID. Un intento de mutación posterior puede reclamar un arrendamiento obsoleto una vez que su edad supera los 30 segundos y el PID registrado ya no está vivo; el estado solo lo inspecciona. + +En Windows, este diagnóstico compartido del Nodo/Bun no lanza un ejecutable para buscar el nombre de la imagen; el PID, la vivacidad, la edad de arrendamiento y la guía de recuperación registrados permanecen disponibles. + +### `ocx codex-shim ` + +En macOS y Linux, instale un envoltorio de inicio automático privado en `/bin/codex` y un `/codex-shell-env.sh` fuente, utilizando la casa OpenCodex resuelta. El lanzador nativo se queda donde brew, npm o fnm lo instaló; las actualizaciones del administrador de paquetes y las reversiones de versiones continúan funcionando sin volver a envolver ese lanzador. En Windows, los lanzadores basados en scripts todavía están envueltos en su lugar. Real `codex.exe` objetivos se dejan intactos. Si se rechaza la instalación o el contenedor no se puede ejecutar, el comando sale de no cero y el panel de control informa de la razón del fallo. Un envoltorio Unix ejecutable cuenta como una instalación exitosa incluso antes de la activación en el shell actual; una shim saludable ya instalada también cuenta como éxito. Para Windows instalaciones que exponen solo `codex.exe`, use `ocx service install` para autoarranque. + +En macOS /APFS, un reinicio puede cambiar los números de dispositivo del sistema de archivos. Después de ese cambio, un entorno de envoltura y shell privado permanece intacto, por lo que el estado, la reparación y la desinstalación continúan funcionando. OpenCodex todavía comprueba sus inodos registrados, rutas, propietario, permisos y enlace de contenido/lanzador; se conservan los archivos reemplazados o no validados. + +Después de brew/fnm y otra configuración PATH, ejecute el comando de activación impreso por install. Con la casa por defecto, es: + +```sh +. "$HOME/.opencodex/codex-shell-env.sh" +``` + +Para un hogar personalizado, use la ruta impresa y cotizada. El abastecimiento es idempotente: elimina entradas duplicadas de contenedores privados y pone ese directorio primero en PATH. Para activar futuros proyectiles, agregue esa línea de origen después de configurar su PATH de administrador de paquetes usted mismo; OpenCodex nunca edita archivos de inicio de shell. La instalación no puede cambiar su shell padre. `ocx status`, `ocx codex-shim status`, `ocx doctor` y `ocx connect` informan de una envoltura ejecutable pero no seleccionada como **No activo**, con el commando de activación. Los alias/funciones de Shell y los lanzadores de escritorio o servicios configurados por separado aún necesitan su propia configuración. + +Para fnm-managed Codex, la instalación resuelve el directorio multishell temporal a la instalación duradera del Nodo mientras se conserva el nombre de archivo del lanzador. Si ese directorio no se puede resolver, la instalación se niega en lugar de envolver una ruta temporal. Cuando se selecciona Codex, `ocx connect` también informa de la preparación de la shim. Esta comprobación de preparación omite entradas PATH de archivo especial y, en macOS y Linux, archivos sin permiso de ejecución, incluidos los objetivos de enlace simbólico. Preserva el orden de los lanzadores ejecutables regulares, incluidos los enlaces simbólicos npm y fnm. Windows mantiene su búsqueda PATHEXT. Si un envoltorio PATH diferente oculta una shim ejecutable, corrige el orden PATH; reinstalar la misma shim no cambia qué comando encuentra primero tu shell. Si la shim rastreada se puede ejecutar pero no se encuentra ningún comando `codex`, connect lo informa como inactivo e imprime el comando de activación. Una inspección PATH fallida informa la activación como no verificada en lugar de afirmar que no existe ningún comando. Estas advertencias no cambian el estado de salida del comando connect. + +Antes de que se realice una instalación o reparación, OpenCodex ejecuta el lanzador guardado con `--version` mientras se omite el inicio del servicio. Rechaza el cambio y retrocede cuando el lanzador resuelve `codex` de nuevo a la shim, sale distinto de cero, excede los cinco segundos, deja a los descendientes corriendo o no puede validarse y limpiarse de forma segura. Por lo tanto, `codex-shim install` no es incondicional. Si se rechaza, reinstale Codex para que la entrada PATH sea un ejecutable concreto o un lanzador y reintente; use `ocx service install` en su lugar cuando un lanzador de administrador de comandos dinámico no pueda cumplir con estas comprobaciones. Los rechazos de limpieza incluyen un sufijo de diagnóstico limitado que identifica la fase de sonda, un código o señal de error nativo reconocido, y el estado de salida cuando se conoce. No incluye rutas de lanzamiento ni salida de raw child, y no relaja las comprobaciones de validación o reversión. Una shim Unix más antigua instalada en su lugar es migrada solo por una `ocx codex-shim install` explícita. La migración restaura el lanzador nativo registrado sin reemplazar un lanzador más nuevo ya presente, luego instala el envoltorio privado. Si la instalación privada falla después de la restauración nativa, el lanzador nativo permanece restaurado y la operación se puede volver a intentar. Lanzadores nativos faltantes o inutilizables requieren reparación del gestor de paquetes; OpenCodex no adivina otra instalación ni vuelve a envolver la ruta del administrador. La migración también se niega cuando el `codex-shim.json` registrado no es un archivo regular de su propiedad o es grabable en grupo o en todo el mundo. Las versiones anteriores escribieron ese archivo con el proceso umask, por lo que un umask de `002` lo dejó en el modo `0664`. El rechazo nombra el archivo y el `chmod 600` que aclara solo el rechazo escrito en grupo o en todo el mundo. Se mantienen Symlink y las denegaciones de propietarios extranjeros; OpenCodex no cambia los permisos en sí. + +La instalación del lanzador por sí sola no prueba que las solicitudes Codex usarán OpenCodex. Después de una instalación ejecutable, el comando comprueba el enrutamiento Codex actual e informa una advertencia en lugar de un resultado verde cuando el enrutamiento es externo, de propiedad del usuario o no verificable. También advierte cuando existen variables proxy salientes solo en el proceso actual, mientras que `config.proxy` no está configurado o no se ha resuelto, porque los lanzadores Codex y los servicios en segundo plano pueden no heredar ese entorno. Estas comprobaciones son de solo lectura y nunca imprimen valores de proxy; resuelva el traspaso informado y ejecute `ocx doctor` antes de confiar en el inicio automático. + +En Unix, la reparación automática actualiza solo el envoltorio privado y nunca reescribe el gestor de paquetes Lanzadores o migra una shim más antigua en el lugar. En Windows, si se ha completado una actualización externa de Codex sobrescribe una shim instalada, el siguiente ordinario `ocx` El comando respalda el nuevo lanzador estable y restablece la shim antes del envío. El efecto cero +`ocx system codex-cli-update check` de inspección e invocaciones malformadas en su reserva +`ocx system codex-cli-update` El espacio de nombres nunca realiza esa reparación. `ocx status`, `ocx doctor`, y +`ocx codex-shim status` también omita la reparación automática de la shim e informe el estado observado. Un lanzador que todavía está cambiando se deja intacto y se vuelve a intentar más tarde. Fallas de reparación advierten sin fallar el pedido comando; fallback manual: `ocx codex-shim install`. Establecer `codexShimAutoRestore` a `false`, o establecer +`OPENCODEX_CODEX_SHIM_AUTO_RESTORE=0` para una opción de exclusión a nivel de proceso. + +El contenedor Unix conserva su ruta nativa de lanzador registrada. Los cambios del gestor de paquetes detrás de esa entrada duradera se siguen automáticamente; eliminar esa entrada requiere reparación del gestor de paquetes. Los lanzadores de administradores de comandos dinámicos todavía tienen que pasar la validación anterior. Windows reparación en el lugar necesita el original guardado al lado de la shim; si un gestor de versiones destruye todo el árbol y copia de seguridad, OpenCodex informa de la condición y se detiene en lugar de inventar un original de reemplazo. + +Si el lanzador del gestor de versiones no puede pasar la validación, rutee la configuración Codex en lugar del lanzador: `ocx start` escribe `openai_base_url` y `ocx service install` proporciona autoarranque. Ejecute `ocx status` para confirmar - informa el enrutamiento activo, y advierte cuando un proxy en ejecución no es el Codex se apunta. + +| Subcomando | Medidas adoptadas | +| --- | --- | +| `install` | Instalar la cuña (o reparar si es rancio). | +| `uninstall` | Retire los artefactos privados de Unix, dejando intacto el nativo Codex; el Windows, restaure el lanzador original. | +| `remove` | Alias de `uninstall`. | +| `status` | Informe el estado de la cuña y si el envoltorio privado está activo en PATH. | + +```bash +ocx codex-shim install +ocx codex-shim status +ocx codex-shim uninstall +``` + +Después de desinstalar Unix, elimine la línea de origen del archivo de inicio de shell y reinicie el shell o elimine la entrada de bin privado de su PATH. La desinstalación elimina el envoltorio, el archivo de entorno de shell y el estado propios; deja intacto el lanzador del administrador de paquetes. Se libera una shim Unix más antigua en el lugar utilizando sus datos de restauración registrados. + +:::note[Entorno del token en Windows] +Windows CMD y las shims PowerShell recientemente generadas restauran el número de la persona que llama `OPENCODEX_API_AUTH_TOKEN` Después de la ejecución. Codex y sus procesos secundarios aún pueden heredar el token. + +Después de actualizar OpenCodex, vuelva a crear una shim Windows existente con `ocx codex-shim uninstall` seguido por `ocx codex-shim install` para obtener este comportamiento. Una actualización ordinaria no reescribe una shim Windows saludable. +::: + +:::tip[Servicio y shim] +Uso `ocx service` para un proxy de fondo siempre activo (recomendado). Uso `ocx codex-shim` por arranque ligero bajo demanda sin un demonio — el proxy se inicia solo cuando `codex` es lanzado. +::: + + + +#### Inyección de token en Codex + +En una unión sin retorno de bucle, el proveedor inyectado lleva `env_key = "OPENCODEX_API_AUTH_TOKEN"`. Esa línea indica a Codex qué variable leer; no la crea. Codex se niega a iniciar una solicitud cuando falta la variable (`Missing environment variable: OPENCODEX_API_AUTH_TOKEN`), y el proxy nunca se alcanza. El valor vive en `$OPENCODEX_HOME/service-api-token`; el proceso de lanzamiento debe suministrarlo en el entorno de Codex. + +Utilice la shim mantenida instalada por `ocx codex-shim install`. Cuando el contexto de lanzamiento resuelve esta shim, lee el archivo de token creado por OpenCodex y suministra la variable a Codex. Los lanzamientos de escritorio, cron y servicio deben usar una ruta PATH o un trazado de lanzamiento que seleccione la shim; la instalación no configura esos entornos automáticamente. Los propios procesos hijo de Codex aún pueden heredar el token. + +No exporte este token portador desde un archivo de inicio de shell ni lo copie en `config.toml`. El archivo `service-api-token` contiene el token sin procesar, no las asignaciones `NAME=value`, por lo que no se puede usar directamente como un systemd `EnvironmentFile=`. + +Un `EnvironmentFile=` o `OCX_API_TOKEN_FILE` en `opencodex-proxy.service` configura el proceso proxy solamente y nunca fluye a un `codex exec` lanzado independientemente. + +Las actualizaciones de Unix package-manager dejan el envoltorio privado intacto. Un envoltorio ejecutable que es **No activo** no inyecta el token: fuente del archivo de activación impreso en el shell de inicio. En Windows o con una shim en el lugar más antigua, una actualización Codex que reemplaza el lanzador elimina la shim; en Windows el siguiente comando ordinario `ocx` lo restaura (ver arriba), pero un `codex exec` que corre antes falla. `ocx doctor` informa de este estado exacto bajo "Codex env_key listo para el lanzamiento" (env_key configurado, variable unset, calza faltante o insalubre, archivo de token presente) con reparación o guía de activación, y nunca imprime el token. La lectura del archivo token no forma parte del contrato `env_key` inyectado; el proceso de lanzamiento debe suministrar esa variable. + +### `ocx tray [--json] [--no-start]` + +Instale y controle el icono de la bandeja de estado Windows. Se inicia en el inicio de sesión Windows y proporciona controles proxy con un solo clic. `start` y `stop` controlan el icono solamente; use su menú para controlar el proxy. `--no-start` se aplica a `install` e instala la bandeja sin lanzarla inmediatamente. En desuso: la aplicación de escritorio OpenCodex proporciona la bandeja en Windows, macOS y Linux; `ocx tray` permanece para las instalaciones sin la aplicación de escritorio. Cuando se conoce una versión de paquete más reciente, la bandeja agrega un punto azul a su icono en línea, advertencia o sin conexión y muestra **Actualización disponible**. La bandeja comprueba su insignia local almacenada en caché aproximadamente una vez por minuto; los resultados obsoletos o no disponibles eliminan el punto. El elemento de menú abre el panel de control, donde puede iniciar la actualización del paquete. No se instala automáticamente. + + + +## Panel + +### `ocx gui` + +Abra el [panel web](/es/guides/web-dashboard/) en `http://localhost:` - o en `http://127.0.0.1:` cuando la entrada de administración de concentradores esté habilitada - inicie automáticamente el proxy si no se está ejecutando. + + + +## Actualización + +`ocx update` actualiza OpenCodex en sí; no actualiza el Codex CLI. Utilice el [comandos de inspección del sistema](/es/reference/cli/agents/) para inspeccionar el candidato Codex CLI configurado con inspección de procedencia limitada de solo lectura. `ocx system codex-cli-update check` no consulta un registro de paquetes ni instala una actualización. + +### `ocx update [--tag latest|preview]` + +Las instalaciones independientes compiladas, incluido el paquete de escritorio MSI Windows, se actualizan a través de **Buscar actualizaciones...** en OpenCodex Desktop, o reinstalando el binario independiente desde [GitHub Lanzamientos](https://github.com/lidge-jun/opencodex/releases). `ocx system update check` reporta `installer: "standalone"`, `canUpdate: false` y `reason: "standalone_install"` con esa guía. `ocx update` sale sin éxito con la misma pista; no ejecuta una actualización de gestor de paquetes para el ejecutable compilado. Una comprobación de fuente genuina todavía reporta `installer: "source"` y `reason: "source_checkout"`. + +Cuando OpenCodex se instala a través de mise, este comando sale sin éxito antes de detener el proxy o cambiar los archivos del paquete y muestra `mise upgrade `, utilizando el alias local mise verificado. Las comprobaciones de actualización permanecen disponibles e informan la instalación como administrada externamente. Un registro de propiedad de mise ilegible o inconsistente provoca el rechazo de la operación sin intentar adivinar el nombre de la herramienta, y `--tag preview` nunca cambia la selección configurada de mise. + +En Linux, un servicio en segundo plano cuyo lanzador registrado es el lanzador de paquetes de mise (`/latest/node_modules/.bin/ocx`, no es una mise shim) sigue `mise upgrade` por sí mismo: dentro de unos diez segundos de la nueva versión se establece, drena las solicitudes activas y se reinicia en ella, y se recupera de la misma manera si mise poda más tarde la versión que estaba ejecutando. En macOS, para un servicio instalado a través de una shim de mise, y para un proxy en primer plano, reinicie el servidor después de actualizar (en macOS, `ocx service repair` primero). + +Auto-actualización opencodex de npm. Las instalaciones estables usan `@latest`; las instalaciones de vista previa permanecen en `@preview` a menos que pase `--tag latest|preview`. Detecta una comprobación de origen y le dice que `git pull && bun install` en su lugar, y es una opción prohibida si ya está en la versión más reciente para esa etiqueta. Antes de detener cualquier cosa, las instalaciones npm ejecutan una propiedad de caché Unix limitada y una verificación de acceso. Los enlaces simbólicos anidados se verifican con `lstat` pero no se siguen; Windows omite explícitamente esta comprobación de solo Unix. Un error se aborta mientras la bandeja y el proxy siguen ejecutándose. Un proxy en ejecución se detiene antes de reemplazar los archivos; un servicio instalado se reconstruye y se inicia automáticamente, mientras que una instalación en primer plano imprime `ocx start` como el siguiente paso. Los registros de actualización del panel de control redactan las rutas de perfil/caché y los valores UID/GID antes de que persistan. Cuando la dirección IP literal de un oyente detenido deja caer el dial de vitalidad en lugar de rechazarlo (por ejemplo, en una red Tailscale), el actualizador intenta brevemente vincular esa misma dirección y puerto. Un enlace exitoso confirma la ausencia en ese instante; un enlace fallido o una sonda de nombre de host no concluyente aún impide la actualización. + +En Windows, las instalaciones predeterminadas de Scoop `nodejs` y `nodejs-lts` `npm` se pueden usar desde el directorio de inicio del usuario cuando su unión `current` permanece dentro del directorio de la aplicación Node; también se admite el directorio `bin` persistente predeterminado. Ejecutando dentro de esa instalación (incluyendo su directorio de versiones resueltas o persistentes `bin`), las entradas de directorio de versiones `npm`, `NO_JUNCTION` de project-local y las raíces Scoop personalizadas debajo de la casa permanecen excluidas. + +Si el paso de instalación falla, la versión anterior permanece instalada y su servicio se reinicia; la salida del terminal nombra el siguiente paso, y [Fallo de actualización en Windows](/es/troubleshooting/update-failed/) cubre terminar la actualización y las carpetas que un intento fallido puede dejar atrás. + +```bash +ocx update +ocx update --tag preview +``` + +Las nuevas versiones estarán disponibles cuando el [Liberar el flujo de trabajo](https://github.com/lidge-jun/opencodex/actions/workflows/release.yml) las publique en npm. + + + +## Ahorre umbrales de limpieza sin iniciar una limpieza + +```bash +ocx storage policy show --json +ocx storage policy set --archived-bytes-over 1073741824 --reduce-to-bytes 536870912 --json +ocx storage policy show --json +``` + +El setter escribe anidado `trigger.archivedBytesOver` y un objetivo. Los valores de bytes son enteros no negativos seguros. Alternativamente, elija `--remove-oldest-percent 10` o `--percent 10` heredado; los dos indicadores de porcentaje y reducir a son mutuamente excluyentes. CLI porcentajes son enteros con el servidor-compatible con el rango 1-100. Omitido `--enabled` deja el valor almacenado sin cambios; los valores explícitos son `true` y `false`. El conjunto no se ejecuta en la limpieza, pero un programa ya habilitado permanece vigente. No agregue habilitar o ejecutar una política inmediata a menos que esté previsto. + +El recibo de nuevo campo es `{ok:true,policy,job:{status}}`, con el disparador observado, el objetivo, el modo, la programación y los hechos opcionales de última/siguiente ejecución. `job.status` describe un estado inactivo/de funcionamiento existente, no una limpieza iniciada por este commando. Lee de nuevo sobre un resultado desconocido en lugar de reproducir la escritura. + + + +## Paridad de aplicación de Remote Link + +Un Remote Link Child aplica la configuración de Codex administrada por su Home al enlazarse (`ocx link add` en el Home) y en cada `ocx sync`. Tres datos permiten comprobar que el Child realmente usa la configuración aplicada sin leer los archivos de configuración de ninguno de los equipos. + +`ocx status --json`, en cualquier dispositivo, incluye: + +| Campo | Significado | +| --- | --- | +| `appliedCodexSettingsDigest` | SHA-256 hexadecimal en minúsculas de la configuración aplicada (descrita abajo). En un Child, los valores de la última aplicación registrada. En un Home o una instalación independiente, el documento que sirve actualmente a sus Children, calculado con su configuración actual. Es `null` en un cliente Hub, un Child sin aplicación registrada, o uno cuya aplicación de cambios está en curso o falló (primero se retira el resumen anterior para no informar valores que Codex ya no tiene). | +| `lastApplyAt` | Solo en un Child: milisegundos desde epoch de la última aplicación correcta que cambió los ajustes. Reaplicar los mismos valores conserva la fecha; un `ocx sync` sin cambios nunca fuerza un reinicio. Es `null` en los demás casos. | +| `runtimeStartedAt` | Solo en un Child: milisegundos desde epoch en que arrancó el entorno cliente en ejecución. Es `null` cuando no responde ningún entorno cliente. | + +El resumen se calcula sobre este JSON compacto en UTF-8, con las claves exactamente en este orden, sin espacios y con los valores realmente aplicados: + +```json +{"version":1,"settings":{"fastMode":true,"multiAgentMode":"v1","webSearchSidecarEnabled":false,"subagentDefaults":null}} +``` + +`subagentDefaults` es `null` si no se configura; en caso contrario, es `{"model":…,"reasoningEffort":…}` en ese orden. El ejemplo anterior produce `57c751eff89844f93db71a6ee4acdac03afbc29fec52734ade80a40193e826cd`. El resumen no contiene los valores de los ajustes, y el nombre y la versión del Home no forman parte de él: un Home y un Child que aplicaron los mismos valores informan el mismo resumen. + +En el Home, cada fila de `ocx link status --json` incluye lo último que declaró el Child: `lastApplyAt`, `runtimeStartedAt`, `appliedCodexSettingsDigest` (con los significados anteriores) y `reportedAt` (milisegundos desde epoch según el reloj del Home). El Child informa poco después del arranque y luego una vez por minuto. El Home solo conserva los informes en memoria: tras reiniciarse, los campos son `null` hasta el siguiente informe. Un Child cuyo entorno arrancó antes de `lastApplyAt` ejecuta un entorno anterior a su última aplicación de ajustes. + +Para los enlaces añadidos por Home, cada fila incluye además `tunnel`: `attempt`, cantidad de intentos SSH desde la última conexión; `nextRetryAt`, hora ISO del próximo intento o `null` si hay uno activo o no hay ninguno programado; `lastTransition` (`{from, to, at, cause}`) y `lastFailure` (`{cause, at}`). Las causas posibles son `auth`, `hostkey`, `forward`, `remote_forward_conflict`, `timeout`, `network`, `unknown`, `spawn_failed` y `listener_unavailable`. Home guarda estos datos en memoria, por lo que empiezan vacíos tras reiniciarse. `GET /api/link/status` solo incluye el campo con `?diagnostics=1`, porque las versiones antiguas de `ocx link status` rechazan campos desconocidos. + +Después de aplicar los ajustes del Home en el Child, `ocx sync` reinicia el entorno cliente si arrancó antes de `lastApplyAt`, mediante el mismo mecanismo de `ocx restart`. No modifica un entorno que ya arrancó después de la aplicación ni inicia uno si no hay ninguno en ejecución. Un reinicio fallido termina con código distinto de cero y deja funcionando el entorno anterior; vuelve a ejecutar `ocx sync` o `ocx restart` para reintentarlo. Dos aplicaciones en un Child nunca se intercalan: un segundo `ocx sync` mientras se aplica otro falla de inmediato y no cambia nada. + + + +## Revocación de enlace forzado y recuperación remota + +Solo cuando se pretenda explícitamente omitir la limpieza remota, use el ID de enlace seleccionado real (el `lnk_0123456789abcdef` a continuación es ficticio): + +```bash +ocx link revoke --link-id lnk_0123456789abcdef --force --yes --json +``` + +`--force` requiere `--yes`; `--yes` solo no es válido. La revocación ordinaria no cambia. Un éxito forzado regresa `{linkId,remoteCleanup:"skipped",recovery}`. En su lugar, idempotente link-not-found reporta `remoteCleanup:"unverified"`. Ambos pueden salir de 0; estos hechos derivan de la intención CLI, no de un informe de limpieza del servidor. Ninguno de los dos medios de desconexión remota se intentó o confirmó. Siga la instrucción de recuperación, `ocx disconnect` en el cliente remoto, cuando esa acción esté autorizada. + + + +## Observar el espacio de trabajo remoto desde el Hub + +```bash +ocx remote-workspace hub status --json +ocx remote-workspace hub runtimes --json +ocx remote-workspace hub sessions --json +``` + +Estas lecturas de gestión fija están separadas del ejecutor-local `ocx remote-workspace status`. La disponibilidad en entorno de ejecución es un objeto clave; un concentrador disponible sin dispositivos/sesiones es un éxito vacío. La observación del Hub desactivado puede llegar como HTTP 200 con `available:false` pero sale 1; no es un éxito vacío. El interior HTTP 409 sale por 5. Nunca registra dispositivos, crea sesiones ni envía mensajes. Véase [Observación y recuperación del Hub](/es/guides/remote-workspace/#inspect-the-hub-without-starting-a-session). + + + +## Ciclo de vida del cliente de Remote Hub + +Use `ocx connect --pairing-code-stdin`, `ocx connect status`, `ocx sync` y `ocx connect rotate --pairing-code-stdin`. La descarga inicial del catálogo falla después de cinco segundos sin bytes entrantes, pero las transferencias activas pueden durar más; use `--catalog-timeout ` (1-120) para anular esa ventana de inactividad. `ocx disconnect` restaura el estado local sin conexión y no revoca la clave de concentrador. Mientras está conectado solamente, `ocx connect revoke --admin-token-stdin` revoca el `apiKeyId` persistente; después de desconectar, use la página **Conecte las llaves → API** del concentrador. Los secretos son solo Stdin y nunca pertenecen a Argv. + + + +## Validación del puerto de configuración + +`ocx init` acepta TCP puertos 1-65535 como números enteros decimales. Presione Enter para usar 10100. La entrada no válida como `0`, `10100oops` o `1.5` nunca se reemplaza o trunca silenciosamente; la configuración la informa y vuelve a solicitar el puerto. + + + +## Iniciar sesión registro diagnósticos + +En Linux, `ocx service install` controles `loginctl show-user -p Linger` antes de imprimir el consejo de arranque. La demora habilitada se informa como ya habilitada. La persona desactivada se queda con el `loginctl enable-linger $USER` hint; los diagnósticos faltantes o ilegibles indican la incertidumbre y no fallan la instalación. + +En macOS, `ocx service status` distingue un elemento de inicio de sesión de escritorio cargado de un registro válido habilitado en espera del siguiente inicio de sesión. `ocx status` acredita a este último en seguridad de reinicio cuando la misma aplicación de escritorio supervisa actualmente el proxy. Una etiqueta o comando de lista incorrecto, una entrada deshabilitada, una sonda de carga no verificada o una identidad de proceso cambiada aún no pueden obtener protección. + + + +## Consentimiento personalizado del proveedor Codex + +`ocx codex-provider status` enumera los ID de proveedor aprobados para el hogar seleccionado Codex. `ocx codex-provider allow ` pregunta antes de permitir la administración de solo URL en inicio/sincronización; `--yes` es el consentimiento explícito no interactivo para ese proveedor nombrado. `ocx codex-provider revoke ` restaura una URL administrada sin cambios y revoca el permiso. Estos comandos son locales y no requieren un proxy en ejecución. Ver [enrutamiento de proveedor personalizado](/es/guides/codex-integration/#opt-in-a-custom-provider-to-managed-local-routing) para elegibilidad, comportamiento de restauración y preservación del transporte. diff --git a/docs-site/src/content/docs/es/reference/cli/messaging.md b/docs-site/src/content/docs/es/reference/cli/messaging.md new file mode 100644 index 00000000000..f8e2b097f89 --- /dev/null +++ b/docs-site/src/content/docs/es/reference/cli/messaging.md @@ -0,0 +1,122 @@ +--- +title: "Codex Mensajería" +description: "Cola de mensajes correlacionados con sesiones Codex cargadas localmente o a través de pares SSH explícitos." +--- + +`ocx message` es una superficie opt-in para Codex sesiones existentes. No inicia ningún proxy o servidor de aplicaciones, no reanuda ningún hilo ni instala ninguna habilidad. Linux / macOS Sockets Unix son compatibles; Windows falla explícitamente. El demonio Codex existente debe soportar el experimento `thread/queue/add`. No se requiere un pin de versión CLI o selección `CODEX_CLI_PATH`. + + + +## Descubrir y enviar + +```bash +ocx message sessions --json +printf '%s\n' 'Please review the current change and send your findings back.' | + ocx message send --name 'reviewer' --stdin --json +``` + +Discovery devuelve solo ID de subproceso cargados, nombres y estados en entorno de ejecución, no historial, Vista previa o directorios de trabajo. Utilice una UUID exacta (`--thread`) o una única exacta nombre (`--name`) Los destinos faltantes, duplicados, incompletos o descargados fallan; no hay coincidencia difusa o retroceso a las sesiones almacenadas. + +El socket de control existente se resuelve bajo `CODEX_HOME` efectivo, usando la misma política de inicio que otros comandos de integración Codex. Antes de conectar, el socket resuelto debe ser propiedad de su uid y ser un socket. Cada padre real a través de root debe ser propiedad de su uid o root y no debe ser escribible en grupo u otro, excepto los directorios sticky propiedad de root como `/tmp`. Se permiten casas conectadas cuando pasan sus caminos resueltos. Las rutas no confiables fallan con `untrusted_socket` y sin detalles de ruta resuelta. + +Discovery, la comprobación final de destino cargado y la cola usan una conexión a ese socket. No se produce ningún ayudante nativo CLI, instalación, reparación o reconexión. Un demonio sin soporte de cola local devuelve `unsupported_queue`. + +Solo se acepta UTF-8 stdin, como máximo 16 KiB de texto no vacío sin NUL. Una fecha límite de 30 segundos cubre la entrada, el descubrimiento, la revalidación y la presentación. Cada RPC tiene un límite de 10 segundos. El sobre completo está limitado a 32 KiB. El texto del mensaje se envía a través de la conexión RPC de Unix y nunca se coloca en los argumentos de proceso generados. + + + +## Remitente y respuestas + +La envoltura genera un UUID de mensaje y adjunta el ID/nombre del remitente a partir de metadatos `CODEX_THREAD_ID` y daemon cargados. Este contexto **no constituye una autoridad de pares autenticada** y nunca otorga aprobación o escalamiento al usuario. Un remitente reclamado no válido/descargado falla; el contexto ausente permanece desconocido, sin adivinar una ruta de respuesta. Los mensajes de pares se ponen en cola como texto, no como aprobaciones de permisos o anulaciones de configuración. El arnés del agente receptor hace cumplir sus permisos; la guía del sobre no es un límite de autorización técnica o una garantía del comportamiento del modelo. + +El tipo predeterminado es `request`. Contesta usando el `replyCommand` generado en el sobre, o correlaciona explícitamente una respuesta: + +```bash +printf '%s\n' 'Review findings: ...' | + ocx message send --thread --kind response \ + --in-reply-to --stdin --json +``` + +`response` requiere `--in-reply-to`; otros tipos lo rechazan. Utilice `--kind notification` para un FYI. Responses y las notificaciones no solicitan reconocimientos. Una respuesta final normal del agente no se envía de vuelta a su compañero; las rutas faltantes no deben adivinarse. No se introducen cambios globales de solicitud ni bucles de acuse de recibo. + + + +## Recepción y códigos de salida + +`--json` emite un recibo versionado (`ocx-message/1`) que contiene el mensaje UUID, tipo, correlación de respuesta, metadatos de remitente/objetivo y estado de envío. Nunca incluye el texto del cuerpo o la salida del demonio en bruto. Fallos de entrada/configuración antes de que exista un recibo, use `ocx-message-error/1` con `not_sent`; los fallos de detección usan el mismo esquema de error sin un estado de envío. El uso no válido sale 64 en stderr antes de E/S. + +| Situación | Salir | Descripción | +| --- | --- | --- | +| `not_sent` | 1 | Validación/descubrimiento/revalidación falló, no se escribió ningún marco de cola o el demonio lo rechazó explícitamente. | +| `queued` | 0 | Una respuesta de demonio correlacionada reconoció la presentación, **no procesamiento** por el destinatario. | +| `unknown` | 3 | El mensaje puede haberse enviado a la cola, pero se perdió el acuse de recibo, estaba malformado, no correspondía a la solicitud o se canceló la operación. **No vuelvas a enviar el mensaje.** | + +El UUID de mensaje de aplicación es también el `clientUserMessageId` de la petición de cola. El ID de envío del daemon está separado; ninguno de los dos demuestra el procesamiento del destinatario. La cola no es la dirección y puede esperar a que un giro ocupado para terminar. OpenCodex no realiza ninguna repetición automática, sondeo de seguimiento, persistencia o monitoreo de entrega. La comprobación final del objetivo cargado y la presentación de la cola no son atómicas: si el objetivo se descarga después, un rechazo explícito es `not_sent` con `queue_rejected`; una respuesta perdida o inválida es `unknown`. OpenCodex no lo reanuda ni vuelve a intentarlo. + + + +## Pares remotos explícitos + +La mensajería remota es independiente del enlace remoto y el inicio proxy normal. No redirige proveedores, comparte credenciales de proveedores o inicia un demonio nativo. Ambos nodos necesitan un OpenCodex CLI compatible y un demonio con capacidad de cola existente. Linux tiene pruebas aisladas de interoperabilidad; macOS requiere su propia calificación. Windows el transporte remoto no es compatible. + +En cada nodo, habilite explícitamente la mensajería. En el nodo receptor, mantenga el propietario en primer plano en ejecución: + +```bash +ocx message enable --port 39176 --json +ocx message serve --json +``` + +En el nodo de inicio, use su destino/alias OpenSSH existente. Verifique la huella digital ofrecida contra una fuente confiable antes de confirmarla: + +```bash +ocx message hosts probe --ssh worker --json +ocx message hosts add worker --ssh worker --fingerprint 'SHA256:' --json +ocx message hosts list --json +ocx message serve --host worker --json +``` + +Los registros de sondeo privados mantienen su formato prefijado por alias incluso cuando su configuración SSH normal habilita `HashKnownHosts`; su archivo known_hosts normal no cambia. Cada intento de inscripción utiliza su propio archivo de rascado de clave fija calificado para la transacción, eliminado después de que su ayudante SSH se resuelva, incluidos los fallos, sin depender del bloqueo del propietario de otra mutación. Si la limpieza no se puede confirmar, el comando informa de un resultado de almacenamiento desconocido, no de éxito. El diario de recuperación está separado. + +`hosts add worker` autoriza mensajes salientes a `worker`, **mensajes no arbitrarios en este nodo de inicio**. El intercambio de control SSH autoriza esa dirección de salida en el nodo receptor usando su inicio de sesión SSH existente. El recibo de inscripción y `hosts list` muestran la política de entrada local de cada nodo. En el nodo iniciador, el valor predeterminado es `responses-only`: el par puede ver y responder solo a las sesiones de remitente local originales que esperan una respuesta correlacionada a una solicitud enviada por este nodo. Una respuesta debe coincidir con el UUID de solicitud, la inscripción y el destino local original; no puede dirigirse a otra sesión ni convertirse en una solicitud/notificación no solicitada. + +Para conceder un acceso más amplio en cualquiera de los nodos, ejecute explícitamente en ese nodo: + +```bash +ocx message hosts allow-inbound --json +# Withdraw the broad grant without removing enrollment: +ocx message hosts deny-inbound --json +``` + +`allow-inbound` permite los tres tipos de mensajes en **cualquier sesión local cargada Codex** y expone sus metadatos de directorio a ese par. No es una subvención de solo respuestas. Los cambios de consentimiento se aplican a las conexiones existentes antes de lecturas/envíos posteriores. Los registros más antiguos sin una política de entrada local tienen por defecto `responses-only`, no un acceso amplio. Las rutas de respuesta están limitadas a 256 solicitudes pendientes por propietario en primer plano y caducan después de 24 horas o el retiro / reinicio del propietario. Ningún contexto de remitente significa ninguna ruta de respuesta. Una respuesta en cola o incierta consume su ruta; un rechazo nativo definido no lo hace. Una ruta caducada/perdida requiere una reconciliación explícita entre el operador y el remitente, nunca una repetición automática. + +Cada `serve` es propiedad de primer plano: manténgalo en funcionamiento y use un terminal separado para la mensajería. A lo sumo se pueden suministrar cuatro selecciones de `--host` distintas. Nada instala un servicio o inicia un propietario automáticamente. SSH utiliza claves de host ancladas confirmadas y sus claves/agente configurados; las solicitudes de contraseña están deshabilitadas. La envoltura posee rutas de retorno y de avance solo de bucle, por lo que el nodo receptor puede enviar respuestas correlacionadas sin un inicio de sesión SSH al iniciador, sujeto a la política anterior. + +```bash +ocx message status --json +ocx message sessions --host worker --json +printf '%s\n' 'Please review and reply using the supplied route.' | + ocx message send --host worker --name reviewer --stdin --json +``` + +`--host` selecciona un alias inscrito exacto o UUID de máquina. Los comandos de respuesta incluyen el UUID de máquina de origen validado y el UUID de subproceso; la identidad de origen se resuelve en el demonio de origen, no se adivina desde un directorio remoto. Sin el contexto del remitente, no hay un comando de respuesta inventado. Los comandos locales sin `--host` conservan su ruta sin estado/sin SSH/sin oyente. El receptor valida la envolvente canónica completa contra el UUID de máquina y mensaje nativo autenticado, incluyendo el host/comando de respuesta y la guía de pares estándar. Un par no puede etiquetar el envoltorio como otro equipo u omitir su advertencia de no mensaje de usuario. Los nombres de sesión y los identificadores de subproceso siguen siendo reclamos descriptivos de esa máquina, no autenticación por sesión. + +Las capacidades direccionales emitidas por el receptor se guardan en el estado privado de mensajería bajo `OPENCODEX_HOME` o el directorio de configuración predeterminado de OpenCodex. Nunca aparecen en la salida habitual de comandos, argumentos auxiliares, URL ni sobres de mensajes. Las pruebas mutuas autentican la conexión WebSocket real antes de aceptar tramas nativas o el cuerpo del mensaje. Una comprobación de salud por separado no demuestra la identidad del par. Este es un protocolo de pasarela de OpenCodex: `codex queue --remote` por sí solo no implementa su autenticación. La pasarela usa el mismo contrato nativo experimental `thread/queue/add` y no modifica `--ws-auth` de Codex, su configuración ni sus listeners nativos con token bearer. Solo expone metadatos de hilos cargados y colas de texto, no el control general del app-server. + +El estado distingue la configuración habilitada, un propietario en ejecución y rutas iniciadas/alquiladas. Los arrendamientos de devolución caducan después de 25 segundos sin actualizar; no son recibos de entrega o procesamiento. La pérdida de una ruta o el cambio de configuración del propietario requiere un reinicio explícito del propietario. La recuperación del transporte nunca reenvía un mensaje incierto. + +```bash +ocx message hosts remove worker --json +ocx message disable --json +``` + +La eliminación revoca la admisión local primero; una limpieza remota no confirmada sale de 3 y también requiere la eliminación de ese par. Cada eliminación saliente utiliza un archivo independiente de scratch de clave fija; un fallo en la preparación de ese archivo aún informa la eliminación local y la limpieza remota no confirmada. La limpieza de rasguños se intenta tanto en el éxito como en el fracaso. La guía de limpieza generada utiliza `hosts remove --transaction --json`; el guardia de transacciones rechaza un recibo antiguo en lugar de eliminar una inscripción más reciente. La eliminación ordinaria sin este protector opcional sigue eliminando el par seleccionado actualmente. Deshabilitar retira la generación actual del propietario; el despacho rechaza el nuevo trabajo inmediatamente, y el propietario en primer plano nota una configuración cambiada dentro de su intervalo de mantenimiento de diez segundos. El remitente vuelve a verificar la autoridad local inmediatamente antes del envío; la revocación tras el envío no puede recordar un mensaje en vuelo o un trabajo nativo ya aceptado. Una respuesta de inscripción perdida retiene una transacción privada: repita exactamente el mismo comando add para reconciliar, en lugar de inscribirse con otro nombre dentro de la misma generación habilitada. Deshabilitar/rehabilitar o cambios de puerto invalidan esa generación de recuperación. Las transacciones completadas o revocadas no pueden restaurar un par eliminado ni borrar el registro de recuperación de otra inscripción. Si el diario local guardado ha malformado JSON, las formas de registro o los valores de campo, `hosts add`, `hosts list`, `status` y `hosts abandon` se desechan con `invalid_enrollment_journal`. Sus bytes se conservan para la recuperación explícita del operador; OpenCodex no lo repara, reemplaza o elimina automáticamente. `hosts add` no envía ninguna solicitud de control de inscripción en este caso, aunque puede ejecutarse su sonda de clave de anfitrión preliminar. El almacenamiento inseguro o un bloqueo de mutación ocupado conserva su clasificación de error separada. Si un diario válido ya no se puede conciliar, inspeccione `ocx message hosts list --json` o `ocx message status --json` para `pendingEnrollment` (alias, UUID de transacción y si su generación es obsoleta), luego abandone explícitamente ese diario local exacto: + +```bash +ocx message hosts abandon --transaction --json +``` + +Abandonar la transacción también funciona cuando la función está desactivada. Conserva los pares existentes, no reintenta la inscripción y termina con código 3 porque la limpieza remota no está confirmada. Si queda una inscripción huérfana, sigue las instrucciones de limpieza en el nodo remoto. Los diarios obsoletos no se borran silenciosamente. Un receptor lleno devuelve `peer_capacity` sin inscribir al par: libera un espacio y repite la misma transacción o abandónala explícitamente. Las respuestas de control perdidas o mal formadas mantienen el resultado incierto. Se aceptan directorios de configuración existentes, confiables y con permisos 0755 sin ejecutar chmod; el subdirectorio de mensajería sigue siendo privado. Un reinicio inmediato del proceso propietario puede reemplazar una concesión de retorno obsoleta cuando el nuevo endpoint se autentica y el anterior deja de hacerlo dentro de una comprobación de un segundo. Un endpoint anterior que todavía se autentica conserva su concesión hasta que venza; una falta temporal de acceso puede permitir el relevo, pero no la repetición. La pérdida inesperada del túnel retira visiblemente al propietario en primer plano; eliminar un par de forma deliberada deja funcionando las rutas no relacionadas. Los bloqueos de modificación que quedan tras un fallo impiden continuar y requieren recuperación del operador; el envoltorio nunca supone que un bloqueo antiguo fue abandonado. La publicación del estado y del diario de recuperación sincroniza el archivo y su directorio antes del trabajo remoto dependiente; eliminar el diario también sincroniza el directorio. `remote_storage_unknown` (salida 3) significa que no se pudo confirmar la persistencia del cambio de almacenamiento ante un fallo. En macOS, un rechazo de ACL o un fallo del sondeo después de reemplazar el archivo también produce este código: el estado nuevo ya es visible, pero su privacidad mediante ACL y su persistencia ante un fallo siguen sin confirmarse. Inspecciona el estado y los permisos antes de realizar una recuperación explícita; no reintentes ni reviertas automáticamente. Un diario que se puede leer de forma segura, pero contiene JSON o un esquema mal formado, no impide eliminar pares y se conserva para la recuperación del operador. El almacenamiento inseguro o la imposibilidad de invalidar un diario coincidente siguen impidiendo la eliminación. + +El propietario en primer plano comparte límites finitos de conexión/solicitud/ayudante/memoria intermedia entre todos los pares y rechaza la sobrecarga sin una cola ilimitada: los pares inscritos juntos pueden contener doce conexiones autenticadas, cuatro más permanecen reservadas para el propio control del propietario, sondas salientes y renovación, y como máximo ocho hijos de túnel y dos ayudantes de control/inspección transitorios, diez en total. La configuración está limitada por 30 segundos en todo el lote de pares seleccionado. Una renovación final del contrato de arrendamiento precede al éxito del inicio; los lotes de renovación final y periódica tienen plazos de cinco segundos, dentro de la fecha límite de configuración cuando corresponda, y el mantenimiento periódico se ejecuta cada diez segundos. La cancelación deja solo a los ayudantes / oyentes de SSH; deja solos a los demonios, hilos y proxies no relacionados con Codex. La limpieza también se une a las rutas de túnel retiradas. Direct - la salida del niño y la tubería natural EOF deben establecerse dentro del techo de limpieza de tres segundos; de lo contrario, la limpieza está incompleta y la reserva de ayudante permanece cargada. La cancelación de las tuberías retenidas no prueba que los descendientes hayan salido. Los descendientes separados o descendientes que cierran pipas heredadas no son rastreados. La captura de Stdout Helper está limitada a 64 KiB; stderr se descarta sin ser impreso o almacenado. Después del desbordamiento de captura, el ayudante se detiene y la salida descartada se drena a EOF natural. La limpieza exitosa informa el error de salida original; la limpieza genuinamente incompleta sigue siendo `cleanup_incomplete` y mantiene su reserva de ayudante cargada. Los procesos del mismo uid pueden leer el estado de inscripción privada; la autenticación de máquina no establece una identidad por agente no falsificable. El tráfico nativo que pasa por alto esta puerta de enlace no está controlado por ella. + +Malla, controles de panel/caché, aislamiento, mensajería Claude, habilidades administradas y notificaciones inactivas permanecen fuera de esta contribución. diff --git a/docs-site/src/content/docs/es/reference/cli/providers-accounts.md b/docs-site/src/content/docs/es/reference/cli/providers-accounts.md new file mode 100644 index 00000000000..60adbddd0f6 --- /dev/null +++ b/docs-site/src/content/docs/es/reference/cli/providers-accounts.md @@ -0,0 +1,768 @@ +--- +title: "CLI Proveedores, cuentas y modelos" +description: "Comandos de configuración, credenciales, cuota y catálogo de proveedores." +--- + +Estos comandos configuran proveedores ascendentes, autentican cuentas, administran grupos de credenciales y controlan el catálogo de modelos expuesto a Codex. + +Los errores de argumento sobrante de `account list`, `account current`, perfiles principales nativos y comandos de proveedor redactan valores de opciones de credenciales, incluidos `--code`, `--token`, `--api-key`, `--key`, `--secret`, `--password` y `--admin-token`, en ambos formularios `--option value` y `--option=value`. El registro de proveedores locales utiliza `ocx provider add --api-key `; se rechaza un `--api-key=` en línea con su valor editado. `ocx provider edit` no acepta `--api-key`. + + + +## Proveedores + +### `ocx provider ` + +Gestión de proveedores no interactivos. Las entradas del registro se siembran por nombre; un nombre personalizado requiere tanto `--adapter` como `--base-url`. + +| Subcomando | Banderas soportadas | Medidas adoptadas | +| --- | --- | --- | +| `list` | `--json`, `--jsonl` | Listar los proveedores configurados y las entradas de registro restantes; `--jsonl` emite un objeto de proveedor configurado por línea. | +| `add ` | `--adapter `, `--base-url `, `--api-key `, `--responses-path `, `--auth-mode `, `--default-model `, `--set-default`, `--force`, `--json`, `--sync`, `--live` | Guardar localmente de forma predeterminada; `--sync` intenta la sincronización del cliente en cualquier modo de salida. `--live` escribe a través del proxy en ejecución y no puede combinar con `--sync`. `--force` permite la sobreescritura. | +| `edit ` | banderas de campo de proveedor, `--headers `, `--model-context-tier `, `--upstream-http-version `, `--fast `, `--context-window `, `--json` | Edite los campos de proveedores activos validados sin reemplazar los grupos de claves. Repita `--model-context-tier` para varios modelos de Copiloto. `--headers` fusiona encabezados de solicitud personalizados; pase `{}` o `-` para borrarlos. | +| `test ` | `--model `, `--yes`, `--json` | Verifique el descubrimiento; con `--model`, solicite una prueba de finalización confirmada. | +| `show ` | `--json` | Mostrar la configuración con las claves API enmascaradas. | +| `remove ` | `--json`, `--live`, `--yes` | La eliminación local rechaza el proveedor predeterminado y el último. La eliminación en vivo requiere `--yes` y utiliza comprobaciones de dependencia del servidor, reasignación predeterminada y limpieza de cuenta / modelo personalizado. | +| `set-default ` | `--json`, `--live` | Seleccione un valor predeterminado local o actualice el proxy en ejecución con `--live`. | +| `pacing ` | `--json`, `--enabled `, `--rpm `, `--min-interval-ms `, `--max-concurrent `, `--file ` | Lea las reglas configuradas y el estado en tiempo de ejecución; actualice escalares o reemplace las reglas de un archivo. Las banderas de archivo y escalar son exclusivas. | +| `snapshot` | `--json` | Lea un documento de proveedor-editor público redactado y validado desde el proxy en ejecución. | +| `apply` | `--baseline `, `--file `, `--yes`, `--json` | Aplique un documento editor revisado con una comparación de línea de base; las eliminaciones / cambios de nombre requieren `--yes`. | +| `selected ` | `--set `, `--clear`, `--json` | Lea o actualice la lista de permisos del modelo de proveedor. | +| `quota` | `--refresh`, `--json` | Lea los informes de cuotas de proveedores. | +| `resets` | `--limit `, `--json` | Listar los restablecimientos de ventana de cuota detectados recientemente. | +| `presets` | `--json` | Listar los ajustes preestablecidos del proveedor del panel de control. | +| `account-mode` | `pool`, `direct`, `--json` | Seleccione el enrutamiento de cuenta agrupado o directo Codex. | + +```bash +ocx provider list --json +ocx provider list --jsonl # one configured provider object per line +ocx provider test ark +ocx provider add anthropic --set-default --sync +ocx provider add local-dev --adapter openai-chat --base-url http://localhost:11434/v1 +ocx provider show anthropic --json +ocx provider edit github-copilot --model-context-tier gpt-5.6-luna=long_context +ocx models --provider anthropic --json +ocx models live --provider ark --json +``` + +`--jsonl` escribe solo proveedores configurados, un objeto JSON por línea, y omite el resumen `registryCount` de `--json`. Cada objeto tiene los mismos campos que un elemento en la matriz `configured`. Utilícelo para scripts que procesan un objeto de proveedor configurado por línea. `--json` y `--jsonl` no se pueden combinar. + +Cada fila configurada también incluye `active`. Es `false` cuando este dispositivo está enlazado con un Home (como Remote Link Child o cliente en modo Hub): la fila describe configuración local que queda sustituida por los proveedores del Home y no atiende solicitudes mientras el enlace esté conectado. Es `true` cuando la fila sí atiende solicitudes, incluso si no se puede leer el estado del enlace. Las filas nunca contienen credenciales: `baseUrl` elimina las credenciales incluidas en la autoridad de la URL y oculta valores de consulta con nombres de credenciales, como `key` o `token`, conservando parámetros normales como `api-version`. + +:::caution[Los encabezados personalizados no son un canal para credenciales] +`--headers` es para los metadatos de solicitud no secreta — sugerencias de enrutamiento, inquilino o selectores de proyectos, identificaciones de rastreo. Es **no** un lugar para poner autenticación material, y el validador rechaza los nombres de encabezado de credenciales estándar (`Authorization`, `X-Api-Key`, `Cookie`, y el resto) con un puntero a +`apiKey` / `authMode`. + +El validador no puede reconocer un nombre arbitrario como `X-My-Token`, por lo que el límite es suyo para respetar. Dos razones por las que importa: + +- El JSON es un argumento de línea de comandos, por lo que un secreto en él aterriza en la historia de la shell y en la lista de procesos, donde cualquier otro proceso en la máquina puede leerlo antes de que el CLI redacte algo. +- Los valores de encabezado se mantienen en `config.json` en texto claro, a diferencia de las claves API, que tienen su propio camino de almacenamiento y enmascaramiento. + +Utilice el inicio de sesión de credenciales compatible o el flujo stdin para la entrada secreta. No coloque claves en una transcripción de agente o copiarlas en ejemplos de comandos. +::: + + + +### Estado de los locales guardados y del proveedor en vivo + +Comience con el descubrimiento fuera de línea: `ocx provider --help`, luego `--help` de la hoja. `list` y `show` leen la configuración local; `add`, `remove` y `set-default` también usan configuración local a menos que se indique `--live`. Otras operaciones de administración de proveedores a continuación requieren un proxy en ejecución. Compruebe `ocx ready --json` y `ocx status --json` antes del trabajo en vivo para confirmar el objetivo y la versión previstos. Una lista local no establece que el proxy adoptó un cambio guardado. + +Local `provider add --json` informes `needsSync: true`. La adición de `--sync` realmente intenta la sincronización tanto en JSON como en los modos de salida humanos. Su recibo suma `sync: {status, ok}`; solo `status: "applied"` con `ok: true` despeja `needsSync`. Sin proxy (`not-running`), la sincronización rechazada o la sincronización fallida devuelve un valor distinto de cero al tiempo que conserva el guardado local. Los resultados omitidos por políticas o solo por catálogo pueden salir de 0 con `needsSync: true`; no son una sincronización de cliente aplicada. La propiedad del catálogo o los rechazos de seguridad de configuración guardada dejan el catálogo sin cambios, devuelve la salida 1 y muestra la guía de recuperación en la salida humana o `sync.warning` en JSON, incluso si la inyección de configuración tuvo éxito. + +Para cambios en vivo autorizados: + +```bash +ocx provider snapshot --json +ocx provider add anthropic --live --json +ocx provider set-default anthropic --live --json +ocx provider snapshot --json +``` + +Live add utiliza los ajustes preestablecidos del objetivo y rechaza un proveedor existente observado sin `--force`. El upsert de comprobación y servidor no son atómicos: los cambios simultáneos pueden acelerarse. Los proveedores personalizados todavía necesitan `--adapter` y `--base-url`. `--live` nunca vuelve a caer en un salvamento local; combinarlo con `--sync` no es válido. Las credenciales pertenecen al login humano soportado o al flujo stdin, no a CLI ejemplos. + +Para eliminar un proveedor autorizado, utilice `ocx provider remove --live --yes --json`. El servidor comprueba las dependencias y aplica la reasignación predeterminada y la limpieza de la cuenta/modelo personalizado. Inspeccione el recibo y lea de nuevo el destino después de escribir. + +Un recibo en vivo puede ser `{"success":true,"name":"example","catalogRefresh":{"status":"committed","changed":true,"degraded":false,"notices":[]}}`. `success` significa que la configuración persistió; no prueba por sí misma la convergencia del catálogo. Por ejemplo, `{"success":true,"name":"example","catalogRefresh":{"status":"skipped","reason":"busy","retryable":true}}` devuelve la salida 1 aunque el guardado haya tenido éxito. La actualización fallida o los saltos para `stale`, `refused` y `catalog-unavailable` también devuelven un valor distinto de cero. Conservar avisos degradados. Nulo, ausente o `not-requested` actualización puede salir 0 sin una sincronización de cliente. Lea antes de la recuperación; no repita una escritura persistente para reparar la convergencia. Los errores usan prosa segura en stderr, incluso en el modo JSON, en lugar de un sobre de error JSON. + +`provider test ` sin `--model` comprueba la conectividad de descubrimiento de modelos aguas arriba. Una conexión fallida sale 1; éxito y un catálogo estático sin salida 0 de punto final de descubrimiento aplicable. `applicable: false` es un resultado estático-catalógico esperado, no una inferencia exitosa o una conexión fallida. + +Para enviar una solicitud de finalización para un modelo elegido, utilice: + +```bash +ocx provider test my-relay --model my-model +ocx provider test my-relay --model my-model --yes --json +``` + +Esta prueba puede incurrir en cargos del proveedor. Un terminal interactivo pide confirmación; `--yes` acepta la advertencia de cargo. El uso no interactivo y `--json` requieren `--yes`. Usar `--yes` sin `--model` es un error de uso. La confirmación declinada no envía ninguna petición y sale 1. El comando usa la gestión del proxy en ejecución API. + +La prueba de finalización envía el mensaje fijo `Reply exactly OK.`, solicita un límite de salida de 32 tokens, se detiene después de 20 segundos o 64 KiB y nunca vuelve a intentarlo o falla. Es compatible con los proveedores locales de OpenAI Chat y Responses, incluidas las anulaciones de cables por modelo. Deshabilitado, OAuth, adaptador reenviado y no soportado o configuraciones de transporte devuelven una razón de aplicabilidad sin enviar una finalización. TLS perfiles, HTTP pines de versión, habilitada solicitud de ritmo y albaceas personalizados con un proxy de proveedor de anulación no son compatibles actualmente. + +Los resultados incluyen el tiempo hasta el primer delta de texto (TTFT), la latencia total, los identificadores de modelo solicitados y de cable, los metadatos de modelo ascendente desinfectados y una coincidencia, desajuste o comparación desconocida distinta. Se desconocen los metadatos faltantes o conflictivos. La comparación utiliza el id aguas arriba antes del enmascaramiento, contra el id realmente enviado después del manejo de alias y sufijos. Los metadatos informados por el proveedor no pueden verificar la identidad del modelo: `identityVerified` es siempre `false`. No se devuelve el texto generado. Una finalización fallida sale 1; el éxito y un resultado no aplicable salen 0. + + + +### Configuración de transporte y ritmo de solicitud + +`provider edit` ya está en vivo. Utilice `--upstream-http-version http1.1` para fijar ese protocolo, o `--upstream-http-version -` para borrarlo. `--fast on|off` alterna rápidamente; `--context-window N` establece una anulación de proveedor positiva y `--context-window -` la borra. Los ajustes omitidos permanecen sin cambios; cero no es una operación clara. + +```bash +ocx provider pacing anthropic --json +ocx provider pacing anthropic --enabled on --rpm 30 --min-interval-ms 1000 --max-concurrent 2 --json +ocx provider pacing anthropic --json +``` + +La lectura devuelve `{provider, rules, status}`. `rules: null` significa no configurado; `status` contiene observaciones separadas de cola/temporización en entorno de ejecución. Los indicadores numéricos solos no habilitan un bloque no configurado; `--enabled off` desactiva el ritmo. RPM acepta valores fraccionarios positivos validados. Intervalo/concurrencia requieren enteros positivos. + +Las ediciones escalares preservan las reglas del modelo observadas, pero PATCH reemplaza todo el bloque sin CAS, por lo que se puede sobrescribir una edición concurrente. Utilice la instantánea/aplicar debajo cuando se requiera una comparación de línea base. Para un objeto de reglas completas, incluyendo reglas específicas del modelo, use `ocx provider pacing anthropic --file pacing.json --json`. Un archivo de reglas mínimas es `{"enabled":true,"requestsPerMinute":30}`. El modo archivo reemplaza todo el bloque y no se puede combinar con banderas escalares. `--file -` lee stdin canalizado; se aplican los límites de entrada a continuación. + + + +### Instantánea, editar y aplicar con una línea de base + +Mantenga el mismo host previsto y el contexto CLI en estos pasos. La fijación de objetivos dura dentro de una invocación; las instantáneas no contienen ningún token de identidad de destino. + +```bash +ocx provider snapshot --json > providers.baseline.json +cp providers.baseline.json providers.next.json +``` + +Edite el siguiente archivo y revise la diferencia mientras conserva la línea base original. Cada documento contiene exactamente `{defaultProvider, providers}`. Snapshot es una proyección de editor de solo lectura, no una exportación de configuración sin procesar. No agregue campos secretos, derivados o desconocidos: las credenciales, cualquier campo `headers` y los marcadores de visualización (`hasApiKey`, `hasHeaders`, `xaiResponsesOptInState`, `initialModelSelection`) no son editables por lotes. La exportación de configuración sin procesar puede exponer credenciales y pertenece a un terminal operado por humanos fuera de una sesión de agente. + +```bash +ocx provider apply --baseline providers.baseline.json --file providers.next.json --json +ocx provider snapshot --json +``` + +Agregue `--yes` solo para eliminaciones o cambios de nombre revisados y autorizados. Batch PUT conserva los valores privados intactos y utiliza la línea de base pública para detectar conflictos. Hace **no** realizar la limpieza de la cuenta OAuth de un solo proveedor DELETE. HTTP 409 devuelve la salida 5: tome una nueva instantánea, revise los cambios simultáneos y reconstruya la edición propuesta. No reemplace la línea base ni vuelva a intentarlo automáticamente. Los resultados de escritura desconocidos requieren inspección, no una suposición de retroceso. + +Use archivos UTF-8 JSON regulares o explícitos canalizados `-`; como máximo una entrada por lotes puede ser stdin. Cada entrada tiene un límite de 4 MiB y una fecha límite de lectura de 30 segundos. La solicitud serializada combinada `{baseline,next}` también debe ajustarse a 4 MiB. Interactivo stdin, archivos especiales, banderas conflictivas, campos no válidos y eliminaciones no confirmadas son rechazadas antes de la mutación con la salida 2. Los errores de entrada nunca se hacen eco de los valores enviados. + + + +## Autenticación + + + +### Diagnosticar la cuota de cuenta principal faltante + +`ocx account list openai --quota --refresh --json` incluye un objeto `quotaRefresh` en la fila de la cuenta principal cuando esa operación intenta una lectura de uso WHAM. La respuesta existente `GET /api/codex-auth/accounts?refresh=1` expone el mismo diagnóstico. + +Su `status` es `ok`, `not_reported` (no hay cuota parseable en una respuesta exitosa), `http_error`, `timeout`, `network_error`, `invalid_response`, o `internal_error`. Solo `http_error` incluye un `httpStatus` numérico. Este objeto no incluye ninguna respuesta sin procesar, mensaje de error, credencial o identificador de cuenta. Las lecturas de solo caché, los aplazamientos de credenciales y las instantáneas de cuenta invalidadas lo omiten; los servidores más antiguos también lo omiten. La ausencia no es prueba de éxito. Un estado de no éxito HTTP permanece `http_error` incluso si su cuerpo de error no se puede leer; `timeout` y `network_error` describen fallos antes de cabeceras o mientras se lee una respuesta exitosa. + +Un inicio de sesión válido no garantiza que esta solicitud de uso por separado tenga éxito. Estas categorías no cambian las reglas de autenticación, selección de cuenta o actualización de cuota, y no convierten cuota desconocida en uso cero. Este diagnóstico actualmente cubre la cuenta principal nativa, no las actualizaciones de la cuenta de grupo. Al informar sobre la cuota faltante, comparta la categoría y el estado HTTP en lugar de archivos de credenciales o una captura de red en bruto. + +### `ocx login ` + +Inicie el flujo de acceso registrado del proveedor. OAuth -Los proveedores de cuentas de estilo abren un navegador y almacenan las credenciales bajo `~/.opencodex/` (los tokens actualizables rotan automáticamente; las concesiones de claves duraderas como OrcaRouter se reutilizan hasta que el proveedor las revoca); API -los proveedores de inicio de sesión con clave abren su panel de control de clave, solicitan la clave, la validan cuando es posible y guardan la configuración del proveedor resultante. El comando imprime los identificadores de proveedor de clave OAuth y API actualmente aceptados cuando el nombre falta o es desconocido. + +Los inicios de sesión fallidos OAuth salen con el estado 1 e imprimen un diagnóstico fijo: el estado HTTP y el código de error estándar OAuth (como `invalid_grant` ) cuando el proveedor devuelve uno, `network_error` o `timeout` cuando no se pudo llegar al proveedor, `configuration_error` con el motivo de que una configuración local como un espacio de nombres de cuenta Codex bloquea el inicio de sesión y `oauth_authentication_failed` de lo contrario. Pool 2 ( `anthropic2`) también informa `configuration_error` antes de solicitar cuando un proveedor personalizado posee ese nombre o su archivo de configuración no se puede leer o analizar. + +Utilice el mismo comando para **reautenticar** después de `ocx status` / `ocx doctor` informes de reautenticación requerida o un fallo de actualización de terminal (o utilice Reautenticar en el panel de control). Codex cuentas de grupo no son uno de esos OAuth o API -proveedores clave, pero `ocx login codex` llega a ellos de todos modos: se dirige al inicio de sesión de grupo de cuenta, por lo que `ocx login codex --reauth` es lo mismo que `ocx account reauth codex`. El grupo de cuentas del panel Codex (Reautenticate) también lo hace. Esa ruta se ejecuta dentro del proxy, por lo que necesita uno en ejecución. + +Para el ChatGPT OAuth proveedor, un código OAuth terminal explícito confirmando una concesión de actualización caducada o revocada requiere iniciar sesión de nuevo. Las descripciones de texto libre por sí solas nunca requieren una nueva autenticación. Los fallos temporales del servicio de tokens, los tiempos de espera y la cancelación dejan a la cuenta elegible para una actualización posterior. El intercambio y actualización de tokens del navegador tienen una fecha límite de 30 segundos por cada búsqueda que cubre los encabezados y el cuerpo. HTTP -los errores derivados muestran solo el estado y un código OAuth permitido. Cancelación, tiempo de espera y fallos de transporte utilizan mensajes fijos sin la razón original o causa. + +```bash +ocx login xai +ocx login anthropic +ocx login orcarouter-oauth # browser consent + S256 PKCE +ocx login orcarouter # paste an existing API key +ocx login anthropic --headless # no browser, no local port +``` + +`--headless` ejecuta el inicio de sesión **code-display** para los hosts cuyo navegador no puede llegar a la devolución de llamada del proxy (contenedores, servidores remotos). El comando imprime una URL de autorización; apruébela en cualquier navegador y el proveedor muestra una cadena `code#state` para volver a pegar en el símbolo. No hay ningún puerto de devolución de llamada y no se inicia ningún navegador. Solo `anthropic` y `anthropic2` lo admiten hoy en día; cualquier otro proveedor sale con la lista de proveedores que lo hacen. Para Codex cuentas utilizan el inicio de sesión de código de dispositivo en su lugar, `ocx account login codex --device` - `ocx login codex --headless` se rechaza en lugar de pasar. La ventana de pegado es de 10 minutos, y cada inicio de sesión acepta un código: si el intercambio falla, inicie un nuevo inicio de sesión. Un inicio de sesión exitoso se convierte en la cuenta activa del proveedor, exactamente como un inicio de sesión del navegador. + +La reautenticación OAuth conserva la configuración del operador, como selecciones de modelo, anulaciones de precios, y preferencias de conmutación por error de cuenta. Campos de transporte/autenticación de inicio de sesión y de registro Se actualizan los metadatos del catálogo. Un proveedor de live-discovery mantiene su modelo predeterminado seleccionado; un El proveedor estático puede reemplazar un valor predeterminado que ya no existe en su catálogo actualizado. + +Para Antigravity, un `401` ascendente puede actualizar la credencial OAuth de la cuenta rechazada y volver a intentar la solicitud una vez. El reintento utiliza el proyecto Cloud Code Assist de esa credencial. Si la actualización falla o no hay ningún proyecto utilizable disponible, la solicitud devuelve un error de autenticación; use el flujo de reautenticación anterior. Un segundo `401` no inicia otro ciclo de refresco/reintentar. Un `403` que solicita verificar la cuenta pone en cuarentena esa credencial como `needs-reauth(verify)`; cuando la conmutación por error de la cuenta está habilitada, la solicitud puede volver a intentar en otra cuenta elegible. Complete la verificación de la cuenta de Google, luego ejecute `ocx login google-antigravity`. La actualización silenciosa del token no borra este requisito de verificación. Si OpenCodex no puede guardar la cuarentena, este intercambio de adaptador conserva el `403` original sin otro envío de recuperación; la cuenta no se ha puesto en cuarentena de forma duradera. Si no se puede construir o admitir una solicitud de hermano para el envío, el intercambio entrega el `403` original a través del formato de error normal. Un combo adjunto o una ruta de directiva aún pueden aplicar sus reglas de reserva existentes. + +Para las solicitudes de búsqueda web basadas en la búsqueda, la rotación automática de hermanos solo acepta un sobre de error Google completo y limitado que contiene `error.details[].reason === "VALIDATION_REQUIRED"`. La redacción de verificación por sí sola no rota. Esta recuperación con alcance de solicitud utiliza el token y el proyecto del hermano sin que persista una marca de `needs-reauth`; la cancelación, la salida comprometida, el agotamiento del presupuesto o un hermano no disponible conserva el error. + +Un proxy que ya se está ejecutando recoge la nueva credencial sin un reinicio: el CLI le pide que vuelva a cargar ese proveedor desde el disco, y la solicitud no tiene credenciales propias. Si el proxy en ejecución no puede aceptar esa solicitud, la mayoría de las veces porque comenzó a partir de una compilación anterior a la recarga certificada, el inicio de sesión aún tiene éxito y la credencial todavía se escribe en el disco, pero el proceso en vivo sigue sirviendo al anterior. El CLI lo dice y te pide que reinicies: + +``` +⚠️ A proxy is running but could not reload this provider (unattested-target). + The credential is saved to disk; the running proxy keeps using the previous one. + Restart it to pick this up: ocx restart +``` + +### `ocx logout ` + +Quite la credencial OAuth almacenada localmente de forma predeterminada. `--json` reporta `{schemaVersion:1, ok, provider, removed}`; las credenciales faltantes devuelven `reason: "not_found"` y la salida 4, mientras que la eliminación devuelve la salida 0. + +Para un cierre de sesión solicitado en el proxy en ejecución, `ocx logout --live --json` acepta OAuth proveedores públicos y devuelve `{schemaVersion:1, success:true, provider, live:true}`. No cierra la sesión Codex /native-main ni elimina una cuenta seleccionada. Nunca elimina las credenciales locales antes de la solicitud en vivo o vuelve a la eliminación local después de un error. + + + +## Cuentas y grupos de claves + + + +### Política Pool, umbrales de cuenta e intención de crédito pagado + +Lee la ayuda sin conexión y, a continuación, la política del objetivo seleccionado antes de cambiarla: + +```bash +ocx account pool --help +ocx account pool openai --json +ocx account pool anthropic --json +``` + +Estas son las lecturas de gestión en vivo. La respuesta incluye `provider`, `kind`, `supported`, la política almacenada nullable, `enabledEffective` y opcional `inert`. Sólo los campos nombrados por `supported` se pueden escribir; nulo no es falso, y una política inerte no es agrupación activa. Los umbrales cero y `enabled:false` son independientes. Utilice `--enabled on|off`, `--threshold 0..100`, `--strategy`, `--sticky 1..100` y `--quota-window` solo donde sea compatible. OpenAI no admite escrituras de agrupación/ventana habilitadas; `reset-first` es para OpenAI y genérico OAuth grupos (nunca Anthropic), `least-loaded` Kiro -sólo, y Anthropic ventanas son `five-hour`, `weekly`, `max-utilization`. Los campos omitidos permanecen sin cambios. Los campos de lectura DTO como rutas, concurrencia por cuenta o Anthropic `nativeMessages` no implican un setter en este comando; use solo las opciones CLI enumeradas. Se persistía un guardado que devuelve `warning: "config_bookkeeping_failed"`, pero necesita una lectura nueva para confirmar el estado en vivo. + +```bash +ocx account pool anthropic --threshold 80 --quota-window five-hour --json +ocx account pool anthropic --json +ocx account auto-switch openai status --account --json +``` + +Un `--account` explícito selecciona el umbral OpenAI por cuenta. Las acciones son `status`, `on` (80), `off` (0), `inherit` (nulo), o `threshold N` (0-100). Sin `--account`, el comando de conmutación automática existente permanece en el grupo. El resultado es `{ok, id, autoSwitchThresholdOverride, autoSwitchThreshold}`; lea la anulación anulable y el valor efectivo observado por separado. + +El uso de crédito pagado después de la cuota incluida es una política distinta que requiere una intención de gasto explícita. `ocx account credits openai on|off --json` apunta a una cuenta. `ocx account credits openai --all on|off --json` es exclusivo con ese selector: en los registros de ID seleccionables actuales más principal, se borra la lista. Los recibos son `{ok, id, creditsAfterLimit}` o `{ok, all, ids}`; conservar los ID devueltos reales y leer de nuevo `ocx account list openai --json`. Mostrar saldos de crédito con `--show-codex-credits` no habilita esta póliza. No permita que los créditos se recuperen de una lectura de inicio de sesión o de cuota fallida. + + + +### Observaciones de activación y reset-grant de cuotas + +```bash +ocx account quota-activation openai --window fiveHour off --json +ocx account list openai --json +ocx account anthropic-reset-grants --json +``` + +La activación de cuotas acepta `fiveHour` o `weekly`, deliberadamente diferente de Anthropic pool `five-hour`. Escribe un toggle de cuenta/ventana; habilitar puede programar la actualización de cuota. `{ok, id, window, enabled, available}` reporta la política y la disponibilidad observada, no la actualización completada. La habilitación no disponible puede devolver 409; la desactivación todavía está permitida. Nunca consume una concesión de reinicio. + +Anthropic reset-grants acepta un ID de cuenta Anthropic exacto opcional, no un selector alias/principal Codex; la omisión utiliza la opción activa/retroactiva existente. El GET puede contactar con el servicio de estado ascendente. Reporta elegibilidad/razón, recuento de subvenciones, fechas anulables, tiempo de reutilización, operación pendiente y disponibilidad de revistas. Las subvenciones vacías no son lo mismo que el estado no disponible. Nunca consume una subvención o reanuda un gasto pendiente. El consumo sigue siendo una operación GUI humana. + + + +### Utilizar la cuota incluida restante + +Para seguir utilizando una cuenta seleccionada más allá de un umbral de conmutación proactiva o el umbral de protección de cuenta principal, habilite explícitamente su preferencia de cuota restante: + +```bash +ocx account use-remaining openai main on +ocx account use openai main +ocx account use-remaining openai main status --json +ocx account use-remaining openai main off +``` + +Reemplace `main` con un ID o alias de cuenta de grupo único para orientar una cuenta agregada. Al habilitar esto, se desactiva el cambio de uso proactivo para esa cuenta. Para el inicio de sesión principal, también mueve ambos umbrales efectivos de bloqueo duro al 100%, por lo que una lectura del 95% aún puede admitir una solicitud. La preferencia persiste en los reinicios hasta que se desactiva; la configuración del umbral original permanece almacenada y se reanuda la aplicación cuando está desactivada. No selecciona una cuenta en sí ni anula la programación de round-robin, la pausa manual / automática, las verificaciones de derechos, la reautenticación o los tiempos de reutilización ascendentes. El permiso de crédito pagado sigue siendo una configuración separada; habilitar esto nunca opta por una cuenta en créditos o canjea una subvención de restablecimiento. La cerradura rígida principal por defecto todavía se niega al 100%. + +`GET /api/codex-auth/accounts/use-remaining?id=` lee la política en vivo. `PUT /api/codex-auth/accounts/use-remaining` acepta `{ id, useRemainingQuota: boolean }`. Ambos requieren la autenticación de gestión existente. Este control está expuesto actualmente a través de los CLI y API. + + + +### Protección de la cuota de cuenta principal + +En **Codex ajustes → Multi-auth → Ajustes avanzados**, **Bloquear cuenta principal** está activado por defecto junto a Ultra Fast. Apagarlo se aplica inmediatamente; volver a encenderlo primero muestra las consecuencias, y la cancelación no cambia la configuración. La tarjeta de la cuenta principal muestra la supervisión, el uso desconocido o un bloque de directiva actual incluso cuando se cierra la configuración avanzada. + +El valor predeterminado sigue a lo que hace una cuenta principal drenada en Codex Desktop: una vez que la ventana de la cuenta ChatGPT informa **0%** restante, Desktop deshabilita su botón de envío y la cuenta deja de aceptar turnos hasta que la ventana se restablece. Mantener el tráfico propio de ocx por debajo de ese punto mantiene la cuenta utilizable ([#5694](https://github.com/lidge-jun/opencodex/issues/5694)). El coste es Luna Reserve: mientras el bloque esté vigente, Reserve en esa cuenta principal no podrá activarse. Para que la cuenta principal se agote y se entregue a Reserve, apague el interruptor. + +El **Ventana de 5h y la ventana semanal cada bloque por su cuenta**: la ventana de 5h alcanza el 90% o la ventana semanal alcanza el 98% de bloques de inmediato, incluso cuando el otro todavía tiene espacio para la cabeza. Las cuentas solo mensuales usan su ventana mensual. El bloque se libera automáticamente, con el interruptor todavía encendido, una vez que cada ventana de bloqueo informa una nueva lectura por debajo de su umbral (un 0% de recuentos de reinicio); la siguiente observación en el umbral bloquea nuevamente. Configure `codexMainAccountHardLockThresholds` en `config.json` con los porcentajes opcionales `short` y `long`, por ejemplo `{ "short": 90, "long": 98 }`. Ambos deben ser números enteros de 80 a 100, y `short` no debe exceder `long`; campos omitidos utilizan los valores predeterminados. La configuración API acepta el mismo objeto y devuelve los valores efectivos en `mainAccountHardLock.thresholds`. + +**Mientras que el bloqueo bloquea, las solicitudes pueden recaer en otro modelo en lugar de fallar.** La fila **Retroceso mientras está bloqueado** se encuentra al lado del interruptor de protección y funciona como la fila de llamada a la sombra: elegir un modelo, por ejemplo `deepseek/deepseek-chat`, enciende la redirección inmediatamente, se le aplica el esfuerzo de pensamiento opcional y el interruptor pausa la redirección sin olvidar el modelo. Mientras que el bloque está en vigor y no Codex cuenta puede servir a una solicitud de un modelo nativo Codex, esa solicitud se encamina al modelo de reserva (con el esfuerzo configurado) en lugar de ser rechazada. Una cuenta Pool utilizable todavía sirve la solicitud primero; selectores calificados por el proveedor, combos, filas calificadas por la cuenta y Luna Reserve mantienen sus propios destinos; y se ignora una reserva que nombra un modelo Codex nativo, porque el reencaminamiento gpt-? solo volvería a ingresar el mismo rechazo. La cerradura en sí no cambia: se suelta por sí misma como antes, y el desvío termina con ella. Configurar `codexMainAccountHardLockFallback` en `config.json` como `{ "model": "deepseek/deepseek-chat", "reasoningEffort": "low" }`; `enabled: false` pausa el desvío mientras mantiene el modelo. Una sección ausente, un modelo omitido o una sección mal formada significa que las solicitudes son rechazadas como de costumbre; `reasoningEffort` debe ser un esfuerzo declarado. La configuración API acepta el mismo objeto, rechaza escrituras inválidas antes de la mutación y `null` borra la sección. + +El panel de control y el `ocx status` muestran **posible uso fuera del opencodex** cuando las lecturas nuevas aumentan en al menos un punto en el mismo episodio de reinicio sin actividad reciente de la cuenta principal a través de este proxy. Esta es una observación de asesoramiento, no una prueba: un giro de larga duración también puede causarlo. La cerradura no puede evitar el agotamiento del tráfico exterior. El aviso de proceso local borra los cambios de identidad o de restablecimiento y caduca después de seis horas o en el restablecimiento observado, lo que ocurra primero. `ocx status --json` expone el estado, los umbrales efectivos, el tipo de ventana de bloqueo y la advertencia opcional `externalUsage` bajo `mainAccountHardLock` cuando hay evidencia de gestión en vivo disponible. + +Una lectura ilegible de 5h no puede ocultar un bloque semanal. El uso desconocido no fabrica un cero, y una lectura faltante no borra una tupla de bloqueo ya medida. Un tiempo de reinicio predicho solo no lo desbloquea. Mientras está bloqueado, la recuperación comprueba los metadatos de uso propio en un horario limitado de 5/10/20/40/60 minutos, por lo que se observa un restablecimiento canjeado fuera de opencodex antes del restablecimiento previsto; el primer cheque espera cinco minutos, los cheques permanecen al menos cinco minutos de diferencia y el siguiente cheque se introduce al último restablecimiento de bloqueo conocido. Un principal en pausa o requerido para la re-autenticación no recibe ninguna comprobación antes de su reset predicho. Un `Retry-After` más largo también retrasa la preparación de perfiles y tokens. Solo el uso nuevo y válido o la evidencia autorizada de ausencia de ventana pueden levantar el bloqueo. En el modo Pool, una cuota `--refresh` evita la frescura de la memoria caché, pero aún honra el ritmo de lectura fallida; una lectura diferida no hace ningún nuevo intento de diagnóstico. Otros límites de pausa, reautenticación y aguas arriba permanecen independientes. + +La protección trata una nueva respuesta de uso WHAM válida como un reemplazo para la lectura de 5 horas anterior cuando su ventana principal dura explícitamente **al menos 24 horas** e informa sobre el uso válido, o su ventana principal es explícitamente `null` y un secundario medido proporciona el uso semanal. En cualquier caso, las ventanas secundarias / terciarias deben ser explícitamente `null` o explícitamente durar al menos 24 horas e informar el uso válido. Esto sigue el límite corto / largo del analizador, por lo que una ventana de un día califica, así como ventanas semanales / mensuales. La ventana actual sigue utilizando el mismo umbral de ventana larga configurado (98% por defecto). Esto se basa en la única instantánea reportada; no se requieren observaciones repetidas. Cualquier campo de ventana omitido, una duración desconocida o encabezados de respuesta parcial no pueden borrar un bloque anterior. Las respuestas totalmente nulas con solo créditos y lecturas complementarias mensuales tampoco pueden establecer la recuperación. El proxy comprueba la credencial almacenada de nuevo antes de aplicar una respuesta retardada. Un archivo ilegible o portador reemplazado no puede actualizar la memoria caché de uso, liberar el bloqueo o poner en cuarentena la nueva credencial, incluso para la misma cuenta sin leer la segunda cuota. Su uso ordinario analizado aún se puede devolver al llamante solicitante, sin actualizaciones de estado compartido o evidencia de recuperación. La tarjeta de cuenta muestra el uso publicado en caché, manteniendo su cuota alineada con el estado de bloqueo; Direct cuota de proveedor omite una respuesta no publicada y su informe en caché anterior. Las identidades de cuentas en conflicto y las respuestas obsoletas 401/403 retienen la información almacenada en caché actual y no pueden borrar o establecer el estado de reautenticación de la cuenta actual. + +Responses a las solicitudes enviadas con la credencial principal identificada actualizan su uso en caché desde sus cabeceras de cuota, ya sea que el proxy sustituya la credencial almacenada o el llamante envíe la misma credencial. Una respuesta se aplica solo si esa credencial sigue siendo la credencial principal observada cuando llega; una credencial propiedad del llamante para otra cuenta o espacio de trabajo nunca actualiza el uso de la cuenta principal. + +La opción persistente es `"codexMainAccountHardLock"` en OpenCodex `config.json`. Una tecla ausente o `true` significa encendido; solo un `false` explícito lo apaga, y eso es lo que almacena el apagado de la configuración. El valor predeterminado cambió aquí: la política solía ser opt-in y el interruptor antiguo eliminó la clave cuando estaba apagada, por lo que una instalación que la había apagado ahora se lee como activada. Si desea el comportamiento anterior, apáguelo una vez para registrar la opción de exclusión. La protección cubre nuevas solicitudes utilizando la cuenta principal identificada, no el último 2% en sí: las solicitudes que ya se están ejecutando, las credenciales de llavero propiedad del llamante sin igual y el tráfico fuera del proxy aún pueden gastar cuota. Las cuentas agregadas y otros proveedores permanecen disponibles. + +Con la protección activada, una startup propia restaura la vinculación de identidad en memoria de la credencial principal después de la recuperación y limpieza del perfil nativo, por lo que un bloque de políticas persistente sobrevive a un reinicio. Las solicitudes Direct, exact-main, main-fallback y main-pin pueden recibir brevemente 503 mientras está pendiente esa vinculación; las cuentas Pool almacenadas saludables siguen siendo elegibles durante todo el proceso. No se lee ninguna credencial de un hogar de servicio extranjero o no confirmado para esta inicialización. + +Mientras que esta política bloquea la principal, la Reserva Luna en esa cuenta también está bloqueada. Mantenerse por debajo del agotamiento de la cuota ordinaria puede evitar la activación de la reserva. Deshabilitar el switch restaura el manejo local normal, no el derecho ascendente adicional. Utilice la acción de actualización de cuota de cuenta para obtener una nueva observación; no se consume automáticamente ningún crédito de reinicio. + + + +### Luna Reserve junto a modelos enrutados + +El [Modo de escritorio](/es/guides/codex-integration/#authless-codex-desktop-opt-in) opcional mantiene inactiva la puerta del selector de solo reserva de Desktop. También deshabilita el manejo automático de reservas de Desktop: Reserve es una opción de modelo explícita, no una alternativa automática. + +Mantenga el proveedor OpenAI integrado habilitado en el modo ChatGPT -forward, habilite el selector de modelo de cuenta y configure un selector público para la cuenta principal almacenada. Con el modo sin autorización de loopback efectivo habilitado, `ocx sync` incluye `/gpt-reserve` junto con los modelos de proveedores enrutados. Un `gpt-reserve` desnudo, un selector de cuenta agregada y el descubrimiento del modelo API -key no se agregan al catálogo. La configuración authless se ignora para el enrutamiento de cliente remoto o un oyente que necesita un encabezado de admisión. Cuando los oyentes públicos y locales se ejecutan juntos, la compatibilidad de reserva solo se aplica a las solicitudes admitidas por el oyente local. Una solicitud pública autenticada permanece en la ruta normal aunque se origine en la misma máquina; los encabezados de la solicitud no pueden seleccionar la directiva local. + +Habilite el modo de escritorio sin autorización con `ocx system settings --desktop-authless on`, ejecute `ocx sync`, luego salga completamente y vuelva a abrir Codex Desktop para que vuelva a cargar la configuración y el catálogo reescritos. Siga el [canónica flujo de trabajo de escritorio authless](/es/guides/codex-integration/#authless-codex-desktop-opt-in). + +Cada solicitud de compatibilidad comprueba una autorización de servidor vinculada a credenciales, almacenada en caché durante un máximo de 60 segundos. OpenCodex envía el encabezado de capacidad de reserva en una lectura de uso de cuenta principal propia y requiere que el uso ordinario no esté permitido, la bandera de Reserva Luna y exactamente un cubo de reserva permitido. La evidencia faltante, denegada, rancia o no coincidente rechaza la solicitud; no cambia de cuentas ni usa silenciosamente la Luna ordinaria. El uso pasivo puede revocar la autorización, pero no puede crearla. El tiempo de reutilización global, la pausa, la reautenticación y el bloqueo de la cuenta principal aún se aplican. Apague el bloqueo duro si desea usar Reserve en una cuenta principal agotada; al hacerlo, no otorga derecho al servidor. Esta ruta de compatibilidad admite solicitudes de conversación y compactación, no se reserva como un ayudante de visión o búsqueda web o un modelo de relé de búsqueda independiente. Elija otro modelo para esos ayudantes. + +El selector prefiere los metadatos de reserva reales. Cuando no se ha observado ninguno, utiliza una adaptación de metadatos de Luna explícitamente marcada, siguiendo el mapeo preestablecido de Reserva o Luna de Desktop. Una entrada visible no es prueba de disponibilidad. Se verificaron las rutas de origen del escritorio y las rutas respaldadas por accesorios; no se usó una cuenta activa de reserva en vivo para validar esta ruta de compatibilidad. + +### `ocx account ` + +Haga una lista y cambie de cuentas de proveedores y grupos de claves API a través del proxy en ejecución. La superficie de ayuda enviada es: + +```text +Usage: ocx account ... + +list [provider] Codex account pool, OAuth accounts and API keys (identifiers shown masked as the API returns them). +history openai [--limit <1-200>] Recent routing decisions for one Codex pool account. +current Show the active account or key. +use Switch the active credential; 'main' selects the Codex App login, 'auto' clears the selection unless an account carries that id. +clear Clear the manual Codex account selection unconditionally. +refresh Force-refresh Codex or provider quota reports. +auto-switch Control the Codex pool threshold. +alias Set or clear an account's display name; '-' clears it. +pause Hold an account out of automatic selection. +resume Return a paused account to automatic selection. +pause-exhausted Pause every account whose quota is spent. +clear-cooldown Drop a cooldown the proxy set after an upstream failure. +strategy [] Pool placement strategy; least-loaded is Kiro-only. +sticky [<1-100>] Requests a bound thread keeps on one account; omit the value to read it. +priority [first|earlier|normal|later|last|-100..100|reset] Selection order; omit the value to read it. +remove --yes Remove a stored account or key after an existence check. +add-key [--label