Guía de inicio de DeepSeek-Reasonix: Agentes de programación con IA de bajo costo

Introducción del proyecto

DeepSeek-Reasonix es un agente de codificación con IA orientado a usuarios finales. No es simplemente una orden de chat en la línea de comandos; organiza un conjunto de motor local de agente configurable combinando el modelo, herramientas, plugins, contexto del proyecto y un flujo de aprobación.

Sus características principales son tres: primero, el sistema está optimizado de forma predeterminada para conversaciones largas centradas en DeepSeek, con especial atención al prefix cache, para reducir el costo en tokens de tareas de desarrollo consecutivas; segundo, Provider, modelos, herramientas y plugins se escriben en reasonix.toml, en lugar de estar codificados de manera rígida en el programa; tercero, se distribuye como un binario único en Go, por lo que CLI/TUI, aplicaciones de escritorio y la extensión para VS Code pueden reutilizar el mismo motor Reasonix.

En este artículo, vamos paso a paso a crear una práctica mínima: instalar Reasonix, configurar la clave de API de DeepSeek, inicializar comandos del proyecto para que ejecute una tarea de modificación de código y, al final, conectar el gateway compatible con OpenAI. Al terminar, sabrás cuándo usar DeepSeek directamente y cuándo conviene usar Defapi como una interfaz unificada para tener una experiencia más cómoda.

Dificultad: Intermedia | Duración: 20-40 minutos | Resultado: Hacer funcionar DeepSeek-Reasonix y entender la configuración basada en drivers, los comandos del proyecto, la colaboración entre dos modelos y la forma de integrar interfaces de bajo costo

Perfil de lectores objetivo

• Desarrolladores que quieren montar agentes de programación de bajo costo con DeepSeek
• Personas que suelen modificar código desde la terminal y necesitan un asistente de IA local
• Quienes quieren integrar agentes de IA en el repositorio de código del equipo, pero les preocupa el costo en tokens
• Ya usaron Claude Code, Codex u OpenClaw y quieren comparar herramientas del ecosistema DeepSeek

Dependencias principales y entorno

Estructura completa del proyecto (árbol)

Preparamos un proyecto de demostración mínimo:

reasonix-agent-demo/
├── .env.example
├── reasonix.toml
├── REASONIX.md
├── tasks/
│   └── bugfix.md
└── demo-app/
    ├── package.json
    └── src/
        └── price.ts

1. Instalar Reasonix CLI

La forma más sencilla es instalarlo mediante npm:

npm i -g reasonix

Verifica el resultado de la instalación:

reasonix --version

Si usas macOS, también puedes instalarlo con Homebrew:

brew install esengine/reasonix/reasonix

Se recomienda a los usuarios de Windows ejecutar en PowerShell o Windows Terminal:

npm i -g reasonix
reasonix --version

2. Configurar la clave de API de DeepSeek

Crea un directorio de demostración:

mkdir reasonix-agent-demo
cd reasonix-agent-demo

Prepara .env.example:

DEEPSEEK_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxx
DEFAPI_API_KEY=defapi_xxxxxxxxxxxxxxxxxxxxx

Cópialo como archivo de entorno local:

cp .env.example .env

Formato para PowerShell:

Copy-Item .env.example .env

Luego introduce tu propia clave de API de DeepSeek.

3. Ejecutar setup para completar la configuración inicial

Ahora ejecuta el comando de inicialización:

reasonix setup

Sigue las indicaciones para elegir Provider y modelo. DeepSeek-Reasonix está optimizado por defecto para DeepSeek; puedes empezar seleccionando el Provider DeepSeek y luego elegir un modelo adecuado para tareas de codificación del día a día.

Tras completar la configuración, inicia una sesión interactiva:

reasonix

Puedes empezar con una pregunta sencilla:

Por favor, indica qué archivos hay en el directorio del proyecto actual y desde dónde recomiendas comenzar la inicialización.

Si Reasonix responde correctamente, significa que la cadena CLI–modelo–API Key ya funciona.

4. Crear un reasonix.toml para fijar el Provider

Para que la configuración sea reproducible, escribimos los ajustes clave en reasonix.toml:

default_model = "deepseek"
language = "zh"

[ui]
theme = "auto"

[agent]
temperature = 0.0
reasoning_language = "zh"
soft_compact_ratio = 0.5
tool_result_snip_ratio = 0.6
compact_ratio = 0.8
compact_force_ratio = 0.9

[[providers]]
name = "deepseek"
kind = "openai"
base_url = "https://api.deepseek.com"
models = ["deepseek-v4-flash", "deepseek-v4-pro"]
default = "deepseek-v4-flash"
api_key_env = "DEEPSEEK_API_KEY"
context_window = 1000000
effort = "high"

[environment]
enabled = true

Aquí hay algunos puntos clave:

• default_model apunta al nombre del Provider; luego podrás cambiar el modelo predeterminado dentro del Provider.
• temperature = 0.0 es más adecuado para tareas de modificación de código y hace que la salida sea más estable.
• context_window reserva espacio para conversaciones largas.
• soft_compact_ratio y compact_ratio permiten mantener el contexto de forma más controlada.

Carga explícitamente las variables de entorno al iniciar:

export $(grep -v '^#' .env | xargs)
reasonix

En PowerShell puedes hacerlo así:

Get-Content .env | ForEach-Object {
  if ($_ -match "^(.*?)=(.*)$") {
    [Environment]::SetEnvironmentVariable($matches[1], $matches[2], "Process")
  }
}
reasonix

5. Usar /init para generar comandos del proyecto

Cuando el agente realiza tareas de código, lo peor es tener que explicar de nuevo cada vez las normas del proyecto. Reasonix permite ejecutarlas en una sesión interactiva:

/init

Con esto, generará un documento de comandos del proyecto a partir del proyecto actual. También puedes preparar REASONIX.md manualmente:

# Instrucciones del proyecto Reasonix

## Objetivos del proyecto

Este es un proyecto de ejemplo mínimo para verificar un agente de programación con Reasonix.

## Reglas de desarrollo

- Antes de modificar código, explica primero el plan.
- Agrega comentarios en chino a las funciones clave.
- Después de completar la modificación, ejecuta las pruebas del proyecto.
- No envíes commits de Git, a menos que el usuario lo solicite explícitamente.

## Comandos habituales

```bash
npm test

> [!TIP]
> Cuanto más estable sea el documento de instrucciones del proyecto, más fácil será que el prefix cache de DeepSeek acierte. No escribas los detalles de tareas que cambian cada día en instrucciones de largo plazo; es mejor ponerlos en archivos de tareas separados.

## 6. Preparar una tarea real de código

Creemos un proyecto mínimo en TypeScript:

```bash
mkdir -p demo-app/src tasks
cd demo-app
npm init -y
npm i -D typescript tsx
npx tsc --init
cd ..

Crea demo-app/src/price.ts:

export type PriceInput = {
  amount: number;
  discountRate?: number;
};

export function calculateFinalPrice(input: PriceInput): number {
  const discount = input.discountRate || 0;
  return input.amount * (1 - discount);
}

Esta función tiene un problema común: discountRate no valida límites; si se pasa 1.5, se obtiene un precio negativo.

Crea tasks/bugfix.md:

# Tarea: corregir el problema de límites del cálculo de precios

Por favor, modifica demo-app/src/price.ts:

1. amount debe ser mayor o igual que 0.
2. discountRate tiene por defecto 0.
3. discountRate solo puede estar entre 0 y 1.
4. Agrega comentarios en chino a calculateFinalPrice.
5. Añade una prueba mínima o un script de validación ejecutable.

Ahora haz que Reasonix ejecute la tarea:

reasonix run "Lee tasks/bugfix.md y completa la modificación de código descrita en el documento."

Verás cómo Reasonix lee la tarea, revisa los archivos y propone un plan de cambios, para luego llamar a herramientas y escribir el código. Ese proceso es la diferencia entre un coding agent y un bot de chat normal: no solo explica el problema, sino que entra al proyecto y modifica archivos.

7. Configurar el modo de doble modelo: planner/executor

El modo de un solo modelo puede completar muchas tareas, pero los requisitos complejos normalmente requieren planificar primero y ejecutar después. Reasonix permite dividir el planner y el executor en la configuración:

[agent]
temperature = 0.0
planner_model = "deepseek-pro"
reasoning_language = "zh"

[[providers]]
name = "deepseek"
kind = "openai"
base_url = "https://api.deepseek.com"
models = ["deepseek-v4-flash", "deepseek-v4-pro"]
default = "deepseek-v4-flash"
api_key_env = "DEEPSEEK_API_KEY"
context_window = 1000000
effort = "high"

[[providers]]
name = "deepseek-pro"
kind = "openai"
base_url = "https://api.deepseek.com"
model = "deepseek-v4-pro"
api_key_env = "DEEPSEEK_API_KEY"
context_window = 1000000
effort = "high"

Una combinación práctica es:

Así puedes controlar costos y, al mismo tiempo, hacer que el modelo más fuerte participe en los pasos clave.

8. Integrar una interfaz compatible con Defapi

El Provider de Reasonix es impulsado por configuración: siempre que el servicio objetivo sea compatible con una interfaz estilo OpenAI, puede conectarse como Provider. Esto es especialmente adecuado para integrar Defapi.

La ventaja de Defapi es que el precio suele ser aproximadamente la mitad del oficial, y los modelos son básicamente compatibles con los siguientes protocolos:

• v1/chat/completions
• v1/messages
• v1beta/models/

Podemos añadir un Provider de Defapi en reasonix.toml:

[[providers]]
name = "defapi-claude"
kind = "openai"
base_url = "https://api.defapi.org/api/v1"
model = "anthropic/claude-sonnet-4.5"
api_key_env = "DEFAPI_API_KEY"
context_window = 200000

Luego cambia el modelo predeterminado:

default_model = "defapi-claude"

También puedes conservar DeepSeek como ejecutor predeterminado y usar el modelo fuerte de Defapi como planner:

default_model = "deepseek"

[agent]
planner_model = "defapi-claude"
temperature = 0.0

[[providers]]
name = "deepseek"
kind = "openai"
base_url = "https://api.deepseek.com"
models = ["deepseek-v4-flash", "deepseek-v4-pro"]
default = "deepseek-v4-flash"
api_key_env = "DEEPSEEK_API_KEY"
context_window = 1000000
effort = "high"

[[providers]]
name = "defapi-claude"
kind = "openai"
base_url = "https://api.defapi.org/api/v1"
model = "anthropic/claude-sonnet-4.5"
api_key_env = "DEFAPI_API_KEY"
context_window = 200000

Esta combinación es muy adecuada para desarrollo real: las tareas habituales pasan por DeepSeek para controlar costos; la planificación compleja o la revisión de código se hace con el modelo fuerte de Defapi. Al unificar la capa Provider, Reasonix no necesita escribir código nuevo para cada proveedor de modelos.

9. Ejecutar una verificación completa

Ahora realicemos una verificación completa:

reasonix run "Revisa la implementación de demo-app/src/price.ts y explica si todavía hay problemas de límites."

Luego haz que ejecute una tarea más cercana al trabajo real:

reasonix run "Agrega un comando npm test para demo-app y usa un script mínimo para validar tres escenarios: el precio normal de calculateFinalPrice, el descuento y el descuento inválido."

Por último, revisa los cambios en Git:

git diff

Si ves que Reasonix modificó el código, añadió pruebas y explicó las razones de los cambios, significa que este flujo mínimo de trabajo del agente ya funciona.

Solución de problemas frecuentes

1. No se encuentra el comando reasonix

Primero confirma el directorio global de npm:

npm config get prefix
npm bin -g

Si npm bin -g no está disponible, puedes usar:

npm root -g

Una vez que encuentres el directorio de instalación global, agrega la ruta del ejecutable correspondiente a PATH. En Windows normalmente es necesario volver a abrir la terminal.

2. Permisos insuficientes para instalar globalmente con npm

En macOS/Linux no se recomienda añadir sudo de forma forzada. Podemos cambiar el directorio global de npm al directorio del usuario:

mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
export PATH="$HOME/.npm-global/bin:$PATH"
npm i -g reasonix

Luego guarda la configuración de PATH en el archivo de inicio del shell.

3. La clave de API de DeepSeek no se aplica

Primero verifica si la variable de entorno existe:

echo "$DEEPSEEK_API_KEY"

En PowerShell:

$env:DEEPSEEK_API_KEY

Si está vacía, significa que la terminal actual no ha cargado .env. Puedes inyectarla manualmente primero:

export DEEPSEEK_API_KEY="sk-xxxxxxxxxxxxxxxx"
reasonix

4. reasonix.toml no se lee

La configuración de Reasonix normalmente se interpreta en el orden: parámetros del comando, configuración del directorio actual, configuración global del usuario y valores predeterminados internos. Primero confirma que estás ejecutando desde la raíz del proyecto:

pwd
ls reasonix.toml

Luego ejecuta:

reasonix run "Por favor, indica qué modelo y Provider estás usando actualmente."

Si la salida no coincide con la configuración, revisa primero si los parámetros de la línea de comandos o la configuración global están sobrescribiendo la configuración del directorio actual.

5. El modelo responde lento o el costo es alto

Divide primero la tarea en partes más pequeñas:

reasonix run "Lee solo demo-app/src/price.ts; por ahora no modifiques nada e indica los posibles problemas."

Luego pídele que haga cambios:

reasonix run "Basándote en el problema anterior, solo modifica demo-app/src/price.ts."

En conversaciones largas, un documento de instrucciones estable del proyecto y descripciones de tareas con pocos cambios favorecen que el caché acierte. Para tareas complejas, puedes habilitar el modo de doble modelo planner/executor, y dejar el modelo más costoso solo para la fase de planificación.

6. El agente no solicita aprobación antes de modificar archivos

Revisa el modo de trabajo actual. En sesiones interactivas puedes cambiar a un modo más conservador, donde se exija confirmar antes de cada llamada a herramientas. Para proyectos de equipo, se recomienda habilitar la aprobación por defecto y no entrar directamente en un modo de modificaciones automáticas sin supervisión.

Puedes primero pedir a Reasonix que solo analice:

reasonix run "No modifiques nada, solo analiza: revisa los problemas en demo-app/src/price.ts."

Confirma el plan y luego ejecuta la modificación.

7. Garbled text en chino en la terminal de Windows

En PowerShell puedes configurar primero UTF-8:

chcp 65001
$OutputEncoding = [System.Text.Encoding]::UTF8

Si la salida sigue siendo extraña, se recomienda usar Windows Terminal y confirmar que el editor, la terminal y Git estén usando UTF-8.

Lectura adicional / Direcciones de nivel avanzado

• Usa la aplicación de escritorio de Reasonix para pasar el flujo de trabajo del agente de la terminal a una interfaz gráfica.
• Instala la extensión de VS Code para que Reasonix lea el contexto del editor y gestione las aprobaciones de herramientas.
• Configura plugins compatibles con MCP para conectar scripts internos, consultas a bases de datos y búsqueda de documentos al agente.
• Usa subagentes para tareas como review, security_review y research.
• Integra Reasonix en el flujo de trabajo de OpenClaw, de modo que la entrada de chat dispare tareas reales de código.
• Integra Defapi usando v1/chat/completions o v1/messages, para gestionar de forma unificada proveedores de modelos como DeepSeek, Claude y Gemini.