一套小型本地模型真正能用的工具腰带——以及证明其效果的实测数据。
pip install openlocal
openlocal quickstart就是这样。quickstart 会找到你已在运行的模型服务器——ollama、LM Studio、llama.cpp、vLLM——写入你的配置，测量你的模型实际能驱动的工具调用协议，然后运行一个真实任务，让你看到它工作：
$ openlocal quickstart
openlocal quickstart - looking for a model server...
found ollama at http://127.0.0.1:11434/v1 with 6 model(s)
wrote ~/.openlocal/models.toml
default model: qwen3-4b (served as qwen3:4b)
measuring which tool protocol this model can drive...
-> native tool calling
demo: Read notes.md and tell me how many lines it has.
tool file_read
final
The file notes.md has 3 lines.
You are set up. Try:
openlocal run "list the files here and summarise what this project is"
openlocal eval # score this model on 15 deterministic tool tasks
openlocal mcp # serve these tools to Claude Code over MCP🪶 零依赖 | 纯标准库。几秒安装，可在树莓派上运行，不会被其他人的发布版本破坏。 |
🔌 与你已有的工具兼容 | 任何支持 OpenAI |
📊 可测量，而非空谈 | 来自 9 家供应商的 10 个模型，在 17 个确定性任务上评分。没有 LLM 裁判——每项检查都是文件差异或正则表达式。 |
🧰 一个注册表，两种界面 | 同一套 8 个工具驱动 MCP 服务器（Claude Code，任何 MCP 客户端）和本地模型代理循环。 |
🩹 基于真实失败调优 | 这里的每一条人体工程学规则都是用模型崩溃换来的。经验教训表 是你在其他地方找不到的部分。 |
🧩 通过编辑 TOML 添加供应商 | 新的模型系列？编辑 |
Related MCP server: Hermes MCP Server
相同任务，相同工具，一次一个模型，每次运行两次。tools 是每个模型实际测量驱动的协议——而非其文档声称的协议。
model | vendor | tools | passed | pass rate | bad json | tok/s |
| Alibaba | native | 17/17 | 100% | 0 | 40.4 |
| z.ai | native | 17/17 | 100% | 0 | 39.9 |
| Alibaba | native | 17/17 | 100% | 0 | 16.6 |
| NVIDIA | native | 16/17 | 94% | 0 | 54.9 |
| native | 16/17 | 94% | 0 | 50.3 | |
| OpenAI | native | 16/17 | 94% | 2¹ | 45.3 |
| IBM | native | 15/17 | 88% | 4 | 66.0 |
| Meta | native | 14/17 | 85% | 2 | 33.4 |
| Mistral | native | 14/17 | 82% | 0 | 11.1 |
| Microsoft | native | 13/17 | 79% | 0 | 61.5 |
¹ gpt-oss 的 harmony 解析器拒绝其自身的一些工具调用（llama.cpp 返回 500）。客户端的重试阶梯会恢复每一个——RESULTS.md 中的 retries 列保证了这一点。
重现方法：openlocal leaderboard --repeat 2
一个 3B 模型失败不是因为笨。而是因为工具输出是一个提示，而大多数工具输出是为人类编写的。以下所有内容都是测量得出的——分数上升时保留，下降时回退。
什么问题 | 修复方法 | 测量效果 |
“第 300 行是什么？”→ 模型回答了第 311 行 | 每行编号： | 一轮修复，跨模型有效 |
模型每轮遍历一个 500 行文件，一次一行 | 页脚陈述事实，而非命令（“文件继续”≠“再次调用以获取…”） | phi：12 次浪费步骤 → 2 |
用散文代替工具调用 | 无工具的散文 = 最终答案（仅限 native） | phi：51 次格式错误回复 → 5 |
……但“当然，我会用 file_grep”是一个计划 | 意图检测：计划被提示，答案被接受 | 运行不再以意图结束 |
| 散文式调用语法被解析并执行 | 消除浪费的轮次 |
| JSON 修复：括号扫描、尾部闭合、Python 字面量、片段合并 | phi bad_json 5 → 0 |
模型在读取源文件之前就写入了文件 | 完成时的陈旧写入检测 | llama：13 → 15 / 15 |
模型猜测“44”并在被提示时重复 | 一轮 | granite 恢复了任务 |
完美读取一个 4 行 CSV，却说总和是 40 | 一个 | granite：+2 个任务 |
从未读取源文件就写入了输出文件 | 完成时的凭空写入检测 | qwen-4b 通过 MCP 恢复 |
将 |
| edit_code：10/10 模型通过 |
相同调用，无限循环（A→B→A→B） | 重复守卫重放缓存结果 | llama 分页循环消失 |
服务器对其自身的工具调用语法返回 500 | 重试阶梯：按原样 → 更温暖 → 同一轮不带 | gpt-oss：11/15 → 14/15 |
已回退： 再多一条系统提示规则 | — | granite 12/15 → 11/15。规则越少越好。 |
openlocal eval --via-mcp 通过真实的 stdio MCP 服务器重新运行整个评估套件——工具通过线路传输模式，结果作为内容块，每个任务一个子进程。分数与进程内数字匹配，这正是关键所在：Claude Code 体验到的就是被测量的结果。
pip install "openlocal[mcp]"
claude mcp add openlocal -- openlocal mcp你的本地模型使用的同一套 10 个工具，现在在 Claude Code 中可用。finish 保留在后面——它是循环控制，而非能力。
openlocal quickstart # find a server, configure, probe, demo
openlocal run "goal" # agent loop over your tools
openlocal run "goal" --url http://host:1234/v1 # no config at all
openlocal chat "hello" # one plain turn, no tools
openlocal tools # what the model can call
openlocal probe # measure native vs JSON tool calling
openlocal eval # 17 deterministic tasks, pass/fail
openlocal eval --via-mcp # same tasks, tools served over a REAL MCP server
openlocal leaderboard --repeat 2 # every configured model, one table
openlocal mcp # stdio MCP server
openlocal models / serve / stop / status / pull # local llama-server managementsmol 是同一 CLI 的较短别名。
你的工作空间是 ~/.openlocal（或任何包含 models.toml 的目录，或 $OPENLOCAL_HOME）。它包含 models.toml、state.json、日志、下载文件和评估结果——从不包含已安装的包。
[engine.ollama]
type = "external"
base_url = "http://127.0.0.1:11434/v1"
[[model]]
id = "qwen"
engine = "ollama"
family = "qwen" # tells openlocal this vendor's tool-calling quirks
served_model = "qwen3:4b" # the exact name the backend knows
default = true环境变量 | 默认值 | 含义 |
|
| 工作空间目录 |
| – | 将所有命令指向一个 |
| cwd | 文件和 shell 工具的沙箱根目录 |
| 8000 | 单个工具结果的硬上限 |
| 开发命令 | 逗号列表，或 |
| 120 | MCP 工具调用被放弃前的秒数 |
file_list(path=".") list files and folders
file_read(path, start_line=1, limit=200) read a file, one page at a time
file_write(path, content) write a file
file_edit(path, find, replace) replace text exactly, leave the rest alone
file_append(path, content) add to the end without touching what exists
file_grep(pattern, path=".") search files
web_search(query, limit=5) search the web (DuckDuckGo, or Tavily via key)
web_read(url, offset=0, max_chars=4000) read a page as text
shell_run(command, timeout=60) run one allowlisted command
calc(expression) exact arithmetic - models cannot count
finish(answer) agent loop only: end the task内部规则，由测试强制执行：带默认值的扁平参数，每个描述中的示例调用，单行结果标题，带真实延续提示的硬上限输出，以及指明下一步操作的错误——no such file: x - call file_list(".") to see the files that exist。
tools/ one registry → mcp_server.py (Claude Code speaks MCP to it)
→ agent.py (a local model calls the same tools)
_http.py the entire network layer, on urllib (this is why deps = 0)
runner.py external servers, or llama-server processes it starts and owns
protocol.py native tool_calls → loose JSON → repair → symptom-specific nudge
families.toml per-vendor quirks as DATA - the file contributors edit
evals/ 17 deterministic tasks + a leaderboard across models添加一个模型系列无需 Python：编辑 families.toml，将你的模型添加到 models.toml，然后
openlocal probe --model your-model
openlocal eval --model your-model并将生成的行粘贴到 PR 中。参见 CONTRIBUTING.md。
在 AMD 硬件（ROCmFP4 + MTP 推测解码）上运行本地 GGUF 模型的方法记录在 docs/ENGINE.md 中——可选，且对于上述任何内容都不是必需的。
MIT © DevXV3
This server cannot be deployed
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
MCP server for building and testing AI agents with multi-model experimentation and insights.
MCP server for progressive tool usage at any scale (see https://klavis.ai)
MCP-first toolbox for agents: KV storage, auth, queue, and utility tools. Free in early access.
