13 KiB
FAQ & Troubleshooting Guide
❓ General Questions
Q: Is OpenCode really free and open source?
A: Yes! OpenCode is 100% open source under the MIT license. You can:
- View the source code: https://github.com/anomalyco/opencode
- Self-host the entire platform
- Modify and distribute your own version
- The only costs are for AI model usage (through Zen or other providers)
Q: How does OpenCode compare to Claude Code?
A: OpenCode offers several advantages:
| Feature | OpenCode | Claude Code |
|---|---|---|
| Model Support | 75+ providers | Claude only |
| Pricing | Pay-as-you-go | Monthly subscription |
| Open Source | ✅ Yes | ❌ No |
| Self-hosting | ✅ Yes | ❌ No |
| Customization | Extensive | Limited |
| MCP Support | ✅ Yes | Limited |
| Local Models | ✅ Yes | ❌ No |
Q: Can I use OpenCode without an internet connection?
A: Partially. You need internet for:
- AI model inference (unless using local models)
- Installing/updating OpenCode
- MCP server communication
You can use OpenCode offline with:
- Local models (Ollama, llama.cpp)
- Cached responses
- Pre-installed MCP servers
🛠️ Installation & Setup
Q: OpenCode command not found after installation
A: Try these solutions:
# 1. Check installation
which opencode
# 2. Add to PATH
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
# 3. Reinstall
curl -fsSL https://opencode.ai/install | bash
# 4. Check permissions
ls -la $(which opencode)
chmod +x $(which opencode)
Q: Zen API key not working
A: Common fixes:
- Regenerate key: Visit opencode.ai/auth → API Keys → Regenerate
- Check billing: Ensure payment method is added and active
- Verify format: Key should be
zen_followed by 64 characters - Test connection:
curl -H "Authorization: Bearer YOUR_KEY" https://api.opencode.ai/v1/models
Q: OpenCode crashes on startup
A: Debug steps:
# Run with debug mode
opencode --debug
# Check system requirements
node --version # Should be 18+
which git # Git should be installed
# Clear corrupted config
rm -rf ~/.config/opencode
rm -rf ~/.opencode
# Try different terminal
# WezTerm or Alacritty recommended
🚀 Usage & Features
Q: File references (@filename) not working
A: Solutions:
# 1. Check current directory
!pwd
# 2. Use absolute path
@/full/path/to/file.ts
# 3. Check file exists
!ls -la @filename
# 4. Fuzzy search works best with unique names
# Instead of @config, use @config/database.ts
Q: OpenCode making wrong changes
A: Recovery options:
# 1. Undo changes
/undo # Can run multiple times
# 2. Check git status
!git status
# 3. Restore from git
!git checkout -- .
# 4. Be more specific in prompts
# Instead of "fix the bug", use:
# "Fix the null pointer exception on line 45 in @src/utils/validation.ts"
Q: Slow response times
A: Performance optimization:
# 1. Use lighter model
/models
# Select smaller/faster model
# 2. Disable thinking steps
/thinking off
# 3. Use simpler theme
/themes
# Select "minimal" or "simple"
# 4. Reduce context size
/compact
# 5. Check system resources
!top -o cpu
🤖 Agents & Skills
Q: Custom agent not appearing in list
A: Fix agent configuration:
# 1. Check agent file location
ls -la ~/.config/opencode/agents/
ls -la .opencode/agents/
# 2. Verify file format
# Should be .md or .json
# Should have proper YAML frontmatter
# 3. Reload agents
/agents reload
# 4. Check permissions
chmod +r .opencode/agents/my-agent.md
Q: Skill execution failing
A: Debug skills:
# 1. Check skill syntax
/skills validate skill-name
# 2. Test with dry run
/skills run skill-name --dry-run
# 3. Check skill permissions
/skills permissions skill-name
# 4. View skill logs
!cat ~/.local/share/opencode/skills.log
Q: Agent using wrong tools
A: Configure tool permissions:
# In agent configuration
## Tools
- read: true
- ask: true
- write: false # Disable file writing
- edit: false # Disable file editing
- bash: false # Disable shell commands
- skill: ["review", "test"] # Only specific skills
🧠 Models & Providers
Q: Model not available in Zen
A: Options:
- Check Zen status: Visit status.opencode.ai
- Use alternative provider:
/connect→ Add OpenAI/Anthropic directly - Request model: Contact OpenCode team via Discord
- Use similar model: Try GPT 5.2 Codex instead of Claude Opus
Q: High token usage/costs
A: Cost optimization:
# 1. Monitor usage
!opencode stats
# 2. Use cheaper models
# Qwen 2.5 Coder instead of GPT 5.2 Codex
# MiniMax M2.5 Free for experimentation
# 3. Reduce context size
/compact "Keep only relevant parts"
# 4. Be concise in prompts
# Instead of long explanations, use:
# "Fix bug: @file.ts line 45"
Q: Model giving poor quality responses
A: Improve responses:
# 1. Adjust temperature
# Lower (0.1) for code, higher (0.7) for creative
/models --temperature 0.1
# 2. Provide more context
# Include relevant files, examples, constraints
# 3. Use chain of thought
# Ask model to think step by step
# 4. Try different model
# Some models better for specific tasks
⚡ Advanced Issues
Q: MCP server connection failed
A: Troubleshoot MCP:
# 1. Check server status
/mcp status
# 2. View server logs
/mcp logs server-name
# 3. Test server manually
!command-from-mcp-config --help
# 4. Reinstall server
/mcp reinstall server-name
Q: OpenCode not recognizing project structure
A: Improve project understanding:
# 1. Run /init
/init
# 2. Check AGENTS.md
cat AGENTS.md
# 3. Provide context manually
# "This is a React/TypeScript project using Tailwind CSS"
# 4. Share project structure
!find . -name "*.ts" -o -name "*.tsx" | head -20
Q: Session sharing not working
A: Fix sharing:
# 1. Check internet connection
!curl -I https://opencode.ai
# 2. Generate share link
/share
# 3. If private, check authentication
/connect status
# 4. Export manually
/export
# Then share the markdown file
⚡ Performance & Optimization
Q: OpenCode using too much memory
A: Memory optimization:
# 1. Reduce context window
export OPENCODE_MAX_CONTEXT=8000
# 2. Disable unused features
export OPENCODE_DISABLE_MCP=1
export OPENCODE_DISABLE_SKILLS=1
# 3. Use lighter models
/models
# Select models with smaller context
# 4. Regular cleanup
rm -rf ~/.cache/opencode
rm -rf ~/.local/share/opencode/sessions/old-*
Q: Slow file operations
A: File system optimization:
# 1. Exclude large directories
echo 'node_modules' > .opencodeignore
echo '.git' >> .opencodeignore
echo 'dist' >> .opencodeignore
# 2. Use SSD if possible
# OpenCode benefits from fast storage
# 3. Limit file scanning
export OPENCODE_FILE_SCAN_LIMIT=1000
# 4. Use specific file references
# Instead of @src/, use @src/utils/validation.ts
Q: High CPU usage
A: CPU optimization:
# 1. Check for background processes
!ps aux | grep opencode
# 2. Limit concurrent operations
export OPENCODE_MAX_CONCURRENT=2
# 3. Use simpler parsing
export OPENCODE_SIMPLE_PARSER=1
# 4. Update to latest version
curl -fsSL https://opencode.ai/install | bash
🔒 Security & Privacy
Q: Is my code sent to AI providers?
A: Yes, when using cloud-based models. For privacy:
- Use local models: Ollama, llama.cpp
- Use enterprise providers: Some offer data privacy guarantees
- Self-host OpenCode: Complete control over data
- Review provider policies: Check data handling terms
Q: How to secure API keys?
A: Best practices:
# 1. Use environment variables
export OPENCODE_API_KEY=your_key
export ZEN_API_KEY=your_zen_key
# 2. Never commit keys to git
echo '.env' >> .gitignore
echo '*.key' >> .gitignore
# 3. Use key rotation
# Rotate keys every 90 days
# 4. Monitor usage
!opencode stats --alert high-usage
Q: Can OpenCode access sensitive files?
A: Yes, by default. Restrict access:
# 1. Create .opencodeignore
echo '.env' > .opencodeignore
echo 'secrets/' >> .opencodeignore
echo '*.key' >> .opencodeignore
# 2. Use agent permissions
# Create "restricted" agent with limited tools
# 3. Run in isolated environment
docker run -it --rm -v $(pwd):/workspace ghcr.io/anomalyco/opencode
# 4. Audit file access
!find ~/.local/share/opencode -name "*.log" | xargs grep "access"
🤝 Community & Support
Q: Where to get help?
A: Support channels:
- Discord: https://opencode.ai/discord (recommended)
- GitHub Issues: https://github.com/anomalyco/opencode/issues
- Documentation: https://opencode.ai/docs/
- Community Forum: GitHub Discussions
Q: How to contribute to OpenCode?
A: Contribution options:
- Code: Fork GitHub repo, submit PRs
- Documentation: Improve docs, add examples
- Skills/Agents: Share with community
- MCP Servers: Create and publish servers
- Bug Reports: Submit detailed issues
Q: Where to find examples and templates?
A: Resources:
- This repository: Examples in
examples/directory - Official examples: https://github.com/anomalyco/opencode-examples
- Community templates: GitHub topic
opencode-template - Skill registry: Built-in
/skills list
🔄 Updates & Migration
Q: How to update OpenCode?
A: Update methods:
# Using install script (recommended)
curl -fsSL https://opencode.ai/install | bash
# Using package manager
npm update -g opencode-ai
# or
brew upgrade opencode
# Check version
opencode --version
# Latest: https://github.com/anomalyco/opencode/releases
Q: Breaking changes in new version
A: Migration steps:
- Backup configuration
tar -czf opencode-backup.tar.gz ~/.config/opencode ~/.opencode - Check changelog: https://github.com/anomalyco/opencode/releases
- Test in isolated environment
- Gradual migration: Update one project at a time
Q: Compatibility with other tools
A: Integration status:
- VS Code: Extension available
- JetBrains IDEs: Plugin in development
- Neovim: Plugin available
- Docker: Official image available
- CI/CD: GitHub Actions available
Check https://opencode.ai/docs/ for latest integration status.
🚨 Common Error Messages
Error: "No provider configured"
# Solution:
/connect
# Follow prompts to add provider
Error: "Model not available"
# Solution:
/models
# Select available model
# or
/connect
# Add different provider
Error: "Permission denied"
# Solution:
# Check file permissions
!ls -la file.ts
# or
# Run with appropriate permissions
sudo chmod +r file.ts
Error: "Out of context window"
# Solution:
/compact
# or
# Be more concise
# or
# Use model with larger context
Error: "Rate limited"
# Solution:
# Wait and try again
# or
# Upgrade plan (Zen)
# or
# Use different provider
💡 Pro Tips & Best Practices
1. Start Simple:
- Begin with basic commands
- Master Plan/Build mode switching
- Create simple agents before complex ones
2. Iterate Gradually:
- Small, testable changes
- Regular undo/redo
- Continuous refinement
3. Document Everything:
- Keep AGENTS.md updated
- Document custom skills/agents
- Share successful workflows
4. Security First:
- Regular key rotation
- Principle of least privilege
- Audit logs review
5. Community Engagement:
- Share learnings
- Contribute improvements
- Help others learn
6. Continuous Learning:
- Stay updated with new features
- Experiment with different models
- Adapt workflows as tools evolve
Remember: OpenCode is a powerful tool that gets better with practice. Start with simple tasks, build confidence, and gradually tackle more complex challenges. The community is here to help!
📚 Additional Resources
Quick Reference:
- Main Guide - Overview and quick start
- Quick Start Guide - Installation and setup
- Zen Guide - Model router details
- TUI Guide - Terminal interface mastery
- Agents Guide - AI agents comprehensive guide
- Skills Guide - Skills system
- Commands Reference - Complete command list
- MCP Guide - MCP servers
- Workflows Guide - Development workflows
Official Links:
- Website: https://opencode.ai
- Documentation: https://opencode.ai/docs/
- GitHub: https://github.com/anomalyco/opencode
- Discord: https://opencode.ai/discord
- Status: https://status.opencode.ai
Last updated: February 2026