---
title: Configuración como código
description: Exporte la configuración a YAML, previsualice cambios y aplíquelos con nexcmp config o Import/Export; los secretos quedan fuera y JSON Schema lo valida.
url: https://nexcmp.com/es/docs/configure-with-ai/config-as-code/
applies_to: NexCMP 1.6.1
updated: 2026-11-02
---

# Configuración como código {#configuration-as-code}

> **En el panel de administración:** System › Settings › Import/Export (`/agent/config`). En el servidor: los comandos `nexcmp config export`, `plan` y `apply`, y `nexcmp admin <tool>`.

## Qué hace {#what-it-does}

La configuración de su panel (marca, ajustes generales, correo electrónico, alertas de Telegram, módulos, moneda, pasarelas de pago, límites, zonas, planes, el proveedor de IA y las páginas legales) se puede guardar como un único archivo YAML. Puede editar el archivo usted mismo, pedirle a un asistente de IA que lo edite, mantenerlo bajo control de versiones y aplicarlo al mismo panel o a otro. Antes de que cambie nada, siempre verá una lista de diferencias. Los secretos nunca se escriben en el archivo.

Úselo para clonar una configuración en una segunda instalación, revisar cambios antes de ponerlos en producción, restaurar ajustes tras un error o permitir que una IA proponga una configuración completa que usted pueda revisar como un único documento.

## Requisitos {#requirements}

| Elemento | Requisito |
|---|---|
| NexCMP | 1.4.0 o posterior. |
| Línea de comandos | Usted es `root` en el servidor del panel (use `sudo`). El comando solicita por sí mismo una clave temporal al panel (15 minutos, todos los ámbitos). Para usar en su lugar una clave más restringida, configure `NEXCMP_KEY` con una [clave de API de administrador](https://nexcmp.com/es/docs/configure-with-ai/admin-api-keys/) y consérvela mediante sudo, por ejemplo `sudo --preserve-env=NEXCMP_KEY nexcmp config plan -f nexcmp.yaml`. |
| Página de administración | Haber iniciado sesión en la administración. La página es de solo lectura en un panel de demostración. |
| Secretos | Valores proporcionados al momento de aplicar (consulte [Secretos](#secrets)); nunca dentro del archivo. |

## Exportar, editar, previsualizar, aplicar {#export-edit-preview-apply}

1. Exporte la configuración actual:

   ```bash
   sudo nexcmp config export -o nexcmp.yaml
   ```

   Sin `-o`, el YAML se muestra en pantalla.
2. Edite `nexcmp.yaml` (consulte el [ejemplo](#example-file) a continuación). Mantenga `version: 1` en la parte superior.
3. Previsualice qué cambiaría. Esto no modifica nada:

   ```bash
   sudo nexcmp config plan -f nexcmp.yaml
   ```

   Cada línea muestra sección, elemento, campo y `old → new`. Las líneas marcadas con `$` pertenecen a secciones de facturación (consulte [Secciones de facturación](#billing-sections)). Si el panel ya coincide con el archivo, verá "No changes".
4. Aplique los cambios. Sin `--yes`, el comando es un **dry run** y solo muestra la misma lista:

   ```bash
   sudo nexcmp config apply -f nexcmp.yaml --yes
   ```

5. Revise el resultado: `applied`, `pending` (a la espera de su confirmación), `skipped` y `errors`.

| Opción | Significado |
|---|---|
| `-f <file>` | El archivo YAML (obligatorio para `plan` y `apply`). |
| `--yes` | Aplica realmente los cambios. Sin ella, `apply` es un dry run. |
| `--confirm-billing` | Aplica también las secciones de facturación (`payments`, `currency`, `plans`). Sin esta opción, se omiten. |
| `--section <name>` | Aplica únicamente esta sección. Repita la opción para varias. |
| `-o <file>` | Con `export`: escribe el YAML en un archivo. |

El código de salida es 0 cuando se aplicó todo o no hubo cambios, 1 cuando se devolvió un error y 2 en caso de error de uso o de clave.

### Secretos {#secrets}

El archivo contiene referencias en lugar de secretos, como `password: secret://smtp_password`. Al momento de aplicar, el valor se obtiene de una variable de entorno llamada `NEXCMP_SECRET_` más el nombre de la referencia en mayúsculas:

```bash
sudo -i
read -rs NEXCMP_SECRET_SMTP_PASSWORD && export NEXCMP_SECRET_SMTP_PASSWORD
read -rs NEXCMP_SECRET_STRIPE_SECRET_KEY && export NEXCMP_SECRET_STRIPE_SECRET_KEY
nexcmp config apply -f nexcmp.yaml --yes --confirm-billing
```

Si una referencia no tiene ningún valor, el secreto ya guardado en el panel se **conserva**. Un secreto que nunca se guardó y no se proporciona permanece vacío.

| Nombre de referencia | Dónde se aplica |
|---|---|
| `smtp_password` | `email.smtp.password` |
| `telegram_bot_token` | `telegram.bot_token` |
| `stripe_secret_key`, `stripe_webhook_secret` | `payments.stripe` |
| `paypal_client_secret` | `payments.paypal.client_secret` |
| `binance_api_key`, `binance_api_secret` | `payments.crypto` |
| `sepay_api_token`, `sepay_webhook_secret` | `payments.bank` |
| `ai_provider_key` | `ai_provider.api_key` |

## Archivo de ejemplo {#example-file}

```yaml
# NexCMP configuration. Preview: nexcmp config plan -f nexcmp.yaml
version: 1

branding:
  name: Example Cloud
  primary: "#1677ff"
  currency: usd
  seller_name: Example Cloud LLC

settings:
  brand_name: Example Cloud
  support_email: support@example.com
  default_lang: en
  invoice_prefix: EX
  company_name: Example Cloud LLC
  company_address: "1 Example Street, New York, NY"
  min_topup_cents: 500

email:
  smtp:
    host: smtp.example.com
    port: 587
    security: starttls
    username: mailer@example.com
    password: secret://smtp_password
    from_email: no-reply@example.com
    from_name: Example Cloud
    reply_to: support@example.com

telegram:
  enabled: true
  chat_id: "123456789"
  bot_token: secret://telegram_bot_token

modules:
  s3: true
  k8s: false

currency:
  site_currency: usd
  manual_rate_vnd: 0        # 0 = automatic

payments:
  stripe:
    mode: test
    publishable_key: pk_test_XXXX
    secret_key: secret://stripe_secret_key
    webhook_secret: secret://stripe_webhook_secret
  bank:
    bank_code: BANK
    account_number: "0000000000"
    account_name: EXAMPLE CLOUD LLC
    prefix: EX
    api_token: secret://sepay_api_token
  channels:
    pay_card_enabled: true

quotas:
  quota_enabled: true
  quota_max_vms_24h: 5
  quota_max_vms_30d: 30

zones:
  - slug: new-york
    name: New York
    country: US
    city: New York
    enabled: true
    is_default: true

plans:
  - slug: vps-1c-1g
    name: 1 vCPU, 1 GB RAM, 25 GB
    cpu: 1
    ram_mb: 1024
    disk_gb: 25
    hourly_usd: 0.0112
    cs_offering_id: OFFERING_ID
    enabled: true
    visible: true

ai_provider:
  enabled: true
  name: Example AI
  base_url: https://api.example.com/v1
  model: example-model
  fallback_models: [example-model-mini]
  reasoning_effort: low
  api_key: secret://ai_provider_key

legal:
  terms:
    en: |
      # Terms of service
      Your terms in simple markdown (no HTML).
  privacy:
    en: |
      # Privacy policy
      Your policy in simple markdown (no HTML).
```

Un archivo puede contener cualquier subconjunto de las secciones. Las secciones que omita no se modificarán. Cualquier archivo que supere 1 MB, no incluya `version: 1`, tenga un número de versión distinto o contenga una sección desconocida será rechazado antes de ejecutar nada.

## Secciones {#sections}

| Sección | Qué controla | Notas |
|---|---|---|
| `branding` | Nombre de la marca (hasta 60 caracteres), color principal, moneda de visualización (`usd` o `vnd`), nombre del vendedor. | Los logotipos no forman parte del archivo; use la [página de marca](https://nexcmp.com/es/docs/customers/branding/). |
| `settings` | Una lista fija de ajustes generales: `brand_name`, `support_email`, `support_telegram_url`, `default_lang`, `require_email_verified`, `min_topup_cents`, `max_topup_cents`, `invoice_prefix`, `company_name`, `company_address`, `company_tax_id`, `auto_destroy_days`, `low_balance_cents`. | Se ignoran las demás claves. |
| `email.smtp` | Host SMTP, puerto, seguridad (`starttls`, `tls`, `none`), usuario, contraseña, nombre y dirección del remitente, reply-to. | [SMTP y plantillas de correo electrónico](https://nexcmp.com/es/docs/administration/smtp-and-emails/). Si cambia el host, el puerto o la seguridad, se requerirá de nuevo la contraseña. |
| `telegram` | Canal de alertas activado o desactivado, chat id, bot token. | [Notificaciones de Telegram](https://nexcmp.com/es/docs/administration/telegram-notifications/). |
| `modules` | Módulos opcionales activados o desactivados (`key: true/false`). | Solo las claves que el panel permite cambiar. Consulte [Módulos](https://nexcmp.com/es/docs/infrastructure/modules/). |
| `currency` | Divisa de visualización y tipo de cambio manual de USD a VND (`0` automático; de lo contrario, de 15000 a 50000). | Sección de facturación. Consulte [Divisas y tipos de cambio](https://nexcmp.com/es/docs/catalog/currency-and-exchange-rates/). |
| `payments` | Credenciales de `stripe`, `paypal`, `crypto`, `bank` y conmutadores de `channels` (`pay_card_enabled`, `pay_wallets_enabled`, `pay_alipay_enabled`, `pay_paypal_enabled`, `pay_usdt_enabled`, `pay_sepay_enabled`). | Sección de facturación. Consulte [Canales de pago](https://nexcmp.com/es/docs/billing/payment-channels/). |
| `quotas` | Límites de `quota_*`. | Consulte [Cuotas](https://nexcmp.com/es/docs/billing/quotas/). |
| `zones` | Zonas por `slug` (obligatorio: `slug`, `name`, `country`; opcional `city`, `enabled`, `is_default`). | Se crean nuevas zonas. Las zonas que ya existen **no se modifican** mediante el archivo. Consulte [Zonas](https://nexcmp.com/es/docs/infrastructure/zones/). |
| `plans` | Planes por `slug` (obligatorio: `slug`, `name`, `cpu`, `ram_mb`, `disk_gb`, `hourly_usd`; opcional `cs_offering_id`, `backend_id`, `zone_id`, `enabled`, `visible`, `sort`, `description`). | Sección de facturación. Se crean planes nuevos y los existentes se actualizan por slug. Los precios se expresan en USD por hora. Consulte [Planes](https://nexcmp.com/es/docs/catalog/plans/). |
| `ai_provider` | El proveedor de IA del panel utilizado por AI Chat y AI Agent de los clientes. | [AI provider](https://nexcmp.com/es/docs/ai/ai-providers/). |
| `legal` | Texto de términos y privacidad por idioma (`en`, `vi`). | [Páginas legales](https://nexcmp.com/es/docs/customers/legal/). |

El orden de aplicación es el indicado arriba: los elementos relacionados con la infraestructura van antes que los planes.

## Reglas para recordar {#rules-to-remember}

- **Idempotente.** Aplicar el mismo archivo dos veces no cambia nada la segunda vez. `plan` muestra "No changes".
- **Sin eliminaciones.** El archivo nunca elimina una zona, plan o ajuste. Eliminar una entrada del archivo deja el panel tal como está.
- **Las reglas de seguridad habituales siguen vigentes.** Desde la línea de comandos, cada cambio pasa por las mismas comprobaciones que un cambio por API: ámbitos y reglas de IP. Los cambios que requieren confirmación (un interruptor a nivel de todo el sitio, por ejemplo) se notifican bajo `pending` con una vista previa en lugar de aplicarse, a menos que pase `--confirm-billing`, lo que los confirma todos.
- **Los clientes de IA no pueden desbloquear la facturación.** Cuando un cliente MCP llama a `config_apply`, `confirm_billing` se ignora; los cambios monetarios quedan a la espera de su confirmación.
- **Compruebe antes de aplicar.** El JSON Schema describe cada campo. Apunte su editor hacia él o proporcióneselo a una IA para que genere YAML válido: `https://cloud.example.com/v1/admin/agent/config/schema.json` (legible públicamente).

### Secciones de facturación {#billing-sections}

`payments`, `currency` y `plans` modifican precios o flujos de dinero. `nexcmp config apply --yes` los **omite** a menos que añada `--confirm-billing`; en ese caso se enumeran bajo `skipped` ("billing section - pass confirm_billing"). Esta opción es su confirmación: con ella, cada cambio de facturación en el archivo (y cualquier otro cambio que solicite confirmación) se aplica sin una segunda solicitud. Ejecute primero `plan` y lea cada línea marcada con `$`.

Cuando una IA aplica el mismo archivo (la herramienta `config_apply` en un cliente MCP o AI Chat), la opción se ignora y, en su lugar, los cambios monetarios quedan a la espera de su aprobación.

## Usar la página Import/Export {#use-the-import-export-page}

1. Abra **System › Settings › Import/Export**.
2. En **Export**, haga clic en **Get current configuration** y luego en **Download .yaml** para guardar `nexcmp.yaml`. Los secretos aparecen como marcadores de posición.
3. En **Import**, elija un archivo, arrástrelo al cuadro o pegue el YAML.
4. Opcional: abra **Secrets that come with it (not in the file)** y añada un nombre y un valor para cada referencia, por ejemplo `smtp_password`.
5. Haga clic en **Preview changes**. La tabla agrupa los cambios por sección; las secciones relacionadas con dinero llevan la etiqueta "Money-related". Desmarque las secciones que no desee.
6. Si se listan secciones relacionadas con dinero, marque **Also apply money-related changes (prices, payment gateways, balances)**. Sin marcar la casilla, se omitirán.
7. Haga clic en **Apply selected**. El resultado muestra lo que se aplicó, se omitió o falló. Los cambios devueltos como pendientes de confirmación aparecen como una tarjeta de confirmación; pulse **Confirm** en ella.

El botón **JSON Schema** en la esquina superior derecha abre el esquema.

![Página Import/Export con la tarjeta Export y la tarjeta Import que contiene el YAML exportado](https://nexcmp.com/es/docs/images/configure-with-ai/config-as-code-01-import-export.webp)

![Tabla de vista previa de cambios agrupados por sección con una etiqueta de facturación y un botón Apply selected](https://nexcmp.com/es/docs/images/configure-with-ai/config-as-code-02-preview.webp)

## Ejecutar cualquier herramienta desde la línea de comandos {#run-any-tool-from-the-command-line}

`nexcmp admin` ejecuta las mismas herramientas que los asistentes de IA ([la lista de herramientas](https://nexcmp.com/es/docs/configure-with-ai/mcp-admin/#tools)) y muestra JSON:

```bash
sudo nexcmp admin tools                       # name, scope and title of every tool
sudo nexcmp admin system_health
sudo nexcmp admin customers_search q=customer@example.com
sudo nexcmp admin settings_update --json '{"values":{"support_email":"support@example.com"}}'
```

Los argumentos son pares `key=value` (los valores se interpretan como JSON si es posible; de lo contrario, como texto) o un objeto `--json '{...}'`. Si la acción requiere confirmación, el comando muestra la vista previa y se detiene con el código de salida 3 y "Nothing changed". Revise la vista previa y vuelva a ejecutar el mismo comando con `--yes` para aplicarla. Al ejecutarse como root, el comando obtiene una clave de 15 minutos con todos los ámbitos, por lo que el paso de confirmación es su protección; con `NEXCMP_KEY` se aplican los propios ámbitos de la clave.

## Verificación {#verify}

1. `sudo nexcmp config plan -f nexcmp.yaml` justo después de un `apply --yes` muestra "No changes".
2. En el panel de administración, las páginas modificadas muestran los nuevos valores y **Logs › Admin actions** lista los cambios.
3. Aplicar de nuevo el mismo archivo no cambia nada.

## Límites y notas {#limits-notes}

- El archivo cubre las configuraciones anteriores, no clientes, servidores, facturas ni fuentes de infraestructura (conexiones de CloudStack y Proxmox). Conéctelas con [AI Chat](https://nexcmp.com/es/docs/configure-with-ai/ai-chat-in-admin/) o desde las páginas de administración.
- Las zonas y los planes se vinculan mediante `slug`. No cambie el slug en el archivo: se crearía como un elemento nuevo.
- Un plan que los clientes ya están utilizando no puede cambiar de tamaño; cree un nuevo plan en su lugar.
- Mantenga la privacidad de los archivos exportados aunque no contengan secretos: enumeran sus precios, direcciones y nombres de cuentas.

## Resolución de problemas {#troubleshooting}

| Síntoma | Causa | Solución |
|---|---|---|
| `missing version: 1` | El archivo no comienza con `version: 1` | Agréguelo. |
| `unsupported version 2` | El archivo tiene otro número de versión | Este panel solo lee la versión 1. |
| `unknown section 'x' (known: ...)` | Una clave de nivel superior mal escrita o no admitida | Utilice las secciones anteriores. |
| `YAML error: ...` | YAML no válido (sangría, tabulaciones) | Corrija la línea que indica el mensaje. |
| `config is larger than 1 MB` | Archivo demasiado grande | Divídalo y utilice `--section`. |
| `no API key: set NEXCMP_KEY=ak_... or run as root on the server` | El comando no encontró ninguna clave | Ejecútelo con `sudo` o exporte `NEXCMP_KEY` y consérvelo mediante sudo. |
| `panel not reachable` | El servicio del panel no se está ejecutando en el puerto predeterminado | Compruebe `sudo nexcmp status`. |
| Líneas de facturación bajo `skipped` | Las secciones de facturación requieren `--confirm-billing` | Añada el flag y revise primero las líneas `$`. |
| Elementos bajo `pending` | El cambio requiere confirmación | Abra **API & AI agents** o el resultado de Import/Export y pulse **Confirm** en la tarjeta. |
| No se actualizó un secreto | No se definió ningún valor para `NEXCMP_SECRET_<NAME>`, por lo que se mantuvo el secreto guardado | Exporte la variable y aplique de nuevo. |
| Entrada bajo `errors` con HTTP 403 `insufficient_scope` | La clave carece del ámbito de esa sección | Utilice una clave con dicho ámbito o ejecútelo como root. |
| Entrada bajo `errors` con HTTP 403 `demo_read_only` | Panel de demostración | Aplíquelo en una instalación real. |