1. Grok Build 本地部署到底解决什么问题Grok Build 是 xAI 开源的一套终端原生 AI 编程智能体用 Rust 写成核心形态是一个命令行 CLI 工具配套专用编码模型 grok-build-0.1。它和常见的 IDE 补全插件不是一类东西补全插件只在你敲代码时猜下一行而 Grok Build 会读取整个代码库、跨文件批量改代码、自动跑 shell 和单元测试、走 Git 提交属于能直接操作本地项目的终端工程师。2026 年 7 月完整开源后Apache 2.0它最大的价值就是可以纯本地离线跑代码不出机器还能对接 Ollama、LM Studio 这类本地推理服务。适合谁手里有 Mac 或 Linux 开发机、想快速跑通一个 Rust CLI 开源项目、又不想把私有代码传到云端的开发者。如果你只是想体验一下 AI 改代码官方云端版更省事但如果你关心私有代码不上云、想自定义本地大模型那本地部署这条链路就值得走一遍。我试过从源码编译到对接本地模型的完整流程踩的坑主要集中在三块Rust 工具链没配好导致 cargo build 失败、配置文件路径写错导致程序默认走云端、本地模型名和 config.toml 不一致导致请求 404。这篇就按「装依赖 → 编译 → 配置 → 验证 → 排障」的顺序把每一步的可复制命令和预期结果都写清楚你照着敲就能从源码拿到一个能跑的可执行文件。需要说明的是本地部署只解决「程序能跑起来」真正让 CLI 干活还需要一个能响应 OpenAI 兼容接口的模型服务。本地 Ollama 适合离线场景如果你想要更稳的模型响应和更省心的接入也可以把 base_url 指向兼容 OpenAI 协议的托管服务后面配置章节会给出两种写法。2. 部署前的前置准备与 TaoToken 接入配置2.1 环境依赖清单本地部署 Grok Build 对系统要求不算高但 Rust 编译比较吃内存建议至少 8GB编译 32B 级别模型相关依赖时 16GB 更稳。先把下面这些确认一遍依赖项版本要求检查命令说明操作系统macOS 12 / Linux x86_64uname -aWindows 建议走 WSL2Rust 工具链1.75rustc --version用 rustup 安装最省事Cargo随 Rust 一起cargo --version编译入口Git2.30git --version拉源码Ollama可选0.1.30ollama --version本地模型服务磁盘空间≥ 10GBdf -h源码 编译产物 模型Rust 安装命令macOS/Linux 通用curl --proto https --tlsv1.2 -sSf https://sh.rustup.rs | sh source $HOME/.cargo/env rustc --version如果rustc --version能打印版本号说明工具链就绪。这里有个容易忽略的点source ~/.zshrc不一定生效因为 rustup 装完是写进~/.cargo/env的直接 source 这个文件更保险。2.2 为什么要在配置里接一个模型服务Grok Build 本身是「壳」真正生成代码的是背后的模型。开源版默认会尝试走 xAI 云端 API如果你没配~/.grok/config.toml启动后请求会直接打到云端本地离线就失去意义了。所以配置的核心就一件事把models_base_url指向一个 OpenAI 兼容的/v1接口。两种常见选择本地 Ollama 的地址是http://localhost:11434/v1完全离线适合私有代码场景缺点是模型能力受本地硬件限制。另一种是接托管服务把 base_url 换成对应服务的 OpenAI 兼容地址即可响应更稳定、模型选择更多。如果你走托管路线可以到 TaoToken 控制台创建一个 API Key再在接入文档里对照 OpenAI 兼容写法填 base_url 和 model。控制台地址是 https://taotoken.net/console 接入文档在 https://taotoken.net/doc API Key 管理页在 https://taotoken.net/api-keys 。这三个页面配合看基本能把「Key 从哪来、base_url 填什么、model 写哪个」一次搞明白。注意无论用本地还是托管config.toml 里的 model 字段必须和服务端实际暴露的模型 ID 完全一致大小写、冒号、版本号都不能差这是后面 404 报错的头号原因。2.3 拉源码前的目录规划建议单独建一个工作目录别把源码和你的业务项目混在一起mkdir -p ~/code/opensource cd ~/code/opensource git clone https://github.com/xai-org/grok-build.git cd grok-build ls正常会看到Cargo.toml、src/、crates/这些目录。如果 clone 卡住多半是网络问题可以换用镜像或稍后重试不要在这里纠结太久。3. 可复制的构建参数与 config.toml 配置3.1 编译 release 版本进入源码目录后直接编译cd ~/code/opensource/grok-build cargo build --release第一次编译会拉取大量 crate 依赖10 到 30 分钟都正常别以为卡死了。想加速可以加并行参数cargo build --release -j 8-j后面的数字按你 CPU 核心数填8 核就写 8。编译成功后产物在target/release/下文件名通常是xai-grok-pager或grok具体以ls target/release/ | grep grok的结果为准。把它复制到全局 bin方便直接调用cp target/release/xai-grok-pager ~/.cargo/bin/grok chmod x ~/.cargo/bin/grok grok --version如果~/.cargo/bin不在 PATH 里补一行echo export PATH$HOME/.cargo/bin:$PATH ~/.zshrc source ~/.zshrc3.2 写 config.toml本地 Ollama 版配置文件默认路径是~/.grok/config.toml目录不存在要先建mkdir -p ~/.grok下面这份是本地 Ollama 的完整配置可以直接整段覆盖[cli] installer internal [marketplace] default_skills_installs_purged true official_marketplace_auto_installed false [ui] max_thoughts_width 120 fork_secondary_model grok-4.5 yolo false compact_mode false permission_mode always-approve # 本地模型服务地址Ollama 默认监听 11434 [endpoints] models_base_url http://localhost:11434/v1 [model.local] model qwen2.5-coder:7b name 本地代码模型 [models] default local几个字段的作用models_base_url决定请求打到哪model.local.model是实际模型 IDmodels.default指定默认用哪个配置块。permission_mode always-approve表示 AI 改代码时不再逐次弹确认本地调试方便但生产项目建议改成需要确认的模式。3.3 写 config.toml托管服务版如果你不想在本地跑模型把 endpoints 段换成托管服务的 OpenAI 兼容地址即可其余结构不变[endpoints] models_base_url https://taotoken.net/api/v1 [model.remote] model grok-build-0.1 name 托管编码模型 [models] default remote这里的 base_url 和 model 要和你实际开通的服务保持一致Key 通过环境变量注入更安全export GROK_API_KEY你的Key把这一行写进~/.zshrc可以持久化。托管路线的好处是模型响应稳定、不用占本地显存适合开发机配置一般的情况。想先确认模型能不能正常对话可以到模型对话页 https://taotoken.net/models 手动发一条测试消息确认服务通了再回来配 CLI能省不少排查时间。3.4 启动 Ollama 并拉模型本地路线需要先把模型服务跑起来ollama serve ollama pull qwen2.5-coder:7b ollama listollama list会列出已下载模型确认qwen2.5-coder:7b在列表里且名字和 config.toml 里写的完全一致。如果拉的是 32B 版本把配置里的模型名同步改掉别只改一处。4. 验证请求与成功结果确认4.1 先验证模型接口连通在启动 Grok Build 之前先用 curl 确认模型服务能响应curl http://localhost:11434/v1/models正常会返回一个 JSON里面包含模型列表。如果这一步就失败说明问题在模型服务侧跟 Grok Build 无关先解决 Ollama。托管路线同理把地址换成你的 base_urlcurl -H Authorization: Bearer $GROK_API_KEY https://taotoken.net/api/v1/models能返回模型列表说明 Key 和地址都对。4.2 启动 Grok Build 并进入 TUI进入你的项目根目录最好是 Git 仓库然后启动cd ~/code/你的项目 grok回车后会进入全屏 TUI 界面带鼠标支持和 Diff 预览。第一次启动如果直接报连接错误八成是 config.toml 没生效或路径写错回到第 5 节排查。4.3 在 TUI 里做一次最小验证进入界面后先切换模型确认配置被读到/model local然后发一条最简单的自然语言需求比如「列出当前项目的目录结构并说明每个目录的作用」。观察它是否生成计划、是否读取文件、是否输出结果。如果它能正常读取项目文件并给出回答说明整条链路通了。再验证一次写操作发「在当前目录新建一个 hello.txt内容写 hello grok」。确认它执行后退出 TUI 检查文件是否真的生成cat hello.txt看到hello grok就说明从源码编译到实际干活的完整链路跑通了。4.4 常用 TUI 指令速查指令作用/model local切换模型配置/inspect查看本地配置和 MCP 插件/mcp add filesystem -- npx -y modelcontextprotocol/server-filesystem $(pwd)挂载文件系统 MCP/quit退出程序MCP 挂载后 AI 才能读写项目文件如果发现它「看不到」你的代码先检查这一步有没有做。5. 常见报错排查对照5.1 401 Unauthorized现象启动后请求模型直接返回 401。原因通常是 Key 没注入或注入的变量名和配置里引用的不一致。排查顺序先echo $GROK_API_KEY确认变量有值再检查 config.toml 里有没有正确引用这个变量。托管路线还要确认 Key 没有过期、额度没耗尽。到 https://taotoken.net/api-keys 重新生成一个 Key 再试是最快的验证方式。5.2 local proxy failed / connection refused现象报连接本地服务失败。这是本地 Ollama 没起来或端口不对。先ollama serve 确认服务在跑再curl http://localhost:11434/v1/models确认端口通。如果 curl 通但 CLI 报错检查 config.toml 里 base_url 是不是写成了http://127.0.0.1:11434而服务只监听 localhost两者在某些系统上不等价统一成localhost更稳。5.3 reading choices 相关解析错误现象请求返回了内容但 CLI 解析失败提示读取 choices 字段出错。这通常是模型服务返回的 JSON 结构和 OpenAI 标准不一致或者模型名写错导致服务返回了错误对象。先确认 model 字段和服务端模型 ID 完全一致再用 curl 直接打一次接口看原始返回结构。本地小模型偶尔会有格式偏差换一个兼容性更好的模型通常能解决。5.4 OAuth / 登录相关报错现象启动时提示需要登录或 OAuth 失败。开源本地版理论上不需要登录出现这个提示说明程序还在走云端默认配置也就是~/.grok/config.toml没被读到。检查文件路径是不是~/.grok/config.toml不是~/.config/grok/文件权限是否可读以及 TOML 语法有没有写错。可以用cat ~/.grok/config.toml确认内容再用grok /inspect看程序实际加载的配置。5.5 cargo build 编译失败现象编译中途报错退出。常见原因是 Rust 版本过低先rustup update升到最新稳定版。如果是某个 crate 编译报链接错误Linux 上可能需要装build-essential和pkg-config。macOS 上确认 Xcode Command Line Tools 已装xcode-select --install。编译报错信息里通常会指明具体 crate按提示补依赖即可。5.6 三件套自查清单无论哪种报错先对照这三项Base URL 是否指向正确的/v1接口、Key 是否有效且被正确注入、Model ID 是否和服务端完全一致。这三项对齐了九成连接类问题都能解决。如果排查完还是不通到接入文档 https://taotoken.net/doc 对照示例再核一遍字段名或者到模型对话页手动测一次确认服务本身没问题。6. 长期使用与 Coding Plan 接入建议本地部署跑通只是第一步。日常真正拿它干活时模型响应速度和稳定性会直接影响体验。本地 Ollama 的优势是离线、免费、代码不出机器但 7B 级别模型在复杂重构任务上能力有限32B 又吃显存。如果你主要做长期编码、Agent 类任务把模型服务换成托管方案会更省心响应稳定、模型选择多也不用担心本地机器跑不动。接入方式就是第 3.3 节那份配置把 base_url 指向托管服务的 OpenAI 兼容地址Key 通过环境变量注入。想了解长期编码场景的套餐和额度可以看 Coding Plan 页面 https://taotoken.net/coding-plan 里面有针对 Agent 类高频调用的方案说明。如果你更习惯在 Claude Code 这类工具里工作也可以参考 Claude Code 接入文档 https://taotoken.net/claudecode 把同一套 Key 和 base_url 复用到不同 CLI 上配置思路是相通的。最后给一个实用建议把~/.grok/config.toml纳入你的 dotfiles 管理换机器时直接同步省得每次重新配。模型名和 base_url 这两项最容易因为环境不同而写错配好后先用grok /inspect确认一遍再开始干活比出问题后回头排查快得多。