Mistral Vibe CLI 搭配本地 Devstral：设置中 route

#Mistral Vibe CLI：它是什么，以及它不是什么

Mistral Vibe CLI 是一个用 Python 编写的命令行程序，于 2025 年 12 月与 Devstral 2 和 Devstral Small 2 同时发布。您在项目目录中启动它，用自然语言描述任务，代理会读取文件、提出修改、执行命令，并不断迭代直到得到结果。其原理与 Claude Code、OpenCode 或 Aider 相同，但围绕 Devstral 模型设计；这些模型经过训练，适合这种代理循环。

源代码发布在 GitHub 的 mistralai/mistral-vibe 仓库中，Mistral 的公告称其采用 Apache 2.0 许可证。您可以阅读、修改并在企业中使用它，无需支付许可费。CLI 能够连接 Mistral 的 API，也能连接任何公开 OpenAI 格式 API 的服务器：Ollama、llama.cpp、LM Studio 或 vLLM。我们这里关注的是第二种模式，文档“offline models”对此有说明。

为什么要选择本地 Vibe CLI，而不是 API？主要有三个原因。代码不会离开机器，这对于专有代码或受保密协议约束的代码很重要。没有按使用量计费，也没有配额：您只需支付已有硬件的电费。最后，该工具可以继续在离线环境或严格防火墙之后运行。代价是，您无法使用拥有 123 十亿个参数的 Devstral 2，因为它太大，不适合工作站；同时还要接受低于生产服务器的速度。

#前置要求：Python、Ollama 以及运行 Devstral Small 2 所需的内存

在安装任何东西之前，请检查这四点。它们可以避免使用本地代码代理时遇到的四分之三故障。

系统

主要面向 Linux 或 macOS。在 Windows 下，请使用 WSL2（Ubuntu）：CLI 会像在 Linux 下一样安装，而用于 Windows 的 Ollama 仍可通过 localhost 地址从 WSL 访问。

较新的 Python

CLI 以 Python 软件包形式发布。代码仓库在其 README 中注明所需的最低版本；在公告发布时，要求 Python 3.12 或更高版本。继续之前，请使用 python3 --version 检查。

已安装并启动 Ollama

Ollama 提供模型服务，并在 http://localhost:11434 上公开兼容 OpenAI 的 API。如果尚未完成安装，我们关于 Ollama 的安装指南涵盖三种系统。

24B 模型所需的内存

Devstral Small 2 包含 24 十亿个参数。在 Q4_K_M 量化下，权重约占 14 GB，此外还要加上上下文缓存。要获得舒适的运行体验，请准备一块 24 GB 的 GPU（RTX 3090、RTX 4090）或一台配备 32 GB 统一内存的 Mac。Mistral 的公告还将「一块 RTX 4090 或一台配备 32 GB RAM 的 Mac」列为目标配置。

使用 16 GB 的 GPU（RTX 4080、RTX 5070 Ti 桌面显卡）时，Q4 模型可以装下，但上下文很快会溢出到系统内存，速度也会下降。使用 12 GB（RTX 3060、RTX 4070）时，Ollama 会在 GPU 和 CPU 之间分配层：代理可以运行，但每轮循环需要几十秒。我们没有测量这些显卡上的具体吞吐率；只需记住，对于以代理方式使用的 24B 模型，24 GB 是舒适运行的门槛，因为上下文会随着读取的每个文件不断增长。

#安装 Mistral Vibe CLI

Mistral 提供单行安装脚本，可在隔离环境中部署 CLI。这是仓库 README 推荐的方法。

curl -LsSf https://mistral.ai/vibe/install.sh | bash

如果您希望控制安装过程，该软件包以 mistral-vibe 的名称发布在 PyPI 上。工具 uv 会将其安装到专用环境中，不会影响您的其他 Python 项目。传统的 pip 也可以使用，最好在虚拟环境中运行。

# Installer uv si besoin : https://docs.astral.sh/uv/
uv tool install mistral-vibe

# Ou avec pip, dans un environnement virtuel
python3 -m venv ~/.venvs/vibe
source ~/.venvs/vibe/bin/activate
pip install mistral-vibe

接下来请确认 vibe 命令可用。如果终端找不到它，请关闭终端后重新打开：安装脚本会将一个目录加入 PATH，并在 shell 下次启动时生效。

vibe --version
vibe --help

#在 Ollama 中准备 Devstral Small 2

Devstral Small 2 由 Mistral 以 Apache 2.0 许可证发布，支持 256 000 tokens 的上下文窗口。Ollama 将其列入了自己的模型库；下面的命令会下载默认版本，即 4 bit 量化版本。下载内容约为 14 GB。

ollama pull devstral-small-2
ollama list

库 Ollama 中模型的确切名称可能会变化（量化变体、大小后缀）。如果命令失败，请在 ollama.com/library 上搜索“devstral”，并使用页面显示的名称。您需要将该名称原样复制到 Vibe 的配置中，它应与 ollama list 中显示的名称一致。

还剩一个关键设置：上下文长度。Ollama 默认以较短的上下文加载模型，通常为 4 096 tokens。对于代码代理来说，这远远不够：Vibe 的系统提示词、工具列表、已读取文件的内容以及会话历史，几轮交互后就会超过这一大小。模型随后会忘记对话开头的内容，代理也会原地打转。请至少设置 32 000 tokens 的上下文，例如使用派生的 Modelfile。

cat > Modelfile.devstral <<'EOF'
FROM devstral-small-2
PARAMETER num_ctx 32768
EOF

ollama create devstral-small-2-32k -f Modelfile.devstral
ollama run devstral-small-2-32k "Réponds en un mot : prêt ?"

您也可以在服务 Ollama 启动时，通过环境变量 OLLAMA_CONTEXT_LENGTH 全局固定上下文。Modelfile 的优点是只作用于该模型，并且名称明确。上下文越长，消耗的内存越多：在 24B 模型上使用 32k tokens 时，根据 KV 缓存类型，需额外预留 2 到 4 GB。对于 24 GB 内存，这是较为舒适的上限；超过 64k 后，请通过 nvidia-smi 监控内存。

#在 config.toml 中接入本地模型

Mistral Vibe CLI 从文件 ~/.vibe/config.toml 读取配置。“offline models”文档在其中介绍了两个表：providers 用于声明服务器及其地址，models 用于将模型名称关联到提供商。active_model 键用于指定默认使用的模型。以下是针对上文准备的Ollama的完整配置。

# Modèle utilisé au lancement (doit correspondre à un alias ci-dessous)
active_model = "devstral-small-local"

# Fournisseur : votre Ollama local, API au format OpenAI
[[providers]]
name = "ollama"
api_base = "http://localhost:11434/v1"
api_key_env_var = ""
api_style = "openai"
backend = "generic"

# Modèle : le nom exact affiché par `ollama list`
[[models]]
name = "devstral-small-2-32k"
provider = "ollama"
alias = "devstral-small-local"
input_price = 0.0
output_price = 0.0

有三个细节需要说明。地址以 /v1 结尾，是因为 Vibe 使用 OpenAI 方言，而 Ollama 仅在此前缀下提供这种格式；Ollama 的原生 API 不带 /v1，因此不适用。api_key_env_var 保持为空：Ollama 在本地无需身份验证。价格设为零，是为了让 CLI 显示的成本估算保持一致；它们不会影响运行。

对于另一种本地服务器，只需更改 providers 部分。使用 llama.cpp（llama-server）时，地址通常是 http://localhost:8080/v1；使用 LM Studio 时是 http://localhost:1234/v1；使用 vLLM 时是 http://localhost:8000/v1。无论哪种情况，模型的 name 字段都必须填写该服务器所要求的标识符，也就是它在 /v1/models 路由上返回的标识符。

curl -s http://localhost:11434/v1/models | python3 -m json.tool

您可以声明多个模型，例如在本地使用 Devstral Small 2、通过 Mistral API 使用 Devstral 2，然后在会话中切换。对于提供商 Mistral，API 密钥从环境变量中读取，通常是 MISTRAL_API_KEY；密钥无需明文写入文件。如果您的目标是 100% 本地运行，只需不要添加任何远程提供商：不会有任何内容离开机器。

#首次会话：启动 vibe 并检查模型

1. 01
   进入项目目录

   在 Git 仓库目录中打开终端，最好确保仓库干净（git status 显示没有待处理的修改）。代理会处理当前目录中的文件；干净的仓库便于使用 git diff 查看其修改，并用 git checkout 撤销这些修改。
2. 02
   启动 CLI

   输入 vibe。首次启动时，CLI 可能会要求输入 Mistral API 密钥，并创建 ~/.vibe 文件夹。如果你之前已经写入 config.toml，本地提供商就已被识别。如果仍然出现密钥提示，请查看 /help：根据版本不同，在配置了本地提供商时，可以跳过该提示或将其留空。
3. 03
   检查当前模型

   界面会显示当前模型。它应当是你的别名 devstral-small-local。/help 命令会列出会话中可用的命令，其中包括在你声明了多个模型时切换模型的命令。
4. 04
   布置第一个有边界的任务

   从小任务开始：「阅读 README，并用五行总结项目架构」，然后说：「为文件 Y 中的函数 X 添加一个单元测试」。观察第一次响应：如果模型不使用工具就直接回答，或虚构文件路径，通常是上下文太短，或者模型没有针对工具调用进行准备。
5. 05
   接受前先复核

   Vibe 会在执行敏感操作前请求确认，例如写入文件或执行命令。请阅读每一项拟议的 diff。本地运行的 24B 模型比通过 API 提供的 123B 模型更容易出错，尤其是在大型代码库上：复核是工作流的一部分，而不是例外情况。

会话期间，请留意 Ollama 的负载：命令 ollama ps 会显示已加载的模型、GPU 和 CPU 的占用比例，以及实际上下文。如果您原以为显存足够，却看到部分内容分配到了 CPU，那么就是上下文导致显卡溢出了。

ollama ps
nvidia-smi --query-gpu=memory.used,memory.total --format=csv

#100% 本地 Vibe CLI 的局限

本地代码代理可以运行，但不能与 API 版本逐项直接比较。以下是您可以预期的情况，不包含臆造的数字：我们没有为本指南进行基准测试，而 Mistral 发布的分数针对的是在基准条件下提供服务的模型，不是搭载量化模型的台式机。

Devstral 2 仍然无法企及

拥有 1230 亿参数的大模型，即使经过高度量化，也需要数十 GB 内存。在本地，您使用的是 Devstral Small 2，Mistral 宣称其在 SWE-bench Verified 上达到 68,0 %，而 Devstral 2 为 72,2 %。在这一基准测试中差距不大，但在长时间任务和大型代码库上会有所体现。

量化会改变模型

公布的分数针对完整权重。Q4_K_M 会使精度略有下降；Q8_0 能更好地保持精度，但仅权重就需要约 26 GB，因此需要 32 GB 显卡或配置充足的 Mac。选择量化方式是一项需要充分了解情况后作出的权衡。

本地上下文远短于 256k

Devstral Small 2 支持 256 000 tokens，但在 24 GB 内存上无法实际使用这么长的上下文。在 32k 到 64k tokens 之间时，该代理可以覆盖一个模块或一个小型服务。对于 monorepo，则需要按文件逐一限定任务范围。

速度取决于硬件，而不是 CLI

在内存相同的情况下，稠密 24B 模型的生成速度低于规模相近的 MoE 模型。代理的每一轮循环都包含对完整上下文的重新读取：会话持续时间越长，每次响应所需时间就越久。请使用较短的会话，并将任务拆分开来。

工具调用与格式

该代理依赖结构化工具调用。量化模型偶尔可能生成格式错误的调用，从而被 CLI 拒绝。Devstral 针对这类用途进行了训练，表现远胜通用模型，但这种情况并非完全不会发生。

一个新生工具

CLI 于 2025 年 12 月发布，目前迭代速度很快。命令、配置格式以及与编辑器的集成都会变化。请定期更新（使用 uv tool upgrade mistral-vibe，或重新运行安装脚本），并在抱怨某个行为之前重新阅读 GitHub 上的版本日志。

Mistral 的公告还提到通过 ACP 协议与编辑器集成，尤其是 Zed。如果您更喜欢使用编辑器而不是终端，我们的 Zed + Ollama 指南展示了该编辑器如何与本地模型交互；将两者结合起来，就是让 Vibe 驱动代理，让 Zed 显示差异。

#故障排除

“vibe：找不到命令”

可执行文件目录不在您的 PATH 中。请重新打开终端。使用 uv 时，路径通常是 ~/.local/bin；请用 uv tool dir --bin 检查，并在必要时将其添加到 shell 配置文件中。

连接 localhost:11434 时出错

Ollama 未启动，或者正在监听其他地址。请测试 curl http://localhost:11434/v1/models。在 WSL2 下，请确保 Ollama 确实在 Windows 端运行，并且 OLLAMA_HOST 变量没有被限制。

服务器不认识该模型

models 部分的 name 字段与 ollama list 中的模型不匹配。请复制确切名称，包括后缀；如果创建了派生的 Modelfile，也要包含其中的名称。

智能体忘记了刚刚读过的内容

上下文过短。请使用 ollama ps 检查实际加载的上下文值；如果是 4 096，说明您的 Modelfile 或 OLLAMA_CONTEXT_LENGTH 变量未生效。

响应非常慢，GPU 利用率很低

模型的一部分运行在 CPU 上。请缩短上下文，改用更轻的量化方式，或关闭 Ollama 加载的其他模型（OLLAMA_MAX_LOADED_MODELS）。

CLI 要求 API 密钥，尽管一切都在本地运行

行为取决于版本。请确认 config.toml 确实位于 ~/.vibe/config.toml，active_model 指向一个已存在的别名，然后查看文档中的「offline models」页面，获取最新操作方法。

#深入了解

如果你重视 Mistral 生态和 Devstral，Vibe CLI 是不错的选择。如果你想在安装前进行比较，OpenCode 属于同一类别，支持的提供商更多；而本地代码模型的问题与所选代理无关。