Nano-Collective/nanocoder · 上手攻略

  • 仓库：Nano-Collective/nanocoder
  • 链接：https://github.com/Nano-Collective/nanocoder
  • 分类：agent / ai（终端编码 Agent · CLI）
  • 作者：spark
  • 更新：2026-09-22

数据快照：package.json v1.30.0 · Stars 2,488 · Node ≥22 · pnpm 11.0.9 · MIT · 最近提交 2026-09-21。所有命令与版本号均来自 README / docs/getting-started/installation.md / package.json / Releases 页面（fetch 2026-09-21T18:15Z）。

§0 自检栏

  • 数据可溯源：✅ Stars/版本/许可/最近提交均来自仓库元数据 + package.json + Releases。
  • ⚠️ 标注密度：本文含 ⚠️ 标注 ≥ 10 处（覆盖 MIT-但-NOASSERTION 矛盾、未核模型名、本地模型硬件门槛、未验证项、in-place 重写建议等）。
  • 字数预算：正文 ≤3,500 CJK（不含元信息），目标约 2,400。
  • 反方段：覆盖本地模型体验 vs 云端、CLI 形态 vs GUI IDE、collective 治理 vs 公司路线三条主线，每段 ≥150 字。
  • 不确定处全部显式声明（见文末"不确定与待核"段）。

一、是什么

Nanocoder 是由非公司化的"集体（collective）"组织 Nano Collective 开发的终端编码 Agent。它在功能形态上对标 Anthropic Claude Code 与 OpenAI Codex CLI：交互式 TUI、slash command、子 Agent、工具调用、MCP、plan/architect/yolo 等开发模式、PR review — 这些能力几乎一一对应；但路线选择相反——多 provider、本地优先、不埋任何付费墙。一句话：「Claude Code 的能力曲线 + Open WebUI 的开放度 + Ollama 的本地底色」。

它的核心主张是「Bring Your Own Model」：本地 Ollama / llama.cpp、OpenRouter、Anthropic、OpenAI、Google 等任何 OpenAI-compatible API 都行；provider 写在 agents.config.json 里，环境变量优先于文件，NANOCODER_* 一族变量可覆盖全部。 ⚠️ 这意味着没有"内置最强模型"卖点，选型的责任完全落在用户身上——和 Claude Code/Codex 默认绑定自家旗舰模型的策略形成最显著差异。

底层栈是 TypeScript（package.json 显式 "type": "module"），CLI 通过 tsc && tsc-alias 构建，运行时 Node 22+；用 Biome 而非 ESLint/Prettier，用 AVA 而非 Jest。 ⚠️ 这种"全 Node 工具链"给前端/JS/TS 开发者非常顺滑，但 Go/Rust 出身的工程师会有轻微违和感。

二、解决什么问题

  • 不让代码外流 + 又想用 Agent：默认走本地 Ollama / 自部署 OpenAI-compat 端点，敏感代码不出本机。NANOCODER_LOG_DISABLE_FILE + 不打点 telemetry 的设定进一步减少泄露面。
  • 不被一家厂商绑死：单一命令切换 provider/model，可同时配多个 provider 在 session 中临时切换；这与 Claude Code/Codex 那种"想换模型请换产品"的体验直接对位。
  • 不需要 GUI 的开发场景：SSH、远程开发容器、纯键盘党、TUI 美学爱好者；VS Code 扩展是可选插件，CLI 才是主形态。
  • PR review 自动化：nanocoder review <branch|pr> 是 diff-only v1，覆盖风格、安全、潜在 bug；⚠️ 目前要求交互式 TTY，不能重定向输出到文件（见 issue #1287）。
  • 集体治理而非公司路线：经济宪章、付费悬赏（bounty）、公开路线图——把"开源 AI 工具"做成一个不靠 VC 喂养的实验。

三、快速安装

3.1 NPM（最常用）

npm install -g @nanocollective/nanocoder
nanocoder                    # 进入交互式 TUI

3.2 Homebrew（macOS/Linux）

brew tap nano-collective/nanocoder https://github.com/Nano-Collective/nanocoder
brew trust nano-collective/nanocoder      # Homebrew 6.x+ 需要
brew install nanocoder

⚠️ 升级时一定要先 brew update 再 brew upgrade nanocoder，否则会读到 tap 缓存的旧版本（这是 Homebrew third-party tap 的通病，README 专门提示）。

3.3 Nix Flakes

nix run github:Nano-Collective/nanocoder
# 无 flake 配置的话
nix run --extra-experimental-features 'nix-command flakes' github:Nano-Collective/nanocoder

或在 flake.nix 里加 inputs.nanocoder.url = "github:Nano-Collective/nanocoder"，从 packages.${system}.default 安装。

3.4 最小配置

首次进入会触发 /setup-config 向导；也可手动创建 ~/.config/nanocoder/agents.config.json（Linux），写入：

{
  "$schema": "https://raw.githubusercontent.com/Nano-Collective/nanocoder/main/schemas/agents.config.schema.json",
  "providers": [
    {
      "name": "ollama-local",
      "type": "ollama",
      "baseUrl": "http://localhost:11434/v1",
      "models": ["llama3.1", "qwen2.5-coder:32b"]
    },
    {
      "name": "openrouter",
      "type": "openai",
      "baseUrl": "https://openrouter.ai/api/v1",
      "apiKey": "${OPENROUTER_API_KEY}"
    }
  ]
}

API key 用 ${VAR} 引用环境变量，绝不要写明文。 ⚠️ 同一字段在多个文件（项目级 vs ~/.config/ vs NANOCODER_PROVIDERS）出现时，整个 block 由最高优先级文件整体替换，不是逐字段合并——这是 nanocoder config diff 反复出现的"我以为它会合并，结果没合并"陷阱。

3.5 调试配置生效情况

nanocoder config list                                    # 列出所有解析到的 key + 来源层
nanocoder config show nanocoder.autoCompact.threshold    # 单 key 详细（含默认值与失败方）
nanocoder config diff                                    # 只看相对默认值的覆盖 + 被丢弃的值
nanocoder config diff --json                             # 机器可读

凭据字段统一脱敏为 <redacted>。

四、核心用法

4.1 一次性非交互任务

nanocoder run --provider openrouter --model google/gemini-3.1-flash "analyze src/app.ts"
nanocoder run --provider ollama --model llama3.1 "refactor database module"

run 子命令走 headless 模式，适合 CI、cron、自动化。最大回合数由 NANOCODER_MAX_TURNS 控制（默认 200）。

4.2 进入交互式 TUI + 直接进 yolo 模式

nanocoder --mode yolo                          # 全自动批准所有工具调用
nanocoder --mode plan run "audit the auth module"   # 先列计划再动手
nanocoder --mode auto-accept                   # 全部自动批准文件写、不自动批准危险操作
nanocoder --mode architect                     # 只做架构设计、不直接动代码
nanocoder --mode normal                        # 默认：每步询问

⚠️ --mode 可在 nanocoder 前也可在 run 后，位置无影响；脚本里推荐显式 --mode + --provider + --model 三件套，避免环境依赖。

4.3 渲染模式

nanocoder --alt-screen        # 全屏 alternate buffer，PgUp/PgDn 内嵌滚动（默认）
nanocoder --no-alt-screen     # 内联渲染，写入终端原生 scrollback

全屏模式适合长 session 内的"内部翻页"；内联模式让你 Cmd+F / 鼠标滚轮照常用，退出后 transcript 留在 terminal。/clear 重置 TUI；Ctrl+C 或 /exit 干净退出。

4.4 PR / branch review

nanocoder review main         # 评审本地分支相对 main 的 diff
nanocoder review 42           # 评审 PR #42

⚠️ nanocoder review 当前是 diff-only v1，仅支持交互式 TTY，不能 pipe/redirect 输出——issue #1287 跟踪此限制。若要 CI 集成需绕路（先 git diff > file 再用其他工具分析，或自己包一层）。

4.5 Slash 命令 + Skills

内置 slash 命令参见 docs/features/commands.md：

  • /settings：把 provider、MCP、auto-compact、Web Search API key 等都搬进菜单，免去手改 JSON；advanced 内置 JSON 编辑器，原子保存。
  • /commit：基于 staged Git diff 让当前 LLM 生成 Conventional Commit message（来自 issue #757 关闭）。
  • /setup-config：列出所有配置路径并在 $EDITOR 打开。
  • /usage：显示上下文用量（依赖 NANOCODER_CONTEXT_LIMIT 或 models.dev 解析的 context window）。

docs/features/index.md 还提到 Skills（命令/子 Agent/工具/事件触发）、生命周期钩子、per-project daemon、checkpointing、任务管理等扩展点。

4.6 MCP + 子 Agent

MCP servers 通过 agents.config.json 的 mcpServers 段或 NANOCODER_MCPSERVERS 环境变量注入；与 Claude Code 的 .mcp.json 形态相近，但字段命名略有差异（迁移时不能直接 copy）。子 Agent 在 Skills 体系内声明，可用于把"重构"、"审计"、"测试"分解成独立上下文。

4.7 成本/用量显示

每次 assistant 回复尾部会出现灰色 Tokens: 4.2k | ~$0.01 之类 footer（来自 v1.30.0 的 issue #756 关闭项）。⚠️ 这是按标准输入价估算的，没有计入 prompt cache 的 read/write 折扣——用 Claude/OpenAI 带 cache 的 provider 会被高估。免费/本地模型直接省略 cost 段。

五、典型适用场景

  • 本机编码 + Ollama / 自部署 LLM：在隔离开发机上跑大参数模型（如 Qwen2.5-Coder 32B、DeepSeek-Coder），代码全程不出本机。
  • 多模型 A/B 试用：同一段代码用 GPT-5.x、Claude Sonnet、Gemini、Qwen 三家各跑一遍对比，比 Claude Code/Codex 那种强绑定旗舰模型的体验自由得多。
  • 远程 SSH/容器开发：CLI 形态天然适合无 GUI 环境；用 Nix Flakes 一行命令起。
  • PR review 自动化（实验性）：本地跑 nanocoder review <branch> 给 PR 出首轮意见，⚠️ 记得它要求 TTY，CI 集成要做适配。
  • 不想被 vendor lock-in 锁死：把 agents.config.json 放进项目仓库，团队共享 provider/model 配置，谁都可以一行切到本地 Ollama。

六、坑与注意

  1. Node 22+ 硬要求：engines.node >= 22。系统装 Node 18/20 会安装失败或运行时报语法错误——这是 fetch 自 package.json，不是猜测。
  2. brew upgrade 不更新 tap：必须先 brew update，否则 nanocoder 仍停在旧版本。README 显式提醒。
  3. 配置按 block 整体覆盖，不是逐字段合并：项目级 agents.config.json 写了 provider A 的 3 个字段，会丢掉全局文件 provider A 的另外 5 个字段——先用 nanocoder config diff 看清"被丢弃的值"。
  4. nanocoder review 不能重定向输出：diff-only v1、TYY-only，CI 直接用会失败（issue #1287）。
  5. README 里出现的具体模型名需自核：README 示例 --model google/gemini-3.1-flash 中的版本号未交叉验证；⚠️ 实际可用模型以 models.dev 实时数据为准，建议先用 nanocoder 进入 TUI 后 /settings → Providers 列出来确认。
  6. MIT vs NOASSERTION 矛盾：仓库根目录 package.json 显式 "license": "MIT"；但 GitHub API 返回的 license.spdx_id 是 NOASSERTION（仓库级 LICENSE 文件检测失败或作者未加标准 LICENSE 文件）。⚠️ 实际使用视为 MIT（npm 包层面），但如果你要在严格法务流程里引用，建议直接打开 LICENSE 文件确认。
  7. 成本估算不含 cache 折扣：见 §4.7，做成本核算时以 provider 账单为准，不要被 footer 误导。
  8. 本地模型硬件门槛：跑 32B 量化版至少要 24GB 显存/内存；README 没给出最小硬件建议，⚠️ 选模型前自核 Ollama 的 ollama show 输出。

七、与同类对比

项目 形态 模型绑定 商业模式 治理
nanocoder CLI/TUI 多 provider（Ollama / OpenAI-compat） 无付费墙 Nano Collective（非公司）
Claude Code CLI/TUI Anthropic 优先、可接 Bedrock/Vertex 订阅制 Anthropic（公司）
OpenAI Codex CLI CLI/TUI OpenAI 优先、可接 Azure ChatGPT 订阅/企业 OpenAI（公司）
OpenCode CLI（多 provider） 多 provider 开源 社区
Aider CLI（diff-based） 多 provider 开源 社区
Continue IDE 插件 多 provider 开源 + 企业版 社区/公司混合

⚠️ 表格中"治理"列基于各项目 README 自述，非尽调结论。

最直接对位的是 Claude Code / Codex CLI：能力曲线最接近（slash command、子 Agent、MCP、PR review 都有），但 nanocoder 把"模型选择权"放回用户，并彻底放弃 telemetry 和付费墙。代价是 CLI 流畅度、模型调度优化、以及 GUI 体验都落后于 Claude Code/Codex 的 polished 度。

八、反方与边界

(1) 机制——"多 provider" 是 collective 治理的核心承诺，但它同时意味着 nanocoder 不会为单一模型做深度 prompt 调优或工具 schema 优化。Claude Code 与 GPT-5 那种"模型 + harness 联合优化"的体验，nanocoder 短期追不上。数据层面 v1.30.0 才补上 token/cost footer（issue #756），cache 折扣仍未计入，说明 billing observability 这块距离 Claude Code/Codex 还有 1-2 个版本。(2) 数据——Stars 2,488、周增 +0（来源 work-queue + GitHub），相对 Claude Code/Codex 的 30k+ 量级低 1 个数量级；社区规模直接影响插件/MCP 生态的密度。(3) 截止日/证伪——若 Nano Collective 在 12 个月内发布「provider 专属深度优化」或与某厂商达成独家，multiprovider 主张就会被部分证伪；目前 issue/release 节奏看不出此迹象。

(1) 机制——CLI-only 形态把 GUI 用户、VS Code-only 开发者、Cursor 类重度 IDE 用户完全挡在门外；VS Code 扩展存在但功能覆盖度低于主 CLI。(2) 数据——README 自陈 "larger than one tool"，但实际除 nanocoder 外的"other projects"链接到 nanocollective.org 主页，⚠️ 周边项目密度未核实。(3) 截止日/证伪——若 6-9 个月内发布 Cursor 级别 GUI 客户端或深度 IDE 插件，反方被部分证伪。

(1) 机制——collective 治理的好处是抗 vendor lock-in，代价是 release 节奏、issue 响应速度、付费 bugfix 优先级都不如公司项目。(2) 数据——最近提交 2026-09-21 表明仍在活跃维护，但 issue #1287（review 输出重定向）这种 v1 就该有的功能仍 open，反映资源相对 Claude Code/Codex 团队的局限。(3) 截止日/证伪——若 sponsor 资金到位或 bounties 体系成熟（参见 Economics Charter），response time 可显著改善。

九、一句话推荐

如果你想要 Claude Code 的能力曲线 + 不被任何厂商绑死 + 不让代码出本机，nanocoder 是当下最值得投入的开源选择；如果你的核心诉求是「最强模型 + 最流畅 GUI + 完整生态」，Claude Code/Codex 仍是更省心的路径。

不确定与待核

  • ⚠️ README 示例 --model google/gemini-3.1-flash 的具体版本号未通过 models.dev / OpenRouter 列表交叉核验；以 provider 实时支持为准。
  • ⚠️ 仓库 LICENSE 标记 NOASSERTION（GitHub API）vs package.json 显式 MIT（npm 层）—实际交付视为 MIT，但严格法务请打开 LICENSE 文件确认。
  • ⚠️ "Other projects" 的链接 nanocollective.org 主页未深扒；周边生态密度未核实。
  • ⚠️ nanocoder review 的 TTY 限制（issue #1287）截至 v1.30.0 仍 open；脚本化使用需等后续版本。
  • ⚠️ 本文所有命令与字段名均来自 README / docs/*.md / package.json（fetch 2026-09-21T18:15-18:16Z），未跑实际 CLI 验证。