本地搭建 Claude Code + Ollama + Gemma 4 实战教程

Claude Code CLI
    ↓ Anthropic-compatible request
Ollama local server: http://localhost:11434
    ↓ custom model variant
Gemma 4 26B MoE: gemma4-claude
    ↓
读文件 / 写补丁 / 跑测试 / 根据错误继续修复

curl -fsSL https://ollama.com/install.sh | sh

ollama version
curl http://localhost:11434

Ollama is running

ollama serve

ollama pull gemma4:26b
ollama list

node --version

npm install -g @anthropic-ai/claude-code
claude --version

mkdir -p ~/.ollama/Modelfiles

FROM gemma4:26b

PARAMETER num_ctx 65536
PARAMETER temperature 0.2
PARAMETER top_p 0.9
PARAMETER repeat_penalty 1.15
PARAMETER num_predict 4096

SYSTEM """You are a senior software engineer operating as a coding agent.

When working with code:
- Read files before editing them. Never assume file contents.
- Make one focused change at a time and verify it before proceeding.
- When a tool call fails, examine the error carefully before retrying.
  Do not retry with identical parameters. Diagnose first.
- Prefer surgical edits over full file rewrites.
- Run tests after each meaningful change, not after a batch of changes.
- If you are uncertain about the codebase structure, read more files
  rather than guessing.

Be precise and methodical. Avoid explaining what you are about to do
when you could simply do it."""

ollama create gemma4-claude -f ~/.ollama/Modelfiles/gemma4-claude
ollama list

ollama run gemma4-claude "What is the time complexity of binary search and why?"

mkdir -p .claude

{
  "env": {
    "ANTHROPIC_BASE_URL": "http://localhost:11434",
    "ANTHROPIC_AUTH_TOKEN": "ollama",
    "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"
  }
}

printf '\n.claude/settings.local.json\n' >> .gitignore

#!/usr/bin/env python3
"""Verify Claude Code + Ollama + local model readiness."""

from __future__ import annotations

import json
import sys
import urllib.error
import urllib.request
from dataclasses import dataclass
from typing import Any


OLLAMA_BASE_URL = "http://localhost:11434"
MODEL_NAME = "gemma4-claude"
TIMEOUT_SECONDS = 120


@dataclass(frozen=True)
class CheckResult:
    name: str
    ok: bool
    detail: str


def request_json(method: str, url: str, payload: dict[str, Any] | None = None) -> dict[str, Any]:
    data = None
    headers = {"Content-Type": "application/json"}
    if payload is not None:
        data = json.dumps(payload).encode("utf-8")
        headers["x-api-key"] = "ollama"
        headers["anthropic-version"] = "2023-06-01"

    request = urllib.request.Request(url, data=data, headers=headers, method=method)
    with urllib.request.urlopen(request, timeout=TIMEOUT_SECONDS) as response:
        return json.loads(response.read().decode("utf-8"))


def request_text(url: str) -> str:
    with urllib.request.urlopen(url, timeout=10) as response:
        return response.read().decode("utf-8", errors="replace")


def check_ollama_health() -> CheckResult:
    try:
        text = request_text(OLLAMA_BASE_URL)
    except urllib.error.URLError as exc:
        return CheckResult("Ollama health", False, f"cannot connect: {exc}")

    if "Ollama is running" in text:
        return CheckResult("Ollama health", True, "localhost:11434 is reachable")
    return CheckResult("Ollama health", False, f"unexpected response: {text[:100]}")


def check_model_available() -> CheckResult:
    try:
        data = request_json("GET", f"{OLLAMA_BASE_URL}/api/tags")
    except Exception as exc:
        return CheckResult("Model availability", False, f"cannot list models: {exc}")

    models = [model.get("name", "") for model in data.get("models", [])]
    normalized = {name.split(":", 1)[0] for name in models}
    if MODEL_NAME in models or MODEL_NAME in normalized:
        return CheckResult("Model availability", True, f"found {MODEL_NAME}")
    return CheckResult("Model availability", False, f"available models: {models}")


def check_messages_api() -> CheckResult:
    payload = {
        "model": MODEL_NAME,
        "max_tokens": 100,
        "messages": [
            {"role": "user", "content": "Reply with exactly: VERIFICATION_OK"}
        ],
    }

    try:
        data = request_json("POST", f"{OLLAMA_BASE_URL}/v1/messages", payload)
    except Exception as exc:
        return CheckResult("Messages API", False, f"request failed: {exc}")

    content_blocks = data.get("content", [])
    text_blocks = [block for block in content_blocks if block.get("type") == "text"]
    if not text_blocks:
        return CheckResult("Messages API", False, f"no text block: {data}")
    return CheckResult("Messages API", True, text_blocks[0].get("text", "")[:80])


def check_tool_calling() -> CheckResult:
    payload = {
        "model": MODEL_NAME,
        "max_tokens": 256,
        "tools": [
            {
                "name": "read_file",
                "description": "Read the contents of a file at the given path.",
                "input_schema": {
                    "type": "object",
                    "properties": {
                        "path": {
                            "type": "string",
                            "description": "The file path to read.",
                        }
                    },
                    "required": ["path"],
                },
            }
        ],
        "tool_choice": {"type": "any"},
        "messages": [
            {"role": "user", "content": "Read the file at /tmp/test.py."}
        ],
    }

    try:
        data = request_json("POST", f"{OLLAMA_BASE_URL}/v1/messages", payload)
    except Exception as exc:
        return CheckResult("Tool calling", False, f"request failed: {exc}")

    content_blocks = data.get("content", [])
    tool_blocks = [block for block in content_blocks if block.get("type") == "tool_use"]
    if not tool_blocks:
        return CheckResult("Tool calling", False, f"no tool_use block: {data}")

    tool_call = tool_blocks[0]
    if tool_call.get("name") != "read_file":
        return CheckResult("Tool calling", False, f"wrong tool: {tool_call}")

    tool_input = tool_call.get("input", {})
    if "path" not in tool_input:
        return CheckResult("Tool calling", False, f"missing path: {tool_call}")

    return CheckResult("Tool calling", True, f"tool_use input={tool_input}")


def main() -> int:
    checks = [
        check_ollama_health(),
        check_model_available(),
        check_messages_api(),
        check_tool_calling(),
    ]

    for result in checks:
        status = "PASS" if result.ok else "FAIL"
        print(f"[{status}] {result.name}: {result.detail}")

    if all(result.ok for result in checks):
        print("All checks passed. Local Claude Code agent setup is ready.")
        return 0

    print("Resolve failed checks before using this setup on a real codebase.")
    return 1


if __name__ == "__main__":
    sys.exit(main())

python3 verify_local_agentic_setup.py

[PASS] Ollama health: localhost:11434 is reachable
[PASS] Model availability: found gemma4-claude
[PASS] Messages API: VERIFICATION_OK
[PASS] Tool calling: tool_use input={'path': '/tmp/test.py'}
All checks passed. Local Claude Code agent setup is ready.

mkdir -p ~/tmp/local-agent-demo/src ~/tmp/local-agent-demo/tests
cd ~/tmp/local-agent-demo
cat > src/user_service.py <<'PY'
from __future__ import annotations


class ValidationError(ValueError):
    pass


class UserService:
    def normalize_email(self, email: str) -> str:
        if "@" not in email:
            raise ValidationError("invalid email")
        return email.strip().lower()

    def display_name(self, first_name: str, last_name: str) -> str:
        return f"{first_name.strip()} {last_name.strip()}"
PY
cat > pyproject.toml <<'TOML'
[project]
name = "local-agent-demo"
version = "0.1.0"
requires-python = ">=3.10"

[tool.pytest.ini_options]
pythonpath = ["."]
TOML

python3 -m venv .venv
. .venv/bin/activate
python -m pip install pytest

claude

请分析 src/user_service.py，为 UserService 写 pytest 测试。
要求：
1. 先读取文件，不要猜测内容。
2. 只新增或修改 tests/test_user_service.py。
3. 覆盖 normalize_email 和 display_name 的正常与异常输入。
4. 写完后运行 python -m pytest -q。
5. 如果失败，基于错误信息修复测试或代码。
6. 不要修改 pyproject.toml，不要安装新依赖。
成功标准：pytest 全部通过。

read_file("src/user_service.py")
write_file("tests/test_user_service.py", ...)
bash("python -m pytest -q")

pwd
ls -la .claude/settings.json

ollama create gemma4-claude -f ~/.ollama/Modelfiles/gemma4-claude

PARAMETER num_ctx 32768

ollama create gemma4-claude -f ~/.ollama/Modelfiles/gemma4-claude

export OLLAMA_KV_CACHE_TYPE=q8_0

export OLLAMA_KEEP_ALIVE=-1
curl http://localhost:11434/api/generate -d '{"model": "gemma4-claude", "keep_alive": -1}'

{
  "env": {
    "CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS": "1"
  }
}

echo "$CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS"

1

本地模型：高频、低风险、可回滚、可测试的小任务
云端强模型：复杂架构、跨仓库推理、关键设计评审
人工 review：所有进入生产分支的最终判断