装好 goose，用内置本地模型跑第一个任务

这一课做完你会得到什么

在 Linux 或 macOS 上装好 goose 命令行，确认版本和配置文件位置，用 goose 内置的本地推理下载一个 Gemma 4 小模型，再用一条 goose run 让它回答第一个问题。全程不需要账号，也不需要 API Key。

goose 是什么

goose 是一个开源的通用 AI Agent（Apache-2.0），用 Rust 编写，最早由 Block 开源，现在由 Linux 基金会旗下的 Agentic AI Foundation（AAIF）托管。它有桌面应用和命令行两种形态，二者共用配置和会话数据库。goose 本身不带模型，要接一个「提供商」：

本课用第一种。官方博客说明，内置本地推理把 llama.cpp 直接嵌进 goose，模型是 Hugging Face 上的 GGUF 文件，不用另起服务。

第 1 步：安装命令行

官方一行安装脚本，Linux 和 macOS 通用：

curl -fsSL \
https://github.com/aaif-goose/goose/releases/download/stable/download_cli.sh \
| bash

官方写在一行里，这里为了排版用 \ 折成三行，粘贴进终端效果相同。

脚本会下载 .tar.bz2 压缩包。精简版 Linux 如果没有 bzip2，解压会失败。

对照结果（2026-10-28 实测，Linux x86_64，未装 bzip2，节选）：

Downloading stable release: goose-x86_64-unknown-linux-gnu.tar.bz2...
Error: Failed to extract goose-x86_64-unknown-linux-gnu.tar.bz2.
'bzip2' is required but not installed.

先装上 bzip2 再重跑脚本（Debian / Ubuntu 用下面这行，其他发行版换成对应的包管理器）：

sudo apt-get install -y bzip2
curl -fsSL \
https://github.com/aaif-goose/goose/releases/download/stable/download_cli.sh \
| bash

对照结果（2026-10-28 实测，节选）：

Downloading stable release: goose-x86_64-unknown-linux-gnu.tar.bz2...
Extracting goose-x86_64-unknown-linux-gnu.tar.bz2 to temporary directory...
Moving goose to /home/box/.local/bin/goose
Skipping 'goose configure', you may need to run this manually later

命令装在 ~/.local/bin/goose。终端提示找不到 goose 的话，把这个目录加进 PATH：

export PATH="$HOME/.local/bin:$PATH"

macOS 也可以用 Homebrew（brew install block-goose-cli），Windows 和桌面版安装包见官方 Install 页。这两种本课没有实测。

第 2 步：确认版本和文件位置

goose --version
goose info

对照结果（2026-10-28 实测）：

goose Version:
  Version:                  1.56.0

Paths:
Config dir:              /home/box/.config/goose
Config yaml:             /home/box/.config/goose/config.yaml
Sessions DB (sqlite):    /home/box/.local/share/goose/sessions/sessions.db
Logs dir:                /home/box/.local/state/goose/logs

记住这四个位置：

• config.yaml 存提供商、模型和扩展设置；
• sessions.db 存所有会话，第 2 课会用到；
• logs 下的 llm_request.*.jsonl 记录发给模型的完整请求，排查问题时很有用。

goose info -v 会把 config.yaml 的内容一起打印出来。

第 3 步：用内置本地推理下载模型

先在 Hugging Face 上搜 GGUF 模型。官方博客说内置推理对 Gemma 4 有原生工具调用支持，所以选 Gemma 4 E2B：

goose local-models search gemma-4-E2B

对照结果（2026-10-28 实测，节选）：

  [gguf] Q4_K_M — 2.9GB — Medium, recommended balance of quality and size
    Download: goose local-models download 'unsloth/gemma-4-E2B-it-GGUF:Q4_K_M'
  [gguf] Q3_K_M — 2.4GB — Small, balanced quality/size
    Download: goose local-models download 'unsloth/gemma-4-E2B-it-GGUF:Q3_K_M'

每一行就是一个量化版本。越小越省内存，质量也越低。按提示下载推荐的 Q4_K_M：

goose local-models download 'unsloth/gemma-4-E2B-it-GGUF:Q4_K_M'
goose local-models list

对照结果（2026-10-28 实测；第一段省略了下载进度，第二段把表格空格压窄了，内容不变）：

Resolving unsloth/gemma-4-E2B-it-GGUF:Q4_K_M...
Downloaded unsloth/gemma-4-E2B-it-GGUF:Q4_K_M (2.9GB)

ID                                       Backend    Variant      Downloaded
-------------------------------------------------------------------------
unsloth/gemma-4-E2B-it-GGUF:Q4_K_M       llamacpp   Q4_K_M       ✓

模型 ID 的写法是 仓库:量化，后面配置时要一字不差。不要的模型用 goose local-models delete <模型 ID> 删除。

第 4 步：告诉 goose 用哪个模型

最快的办法是用环境变量，只对当前终端生效：

export GOOSE_PROVIDER=local
export GOOSE_MODEL='unsloth/gemma-4-E2B-it-GGUF:Q4_K_M'

想长期生效，就写进第 2 步看到的 ~/.config/goose/config.yaml：

GOOSE_PROVIDER: local
GOOSE_MODEL: unsloth/gemma-4-E2B-it-GGUF:Q4_K_M

写好后用 goose info -v 检查。

对照结果（2026-10-28 实测，节选）：

goose Configuration:
  GOOSE_MODEL: unsloth/gemma-4-E2B-it-GGUF:Q4_K_M
  GOOSE_PROVIDER: local

也可以运行 goose configure，按交互菜单选提供商、填 API Key。这是官方推荐的首次配置方式，本课没有实测。接 Ollama 的话，在菜单里选 Ollama，必要时设 OLLAMA_HOST。接 OpenAI 兼容服务的话，选 OpenAI 并设 OPENAI_HOST。这些写法都出自官方 Supported Providers 页。

第 5 步：第一次运行

goose run -t 后面接一段文字，goose 处理完就退出，不进入交互界面。--no-session 表示这次不写入会话记录：

mkdir -p ~/goose-demo && cd ~/goose-demo
time goose run --no-session -t "用一句话介绍你自己"

对照结果（2026-10-28 实测，8 核 CPU、无 GPU，实测时的工作目录是 /tmp/gtest；模型输出每次会不同）：

    __( O)>  ● new session · local unsloth/gemma-4-E2B-it-GGUF:Q4_K_M
   \____)    20261027_2 · /tmp/gtest
     L L     goose is ready
我是 Gemma 4，一个由 Google DeepMind 开发的开放权重大型语言模型。

real	1m55.7s

开头的 __( O)> 是 goose 的标志，旁边依次显示提供商、模型、会话 ID 和工作目录。会话 ID 里的日期按 UTC 计算，北京时间 10 月 28 日凌晨看到的仍是 20261027。

这一句话花了将近 2 分钟，主要是第一次把模型载入内存。官方博客也提醒，本地模型首次请求要 30 到 120 秒，只用 CPU 的机器生成速度明显更慢，上下文也比云端模型小。日常写代码建议接云端或更强的本地模型。本课用小模型，是为了让每一步都能免费复现。

想直接进入对话界面，运行 goose session，输入 exit 或按 Ctrl+C 退出。本课只用无头运行，因为输出可以直接对照。

小结

• 一行脚本装好 goose，缺 bzip2 先装上；用 goose info 看配置和会话文件在哪；
• goose local-models search / download / list 管理内置本地模型，模型 ID 写成 仓库:量化；
• GOOSE_PROVIDER 和 GOOSE_MODEL 可以用环境变量临时设置，也可以写进 config.yaml；
• goose run -t "…" 跑完一次就退出，第一次加载模型会比较慢。

下一课让 goose 动手写文件、执行命令，并学会管理会话和项目提示文件。