DeepSeek-Reasonix 入門ガイド: 低コストAIプログラミング・エージェント

プロジェクト概要

DeepSeek-Reasonix は、端末向けのAIコーディング・エージェントです。単なるチャット用CLIコマンドではなく、モデル、ツール、プラグイン、プロジェクトのコンテキスト、そして承認フローをひとまとめにして、ローカルで動作する設定可能なエージェント・エンジンとして組み立てます。

主な特徴は3つあります。1つ目は、デフォルトでDeepSeek中心のロングセッション最適化が入っており、とりわけ prefix cache を重視することで、連続した開発タスクのトークンコストを下げられる点です。2つ目は、Provider、モデル、ツール、プラグインがすべて reasonix.toml に記述され、プログラムにハードコードされていないことです。3つ目は、Goの単一バイナリで配布されるため、CLI/TUI、デスクトップ、VS Code 拡張などで同じ Reasonix エンジンを再利用できる点です。

この記事では、最小の実践として一緒にセットアップします。Reasonix をインストールし、DeepSeek の API Key を設定し、プロジェクトの初期化コマンドを整えて、コード修正の1回のタスクを完了させ、最後に OpenAI 互換ゲートウェイも接続します。最後には次が分かるはずです――「いつ DeepSeek を直接使うべきか」「いつ Defapi を統一インターフェースとして使う方が気楽か」。

難易度: 中級 | 所要時間: 20〜40分 | 得られるもの: DeepSeek-Reasonix を通して動かし、設定ドリブン、プロジェクト指示、双モデル協調、そして低コストなAPI接続方法を理解する

対象読者

• DeepSeek を使って低コストのプログラミング・エージェントを作りたい開発者
• ターミナルでコードを頻繁に修正するので、ローカルのAIアシスタントが欲しいエンジニア
• AIエージェントをチームのコードベースに組み込みたいが、トークンコストも気にしている人
• 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 でプロジェクト指示を生成

エージェントがコードタスクを行うとき、毎回プロジェクトのルールを最初から説明し直すのが一番大変です。Reasonix はインタラクティブ会話内で次を実行できます。

/init

現在のプロジェクトに基づいて、プロジェクト指示を生成してくれます。さらに手動で REASONIX.md を準備することも可能です。

# Reasonix プロジェクト指示

## プロジェクト目標

これは Reasonix のプログラミング・エージェントを検証するための最小サンプルプロジェクトです。

## 開発ルール

- コードを変更する前に、計画を説明する。
- 重要な関数には中国語の注釈（コメント）を追加する。
- 修正が完了したら、プロジェクトのテストを実行する。
- ユーザーが明確に要求しない限り、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 がタスクを読み取り、ファイルを確認し、修正案を提示したうえで、ツールを使ってコードを書き込みます。この一連は、コーディング・エージェントと通常のチャットボットの違いです。問題を説明するだけでなく、プロジェクトに入り、ファイルを実際に修正します。

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 をデフォルトの実行側（executor）として残し、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. 完全な検証を1回実行する

それでは完全な検証を行います。

reasonix run "demo-app/src/price.ts の実装を確認し、まだ境界値の問題があるか説明してください。"

次に、より実際の仕事に近いタスクを実行させます。

reasonix run "demo-app に npm test コマンドを追加し、最小のスクリプトで calculateFinalPrice の正常価格、割引、無効な割引の3つのシナリオを検証してください。"

最後に 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. エージェントがファイルを修正する前に承認がない

現在の動作モードを確認してください。インタラクティブ会話では、より慎重なモードに切り替えて、ツール呼び出しの前に確認が必要になるようにできます。チーム開発のプロジェクトでは、デフォルトで承認を有効にし、監視なしの自動修正モードに直接入らないことをおすすめします。

まずは 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 のデスクトップ版を使い、ターミナルのエージェント・ワークフローをグラフィカルな画面に切り替える。
• VS Code 拡張を入れて、Reasonix がエディタのコンテキストを読み取り、ツールの承認を処理できるようにする。
• MCP-compatible プラグインを設定し、社内スクリプト、DBクエリ、ドキュメント検索をエージェントに接続する。
• サブエージェントを使って review、security_review、research などの分担タスクを行う。
• Reasonix を OpenClaw のワークフローに組み込み、チャットの入口から実際のコードタスクをトリガーする。
• Defapi の v1/chat/completions または v1/messages を接続し、DeepSeek、Claude、Gemini などのモデル供給元を統一的に管理する。