gakonst/nanocodex · 上手攻略

  • 仓库：gakonst/nanocodex
  • 链接：https://github.com/gakonst/nanocodex
  • 分类：AI Agent 框架 / OpenAI Agent SDK
  • 作者：Tom
  • 更新：2026-10-08

是什么

Nanocodex 是一个无头、库优先的 Rust SDK，用于构建基于 OpenAI 编码 Agent 的产品。它把完整的 OpenAI Responses 循环（包括保留会话、类型化历史、工具调用、Code Mode、分支、事件流、重试和清理）打包成一个嵌入式生命周期，开发者保留自己的界面、数据、内存、基础设施和策略。

核心定位是「编码 Agent 就是这个库」，而非提供一个完整的应用服务器或供应商抽象层。Nanocodex 把调用者不需要重复构建的部分全部封装好：不需要在每次调用时手动传递历史消息、不需要单独的状态机处理断线重连、不需要把事件流和类型结果耦合在一起、不需要担心 Agent 分叉时产生孤儿进程。

解决什么问题

自建 OpenAI Coding Agent 通常面临几个绕不开的工程难题：

  • 每次调用要手动维护 messages[] 数组和 response_id
  • 断线重连时需要实现 replay 逻辑
  • 工具调用结果和事件流耦合混乱
  • Agent 分叉（fork/delegate）时进程树管理复杂
  • 格式化输出（如 TUI、React）需要重新发明轮子

Nanocodex 把这些问题全部封装进一个 Rust 核心库，提供 Rust / Node.js / Python / macOS App / iOS App 多语言绑定，所有语言路径共享同一个 Rust 生命周期实现。

快速安装

Rust（推荐方式）

cargo add nanocodex

要求 Rust ≥1.9（从源码开发需要 Rust 1.97 + wasm32 目标 + wasm-bindgen-cli 0.2.126）。

Node.js（22.13+）

npm install nanocodex

⚠️ 22.13+ 是已发布包的消费者最低要求；源码开发需要 Node.js 24。

Python（3.11+，从源码构建）

uv venv --python 3.11 py/bindings/.venv
uv pip install --python py/bindings/.venv/bin/python 'maturin>=1.9,<2'
VIRTUAL_ENV="$PWD/py/bindings/.venv" \
  py/bindings/.venv/bin/maturin develop --manifest-path py/bindings/Cargo.toml

一键安装 CLI/TUI（macOS / Linux）

curl -fsSL https://nanocodex.paradigm.xyz | bash
nanocodex

支持 Apple Silicon macOS、x86-64 glibc Linux 和 x86-64 Windows 10/11（PowerShell bootstrap）。

Nix（Linux / macOS）

nix run github:gakonst/nanocodex
# 或安装到 profile
nix profile install github:gakonst/nanocodex

也提供 NixOS module 和 nix-darwin module。

核心用法

Rust 基本模式

use nanocodex::*;

let agent = Agent::new("gpt-4o", api_key)?;
let session = agent.session().with_tools(my_tools);

let response = session.prompt("帮我写一个 HTTP 服务器").await?;
println!("{}", response.text());

CLI/TUI 使用（nanocodex 命令）

安装后直接运行 nanocodex，它会启动一个持久化的 Hand（计算代理实例），sign-in 后在后台保持运行，关闭终端不会中断。

nanocodex2 run    # 启动新任务
nanocodex2 attach # 接入已有 Hand

⚠️ Hand 是 Nanocodex 的核心概念：一个持久化的、长期运行的 Agent 实例，跨终端保持状态。

从源码开发完整栈

rustup toolchain install 1.97
rustup target add wasm32-unknown-unknown --toolchain 1.97
cargo +1.97 install --locked wasm-bindgen-cli --version 0.2.126
corepack enable
pnpm install --frozen-lockfile
pnpm build
pnpm dev   # 通过 Portless 启动完整 Turbo stack

本地 HTTPS 需要一次证书信任配置；macOS 绑定 443 端口可能需要管理员权限。

推送前检查

pnpm check:fast

会运行 cargo fmt 和 CI Clippy 命令，检查自 origin/master 以来变更的 crates。

典型适用场景

  1. Rust 原生应用嵌入 Agent：在 Rust 服务中直接集成 OpenAI Coding Agent，不需要额外进程
  2. 跨平台 Agent 产品：共用 Rust 核心，绑定 Node.js / Python / Swift 多语言前端
  3. 桌面/移动 Agent App：Nanocodex 的 macOS 原生 App（SwiftUI/AppKit）和 iOS Inbox 是它自身的产品示范
  4. 需要持久化 Hand 的场景：后台长期运行 Agent，需要跨会话保持上下文
  5. 评测/沙箱集成：项目自带评测 harness 和沙箱支持

坑与注意

  1. Python 绑定需要从源码构建：没有预编译的 PyPI wheel，需用 maturin 从 checkout 构建（maturin develop）
  2. macOS CLI 签名需一次配置：HTTPS 证书和 443 端口权限需要在首次使用时处理
  3. Hand 生命周期需要理解：Hand 是持久化的，不理解这一点可能导致多个重复 Hand 被启动
  4. Intel macOS 二进制暂不支持：x86-64 macOS 没有预编译二进制（上游未发布）
  5. Windows 引导脚本需要 PowerShell：irm ... | iex 是 PowerShell 语法，CMD 不适用
  6. Portless 开发依赖：本地 pnpm dev 需要通过 Portless 代理，不是标准反向代理
  7. Node.js 22.13+ 才可消费发布包：用旧版 Node.js 需要从源码构建

与同类对比

Nanocodex LangChain.js OpenAI SDK (official)
架构 无头库 + 多语言绑定 应用框架 基础 HTTP 客户端
生命周期管理 内置持久化 Agent + Hand 需自行实现 需自行实现
工具调用 自动管理 支持 基础支持
状态持久化 有（Hand 概念） 无 无
多语言 Rust/JS/Python/Swift JS/Python 多语言官方 SDK
Agent 分叉/分支 原生支持 需自行实现 不支持
评测/沙箱 内置 harness 无 无
上手门槛 高（Rust-first） 中 低

Nanocodex 的核心差异化在于 Rust 性能 + 多语言绑定 + 持久化 Agent 生命周期，适合要做 Agent 产品而非实验性项目的团队；LangChain 适合快速原型；官方 SDK 适合轻量调用。

一句话推荐结论

如果你的产品需要嵌入一个持久化的 OpenAI Coding Agent，且团队有 Rust 能力或需要多语言支持，Nanocodex 是目前该领域最认真工程化的选择——它解决的不是「怎么调用模型」，而是「怎么正确管理一个长期运行的 Agent 的全部生命周期」；如果只是轻量调用模型，直接用 OpenAI SDK 即可。