ljwx-harbor/ai/CLAUDE_QWEN_GUIDE.md

Claude-Qwen 使用指南

🤖 Claude-Qwen: 本地 AI 代码助手，使用 Qwen3-Coder:30B 完美平替 Claude！

🚀 快速开始

1. 一键安装

cd /Users/brunogao/work/codes/tools/macos/ai
./setup.sh

2. 安装依赖

claude-qwen install

3. 启动服务

# 前台运行
claude-qwen start

# 后台运行
claude-qwen start --background

📋 命令参考

基础命令

claude-qwen install      # 安装依赖环境
claude-qwen start        # 启动服务
claude-qwen start -b     # 后台启动服务
claude-qwen stop         # 停止服务
claude-qwen status       # 查看状态
claude-qwen test         # 测试功能
claude-qwen version      # 显示版本

配置管理

claude-qwen config                       # 查看所有配置
claude-qwen config model                 # 查看模型配置
claude-qwen config temperature 0.5       # 设置温度参数
claude-qwen config max_tokens 4096       # 设置最大 token 数

⚙️ 配置选项

配置项	默认值	说明
ollama_url	http://localhost:11434	Ollama 服务地址
model	qwen3-coder:30b	使用的模型
max_tokens	2048	最大生成 token 数
temperature	0.3	生成温度 (0-1)
timeout	300	请求超时时间 (秒)
auto_start_llm	True	自动启动 LLM 服务

🎯 使用场景

1. 日常编码助手

# 启动后台服务
claude-qwen start --background

# 在任何项目中使用 Claude-Code，它会自动连接到本地 Qwen3-Coder
# 与使用 Claude API 完全相同的体验！

2. 项目开发

cd your-project
claude-qwen start

# 现在可以使用 Claude-Code 的所有功能：
# - 代码生成和补全
# - 代码重构和优化
# - 错误诊断和修复
# - 文档生成

3. 配置优化

# 针对不同任务调整参数
claude-qwen config temperature 0.1    # 代码生成用较低温度
claude-qwen config max_tokens 4096    # 长文本生成
claude-qwen config timeout 600        # 复杂任务延长超时

🔧 故障排除

服务未运行

claude-qwen status      # 检查状态
claude-qwen start       # 启动服务

模型不可用

# 检查模型状态
ollama list

# 下载模型
ollama pull qwen3-coder:30b

# 测试模型
ollama run qwen3-coder:30b

依赖问题

claude-qwen install    # 重新安装依赖

性能优化

# 监控资源使用
top -pid $(pgrep -f "qwen3-coder")

# 调整参数
claude-qwen config temperature 0.2
claude-qwen config max_tokens 1024

📁 文件结构

~/.claude-qwen/              # 配置目录
├── config.json             # 主配置文件
├── logs/                   # 日志目录
│   └── claude-qwen.log     # 运行日志
└── claude-qwen.pid         # 后台运行 PID

~/.local/bin/claude-qwen    # 全局命令

原始项目目录/
├── claude-qwen             # 主程序
├── qwen-mcp-server.py      # MCP Server
├── requirements.txt        # Python 依赖
├── qwen-mcp-env/          # 虚拟环境
└── README.md              # 项目文档

🚨 重要提醒

1. 首次使用: 确保 Qwen3-Coder:30b 模型已下载
2. 内存需求: 建议至少 100GB 可用内存
3. 启动时间: 首次启动可能需要 30-60 秒
4. 网络依赖: 完全本地运行，无需网络连接

💡 最佳实践

开发工作流

# 1. 启动服务
claude-qwen start --background

# 2. 在项目中使用 Claude-Code
# 享受本地 AI 助手的强大功能！

# 3. 完成后停止服务
claude-qwen stop

参数调优

• 代码生成: temperature: 0.1-0.3, max_tokens: 2048
• 创意写作: temperature: 0.7-0.9, max_tokens: 4096
• 代码解释: temperature: 0.3-0.5, max_tokens: 1024

性能监控

# 查看日志
tail -f ~/.claude-qwen/logs/claude-qwen.log

# 检查状态
claude-qwen status

🎉 优势总结

✅ 零成本: 无 API 费用，仅电费 ✅ 高隐私: 数据完全本地处理 ✅ 强性能: 30B 参数，代码能力接近 Claude ✅ 易使用: 与 Claude-Code 无缝集成 ✅ 可定制: 支持参数调优和配置 ✅ 稳定可靠: 7x24 小时可用

---

🎊 恭喜！你现在拥有了一个完全本地化的 Claude 替代方案！

开始使用: claude-qwen start