Clawd BotandClaude Opus 4.6
ca9b510922
- Reset master to upstream/main (16,697 commits) - Overlay 2,271 local-only files (skills, tools, workspace, configs, apps) - Restore IDENTITY.md and USER.md templates - Build verified, gateway running, Discord working Co-Authored-By: Claude Opus 4.6 <[email protected]>
24 KiB
Claude Code
Running Locally with Ollama
Complete Setup Guide
✓ Zero API Costs Forever
✓ Complete Privacy - Code Never Leaves Your Machine
✓ All Features: MCP Servers, Tool Use, Multi-turn Conversations
✓ Works with Open Source Models
Last Updated: February 04, 2026
Claude Code + Ollama Setup Guide Page 1 of 27 Table of Contents
Section Page
1. Introduction 3
2. What is Claude Code? 3
3. Why Run Locally with Ollama? 4
4. System Requirements 5
5. Step 1: Install Ollama 6
6. Step 2: Download Coding Models 7
7. Step 3: Install Claude Code 9
8. Step 4: Configure Environment Variables 10
9. Step 5: Launch Claude Code 11
10. Recommended Models for Coding 12
11. Using Claude Code Features 13
12. Troubleshooting Common Issues 14
13. Performance Tips 15
14. Advanced Configuration 16
Claude Code + Ollama Setup Guide Page 2 of 27 1. Introduction Claude Code is Anthropic's revolutionary agentic coding tool that lives in your terminal, understands your codebase, and helps you code faster through natural language commands. Until recently, using Claude Code required an API connection to Anthropic's servers and incurred per-use costs.
With Ollama version 0.14.0 and later, everything changed. Ollama now provides an Anthropic-compatible API, which means you can run Claude Code entirely on your local machine using open source models - completely free, forever.
This guide provides step-by-step instructions to set up Claude Code with Ollama, from installation through advanced configuration. By the end, you'll have a fully functional local coding assistant that respects your privacy and costs nothing to run.
-
What is Claude Code? Claude Code is an agentic AI coding assistant that can:
• Read and analyze your entire codebase to understand context • Write and modify files directly with your permission • Execute commands in your terminal to run tests, install packages, etc. • Handle git workflows including commits, branches, and merge conflicts • Explain complex code in plain language • Debug and fix errors automatically • Refactor code to improve quality and performance • Use external tools through MCP (Model Context Protocol) servers
Unlike simple code completion tools, Claude Code is truly agentic - it can break down complex tasks, execute multiple steps, and adapt its approach based on results. It's like having an experienced developer pair programming with you.
Claude Code + Ollama Setup Guide Page 3 of 27 3. Why Run Locally with Ollama? Cost Savings Claude Code with Anthropic's API can cost $100-200 per month for regular users. Running locally with Ollama is completely free after the initial setup. You only pay for electricity - typically pennies per session.
Complete Privacy When running locally, your code never leaves your machine. No data is sent to external servers, no metadata is collected, and no code snippets are uploaded. This is crucial for proprietary projects, sensitive client work, or regulated industries.
Offline Capability Once models are downloaded, you can code completely offline. Perfect for travel, unstable internet connections, or working in secure environments without internet access.
Learning and Experimentation Free local models are ideal for learning, testing ideas, and building prototypes without worrying about API costs. Experiment freely, iterate rapidly, and only use paid APIs when you need maximum quality for production code.
■ Important Note: Local open source models are not as capable as Anthropic's Claude Opus 4.5 or
Claude Sonnet 4.5. However, they excel at routine tasks: bug fixes, code explanations, refactoring,
boilerplate generation, and testing. Think of local models as your tireless junior developer, and
premium models as your senior architect.
Claude Code + Ollama Setup Guide Page 4 of 27 4. System Requirements Hardware Requirements
Component Minimum Recommended Ideal
RAM 8 GB 16 GB 32 GB+
Storage 10 GB free 50 GB free 100 GB+ free
CPU Quad-core 8+ cores 12+ cores
GPU None (CPU only) NVIDIA RTX 3060 NVIDIA RTX 4090
RAM Guidance: With 8 GB, use small models (1-3B parameters). With 16 GB, use medium models
(6-13B). With 32 GB+, use large models (20-30B) for best quality.
Software Requirements • Operating System: macOS 13.0+, Windows 10 1809+ (with WSL2), or Linux (Ubuntu 20.04+, Debian 10+)
• Terminal: Bash or Zsh (bash included with macOS/Linux, available in WSL2 for Windows)
• Node.js: Not required for native installation (recommended method)
• Internet: Required for initial setup and model downloads, then optional
■■ Windows Users: Claude Code works best with WSL2 (Windows Subsystem for Linux). Native
Windows support is limited. Install Ubuntu from the Microsoft Store and run all commands in WSL2.
Claude Code + Ollama Setup Guide Page 5 of 27 5. Step 1: Install Ollama Ollama makes it simple to run large language models locally. It handles model management, provides an API server, and now offers Anthropic API compatibility.
Installation by Platform macOS Option 1: Download from website (recommended)
Visit https://ollama.com/download and download the macOS installer
Open the .dmg file and drag Ollama to Applications
Option 2: Install with Homebrew
brew install ollama
Linux Run the official installation script:
curl -fsSL https://ollama.com/install.sh | sh
Windows (WSL2) First, ensure WSL2 is installed:
wsl --install
Then install Ubuntu from Microsoft Store, open Ubuntu, and run:
curl -fsSL https://ollama.com/install.sh | sh
Verify Installation After installation, verify Ollama is working:
ollama --version
You should see output like: ollama version is 0.15.0
Claude Code + Ollama Setup Guide Page 6 of 27 Start Ollama Service Start the Ollama API server (keep this terminal window open):
ollama serve
You should see: Listening on 127.0.0.1:11434
✓ Success: If you see 'Listening on 127.0.0.1:11434', Ollama is running correctly!
Claude Code + Ollama Setup Guide Page 7 of 27 6. Step 2: Download Coding Models Claude Code requires models with large context windows (at least 64K tokens recommended) and tool-calling capabilities. Open a new terminal window (keep ollama serve running) for the following commands.
Quick Start: Best All-Around Model For most users, start with GLM-4.7-Flash:
ollama pull glm-4.7-flash
This model offers excellent coding ability, 128K context window, tool-calling support, and runs well on most systems. Download size: approximately 5 GB. Download time: 5-15 minutes depending on your internet speed.
Alternative Recommended Models
<b>Model</b> <b>Size</b> <b>Context</b>
<b>Best For</b> <b>Command</b>
qwen3-coder ~4 GB 64K General coding, fast ollama pull qwen3-coder
gpt-oss:20b ~12 GB 128K High quality, needs 16GB+ RAMollama pull gpt-oss:20b
gpt-oss:120b ~70 GB 128K Maximum quality, needs 64GB+ ollama
RAM pull gpt-oss:120b
deepseek-coder-v2 ~9 GB 64K Strong code generation ollama pull deepseek-coder-v2
■ Context Window Importance: Claude Code works best with models that have 64K+ token context
windows. This allows the model to see more of your codebase at once, leading to better understanding
and suggestions.
Configure Context Length (Important!) By default, Ollama uses 2048 token context. For coding, you need at least 64000 tokens. Create or edit the Ollama configuration:
macOS/Linux:
Claude Code + Ollama Setup Guide Page 8 of 27 mkdir -p ~/.ollama nano ~/.ollama/config.json
Add this configuration:
{
"num_ctx": 64000
}
Save (Ctrl+X, then Y, then Enter) and restart Ollama:
pkill ollama
ollama serve
Verify Downloaded Models Check which models you have:
ollama list
Claude Code + Ollama Setup Guide Page 9 of 27 7. Step 3: Install Claude Code Claude Code can be installed using the native installer (recommended) or npm. The native installer doesn't require Node.js and provides automatic updates.
Native Installation (Recommended) macOS / Linux / WSL2:
curl -fsSL https://claude.ai/install.sh | bash
Windows PowerShell:
irm https://claude.ai/install.ps1 | iex
Alternative: npm Installation If you prefer npm and have Node.js 18+ installed:
npm install -g @anthropic-ai/claude-code
■■ Warning: Do NOT use sudo npm install as this can cause permission issues. If you get
EACCES errors, fix npm permissions or use the native installer instead.
Verify Installation Check that Claude Code is installed:
claude --version
You should see the version number (e.g., 2.1.12)
Run Claude Code Doctor Verify your installation is healthy:
claude doctor
This checks your installation and identifies any issues.
Claude Code + Ollama Setup Guide Page 10 of 27 ✓ Success: If 'claude --version' shows a version number, installation was successful!
Claude Code + Ollama Setup Guide Page 11 of 27 8. Step 4: Configure Environment Variables To use Claude Code with Ollama instead of Anthropic's API, you need to set environment variables that point Claude Code to your local Ollama server.
Quick Setup (Temporary) For a quick test, set variables in your current terminal session:
macOS / Linux / WSL2 (bash/zsh):
export ANTHROPIC_BASE_URL="http://localhost:11434"
export ANTHROPIC_AUTH_TOKEN="ollama"
export ANTHROPIC_API_KEY=""
Windows PowerShell:
$env:ANTHROPIC_BASE_URL = "http://localhost:11434"
$env:ANTHROPIC_AUTH_TOKEN = "ollama"
$env:ANTHROPIC_API_KEY = ""
Permanent Setup (Recommended) Add environment variables to your shell configuration file:
For bash (most Linux, WSL2):
nano ~/.bashrc
For zsh (macOS default):
nano ~/.zshrc
Add these lines at the end of the file:
# Claude Code with Ollama
export ANTHROPIC_BASE_URL="http://localhost:11434"
export ANTHROPIC_AUTH_TOKEN="ollama"
export ANTHROPIC_API_KEY=""
export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1
Save (Ctrl+X, Y, Enter) and reload your configuration:
source ~/.bashrc # or source ~/.zshrc
Claude Code + Ollama Setup Guide Page 12 of 27 Alternative: JSON Configuration You can also configure via Claude Code's settings file:
mkdir -p ~/.claude
nano ~/.claude/settings.json
Add this configuration:
{
"env": {
"ANTHROPIC_BASE_URL": "http://localhost:11434",
"ANTHROPIC_AUTH_TOKEN": "ollama",
"CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"
}
}
■ Environment Variable Explanation:
• ANTHROPIC_BASE_URL: Points to Ollama's API instead of Anthropic's
• ANTHROPIC_AUTH_TOKEN: Set to 'ollama' for Ollama authentication
• ANTHROPIC_API_KEY: Empty string (Ollama doesn't need an API key)
• CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: Prevents telemetry for offline use
Claude Code + Ollama Setup Guide Page 13 of 27 9. Step 5: Launch Claude Code With everything configured, you're ready to launch Claude Code! Make sure Ollama is still running (ollama serve in one terminal).
Using ollama launch (Easiest Method) Ollama 0.15+ includes a convenient launch command:
ollama launch
This command automatically configures environment variables and launches Claude Code. Select 'Claude Code' from the menu, choose your model, and you're done!
Manual Launch Navigate to your project directory and launch Claude Code:
cd /path/to/your/project
claude --model qwen3-coder
Replace qwen3-coder with your chosen model name.
First Run Setup On first run, Claude Code may ask for permissions. Since you're using Ollama locally, you can skip authentication. Accept file access permissions for your project directory.
Test Your Setup Try a simple command to verify everything works:
create a hello.py file that prints Hello World
If Claude Code creates the file successfully, congratulations! Your setup is complete.
✓ You're All Set! Claude Code is now running locally with Ollama. Try some commands to explore its
capabilities!
Claude Code + Ollama Setup Guide Page 14 of 27 Verify Local Operation To confirm you're running fully local (not using Anthropic's API), disconnect from the internet and run a command. If you get a response, you're successfully running offline!
Claude Code + Ollama Setup Guide Page 15 of 27 10. Recommended Models for Coding Different models excel at different tasks and have varying resource requirements. Here's a detailed guide to help you choose the right model for your needs.
For 8 GB RAM Systems Best Choice: qwen3-coder (Small version)
The small version of qwen3-coder fits in 8 GB RAM and provides decent coding assistance for simple tasks. Expect slower inference and lower quality compared to larger models.
For 16 GB RAM Systems Best Choice: glm-4.7-flash or qwen3-coder
Both models offer excellent balance of performance and resource usage. GLM-4.7-Flash has better tool-calling support and 128K context, making it ideal for most coding tasks.
For 32 GB+ RAM Systems Best Choice: gpt-oss:20b or deepseek-coder-v2
These larger models provide significantly better code quality, deeper understanding, and more sophisticated solutions. Recommended if you have the resources.
For 64 GB+ RAM Systems with GPU Best Choice: gpt-oss:120b
The highest quality open source coding model available. Approaches premium API quality for complex tasks. Requires substantial hardware (NVIDIA RTX 4090 or better recommended).
Task-Specific Recommendations
<b>Task Type</b> <b>Recommended Model</b> <b>Why</b>
Quick bug fixes glm-4.7-flash Fast responses, tool support
Code explanations qwen3-coder Good balance, clear output
Claude Code + Ollama Setup Guide Page 16 of 27 Refactoring gpt-oss:20b Better architecture understanding
Complex debugging gpt-oss:20b or 120b Deep reasoning capability
Boilerplate code glm-4.7-flash Fast generation, good patterns
Test generation qwen3-coder Solid coverage, fast
Switching Models You can easily switch models by specifying a different model:
claude --model gpt-oss:20b
Claude Code + Ollama Setup Guide Page 17 of 27 11. Using Claude Code Features Basic Commands Once Claude Code is running, you can use natural language:
• Create a Python script that sorts a list of numbers
• Explain what this function does (with file selected)
• Fix the bug in auth.py
• Refactor this code to use async/await
• Add error handling to database.py
• Write unit tests for the user class
Slash Commands Claude Code includes built-in slash commands:
• /help - Show all available commands
• /edit [file] - Edit mode for specific file
• /clear - Clear conversation history
• /exit - Exit Claude Code
• /bug - Report a bug to Anthropic
• /settings - View/modify settings
Tool Use and MCP Servers Claude Code can use external tools through MCP (Model Context Protocol) servers. This allows integration with databases, APIs, and other services. Note that tool-calling requires models that support it (like glm-4.7-flash, gpt-oss).
Multi-turn Conversations
Claude Code + Ollama Setup Guide Page 18 of 27 Claude Code maintains context across multiple messages. You can have a back-and-forth conversation to refine solutions:
Create a REST API endpoint
[Claude creates endpoint]
Add input validation
[Claude adds validation]
Now add error handling
[Claude adds error handling]
Edit Mode Edit mode allows direct file modifications. Claude Code will show you a diff of proposed changes before applying them:
/edit src/main.py
Optimize this function for performance
Claude Code + Ollama Setup Guide Page 19 of 27 12. Troubleshooting Common Issues Issue: Connection Refused Symptom: Error connecting to localhost:11434
Solution:
• Ensure Ollama is running: ollama serve
• Check if port 11434 is available: lsof -i :11434
• Restart Ollama service
Issue: Model Not Found Symptom: 'Model qwen3-coder not found'
Solution:
• Verify model is downloaded: ollama list
• Pull the model: ollama pull qwen3-coder
• Use exact model name from ollama list
Issue: Very Slow Responses Symptom: Takes minutes to get a response
Solutions:
• Switch to a smaller model (glm-4.7-flash instead of gpt-oss:20b)
• Close other memory-intensive applications
• Monitor system resources: top or Activity Monitor
• Consider upgrading RAM if consistently slow
Issue: Out of Memory Symptom: System freezes or Ollama crashes
Claude Code + Ollama Setup Guide Page 20 of 27 Solutions:
• Use a smaller model that fits your RAM
• Reduce context length in ~/.ollama/config.json
• Use quantized models (they use less memory)
Issue: Command Not Found: claude Symptom: Terminal doesn't recognize 'claude' command
Solutions:
• Restart terminal after installation
• Check PATH: echo $PATH
• For native install, add to PATH: export PATH="$HOME/.local/bin:$PATH"
• Run claude doctor for diagnosis
Issue: Still Using Anthropic API Symptom: Getting API key errors or being charged
Solution:
• Verify environment variables: echo $ANTHROPIC_BASE_URL
• Should show: http://localhost:11434
• Disconnect internet and test - should still work if truly local
Claude Code + Ollama Setup Guide Page 21 of 27 13. Performance Tips Optimize Inference Speed Use GPU Acceleration (NVIDIA only):
Ollama automatically uses GPU if available. Verify with:
nvidia-smi
You should see ollama process using GPU memory.
Adjust Context Window:
Larger context = slower inference. If you don't need 64K tokens, reduce it:
# In ~/.ollama/config.json
{"num_ctx": 32000} # Faster than 64000
Use Quantized Models:
Quantized models (e.g., q8_0, q4_0) are smaller and faster with minimal quality loss:
ollama pull glm-4.7-flash:q8_0
Memory Management Keep Models Loaded:
Ollama keeps recently used models in memory. If you frequently switch models, increase keep-alive:
# In ~/.ollama/config.json
{"keep_alive": "1h"} # Keep model loaded for 1 hour
Unload Unused Models:
Free up memory by stopping Ollama:
pkill ollama
Coding Workflow Optimization
Claude Code + Ollama Setup Guide Page 22 of 27 Use the Right Model for the Task:
Don't use large models for simple tasks. Keep multiple models and switch based on complexity:
• Simple fixes: glm-4.7-flash (fast)
• Complex refactoring: gpt-oss:20b (quality)
Batch Similar Tasks:
Process multiple related files in one session to leverage context:
Refactor all utility files in src/utils/
Disk Space Management Models can take significant space. Remove unused models:
ollama rm model-name
List all models with sizes:
ollama list
Claude Code + Ollama Setup Guide Page 23 of 27 14. Advanced Configuration Using Ollama Cloud Models Ollama offers cloud-hosted models with full context length. These aren't free but are often cheaper than Anthropic's API:
ollama pull glm-4.7:cloud
Cloud models run at full context length without local hardware requirements. Free tier available with generous limits.
Custom Model Configuration Create a Modelfile to customize system prompts, temperature, and other parameters:
nano Modelfile
FROM qwen3-coder
PARAMETER temperature 0.7
PARAMETER top_p 0.9
SYSTEM You are an expert Python developer focused on clean, efficient code.
Create the custom model:
ollama create my-coding-assistant -f Modelfile
Use your custom model:
claude --model my-coding-assistant
Multiple Ollama Instances Run multiple Ollama servers on different ports for different models:
OLLAMA_HOST=127.0.0.1:11435 ollama serve
Then configure Claude Code to use the specific port:
ANTHROPIC_BASE_URL=http://localhost:11435 claude --model qwen3-coder
Claude Code + Ollama Setup Guide Page 24 of 27 Remote Ollama Server Run Ollama on a powerful remote server and connect from your laptop:
On server:
OLLAMA_HOST=0.0.0.0:11434 ollama serve
On laptop:
export ANTHROPIC_BASE_URL="http://server-ip:11434"
■■ Security Warning: Only expose Ollama on trusted networks. Use SSH tunneling or VPN for
secure connections.
Hybrid Workflow: Local + Cloud Use local models for iteration and premium APIs for production:
1. Develop and test with local Ollama models (free, fast iteration)
2. Final review/production code with Claude Opus 4.5 (premium quality)
Switch between local and API:
# Local
export ANTHROPIC_BASE_URL="http://localhost:11434"
# Anthropic API
unset ANTHROPIC_BASE_URL
export ANTHROPIC_API_KEY="your-api-key"
Claude Code + Ollama Setup Guide Page 25 of 27 Conclusion Congratulations! You've successfully set up Claude Code to run locally with Ollama. You now have a powerful, free, private coding assistant that works entirely on your machine.
What You've Achieved • Zero ongoing costs - No API fees, ever
• Complete privacy - Your code stays on your machine
• Offline capability - Work anywhere, anytime
• Full features - All Claude Code capabilities available
Next Steps 1. Experiment with different models to find your favorite
2. Try complex tasks to understand capabilities and limitations
3. Configure shortcuts and aliases for common workflows
4. Join the community - Claude Developers Discord for tips and support
5. Contribute back - Share your learnings and help others
Important Reminders • Local models are excellent for routine tasks but may struggle with very complex problems
• Keep Ollama updated: ollama update
• Monitor resource usage and adjust model size to your hardware
• Consider a hybrid approach: local for development, premium API for production
■ Happy Coding! You're now equipped to code faster, learn more, and build amazing things with your
free local AI assistant. The future of development is here, and it runs on your machine.
Claude Code + Ollama Setup Guide Page 26 of 27 For questions, issues, or feedback:
• Claude Code GitHub: https://github.com/anthropics/claude-code
• Ollama Documentation: https://ollama.com/docs
• Claude Developers Discord: https://discord.gg/claude
This guide is community-maintained. Contributions welcome!
Claude Code + Ollama Setup Guide Page 27 of 27