Qwen Code：终端中的代码代理，配备 Ollama

#什么是 Qwen Code，以及为什么要在本地运行它

Qwen Code 是 Gemini CLI 的一个分支，Gemini CLI 是 Google 的开源终端代理，Qwen 团队已将其适配到 Qwen3-Coder 模型。该项目在 GitHub（QwenLM/qwen-code）上以 Apache 2.0 许可证发布，通过 npm 安装，并使用 qwen 命令。它沿用了现代代码代理的工作机制：模型接收您的请求，使用工具（读取和写入文件、在代码仓库中搜索、执行 shell、发起 Web 请求、使用 MCP 服务器），并不断调用这些工具，直到生成可验证的结果。

默认情况下，Qwen Code 会引导你使用“Qwen OAuth”连接：使用 Qwen 账户登录，请求会发送到 Alibaba Cloud 的服务器。该路径提供免费方案，但其配额可能变化，并且取决于所在地区。因此我们不在此给出具体数字：官方文档的身份验证页面是唯一的最新信息来源。不变的是另一种称为“OpenAI-compatible”的模式：Qwen Code 接受任何提供 OpenAI API 的服务器，包括你机器上的 Ollama 和 LM Studio。

隐私

在本地模式下，源代码、执行的命令及其输出永远不会离开本机。对于客户代码或受保密协议约束的代码，这是决定性优势。

成本

没有配额，也没有按 token 计费。唯一的成本是电费和已经购买的硬件。

可用性

没有服务故障，也没有高峰期排队。只要 GPU 在运行，代理就会响应。

代价

采用 Q4 量化、拥有 7 到 30 十亿参数的模型，水平不及拥有数千亿参数的云端模型。任务需要拆分得更细，并进行更多复核。

#先决条件

Node.js 20 或更高版本

Qwen Code 是一个 npm 软件包。使用 node --version 检查。在 Linux 和 macOS 上，nvm 或 fnm 可以避免全局安装时的权限问题。

Ollama 已安装并正常运行

守护进程监听于 http://localhost:11434。运行 ollama list 应能在不报错的情况下返回结果。如果不能，请先从 Ollama 的安装指南开始。

支持工具调用的模型

这是不可妥协的要求：代码代理会连续发起结构化工具调用。Qwen3-Coder 和 Qwen2.5-Coder 系列模型，以及 Devstral，都能在 Ollama 中支持这些调用。不支持 tools 的模型会用文本代替操作，代理将因此停滞。

GPU 内存

Q4_K_M 参考值：7B 模型约占 5 GB VRAM，14B 约占 9 GB，32B 约占 19 GB，均不含上下文。代理所需的长上下文还会增加数 GB：请预留充足空间。

一个 Git 仓库

不是必需的，但强烈建议这样做。代理会修改文件；git diff 和 git checkout 是你的安全网。

#1. 安装 Qwen Code

仓库推荐的安装方式是通过 npm 全局安装。在 macOS 上也发布了 Homebrew 软件包。二进制文件名为 qwen。

npm install -g @qwen-code/qwen-code@latest
qwen --version

brew install qwen-code
qwen --version

首次在未配置的情况下启动 qwen 时，该工具会提示选择身份验证方式。如果目标是本地运行，请不要选择 Qwen OAuth：请选择 OpenAI 选项，或者更好的是退出并先准备好下一步所述的配置。之后仍可在会话中使用 /auth 命令更改方式。

#2. 将 Qwen Code 连接到 Ollama

Ollama 在 11434 端口的 /v1 路径上公开兼容 OpenAI 的 API。Qwen Code 会读取三项环境变量来启用此模式：基础 URL、API 密钥和模型名称。Ollama 不要求密钥，但 Qwen Code 拒绝空值，因此可以填入任意字符串。

1. 01
   下载兼容工具调用的代码模型

   以 Qwen3-Coder 30B-A3B 为例：这是一个拥有 300 亿参数的专家混合（MoE）模型，每个 token 只有 30 亿参数处于激活状态，因此以其规模而言速度很快。它在 Q4 下约占 19 GB：要让它完全运行在 GPU 上，需要 24 GB VRAM，或者一台配备至少 32 GB 统一内存的 Apple Silicon 设备。在 12 GB 显卡上，建议改用 qwen2.5-coder:7b 或 14B 模型。
2. 02
   确认 Ollama 的 OpenAI API 能够响应

   对 /v1/models 的请求应列出你的模型。如果失败，说明 Ollama 未启动，或正在其他地址监听。
3. 03
   在项目根目录创建 .env 文件

   Qwen Code 会自动加载当前目录、项目的 .qwen 子目录或 ~/.qwen 中的 .env 文件，以实现全局配置。距离工作目录最近的文件优先。
4. 04
   在项目中启动 qwen

   窗口底部会显示当前模型。如果看到模型名称 Ollama，说明连接已建立。输入第一个简单请求，例如总结代码仓库结构，以确认读取工具正常工作。

ollama pull qwen3-coder:30b
curl http://localhost:11434/v1/models

OPENAI_API_KEY=ollama
OPENAI_BASE_URL=http://localhost:11434/v1
OPENAI_MODEL=qwen3-coder:30b

cd mon-projet
qwen

相同参数也可以作为命令行选项传入，用于一次性会话，而无需修改 .env 文件。这样可以方便地测试第二个模型，而不会破坏当前正常工作的配置。

qwen --openai-api-key ollama \
  --openai-base-url http://localhost:11434/v1 \
  --model qwen2.5-coder:14b

#3. 变体：将 LM Studio 作为服务器

如果您更喜欢 LM Studio，原理也相同。在应用中加载代码模型，打开 Developer 选项卡并启动本地服务器：它默认监听 1234 端口，并公开相同的兼容 OpenAI 的 API。如果服务器选项中尚未启用工具调用支持，请记得将其启用，并在界面中设置模型的上下文长度（见下一步）。

OPENAI_API_KEY=lm-studio
OPENAI_BASE_URL=http://localhost:1234/v1
OPENAI_MODEL=qwen2.5-coder-14b-instruct

要填写的模型名称，是 LM Studio 在已加载模型列表中显示的标识符，或通过向 http://localhost:1234/v1/models 发起请求返回的标识符。它不同于 Ollama 名称。

#4. 调整上下文窗口：所有人都会跳过的一步

这是本地运行 Qwen Code 失败的首要原因。代码代理每轮都会发送一段很长的系统提示（工具描述、行为规则、QWEN.md 文件内容），然后是会话历史，最后是读取的文件。刚开始几轮交互后，token 数就会超过 10,000。然而，Ollama 默认打开的是较短的窗口（近期版本中为 4,096 个 token）：超出的内容会被静默截断，模型会“忘记”工具指令，开始用散文形式回复而不是执行操作，或者反复执行同一个操作。

因此，必须将上下文设置为至少 32,000 个 token。在 Ollama 下有两种方法：在守护进程上设置全局环境变量，或使用 Modelfile 为特定模型固定 num_ctx。

sudo systemctl edit ollama
# Ajouter dans le bloc [Service] :
# Environment="OLLAMA_CONTEXT_LENGTH=32768"
sudo systemctl restart ollama

launchctl setenv OLLAMA_CONTEXT_LENGTH 32768
# puis relancer l'application Ollama

cat > Modelfile.qwen-code <<'EOF'
FROM qwen3-coder:30b
PARAMETER num_ctx 32768
EOF
ollama create qwen3-coder-32k -f Modelfile.qwen-code
# puis OPENAI_MODEL=qwen3-coder-32k dans le .env

第二种方法更整洁：它不会影响其他模型，而且派生模型的名称会提示其设置。代价是内存：键值缓存会随上下文增大。对于使用 Q4 量化的 7B 模型，32,000 个 token 的上下文大致会额外增加 2 到 4 GB，具体取决于架构和缓存量化方式。如果模型无法继续完全放入 GPU，Ollama 会将部分层卸载到 CPU，速度就会骤降：请监控 ollama ps 的 PROCESSOR 列，该列应显示 100 % GPU。

在 Qwen Code 方面，也存在会话限制。设置文件中的 sessionTokenLimit 会限制一个对话累计使用的 token 数量；达到上限后，该工具会提示你使用 /compress 压缩历史记录，或使用 /clear 从头开始。请将此值与模型实际支持的容量对齐：对于使用 num_ctx 32768 提供服务的模型，将上限设为 32 000，可避免 Ollama 一侧出现无提示的截断。

#5. 设置文件与 QWEN.md

Qwen Code 会在两个层级读取 settings.json：用户级别的 ~/.qwen/settings.json，以及项目中的 .qwen/settings.json，后者优先级更高。本地使用时最有用的键包括会话上限、操作审批模式和 MCP 服务器。确切名称在不同版本之间有所变动；下面的示例遵循公开文档，但应与您所用版本的 Settings 页面进行核对。

{
  "sessionTokenLimit": 32000,
  "contextFileName": "QWEN.md",
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/moi/mon-projet"]
    }
  }
}

QWEN.md 文件所起的作用与 Claude Code 的 CLAUDE.md 或其他代理的 AGENTS.md 相同：它是注入每个会话的永久备忘录。其中应描述技术栈、构建和测试命令、命名约定，以及代理绝不能修改的内容。/init 命令会根据代码仓库生成初始版本；/memory show 会显示代理实际加载的内容。

# Projet API Facturation

- Python 3.12, FastAPI, tests avec pytest (`make test`).
- Ne jamais modifier les migrations existantes dans alembic/versions/.
- Toute nouvelle route doit avoir un test dans tests/api/.
- Style : ruff, lignes de 100 caractères max.

审批模式控制代理无需征求您同意即可执行的操作。默认情况下，每次文件写入和每条 shell 命令都要等待您的确认。--approval-mode auto-edit 选项允许文件修改通过，但不允许命令通过；--yolo 则取消所有确认。使用比云端模型更容易出错的本地模型时，在建立信任之前请保持默认模式，并仅将 --yolo 用于干净且已提交的仓库。

#6. 第一次工作会话

Qwen Code 会通过自然语言操作，并提供一些快捷方式。前缀 @ 会将文件或目录插入请求（@src/api/routes.py），前缀 ! 会绕过模型直接执行 shell 命令，而以 / 开头的命令则用于控制工具本身。

/help

列出您的版本中可用的命令。

/auth

更改身份验证方式，便于在本地与云端之间切换。

/model

显示或更改当前会话中的模型。

/stats

已消耗的 token 数量与会话时长：当响应质量下降时，首先应检查这些信息。

/compress

总结历史记录，以释放上下文空间，同时保持连贯性。

/clear

从空白对话重新开始；QWEN.md 仍会被加载。

/init et /memory

生成并检查项目上下文文件。

/mcp

已配置的 MCP 服务器状态及其公开的工具。

/quit

退出会话。

一种适用于本地模型的流程：先要求读取（“解释 @src/auth/ 中如何处理身份验证”），然后进行范围明确的修改（“在 verify_token 中添加令牌过期检查，并添加相应测试”），最后进行验证（“运行 make test 并修复出错的部分”）。每个步骤都控制在几千个 token 以内，模型也能保持上下文连贯。诸如“重构整个模块”之类的请求，超出了 7 到 30B 模型能够可靠处理的范围。

对于自动化，非交互模式接受作为参数传入的请求，并在完成后返回控制权。它可以集成到脚本或 Git hook 中。

qwen -p "Relis le diff de git diff --cached et liste les problèmes potentiels, sans modifier de fichier"

#本地使用 Qwen Code 的限制

Qwen Code 围绕 Alibaba Cloud 提供的 Qwen3-Coder 模型构建，因此在较小的本地模型上运行时，这一点很快就会显现出来。以下是需要接受的事实。

沉重的系统提示词

该工具每轮都会发送一长段工具描述。对于 7B 模型而言，仅这条提示就会占用相当一部分上下文和模型注意力，因此它对工具调用格式的遵循程度不如更大的模型。与提示词更紧凑的 OpenCode 或 Aider 相比，循环和以散文形式回复而不是执行操作的情况更常见。

视觉功能仅限云端

图像支持（屏幕截图、设计稿）依赖在线提供的视觉模型。在本地，只有当您的服务器公开了兼容的多模态模型时才可用，而大多数代码模型都不具备这一条件。

不原生管理本地模型

不同于会在菜单中列出模型 Ollama 的 OpenCode，Qwen Code 要求在文件中或通过选项输入模型名称和 URL。更换模型意味着修改 .env，或使用 --model 重新启动。

配置格式不断变化

该项目还很年轻，其 settings.json 文件的结构随着版本变化而改变。论坛上找到的示例可能已经不再有效。以阅读时点的官方文档为准。

通过重写编辑

与其衍生而来的 Gemini CLI 一样，Qwen Code 通过替换代码块来修改文件。而 Aider 使用统一 diff，并会自动为每次更改提交，使历史记录更清晰。如果你希望每次修改都生成一个提交，Aider 更合适。

作为交换，Qwen Code 提供完整的 MCP 支持、继承自 Gemini CLI 的成熟会话管理命令、简洁的非交互模式，以及通过扩展延伸到 IDE 的集成。如果你已经在使用 Qwen 模型，并希望用一个工具在 Alibaba 云端与自己的 GPU 之间切换，它就很合适。如果目标仅是本地运行，OpenCode 或 Aider 只需较少设置即可达到相同结果。我们不发布量化对比：质量首先取决于所选模型，而非代理。

#故障排除

代理以文本响应，而不是执行操作

要么模型不支持工具调用（请检查其 Ollama 页面），要么上下文过短，工具描述被截断了。执行第 4 步，并使用 ollama ps 检查模型是否已加载且 num_ctx 设置正确。

404 错误或“model not found”

OPENAI_MODEL 中的名称与 ollama list 不完全匹配。请复制粘贴带标签的名称。

连接 localhost:11434 时出错

Ollama 未启动，或监听在其他接口（OLLAMA_HOST）上。请使用 curl http://localhost:11434/v1/models 测试。

交互几轮后响应非常缓慢

上下文变大后，模型超出了 GPU 的承载能力。ollama ps 会显示部分负载在 CPU 上。请减小 num_ctx，改用更小的模型，或在会话中更早运行 /compress。

Qwen Code 再次要求进行 OAuth 身份验证

未读取环境变量：.env 不在当前目录或 ~/.qwen 中。在会话中运行 /auth 并选择 OpenAI 选项，或通过命令行传入参数，以隔离问题。

模型忽略了 QWEN.md

使用 /memory show 检查文件是否已加载。如果 settings.json 中修改了 contextFileName，其名称必须匹配。

npm 安装因 EACCES 失败

对 npm 全局目录的权限不足。请通过 nvm 或 fnm 安装 Node，而不是使用系统软件包，然后重新运行安装。

#深入了解

Qwen Code 只是支持本地服务器的终端代理之一。以下指南涵盖其他方案和模型选择，本文有意不展开这些内容。

• OpenCode + Ollama：终端中的代码智能体
• Aider + Ollama：使用 100% 本地代理在终端中编码
• Goose (Block)：终端中的本地 AI 智能体
• 最适合编程的本地 LLM：Devstral、Qwen3-Coder

指南撰写于 2026 年 10 月 11 日；参考资料包括 GitHub 仓库和 Qwen Code 文档，以及 Ollama 文档。本文未进行速度或质量测量；记忆方面的参考数值仅为数量级估计。命令和键名会随版本变化：复制前请在下方页面上进行核对。

• GitHub 仓库 QwenLM/qwen-code（README、安装、许可证）
• Qwen Code 官方文档（身份验证、settings、命令）
• Ollama 文档（兼容 OpenAI API、环境变量）