DeepSeek-Reasonix 입문 가이드: 저비용 AI 코딩 Agent

프로젝트 소개

DeepSeek-Reasonix는 터미널용 AI 코딩 agent입니다. 단순한 채팅용 CLI가 아니라, 모델, 도구, 플러그인, 프로젝트 컨텍스트, 승인 절차를 하나의 설정 가능한 로컬 Agent 엔진으로 구성합니다.

핵심 특징은 세 가지입니다. 첫째, 기본적으로 DeepSeek 중심의 장기 세션 최적화에 맞춰져 있으며, 특히 prefix cache를 중시해 연속 개발 작업의 토큰 비용을 더 낮춥니다. 둘째, Provider, 모델, 도구, 플러그인이 모두 reasonix.toml에 작성되며, 프로그램 내부에 하드코딩되지 않습니다. 셋째, Go 기반 단일 바이너리로 배포되어 CLI/TUI, 데스크톱, VS Code 확장도 같은 Reasonix 엔진을 재사용할 수 있습니다.

이번 글에서는 가장 작은 실전 예제를 함께 구성해 보겠습니다. Reasonix를 설치하고, DeepSeek API Key를 설정한 뒤, 프로젝트 지침을 초기화해서 한 번의 코드 수정 작업을 수행하고, 마지막으로 OpenAI-compatible 게이트웨이를 연결해 보겠습니다. 끝까지 따라오면 언제 DeepSeek를 직접 쓰면 좋은지, 언제 Defapi를 통합 인터페이스로 두는 편이 더 편한지 알 수 있습니다.

난이도: 중급 | 소요 시간: 20-40분 | 배울 내용: DeepSeek-Reasonix 실행, 설정 기반 구성, 프로젝트 지침, 이중 모델 협업, 저비용 인터페이스 연동 방식 이해

대상 독자

• DeepSeek로 저비용 코딩 Agent를 구축하고 싶은 개발자
• 터미널에서 코드를 자주 수정하며 로컬 AI 비서를 원한 엔지니어
• AI Agent를 팀 코드베이스에 연결하고 싶지만 토큰 비용이 신경 쓰이는 사람
• 이미 Claude Code, Codex, OpenClaw를 사용해 봤고 DeepSeek 생태계 도구와 비교해 보고 싶은 사람

핵심 의존성 및 환경

전체 프로젝트 구조

최소 데모 프로젝트를 준비합니다:

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

1. Reasonix CLI 설치

가장 간단한 방법은 npm으로 설치하는 것입니다:

npm i -g reasonix

설치 결과를 확인합니다:

reasonix --version

macOS에서는 Homebrew로도 설치할 수 있습니다:

brew install esengine/reasonix/reasonix

Windows 사용자는 PowerShell 또는 Windows Terminal에서 실행하는 것을 권장합니다:

npm i -g reasonix
reasonix --version

2. DeepSeek API Key 설정

새 데모 디렉터리를 만듭니다:

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

.env.example를 준비합니다:

DEEPSEEK_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxx
DEFAPI_API_KEY=defapi_xxxxxxxxxxxxxxxxxxxxx

로컬 환경 파일로 복사합니다:

cp .env.example .env

PowerShell에서는 다음과 같이 합니다:

Copy-Item .env.example .env

그다음 자신의 DeepSeek API Key를 입력합니다.

3. setup 실행으로 초기 설정 완료

이제 초기화 명령을 실행합니다:

reasonix setup

프롬프트에 따라 Provider와 모델을 선택합니다. DeepSeek-Reasonix는 기본적으로 DeepSeek와 잘 맞으므로, 먼저 DeepSeek Provider를 선택한 뒤 일상적인 코딩 작업에 적합한 모델을 고르면 됩니다.

설정이 끝나면 대화형 세션을 시작합니다:

reasonix

먼저 간단한 질문을 해볼 수 있습니다:

현재 프로젝트 디렉터리에 어떤 파일들이 있는지 설명하고, 어디서부터 초기화하는 것이 좋을지 제안해 주세요.

Reasonix가 정상적으로 응답하면 CLI, 모델, API Key 연결은 이미 정상적으로 동작하는 것입니다.

4. reasonix.toml로 Provider 고정

설정을 재현 가능하게 만들기 위해 핵심 설정을 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

여기에는 몇 가지 중요한 포인트가 있습니다:

• default_model은 Provider 이름을 가리키며, 이후 Provider 내부에서 기본 모델을 바꿀 수 있습니다.
• temperature = 0.0은 코드 수정 작업에 더 적합하며 출력이 더 안정적입니다.
• context_window는 긴 세션을 위해 여유를 남깁니다.
• soft_compact_ratio와 compact_ratio는 컨텍스트 유지 관리를 더 예측 가능하게 해 줍니다.

시작할 때 환경 변수를 명시적으로 불러옵니다:

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

PowerShell에서는 다음과 같이 쓸 수 있습니다:

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

5. /init으로 프로젝트 지침 생성

Agent가 코드 작업을 할 때 가장 곤란한 점은 매번 프로젝트 규칙을 다시 설명해야 한다는 것입니다. Reasonix는 대화형 세션에서 다음을 실행할 수 있습니다:

/init

이 명령은 현재 프로젝트를 바탕으로 프로젝트 지침을 생성합니다. 또한 REASONIX.md를 수동으로 준비할 수도 있습니다:

# Reasonix 프로젝트 지침

## 프로젝트 목표

이 프로젝트는 Reasonix 코딩 Agent를 검증하기 위한 최소 예제입니다.

## 개발 규칙

- 코드를 수정하기 전에 먼저 계획을 설명한다.
- 핵심 함수에는 한국어 주석을 추가한다.
- 수정이 끝나면 프로젝트 테스트를 실행한다.
- 사용자가 명시적으로 요청하지 않는 한 Git commit은 하지 않는다.

## 자주 사용하는 명령

```bash
npm test

> [!TIP]
> 프로젝트 지침이 안정적일수록 DeepSeek의 prefix cache가 더 잘 맞습니다. 매일 바뀌는 작업 세부사항을 장기 지침에 넣지 말고, 별도의 작업 파일에 두는 편이 좋습니다.

## 6. 실제 코드 작업 준비

가장 작은 TypeScript 프로젝트를 만들어 봅니다:

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

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);
}

이 함수에는 흔한 문제가 하나 있습니다. discountRate에 대한 경계 검사가 없어서, 1.5를 넣으면 음수 가격이 나올 수 있습니다.

tasks/bugfix.md를 새로 만듭니다:

# 작업: 가격 계산 경계 문제 수정

demo-app/src/price.ts를 수정해 주세요:

1. amount는 반드시 0 이상이어야 합니다.
2. discountRate의 기본값은 0이어야 합니다.
3. discountRate는 0에서 1 사이여야 합니다.
4. calculateFinalPrice에 한국어 주석을 추가해 주세요.
5. 최소 테스트 또는 실행 가능한 검증 스크립트를 하나 추가해 주세요.

이제 Reasonix에 작업을 실행시킵니다:

reasonix run "tasks/bugfix.md를 읽고, 그 안에 설명된 코드 수정을 완료해 주세요."

Reasonix가 작업을 읽고, 파일을 확인하고, 수정안을 제시한 다음, 도구를 호출해 코드를 작성하는 과정을 보게 될 것입니다. 이게 바로 coding agent와 일반 채팅봇의 차이입니다. 문제를 설명하는 데서 끝나는 것이 아니라, 프로젝트 안으로 들어가 파일을 수정합니다.

7. planner/executor 이중 모델 모드 구성

단일 모델 모드로도 많은 작업을 처리할 수 있지만, 복잡한 요구사항은 보통 먼저 계획하고 그다음 실행하는 방식이 더 좋습니다. Reasonix는 설정에서 planner와 executor를 분리할 수 있습니다:

[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"

실용적인 조합은 다음과 같습니다:

이렇게 하면 비용은 관리하면서도, 중요한 단계에서는 더 강한 모델을 판단에 참여시킬 수 있습니다.

8. Defapi 호환 인터페이스 연결

Reasonix의 Provider는 설정 기반입니다. 대상 서비스가 OpenAI 스타일 인터페이스와 호환되기만 하면 Provider로 연결할 수 있습니다. 이 점은 Defapi 연동에 특히 잘 맞습니다.

Defapi의 장점은 가격이 보통 공식의 절반 수준이며, 모델이 대체로 다음 프로토콜과 호환된다는 점입니다:

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

reasonix.toml에 Defapi Provider를 추가할 수 있습니다:

[[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

그다음 기본 모델을 전환합니다:

default_model = "defapi-claude"

또는 DeepSeek를 기본 실행기로 유지하고, Defapi의 강한 모델을 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

이 조합은 실제 개발에 매우 적합합니다. 일반 작업은 DeepSeek로 비용을 낮추고, 복잡한 계획이나 코드 리뷰는 Defapi의 강한 모델로 처리할 수 있습니다. Provider 계층이 통합되면 Reasonix는 각 모델 공급자마다 새 코드를 작성할 필요가 없습니다.

9. 전체 검증 실행

이제 전체 흐름을 한 번 검증해 봅니다:

reasonix run "demo-app/src/price.ts의 구현을 확인하고, 아직 남아 있는 경계 문제가 있는지 설명해 주세요."

그다음 실제 작업에 더 가까운 명령을 실행해 봅니다:

reasonix run "demo-app에 npm test 명령을 추가하고, calculateFinalPrice의 정상 가격, 할인, 잘못된 할인 세 가지 상황을 최소 스크립트로 검증해 주세요."

마지막으로 Git 변경 사항을 확인합니다:

git diff

Reasonix가 코드를 수정하고, 테스트를 추가하고, 변경 이유까지 설명해 준다면, 이 최소 Agent 워크플로는 성공적으로 동작한 것입니다.

자주 발생하는 문제 해결

1. reasonix 명령을 찾을 수 없음

먼저 npm 전역 디렉터리를 확인합니다:

npm config get prefix
npm bin -g

npm bin -g를 사용할 수 없으면 다음을 사용합니다:

npm root -g

전역 설치 디렉터리를 찾은 뒤, 해당 실행 파일 디렉터리를 PATH에 추가하세요. Windows 사용자는 보통 터미널을 다시 열어야 합니다.

2. npm 전역 설치 권한 부족

macOS/Linux에서는 sudo를 직접 붙여 강제 설치하는 것을 권장하지 않습니다. 대신 npm 전역 디렉터리를 사용자 디렉터리로 바꿀 수 있습니다:

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

그다음 PATH 설정을 셸 시작 파일에 기록하세요.

3. DeepSeek API Key가 적용되지 않음

먼저 환경 변수가 존재하는지 확인합니다:

echo "$DEEPSEEK_API_KEY"

PowerShell:

$env:DEEPSEEK_API_KEY

비어 있다면 현재 터미널이 .env를 불러오지 않은 것입니다. 우선 수동으로 주입할 수 있습니다:

export DEEPSEEK_API_KEY="sk-xxxxxxxxxxxxxxxx"
reasonix

4. reasonix.toml이 읽히지 않음

Reasonix 설정은 보통 “명령행 인자, 현재 디렉터리 설정, 사용자 전역 설정, 내장 기본값” 순으로 해석됩니다. 먼저 프로젝트 루트에서 실행 중인지 확인하세요:

pwd
ls reasonix.toml

그다음 실행합니다:

reasonix run "현재 사용 중인 모델과 Provider를 설명해 주세요."

출력이 설정과 다르다면, 먼저 명령행 인자나 전역 설정이 현재 디렉터리 설정을 덮어쓰고 있는지 확인하세요.

5. 모델 응답이 느리거나 비용이 높음

먼저 작업을 더 잘게 나눠 보세요:

reasonix run "demo-app/src/price.ts만 읽고, 아직 수정하지 말고 잠재 문제를 지적해 주세요."

그다음 수정하게 합니다:

reasonix run "방금 지적한 문제를 바탕으로 demo-app/src/price.ts만 수정해 주세요."

긴 세션에서는 안정적인 프로젝트 지침과 적게 변하는 작업 설명이 캐시 적중에 더 유리합니다. 복잡한 작업은 planner/executor 이중 모델을 켜고, 고비용 모델은 계획 단계에만 사용하면 됩니다.

6. Agent가 파일을 수정하기 전에 승인하지 않음

현재 작업 모드를 확인하세요. 대화형 세션에서는 도구 호출 전에 확인을 요구하는 더 보수적인 모드로 전환할 수 있습니다. 팀 프로젝트라면 기본적으로 승인 절차를 켜 두고, 무인 자동 수정 모드로 바로 들어가지 않는 것이 좋습니다.

먼저 Reasonix에 읽기 전용 분석만 시킬 수도 있습니다:

reasonix run "파일은 수정하지 말고 분석만 해 주세요: demo-app/src/price.ts의 문제를 점검해 주세요."

방안을 확인한 뒤 수정 작업을 실행하세요.

7. Windows 터미널에서 중국어/한글이 깨짐

PowerShell에서 먼저 UTF-8을 설정할 수 있습니다:

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

그래도 출력이 이상하면 Windows Terminal을 사용하고, 편집기, 터미널, Git 모두 UTF-8을 사용하도록 확인하세요.

추가 읽을거리 / 심화 방향

• Reasonix 데스크톱 버전을 사용해 터미널 Agent 워크플로를 GUI로 전환하기
• VS Code 확장을 설치해 Reasonix가 편집기 컨텍스트를 읽고 도구 승인까지 처리하게 하기
• MCP-compatible 플러그인을 구성해 내부 스크립트, 데이터베이스 조회, 문서 검색을 Agent에 연결하기
• 서브 Agent로 review, security_review, research 같은 역할 분담 작업 수행하기
• Reasonix를 OpenClaw 워크플로에 연결해 채팅 진입점에서 실제 코드 작업을 트리거하기
• Defapi의 v1/chat/completions 또는 v1/messages를 연결해 DeepSeek, Claude, Gemini 등 모델 공급자를 통합 관리하기