Goose 使用指南

本章概览

本章将详细介绍 Goose 的安装、配置和使用方法，包括：

安装（Desktop 和 CLI）
配置 LLM Provider
基本使用
扩展管理
高级功能

1. 安装

1.1 Desktop 安装

macOS

下载安装包：
- Apple Silicon: goose-darwin-arm64.zip
- Intel: goose-darwin-x64.zip

解压并运行：

bash

unzip goose-darwin-arm64.zip
open Goose.app

Windows

下载 goose-win32-x64.zip
解压后运行 Goose.exe

Linux

下载 DEB 包：goose-linux-amd64.deb
安装：
bash
```
sudo dpkg -i goose-linux-amd64.deb
```
1

1.2 CLI 安装

自动安装（推荐）

bash

# macOS / Linux
curl -fsSL https://github.com/block/goose/releases/download/stable/download_cli.sh | bash

# 验证安装
goose --version

Windows（PowerShell）

powershell

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

从源码编译

bash

# 克隆仓库
git clone https://github.com/block/goose.git
cd goose

# 编译
cargo build --release

# 安装
cargo install --path crates/goose-cli

1.3 验证安装

bash

# 检查版本
goose --version
# 输出: goose 1.18.0

# 查看帮助
goose --help

2. 配置 Provider

2.1 首次配置

bash

goose configure

会显示配置菜单：

┌   goose-configure
│
◆  What would you like to configure?
│  ● Configure Providers
│  ○ Add Extension
│  ○ Toggle Extensions
│  ○ Remove Extension
│  ○ goose settings
└

2.2 配置 OpenAI

◆  Which model provider should we use?
│  ● OpenAI
│  ○ Anthropic
│  ○ Azure OpenAI
│  ○ Ollama
│  ...

◆  Provider OpenAI requires OPENAI_API_KEY, please enter a value
│  sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxx

◆  Select a model:
│  ○ gpt-4o (Recommended)
│  ● gpt-4o-mini
│  ○ gpt-4-turbo
│  ○ Search all models...

2.3 配置 Anthropic

bash

# 方式一：通过配置命令
goose configure

# 方式二：环境变量
export ANTHROPIC_API_KEY="sk-ant-xxxxx"

2.4 配置 Ollama（本地模型）

bash

# 1. 先安装并启动 Ollama
ollama serve

# 2. 拉取模型
ollama pull llama3.2

# 3. 配置 Goose
goose configure
# 选择 Ollama，模型选 llama3.2

2.5 配置文件位置

配置存储在：

平台	路径
macOS	`~/.config/goose/config.yaml`
Linux	`~/.config/goose/config.yaml`
Windows	`%APPDATA%\goose\config.yaml`

配置文件示例：

yaml

provider: openai
model: gpt-4o-mini
goose_mode: smart_approve

extensions:
  - name: developer
    enabled: true
  - name: computercontroller
    enabled: false

secrets:
  OPENAI_API_KEY: sk-xxxxx  # 加密存储

3. 基本使用

3.1 开始会话

bash

# 开始新会话
goose session

# 恢复上次会话
goose session -r

# 指定目录
goose session --dir /path/to/project

3.2 会话界面

╭─────────────────────────────────────────────────────────────────╮
│  🦢 goose                                                       │
│  Model: gpt-4o-mini | Provider: openai                          │
╰─────────────────────────────────────────────────────────────────╯

> 你好，帮我创建一个 Python 项目

🦢 好的，我来帮你创建一个 Python 项目。首先让我检查一下当前目录...

[Using tool: shell]
Command: ls -la
...

我发现当前目录是空的。让我为你创建一个标准的 Python 项目结构：

[Using tool: write_file]
Path: pyproject.toml
...

✅ 项目创建完成！结构如下：
├── pyproject.toml
├── src/
│   └── myproject/
│       └── __init__.py
├── tests/
│   └── __init__.py
└── README.md

>

3.3 常用命令

在会话中可以使用的命令：

命令	功能
`/help`	显示帮助
`/clear`	清除屏幕
`/exit` 或 `Ctrl+C`	退出会话
`/compact`	手动压缩对话
`/extensions`	显示扩展状态
`/mode`	切换安全模式

3.4 Web 界面

bash

# 启动 Web 界面
goose web --open

# 指定端口
goose web --port 8080

4. 扩展管理

4.1 查看可用扩展

bash

goose configure
# 选择 "Toggle Extensions"

4.2 内置扩展

扩展	功能	默认状态
developer	文件操作、Shell 命令	✅ 启用
computercontroller	浏览器控制	❌ 禁用
memory	跨会话记忆	❌ 禁用
jetbrains	IDE 集成	❌ 禁用

4.3 启用扩展

bash

goose configure
# 选择 "Add Extension"
# 选择 "Built-in Extension"
# 选择 "Computer Controller"

4.4 添加外部 MCP Server

bash

goose configure
# 选择 "Add Extension"
# 选择 "MCP Server (stdio)"
# 输入命令: npx @anthropic/mcp-server-filesystem /path/to/dir

4.5 配置文件中管理扩展

yaml

# ~/.config/goose/config.yaml

extensions:
  # 内置扩展
  - name: developer
    enabled: true

  - name: computercontroller
    enabled: true
    timeout: 300

  # 外部 MCP Server
  - name: filesystem
    type: stdio
    command: npx
    args:
      - "@anthropic/mcp-server-filesystem"
      - "/home/user/documents"
    env:
      DEBUG: "true"

  # SSE 连接
  - name: remote-api
    type: sse
    url: "http://localhost:3000/mcp"

5. 安全模式

5.1 模式说明

模式	描述	适用场景
smart_approve	智能判断，只读操作自动批准	日常使用（默认）
auto_approve	自动批准所有操作	信任环境
ask_every_time	每次操作都询问	高安全要求
chat_only	仅聊天，不执行工具	纯对话

5.2 切换模式

bash

# 配置时选择
goose configure
# 选择 "goose settings"
# 选择 "Approval Mode"

# 或在会话中
/mode auto_approve

5.3 操作确认

在 smart_approve 模式下，敏感操作会请求确认：

🦢 我需要执行以下命令来安装依赖：
   pip install requests

[Allow this operation?] (y/n/always):

选项说明：

y: 允许本次
n: 拒绝
always: 始终允许此类操作

6. 高级功能

6.1 Recipe（配方）

使用预定义的任务模板：

bash

# 从 URL 加载
goose session --recipe https://example.com/code-review.yaml

# 从本地文件
goose session --recipe ./my-recipe.yaml

Recipe 文件示例：

yaml

# code-review.yaml
name: Code Review
description: Automated code review workflow

settings:
  system_prompt_template: |
    You are a code reviewer. Focus on:
    - Code quality
    - Security issues
    - Performance
    - Best practices

  required_extensions:
    - developer

sub_recipes:
  - name: security-check
    prompt: Check for security vulnerabilities

6.2 会话恢复

bash

# 恢复最近会话
goose session -r

# 恢复指定会话
goose session --resume-id abc123

# 列出所有会话
goose sessions list

6.3 批量处理

bash

# 非交互模式
echo "Create a hello world Python script" | goose session --non-interactive

# 从文件读取
goose session --input tasks.txt

6.4 环境变量

bash

# 设置 Provider
export GOOSE_PROVIDER=anthropic
export ANTHROPIC_API_KEY=sk-ant-xxxxx

# 设置模型
export GOOSE_MODEL=claude-3-5-sonnet-20241022

# 设置模式
export GOOSE_MODE=auto_approve

7. 常用工作流

7.1 项目初始化

> Create a new React project with TypeScript and Tailwind CSS

Goose 会：

使用 create-react-app 或 vite 创建项目
安装 TypeScript 配置
设置 Tailwind CSS
创建基础组件

7.2 代码调试

> My Python script at main.py is throwing a KeyError. Help me debug it.

Goose 会：

读取文件
分析错误原因
提供修复方案
应用修复并测试

7.3 代码审查

> Review the code in src/ for security issues and best practices

Goose 会：

遍历源码文件
识别潜在问题
提供改进建议
可选：自动修复

7.4 文档生成

> Generate API documentation for all Python functions in this project

Goose 会：

扫描所有 Python 文件
提取函数签名和 docstring
生成 Markdown 文档

8. 故障排除

8.1 常见问题

API Key 错误

Error: Authentication failed

解决：检查 API Key 是否正确

bash

# 重新配置
goose configure

模型不可用

Error: Model not found

解决：检查模型名称或切换 Provider

扩展连接失败

Error: Failed to connect to extension

解决：

检查 MCP Server 是否运行
检查网络连接
查看日志

8.2 查看日志

bash

# 日志位置
~/.config/goose/logs/goose.log

# 实时查看
tail -f ~/.config/goose/logs/goose.log

# 启用详细日志
GOOSE_LOG_LEVEL=debug goose session

8.3 重置配置

bash

# 删除配置
rm -rf ~/.config/goose

# 重新配置
goose configure

9. 快捷键

9.1 CLI 快捷键

快捷键	功能
`Ctrl+C`	中断/退出
`Ctrl+L`	清屏
`Ctrl+R`	搜索历史
`↑/↓`	浏览历史
`Tab`	自动补全

9.2 Desktop 快捷键

快捷键	功能
`Cmd/Ctrl + N`	新会话
`Cmd/Ctrl + W`	关闭会话
`Cmd/Ctrl + ,`	设置
`Cmd/Ctrl + K`	命令面板

10. 最佳实践

10.1 提示技巧

好的提示：

Create a REST API using FastAPI that:
- Has CRUD operations for users
- Uses SQLite database
- Includes authentication
- Has proper error handling

不太好的提示：

make an api

10.2 项目组织

my-project/
├── .goosehints          # Goose 提示文件
├── .goose/              # Goose 配置目录
│   └── recipes/         # 项目 Recipe
├── src/
└── ...

10.3 .goosehints 文件

创建 .goosehints 文件提供项目上下文：

# .goosehints

## 项目说明
这是一个 Python Web 应用，使用 FastAPI 框架。

## 代码风格
- 使用 Black 格式化
- 遵循 PEP 8
- 类型注解必须

## 测试要求
- 使用 pytest
- 覆盖率 > 80%

## 禁止操作
- 不要修改 config.py 中的密钥
- 不要删除 migrations/ 目录

Goose 使用指南 ​

本章概览 ​

1. 安装 ​

1.1 Desktop 安装 ​

macOS ​

Windows ​

Linux ​

1.2 CLI 安装 ​

自动安装（推荐） ​

Windows（PowerShell） ​

从源码编译 ​

1.3 验证安装 ​

2. 配置 Provider ​

2.1 首次配置 ​

2.2 配置 OpenAI ​

2.3 配置 Anthropic ​

2.4 配置 Ollama（本地模型） ​

2.5 配置文件位置 ​

3. 基本使用 ​

3.1 开始会话 ​

3.2 会话界面 ​

3.3 常用命令 ​

3.4 Web 界面 ​

4. 扩展管理 ​

4.1 查看可用扩展 ​

4.2 内置扩展 ​

4.3 启用扩展 ​

4.4 添加外部 MCP Server ​

4.5 配置文件中管理扩展 ​

5. 安全模式 ​

5.1 模式说明 ​

5.2 切换模式 ​

5.3 操作确认 ​

6. 高级功能 ​

6.1 Recipe（配方） ​

6.2 会话恢复 ​

6.3 批量处理 ​

6.4 环境变量 ​

7. 常用工作流 ​

7.1 项目初始化 ​

7.2 代码调试 ​

7.3 代码审查 ​

7.4 文档生成 ​

8. 故障排除 ​

8.1 常见问题 ​

API Key 错误 ​

模型不可用 ​

扩展连接失败 ​

8.2 查看日志 ​

8.3 重置配置 ​

9. 快捷键 ​

9.1 CLI 快捷键 ​

9.2 Desktop 快捷键 ​

10. 最佳实践 ​

10.1 提示技巧 ​

10.2 项目组织 ​

10.3 .goosehints 文件 ​

Goose 使用指南

本章概览

1. 安装

1.1 Desktop 安装

macOS

Windows

Linux

1.2 CLI 安装

自动安装（推荐）

Windows（PowerShell）

从源码编译

1.3 验证安装

2. 配置 Provider

2.1 首次配置

2.2 配置 OpenAI

2.3 配置 Anthropic

2.4 配置 Ollama（本地模型）

2.5 配置文件位置

3. 基本使用

3.1 开始会话

3.2 会话界面

3.3 常用命令

3.4 Web 界面

4. 扩展管理

4.1 查看可用扩展

4.2 内置扩展

4.3 启用扩展

4.4 添加外部 MCP Server

4.5 配置文件中管理扩展

5. 安全模式

5.1 模式说明

5.2 切换模式

5.3 操作确认

6. 高级功能

6.1 Recipe（配方）

6.2 会话恢复

6.3 批量处理

6.4 环境变量

7. 常用工作流

7.1 项目初始化

7.2 代码调试

7.3 代码审查

7.4 文档生成

8. 故障排除

8.1 常见问题

API Key 错误

模型不可用

扩展连接失败

8.2 查看日志

8.3 重置配置

9. 快捷键

9.1 CLI 快捷键

9.2 Desktop 快捷键

10. 最佳实践

10.1 提示技巧

10.2 项目组织

10.3 .goosehints 文件