Local Agentic Programming on the Cheap: Claude Code + Ollama + Gemma4

# macOS 和 Linux -- 一键安装
curl -fsSL https://ollama.com/install.sh | sh

# 验证版本 -- 必须为 0.14.0+ 才能支持 Anthropic Messages API
# Anthropic 兼容端点是在 2026 年 1 月添加的
ollama version
# 预期输出: ollama 版本是 0.22.x 或更高（截至 2026 年 5 月）

# Windows: 从 https://ollama.com 下载原生安装程序
# 如果你希望在 Windows 上实现 GPU 传递，建议使用 WSL2

curl http://localhost:11434
# 预期响应: Ollama 正在运行

# 26B MoE -- 推荐用于此设置（约 18 GB 下载）
ollama pull gemma4:26b

# 等待期间，确认下载是否正在进展
ollama ps
# 显示当前正在下载或运行的模型

# 可选：在支持的硬件上，也拉取 31B 以进行比较
ollama pull gemma4:31b

# 确认拉取完成
ollama list
# 应显示 gemma4:26b 及其大小和修改日期

# 先决条件：Node.js 18 或更高版本
node --version   # 确认你使用的是 18+

# 全局安装 Claude Code CLI
npm install -g @anthropic-ai/claude-code

# 验证安装
claude --version

# ~/.ollama/Modelfiles/gemma4-claude
# Gemma 4 26B MoE 变体，针对 Claude Code 代理会话进行了优化。
# 将上下文窗口、温度和系统提示嵌入模型中
# 使每个 Claude Code 会话都以正确的配置开始。
#
# 构建方法如下:
#   mkdir -p ~/.ollama/Modelfiles
#   ollama create gemma4-claude -f ~/.ollama/Modelfiles/gemma4-claude

FROM gemma4:26b

# 上下文窗口 -- 65536 个标记（64K）是经过测试的安全下限，适用于真实
# 的代码库，不会在 16-18 GB 显存系统上触发交换操作。
# 如果你的系统有 24 GB 或更大的显存，可以增加到 131072（128K）。
# 除非你已经对负载下的内存使用情况进行了分析，否则不要超过 131072 -- Ollama 会提前分配完整的 KV 缓存。
PARAMETER num_ctx 65536

# 温度 -- 0.2 是特意设置得较低，用于代理编码任务。
# 更高的温度会引入工具调用参数格式的变异性，导致 Claude Code 的工具验证器拒绝调用。
# 对于创意任务，你可以将这个值设得更高。对于代理循环：保持较低值。
PARAMETER temperature 0.2

# top_p -- 核心采样阈值。0.9 有助于保持生成的专注度
# 同时避免在长时间代理会话中 top_p=1.0 可能导致的重复循环问题。
PARAMETER top_p 0.9

# repeat_penalty -- 对重复标记进行惩罚。
# 1.15 有助于防止 Gemma 4 无限重复相同的失败工具调用，几乎使用相同的参数进行重试的情况。
PARAMETER repeat_penalty 1.15

# num_predict -- 每次响应的最大标记数。4096 对于大多数代码补丁已经足够。
# 如果你经常在单次生成中生成大文件，可以增加到 8192。
PARAMETER num_predict 4096

# 系统提示 -- 强化编码代理行为和显式
# 工具使用纪律。Gemma 4 从被提醒要承诺工具调用而不是描述它将做什么中获益。
SYSTEM """你是一名高级软件工程师，以编码代理的身份工作。

在处理代码时:
- 编辑文件前先阅读文件。不要假设文件内容。
- 每次只进行一个专注的更改，并在继续之前验证它。
- 当工具调用失败时，仔细检查错误后再重试。
  不要使用相同的参数重试。首先进行诊断。
- 优先选择精确的编辑，而不是对整个文件进行重写。
- 每次进行有意义的更改后运行测试，而不是在一批更改后运行测试。
- 如果你对代码库结构不确定，多读一些文件，而不是猜测。

要精确且有条理。当你能够直接执行时，避免解释你即将做什么。

# 如果目录不存在，请创建 Modelfiles 目录
mkdir -p ~/.ollama/Modelfiles

# 将上面的 Modelfile 内容保存到此路径，然后构建:
ollama create gemma4-claude -f ~/.ollama/Modelfiles/gemma4-claude

# 验证变体是否已创建
ollama list
# 应该显示 gemma4-claude 与 gemma4:26b 一起出现

# 快速测试 -- 验证它是否加载并响应
ollama run gemma4-claude "二分查找的时间复杂度是什么，为什么？"
# 预期在几秒钟内得到一个清晰、简洁的技术响应

{
  "env": {
    "ANTHROPIC_BASE_URL": "http://localhost:11434",

    "ANTHROPIC_AUTH_TOKEN": "ollama",

    "ANTHROPIC_API_KEY": "",

    "ANTHROPIC_MODEL": "gemma4-claude",

    "ANTHROPIC_DEFAULT_SONNET_MODEL": "gemma4-claude",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "gemma4-claude",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "gemma4-claude",

    "CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS": "1"
  }
}

# 在你的项目根目录中
mkdir -p .claude

cat > .claude/settings.json << 'EOF'
{
  "env": {
    "ANTHROPIC_BASE_URL": "http://localhost:11434",
    "ANTHROPIC_AUTH_TOKEN": "ollama",
    "ANTHROPIC_API_KEY": "",
    "ANTHROPIC_MODEL": "gemma4-claude",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "gemma4-claude",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "gemma4-claude",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "gemma4-claude",
    "CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS": "1"
  }
}
EOF

pip install httpx   # 用于验证脚本的异步 HTTP 客户端

#!/usr/bin/env python3
"""
verify_local_setup.py

在使用前验证完整的 Claude Code + Ollama + Gemma 4 堆栈。
依次运行三个检查：
  1. Ollama 健康状态和模型可用性
  2. 基本的 Anthropic Messages API 调用
  3. 工具调用往返测试

前提条件：
  pip install httpx

如何运行：
  python verify_local_setup.py

在正常设置下预期的输出：
  [通过] Ollama 正在 localhost:11434 上运行
  [通过] 模型 'gemma4-claude' 可用
  [通过] Anthropic Messages API 调用成功
  [通过] 工具调用：模型生成了有效的 tool_use 块
  所有检查通过 -- Claude Code + Ollama + Gemma 4 已准备就绪。
"""

import httpx
import json
import sys

# ── 配置 ─────────────────────────────────────────────────────────────
OLLAMA_BASE_URL = "http://localhost:11434"
MODEL_NAME      = "gemma4-claude"   # 必须与你的 Modelfile 变体名称匹配
TIMEOUT         = 120.0             # 秒 -- 第一次调用时生成可能较慢

def check_ollama_health() -> bool:
    """
    检查 1：验证 Ollama 是否正在运行并响应。
    访问根端点，当健康时返回 'Ollama is running'。
    """
    print("\n检查 1: Ollama 健康状态")
    try:
        response = httpx.get(OLLAMA_BASE_URL, timeout=5.0)
        if "Ollama is running" in response.text:
            print(f"  [通过] Ollama 正在 {OLLAMA_BASE_URL} 上运行")
            return True
        else:
            print(f"  [失败] 不预期的响应: {response.text[:100]}")
            return False
    except httpx.ConnectError:
        print(f"  [失败] 无法连接到 {OLLAMA_BASE_URL}")
        print("         Ollama 是否正在运行？尝试: ollama serve")
        return False

def check_model_available() -> bool:
    """
    检查 2：验证特定模型变体是否在 Ollama 中可用。
    使用 /api/tags 端点，该端点列出所有已拉取的模型。
    """
    print("\n检查 2: 模型可用性")
    try:
        response = httpx.get(f"{OLLAMA_BASE_URL}/api/tags", timeout=5.0)
        data     = response.json()
        models   = [m["name"] for m in data.get("models", [])]

        # 规范化：Ollama 可能会添加 ":latest" 如果未指定
        normalized = [m.split(":")[0] for m in models]

        if MODEL_NAME in models or MODEL_NAME in normalized:
            print(f"  [通过] 模型 '{MODEL_NAME}' 可用")
            return True
        else:
            print(f"  [失败] 模型 '{MODEL_NAME}' 未找到")
            print(f"         可用模型: {', '.join(models) or 'none'}")
            print(f"         运行: ollama create {MODEL_NAME} -f ~/.ollama/Modelfiles/gemma4-claude")
            return False
    except Exception as e:
        print(f"  [失败] 检查模型列表时出错: {e}")
        return False

def check_messages_api() -> bool:
    """
    检查 3：向本地端点发送基本的 Anthropic Messages API 调用。
    验证请求格式、模型路由和基本生成是否正常工作。
    使用与 Claude Code 相同的 /v1/messages 路径和请求模式。
    注意：Claude Code 使用 http://localhost:11434（根），而不是 /v1。
    Anthropic 兼容的 API 在 /api/chat 或根 -- Ollama 路由它。
    """
    print("\n检查 3: Anthropic Messages API 调用")

    payload = {
        "model": MODEL_NAME,
        "max_tokens": 100,
        "messages": [
            {
                "role": "user",

print(f"  [FAIL] HTTP {response.status_code}: {response.text[:200]}")
return False

data = response.json()
content_blocks = data.get("content", [])
tool_blocks = [b for b in content_blocks if b.get("type") == "tool_use"]

if not tool_blocks:
    print("  [FAIL] 模型未生成 tool_use 块")
    print("         这意味着工具调用功能未正常工作。")
    print("         Agentic Claude Code 会话在文件操作时会失败。")
    print(f"         完整响应: {json.dumps(data, indent=2)}")
    return False

tool_call = tool_blocks[0]
tool_name = tool_call.get("name", "")
tool_input = tool_call.get("input", {})

print(f"  [PASS] 工具调用: 模型生成了一个有效的 tool_use 块")
print(f"         调用的工具: {tool_name}")
print(f"         参数:  {json.dumps(tool_input)}")

# 合理性检查: 是否调用了正确的工具并传入了正确的参数?
if tool_name == "read_file" and "path" in tool_input:
    print(f"         工具名称和参数是正确的。")
else:
    print(f"         警告: 工具名称不符合预期或缺少 'path' 参数。")
    print(f"         模型调用了一个工具，但不是预期的那个。")

return True

except Exception as e:
    print(f"  [FAIL] 请求失败: {e}")
    return False

def main():
    print("=" * 60)
    print("Claude Code + Ollama + Gemma 4 设置验证")
    print("=" * 60)

    checks = [
        check_ollama_health,
        check_model_available,
        check_messages_api,
        check_tool_calling,
    ]

    results = [check() for check in checks]

    print("\n" + "=" * 60)
    passed = sum(results)
    total = len(results)

    if all(results):
        print(f"所有 {total} 项检查都通过了。")
        print("Claude Code + Ollama + Gemma 4 已准备就绪。")
        print(f"\n启动命令: claude")
        sys.exit(0)
    else:
        failed_checks = [i + 1 for i, r in enumerate(results) if not r]
        print(f"{passed}/{total} 项检查通过。失败项: {failed_checks}")
        print("在本地使用 Claude Code 之前，请解决上述失败问题。")
        sys.exit(1)

if __name__ == "__main__":
    main()

pip install httpx
python verify_local_setup.py

# 导航到项目目录
cd ~/projects/my-service

# 确认 Claude Code 能够看到本地配置
claude --version
# 确保它不会提示输入 Anthropic API 密钥 —— 如果提示了，
# 说明 settings.json 没有被正确读取

# 启动一个 agentic 会话
claude

# 在 Claude Code 中，给代理一个具体的任务：
# > 分析 src/user_service.py 中的 UserService 类。
# > 编写一个覆盖所有公共方法的 pytest 测试套件。
# > 运行测试并修复任何失败。
# > 目标是实现一个没有跳过的干净的 pytest 运行。

→ read_file("src/user_service.py")
  正在读取 247 行...

→ list_files("src/")
  找到: user_service.py, models.py, db.py, exceptions.py

→ read_file("src/models.py")
  正在读取 89 行...

→ write_file("tests/test_user_service.py", [测试内容])
  已写入 312 行

→ bash("python -m pytest tests/test_user_service.py -v 2>&1")
  正在运行 14 个测试...
  失败: tests/test_user_service.py::test_update_email_invalid
    AssertionError: 预期 ValidationError，但得到 None

→ read_file("src/user_service.py")  [对 update_email 方法的针对性重读]
  ...

→ write_file("tests/test_user_service.py", [修正后的测试])
  修正了 test_update_email_invalid 的断言

→ bash("python -m pytest tests/test_user_service.py -v 2>&1")
  14 个通过，耗时 1.23 秒