OSSエージェントNanocoderを導入、プロバイダ名の英数字制限にハマった

対象読者は、ローカルモデル（Ollama）や複数の LLM プロバイダを切り替えながら使える OSS のコーディングエージェント CLI を探している開発者です。Claude Code や Codex のような商用エージェント CLI に加えて、非営利コミュニティが開発する選択肢がどこまで実用的か、実際に npm install して確かめました。

Nanocoder とは何か

Nanocoder は、Nano Collective という非営利のコミュニティ集団が開発しているターミナル向けコーディングエージェントです。README には「企業ではなくコミュニティが作る」「モデルは自分で選ぶ」「コードはローカルマシンに留まる」という設計理念が明記されています。Ollama によるローカルモデル実行と、OpenRouter・Anthropic・Google・OpenAI 互換 API 全般への接続をサポートし、クローズドソース機能や有料ティアは設けていません。

2026-08-09 時点で GitHub スター数は 2.3k、フォーク数は 249（Nano-Collective/nanocoder）。npm パッケージ @nanocollective/nanocoder のバージョンは 1.29.0、ライセンスは MIT です（npm view @nanocollective/nanocoder version license で確認）。

セットアップ手順を実機で確認する

まずグローバルインストールします。

npm install -g @nanocollective/nanocoder

added 350 packages in 29s で完了し、nanocoder --version は 1.29.0 を返しました。ヘルプを見ると、対話モード（normal/auto-accept/yolo/plan）・非対話実行（run サブコマンド）・エディタ連携用の ACP（Agent Client Protocol）サーバーモード・セッション再開（--continue/--resume）まで一通り揃っていることが分かります。

$ nanocoder --help
Usage: nanocoder [options] [command]

Commands:
  copilot login [provider-name]   Log in to GitHub Copilot (device flow)...
  daemon <subcommand>             Manage the per-project skill daemon...

Options:
  --provider          Specify AI provider (must be configured in agents.config.json)
  --model             Specify AI model (must be available for the provider)
  --mode              Start in a specific development mode (normal, auto-accept, yolo, plan)
  --plain             Use a lightweight, Ink-free runtime for non-interactive runs
  --json              Output execution results as a single well-formed JSON object to stdout
  -c, --continue      Resume the most recent session for the current directory
  -r, --resume [id]   Resume a session by id or 1-based list index
  run                 Run in non-interactive mode

初めてのディレクトリで run を叩くと、無条件には実行されません。

$ nanocoder --plain run "echo hello"
Directory /tmp/nanocoder-test is not trusted. Pass --trust-directory or set NANOCODER_TRUST_DIRECTORY=1 to bypass the disclaimer for this run.

エラーメッセージにある NANOCODER_TRUST_DIRECTORY 環境変数はコマンド起動時のヘルプや docs/getting-started/index.md には記載がなく、実行結果に表示された値をそのまま引用しています（--trust-directory フラグ自体は公式ドキュメントに記載あり）。今回は --trust-directory を付けて再実行すると、今度はプロバイダ未設定のエラーに変わりました。

$ nanocoder --plain --trust-directory run "echo hello"
No providers configured. Run nanocoder interactively to set them up.

初回起動を無警戒に自動化スクリプトへ組み込めない設計になっており、CI で使う場合は --trust-directory とプロバイダ設定を事前に用意しておく必要があります。

プロバイダ設定でハマった箇所

公式ドキュメントの docs/configuration/providers/index.md には、ローカル Ollama 向けの設定例として次の JSON が掲載されています。

{
  "nanocoder": {
    "providers": [
      {
        "name": "Local Ollama",
        "baseUrl": "http://localhost:11434/v1",
        "models": ["custom-model"],
        "contextWindow": 32768
      }
    ]
  }
}

この name をそのまま --provider フラグに渡すと、実際には拒否されます。

$ nanocoder --plain --trust-directory --provider "Local Ollama" --model llama3.1 run "echo hello"
Invalid --provider value: "Local Ollama". Provider name must contain only alphanumeric characters, hyphens, and underscores.

ドキュメントのサンプル name はスペース入りの表示名（Local Ollama）ですが、CLI フラグのバリデーションは英数字・ハイフン・アンダースコアしか通しません。設定ファイル側の name に制約が書かれていないため、ドキュメント通りに書くと --provider 経由の呼び出しで詰まります。name をハイフン区切り（local-ollama）に変更すると通過しました。このバリデーション仕様（許可文字種・エラー文言）は公式ドキュメント・リリースノートには明記が見当たらず、今回の実行結果（v1.29.0）で確認した挙動です。バージョンが変われば挙動が変わる可能性があるため、再現する際は手元のバージョンでも確認してください。

$ nanocoder --plain --trust-directory --provider local-ollama --model llama3.1 run "echo hello"
nanocoder · local-ollama · llama3.1 · auto-accept

Connection failed: Unable to reach the model server

ローカルに Ollama サーバーを起動していない環境のため、ここで接続エラーになるのは想定どおりです。設定ファイルの読み込み自体は成功しており、--provider の文字種バリデーションだけが個別に効いているという挙動が確認できました。対話モードの /setup-providers ウィザード経由であればスペース入り名を入力させない可能性もありますが、少なくとも設定ファイルを手書き・自動生成してから CLI フラグで指定する運用では、ハイフンかアンダースコア区切りの name にしておくのが無難です。

daemon サブコマンドと Copilot 連携

nanocoder daemon --help を実行すると、プロジェクト単位のスキルデーモンを start/stop/status/logs/install/uninstall で管理できることが分かります。エディタ内で常駐させて MCP ツールのように使う想定と考えられますが、今回は起動確認までに留めました。copilot login サブコマンドも用意されており、GitHub Copilot をデバイスフローで認証してプロバイダとして扱える設計です。

まとめ

Nanocoder は npm 一発でインストールでき、プロバイダを選ばない設計が徹底されている OSS コーディングエージェントです。ただし、公式ドキュメントの設定例をそのまま --provider フラグに渡すとバリデーションで弾かれる、という実装と説明の齟齬に実機で遭遇しました。ローカル LLM や複数プロバイダを切り替えて Claude Code・Codex 以外の選択肢を試したい場合、プロバイダ名は英数字・ハイフン・アンダースコアに揃えて設定するところから始めるとつまずきません。

関連記事

• OfficeCLI入門 — Excel数式を自動評価するAI向けCLIの仕組み
• agmsg入門 — MCPなしでClaude CodeとCodexを直接会話させる仕組み
• Claude Codeの10分の1のトークンで動くエージェント「Pi」を試した

参考リンク

• Nano-Collective/nanocoder（GitHub）
• Nanocoder 設定ドキュメント（GitHub・mainブランチ）
• npm: @nanocollective/nanocoder