FreeX Hub 是一个专注于技术分享、开发者工具、云原生、AI 工程化、VPS 测评、教育邮箱资源与互联网实用福利的开放平台。提供可复现的教程、实测评测、部署指南与实用工具，帮助开发者与技术爱好者高效探索无限可能。
OpenCode 完整使用教程：安装、配置本地模型、卡顿排查与任务恢复
OpenCode 完整使用教程：安装、配置本地模型、卡顿排查与任务恢复面向普通开发者的实战指南：从安装 OpenCode，到接入本地模型，再到解决执行过程中卡住、异常退出、任务恢复等常见问题。一、什么是 OpenCode？OpenCode 官方网站https://opencode.aiOpenCode 官方文档https://opencode.ai/docsOpenCode GitHubhttps://github.com/sst/opencodeOpenCode 是一款运行在终端中的 AI 编码助手。它的核心特点包括：支持本地大模型（LM Studio、Ollama 等）支持云端模型（OpenAI、Anthropic 等）自动分析项目结构自动读写文件自动执行 Shell 命令自动生成代码、文档和测试支持多轮上下文协作如果你使用过：Claude CodeOpenAI Codex CLIOpenClaw那么可以把 OpenCode 理解为一个轻量、现代、专注于代码工作的终端 AI Agent。二、OpenCode 的工作原理OpenCode 并不是简单地“把问题发给模型”。它的执行流程通常如下：用户提出任务 ↓ 扫描项目文件 ↓ 构建上下文 ↓ 调用模型制定计划 ↓ 执行命令（npm、git、mvn 等） ↓ 修改文件 ↓ 再次调用模型 ↓ 完成任务也就是说，模型只是其中一个环节。很多时候界面显示“正在执行”，但实际上 OpenCode 正在运行本地命令，而不是调用大模型。三、安装 OpenCode1. 安装 Node.jsurlNode.js 官方网站https://nodejs.org建议安装：Node.js 20+2. 全局安装npm install -g opencode-ai3. 验证安装opencode --version如果输出版本号，说明安装成功。四、项目目录结构推荐在项目根目录中准备以下文件：my-project/ ├── opencode.json # OpenCode 配置 ├── SOUL.md # 项目级系统提示词 ├── .gitignore └── src/五、配置本地模型（局域网 IP）如果你的模型服务已经部署在局域网中，例如：http://192.168.10.86:1234/v1则可以在项目根目录创建 opencode.json。最简配置示例{ "$schema": "https://opencode.ai/config.json", "provider": { "local": { "npm": "@ai-sdk/openai-compatible", "name": "My Local Model", "options": { "baseURL": "http://192.168.10.86:1234/v1", "apiKey": "dummy" }, "models": { "google/gemma-3-27b-it": { "name": "Gemma 3 27B", "limit": { "context": 128000, "output": 8192 } } } } }, "model": "local/google/gemma-3-27b-it" }六、配置项详解provider定义模型提供者。"provider": { "local": { ... } }这里的 local 是你自定义的名称。npm指定兼容 OpenAI API 的 SDK。"npm": "@ai-sdk/openai-compatible"baseURL模型 API 地址。"baseURL": "http://192.168.10.86:1234/v1"apiKey即使本地模型不验证，也需要提供一个值。"apiKey": "dummy"models定义可用模型。limit.context上下文窗口大小。limit.output最大输出 token 数。model默认使用的模型。"model": "local/google/gemma-3-27b-it"七、获取正确的模型名称在浏览器中打开：http://192.168.10.86:1234/v1/models返回：{ "data": [ { "id": "google/gemma-3-27b-it" } ] }其中的 id 就是模型名称。八、启动 OpenCodecd my-project opencode九、常用命令查看帮助/help查看模型/models切换模型/model local/google/gemma-3-27b-it退出/exit十、SOUL.md：项目级提示词在项目根目录创建：SOUL.md示例：你是一位资深 Java 架构师。 要求： - 使用 Spring Boot 3 - 使用 MyBatis - 所有注释使用中文 - 优先考虑可维护性 - 修改代码前先分析整体架构OpenCode 启动时会自动加载。十一、基础使用示例分析项目请分析当前项目架构，并给出优化建议。修复 Bug找出登录失败的原因并修复。生成代码创建用户管理 REST API。生成测试为 UserService 编写 JUnit 5 测试。编写文档生成完整 README.md。十二、推荐的高质量提示词请先分析项目结构，列出执行计划，逐步完成任务，并在每一步说明原因。这个提示词可以显著提高结果质量和稳定性。十三、OpenCode 卡在 14% 是什么原因？很多用户会遇到这种情况：OpenCode 显示 14% ExecutingLM Studio 没有任何请求CPU 占用很低长时间无响应这通常说明：OpenCode 正在执行本地工具步骤，而尚未调用模型。十四、执行流程示意图任务开始 ↓ 创建目录 ↓ 安装依赖（npm install） ← 最常卡住 ↓ 扫描文件 ↓ 调用模型 ↓ 生成代码如果卡在前面步骤，模型不会被调用。十五、最常见卡顿原因1. npm install 或 pnpm install 阻塞最常见原因。可能是：下载依赖过慢网络问题等待输入镜像源异常2. 等待权限确认OpenCode 在执行命令或写文件前可能等待批准。3. 文件数量过多例如：node_modules.gitdistbuild4. Windows Defender 实时扫描大量文件操作会导致明显变慢。5. 模型尚未准备好虽然通常会显示请求，但部分情况下加载模型也会造成延迟。十六、如何排查卡顿开启调试模式opencode --debug你可以看到：正在执行的命令是否等待批准是否调用模型错误信息手动测试命令git status npm install pnpm install检查模型接口curl http://192.168.10.86:1234/v1/models十七、为什么 OpenCode 会自动关闭？可能原因：Shell 命令失败模型请求超时Node.js 崩溃内存不足未捕获异常十八、自动关闭后为什么任务消失？OpenCode 的会话主要保存在内存中。当进程退出时：内存中的上下文丢失已生成的文件仍然保留重新启动时会创建新会话。十九、如何恢复任务进入项目目录：cd your-project opencode然后输入：请扫描当前目录，确认哪些部分已经完成，并继续完成未完成的工作。二十、推荐恢复提示词请分析当前项目状态，判断哪些内容已经完成，哪些尚未完成，并从中断处继续。二十一、检查是否已生成部分文件git status或者：dir通常会发现：项目目录已创建部分文件已生成依赖尚未安装完成二十二、避免任务丢失的最佳实践1. 初始化 Gitgit init git add . git commit -m "initial state"2. 分阶段执行不要一次性要求：创建项目安装依赖编写全部代码执行测试建议拆成多个步骤。3. 使用调试模式opencode --debug4. 手动安装依赖npm install二十三、最稳定的工作流第一步：手动创建项目npm create vite@latest myapp cd myapp npm install第二步：初始化 Gitgit init git add . git commit -m "base project"第三步：启动 OpenCodeopencode第四步：逐步下达任务先分析项目，然后实现用户管理功能。二十四、适合 Java 开发者的使用方式作为 Java 程序员，可以让 OpenCode 处理以下工作：Spring Boot 接口开发MyBatis Mapper 编写SQL 优化单元测试架构分析技术文档生成二十五、推荐任务模板创建 REST API使用 Spring Boot 3 和 MyBatis 实现用户管理模块。优化 SQL分析这些 SQL 并给出索引优化建议。生成博客根据项目内容生成一篇技术博客。二十六、性能优化建议在子目录运行cd backend opencode避免扫描整个仓库。配置 .gitignorenode_modules dist build .next coverage *.logWindows Defender 排除建议将以下目录加入排除：项目目录Node.js 安装目录npm 全局缓存目录二十七、常见问题汇总Q1：启动后提示找不到模型原因：模型 ID 配置错误。解决：访问 /v1/models 获取正确的 id。Q2：显示执行中但模型没有调用原因：OpenCode 正在执行本地命令。Q3：程序自动退出原因：命令失败、超时或异常。Q4：重新打开任务不见了原因：会话保存在内存中，进程退出后丢失。二十八、与其他工具对比工具特点适用人群OpenCode轻量、终端优先普通开发者Claude Code工具能力强高级开发者Codex CLI官方生态OpenAI 用户OpenClaw自动化程度高高级玩家二十九、推荐的生产实践建议按照以下流程使用：1. 手动创建项目 2. 手动安装依赖 3. 初始化 Git 4. 编写 SOUL.md 5. 启动 OpenCode 6. 分步骤完成任务 7. 每个阶段提交 Git三十、我的实际建议如果你的主要工作是：Java 后端开发技术博客写作自动生成测试项目重构那么 OpenCode 是一个非常高效的终端 AI 工具。尤其适合与本地模型结合使用：数据不离开本地成本几乎为零可长期稳定使用三十一、最推荐的提示词模板请先分析整个项目结构，列出详细计划，逐步完成任务。 在每一步执行前说明原因，执行后总结结果。 如果遇到错误，请自行排查并继续。三十二、总结OpenCode 的本质并不是“聊天机器人”，而是一个能够：理解代码制定计划执行命令修改文件自动恢复上下文的终端 AI Agent。理解以下三个关键点后，使用体验会非常稳定：执行中不一定是在调用模型自动关闭后文件仍然存在重新扫描项目即可继续任务三十三、最简工作流程# 安装 npm install -g opencode-ai # 进入项目 cd my-project # 启动 opencode --debug然后输入：请分析当前项目，并逐步完成用户管理模块。三十四、结语对于希望长期利用 AI 提升开发效率的程序员而言，OpenCode 是值得深入掌握的工具。它最大的价值不在于“自动写代码”，而在于：将模型能力与真实开发流程（文件、命令、Git、测试）融合为统一的自动化工作流。一旦掌握配置、调试和恢复技巧，你就可以把 OpenCode 打造成真正的个人 AI 开发助手。
Docker Mailu 邮箱服务网络故障排查实录：iptables FORWARD 链引发的"连接超时"陷阱
🐳 Docker Mailu 邮箱服务网络故障排查实录：iptables FORWARD 链引发的"连接超时"陷阱摘要：本文记录了一次 Docker Mailu 邮件服务器网络故障的完整排查过程。问题表现为容器无法解析域名、无法连接外网，最终定位到宿主机 iptables 的 FORWARD 链策略限制。文章提供系统性排查思路和可复用的修复方案，适合运维工程师和自建服务爱好者参考。标签：#Docker #Mailu #iptables #网络故障 #运维实战作者：黄振华 | 发布于：bloghua.com | 阅读时间：约 8 分钟🔍 一、问题现象：邮件服务"集体失联"📋 故障表现Mailu 管理后台加载缓慢，部分功能报错用户无法收发邮件，Webmail 提示"连接服务器失败"执行 docker compose exec front nslookup google.com 返回：;; connection timed out; no servers could be reachedsystemctl status docker 日志中出现大量：[resolver] failed to query external DNS server lua_bayes_redis.lua:145: cannot get bayes statistics: timeout while connecting to redis🧩 初步判断容器网络出口被阻断，但宿主机本身网络正常。问题可能出在：Docker 网络配置异常宿主机防火墙规则拦截云平台安全组限制🕵️ 二、排查过程：分层诊断，精准定位✅ 第 1 层：确认容器网络状态# 检查 Mailu 容器运行状态 docker compose ps发现 mailu-resolver-1 状态为 unhealthy，其他容器虽 healthy 但网络功能异常。✅ 第 2 层：测试容器网络连通性（关键！）# 测试 1：绕过 Docker DNS，直连外部 DNS 服务器 docker compose exec front nslookup google.com 8.8.8.8 # 结果：❌ 仍超时 → 排除 Docker 嵌入式 DNS 故障 # 测试 2：测试纯 IP 连通性（排除 DNS 问题） docker compose exec front ping -c 2 8.8.8.8 # 结果：❌ 超时 → 容器无法访问外网 # 测试 3：测试容器间通信 docker compose exec front ping -c 2 redis # 结果：❌ 超时 → 容器间网络也异常📋 结论：容器网络栈整体失效，问题在宿主机网络层。✅ 第 3 层：检查宿主机防火墙（根因定位）# 查看 FORWARD 链策略（容器流量必经之路） sudo iptables -L FORWARD -n -v --line-numbers # 关键发现： # Chain FORWARD (policy DROP) ← 默认策略为 DROP！ # 且无允许容器网段（172.16.0.0/12）转发的规则💡 知识卡片：Docker 容器通信依赖 Linux 内核的 net.ipv4.ip_forward 和 iptables 的 FORWARD 链。如果策略为 DROP 且无放行规则，容器流量将被静默丢弃。🛠️ 三、解决方案：两步修复，立竿见影🔧 临时修复（立即恢复服务）# 1. 将 FORWARD 链默认策略改为 ACCEPT sudo iptables -P FORWARD ACCEPT # 2. 清空 FORWARD 链现有规则（避免冲突） sudo iptables -F FORWARD # 3. 验证修复 docker compose exec front nslookup google.com 8.8.8.8 # ✅ 返回正常解析结果🔐 生产环境推荐：精细化规则（安全加固）临时方案虽有效，但 FORWARD ACCEPT 会放行所有转发流量，存在安全风险。建议替换为精细化规则：# 1. 恢复默认策略 sudo iptables -P FORWARD DROP # 2. 允许已建立连接的回包 sudo iptables -A FORWARD -m conntrack --ctstate ESTABLISHED,RELATED -j ACCEPT # 3. 允许容器网段出网（根据实际网段调整） sudo iptables -A FORWARD -s 172.16.0.0/12 -j ACCEPT sudo iptables -A FORWARD -s 192.168.0.0/16 -j ACCEPT # 4. 允许 Docker 网桥通信 sudo iptables -A FORWARD -i docker0 -o docker0 -j ACCEPT # 5. 保存规则（根据系统选择） # Debian/Ubuntu: sudo iptables-save > /etc/iptables/rules.v4 # CentOS/RHEL: sudo service iptables save🔄 永久生效：确保开机自动加载# 1. 安装 iptables-persistent（Debian/Ubuntu） sudo apt install iptables-persistent sudo netfilter-persistent save # 2. 或创建 systemd 服务自动恢复规则 # /etc/systemd/system/iptables-restore.service [Unit] Description=Restore iptables rules Before=docker.service [Service] Type=oneshot ExecStart=/sbin/iptables-restore < /etc/iptables/rules.v4 RemainAfterExit=yes [Install] WantedBy=multi-user.target🧪 四、验证清单：确保服务完全恢复#!/bin/bash echo "=== 🧪 Mailu 网络修复验证 ===" echo -e "\n1️⃣ 容器外网解析" docker compose exec front nslookup google.com 8.8.8.8 | grep "Address:" echo -e "\n2️⃣ 容器间服务发现" docker compose exec front nslookup redis | grep "Address:" echo -e "\n3️⃣ Redis 连通性（反垃圾核心）" docker compose exec antispam redis-cli -h redis ping echo -e "\n4️⃣ 邮件端口监听状态" ss -tlnp | grep -E '25|465|587|993' | awk '{print $1, $4}' echo -e "\n5️⃣ resolver 健康状态" docker compose ps resolver --format "table {{.Status}}" echo -e "\n✅ 全部通过 = 修复成功！"🛡️ 五、预防措施：避免问题复发🔹 1. 监控 iptables 规则变更# 创建监控脚本 /usr/local/bin/watch-iptables.sh #!/bin/bash iptables -L FORWARD -n > /tmp/iptables.forward.bak # 配合 cron 每分钟检查，变动时告警🔹 2. Docker 启动时自动修复规则在 /etc/docker/daemon.json 中添加：{ "iptables": true, "ip-forward": true, "fixed-cidr": "172.16.0.0/12" }⚠️ 注意："iptables": true 会让 Docker 自动管理规则，但部分系统策略可能覆盖它，需测试验证。🔹 3. 云服务器额外检查云平台检查项操作路径阿里云安全组出方向ECS 控制台 → 安全组 → 出方向规则腾讯云防火墙策略CVM 控制台 → 安全组 → 出站规则AWSSecurity GroupEC2 → Security Groups → Outbound rules华为云安全组规则控制台 → 虚拟私有云 → 安全组✅ 通用原则：确保出方向允许 0.0.0.0/0 或至少 8.8.8.8/32:53、0.0.0.0/0:443🔹 4. 定期健康检查脚本# /opt/mailu/health-check.sh #!/bin/bash cd /opt/mailu # 检查关键容器 docker compose ps | grep -E "(unhealthy|exit)" && echo "❌ 容器异常" && exit 1 # 检查网络连通性 docker compose exec front nslookup google.com 8.8.8.8 >/dev/null 2>&1 || { echo "❌ 容器外网异常" # 可在此处自动执行修复命令 exit 1 } echo "✅ 健康检查通过"配合 cron 每小时执行，故障早发现早恢复。💡 六、经验总结与思考🎯 核心收获容器网络问题，先查宿主机：Docker 网络依赖宿主机内核和防火墙，不要只在容器内打转。分层测试是关键：域名解析 → IP 连通 → 端口访问 → 服务发现，逐层缩小范围。临时方案 + 永久加固：先恢复业务，再完善规则，避免"救火式运维"。⚠️ 避坑指南❌ 不要直接 iptables -F 清空所有规则（会误删 SSH 等关键规则）✅ 优先操作 FORWARD 链，谨慎触碰 INPUT/OUTPUT❌ 不要忽略云平台安全组（容器流量也受其约束）✅ 修改防火墙后务必 save 并测试重启生效🔮 延伸思考如果业务允许，可考虑使用 Podman + Quadlet 替代 Docker，其网络模型更贴近 systemd，规则管理更直观。对于关键服务，建议部署 双机房 + 自动故障转移，避免单点网络故障导致服务中断。📚 附录：常用命令速查# 🔍 网络诊断 ip route show | grep default # 查看默认路由 sysctl net.ipv4.ip_forward # 检查内核转发 docker network inspect mailu_default # 查看 Docker 网络详情 # 🛡️ 防火墙管理 iptables -L FORWARD -n -v --line-numbers # 查看 FORWARD 链 iptables -P FORWARD ACCEPT # 修改默认策略 iptables-save > /etc/iptables/rules.v4 # 保存规则 # 🐳 Docker 网络修复 systemctl restart docker # 重启 Docker（重载网络规则） docker compose down && docker compose up -d # 重建容器网络🙋 互动时间：你在部署自建服务时遇到过哪些"诡异"的网络问题？欢迎在评论区分享你的排查故事～ 🔔 订阅更新：关注 bloghua.com，获取更多运维实战、开源工具深度评测内容。版权声明：本文原创首发于 freex.cc，采用 CC BY-NC-SA 4.0 协议，转载需注明作者及出处。
TinyClaw：用 500 行代码复刻生产级 AI Agent 引擎｜轻量级多智能体框架实战
🔧 TinyClaw：用 500 行代码复刻生产级 AI Agent 引擎｜轻量级多智能体框架实战摘要：在 AI Agent 开发日益复杂的今天，是否有一个"小而美"的方案能快速落地？本文深度解析开源项目 TinyClaw——一个基于 FastAPI + LangChain 0.3 + Vue 3 的轻量级 AI Agent 执行引擎，带你从零理解多智能体委派、记忆管理、技能热加载等核心机制。🎯 为什么需要 TinyClaw？当前主流的 Agent 框架（如 LangGraph、AutoGen、CrewAI）功能强大但学习曲线陡峭，部署复杂且资源消耗大。对于个人开发者、快速原型验证或边缘部署场景，往往"杀鸡用牛刀"。TinyClaw 的诞生正是为了解决这一痛点："用最小的代码复杂度，复刻生产级的 Agent 执行能力"它从 OpenClaw 精简而来，剥离分布式网关与复杂图编排，保留最核心的 Tool Calling、多智能体路由、工作空间隔离等能力，单机即可运行，代码清晰易读，是学习 Agent 架构的绝佳实践项目。✨ 核心特性全景图🤖 多智能体智能委派用户 → main Agent → "@coder 请写个网页" → 自动路由 → coder Agent → 执行 file.write支持主 Agent 与多个子 Agent（如 @coder、@researcher）前端无缝切换角色，后端自动转发消息上下文基于 Prompt 指令的软路由，无需复杂配置🧩 OpenClaw 技能完全兼容backend/skills/ ├── file.read/ # 读取文件技能 │ ├── skill.json # 元数据定义 │ └── run.py # 业务逻辑实现 └── file.write/ # 写入文件技能复用 OpenClaw 生态技能插件动态热加载：新增技能文件夹，重启即生效标准化入参：params 字典 + 隐式注入 __workspace_dir🧠 高级记忆管理系统功能作用适用场景记忆裁剪 🗑️删除单条错误回复，防止幻觉污染上下文模型输出错误时快速修正记忆压缩 🗜️自动摘要长对话，重置上下文窗口长会话防 Token 溢出，节省 API 成本🛠️ 硬核调试能力Traces 控制台：折叠式展示技能调用链，入参/出参一目了然AOP 切面日志：@log_call 注解无侵入记录函数执行debug.log：原始 Prompt 与 Model Response 完整留存，排查"模型不听话"问题🔐 工作空间物理隔离data/workspaces/ ├── default/ │ ├── memory.json # 对话历史 │ ├── files/ # 生成/读取的文件 │ └── logs/ # 运行日志 └── project_x/ # 多项目并行，数据绝不串号🏗️ 技术架构深度解析后端：FastAPI + LangChain 0.3# core/agent.py - Agent 执行核心 async def run_agent(agent_name: str, message: str, workspace: str): # 1. 加载 Agent 配置（prompt + skills） # 2. 构建 LangChain Tool 列表（Pydantic Schema 自动转换） # 3. 调用 LLM 并处理 Tool Calling 循环 # 4. 记忆裁剪/压缩策略介入 # 5. 返回结构化响应关键设计：使用 LangChain 0.3 原生 bind_tools + tool_calling，避免自定义解析器技能参数通过 Pydantic 自动校验，类型安全异步 async/await 全程支持，高并发友好前端：Vue 3 + Composition API <AgentSwitcher v-model="currentAgent" :agents="agents" /> <ChatWindow :messages="messages" @trim="deleteMessage" /> <TracePanel :traces="debugTraces" v-if="showDebug" /> 响应式状态管理：Agent 切换、消息流、调试面板联动自定义指令：v-trim 实现消息裁剪交互轻量无状态：所有数据通过 API 与后端同步，前端专注渲染配置驱动：solu.json{ "model": { "type": "openai", "name": "gpt-4o-mini", "base_url": "https://api.openai.com/v1" }, "agents": { "main": { "prompt": "你是前台管家...", "skills": [] }, "coder": { "prompt": "你是代码专家...", "skills": ["file.read", "file.write"] } }, "runtime": { "timeout": 20, "max_steps": 5 } }零代码配置 Agent 网络：修改 JSON 即可调整角色分工多模型支持：OpenAI 标准接口 / Ollama 本地模型无缝切换运行时控制：超时、最大步骤防止死循环🚀 5 分钟快速上手环境准备# 后端：Python 3.10+ cd backend && pip install -r requirements.txt # 前端：Node 18+ cd frontend && npm install启动服务# Terminal 1: 后端 cd backend && uvicorn app:app --reload --port 8000 # Terminal 2: 前端 cd frontend && npm run dev配置模型（backend/solu.json）// 使用 Ollama 本地模型（免费！） "model": { "type": "openai", "name": "qwen2.5-coder", "base_url": "http://localhost:11434/v1", "api_key": "ollama" }访问 http://localhost:5173，即刻体验多智能体对话！💡 高级技巧：让 TinyClaw 更强大1️⃣ 自定义技能开发（3 步搞定）# 1. 创建技能目录 mkdir backend/skills/weather.query # 2. 编写 skill.json { "name": "weather.query", "description": "查询城市天气", "entry": "run.py", "params": { "city": "string" } } # 3. 实现 run.py async def run(params: dict) -> dict: city = params["city"] # 调用天气 API... return {"success": True, "data": f"{city} 晴，25℃"}✅ 重启后端，@main 北京天气 即可自动调用！2️⃣ 记忆压缩实战：节省 80% Token# 当对话超过 20 条时触发 if len(messages) > 20: summary = await llm.invoke(f"请总结以下对话：{messages}") messages = [SystemMessage(content=f"前情提要：{summary}")]适合：长文档分析、多轮需求澄清、代码迭代开发效果：上下文从 10K tokens → 1K tokens，API 成本直降3️⃣ 调试"模型不调用工具"问题# 查看底层日志 tail -f backend/data/workspaces/default/logs/debug.log # 常见原因： # 1. skill.json 描述不清晰 → 优化 description # 2. 参数类型不匹配 → 检查 Pydantic Schema # 3. Prompt 未明确触发条件 → 加强 agent prompt🔍 适合谁用？用户类型使用场景收益个人开发者快速验证 Agent 想法10 分钟搭建原型，专注业务逻辑学生/学习者学习 Agent 架构原理代码精简，核心流程一目了然边缘部署场景本地/私有化运行单机启动，无 Redis/K8s 依赖OpenClaw 用户轻量级替代方案技能复用，配置兼容，迁移成本低📦 项目信息🔗 源码：https://github.com/qyhua0/TinyClaw📜 协议：MIT License（可商用）🐍 后端：Python 3.10+ / FastAPI / LangChain 0.3⚛️ 前端：Vue 3 / Vite / TypeScript🤖 模型：OpenAI 标准接口 / Ollama / 任意兼容端点🌟 总结TinyClaw 证明了：强大的 Agent 能力，不需要复杂的架构。它用极简的设计哲学，将多智能体协作、技能扩展、记忆管理等核心能力封装为可配置的模块，既适合快速落地业务，也适合深入理解 Agent 底层原理。💡 个人建议：如果你正在寻找一个"能跑起来、看得懂、改得动"的 Agent 框架，TinyClaw 值得加入你的技术栈。
AgentCode v1.0 发布：一款极简高效的 AI 编程代理，让你的开发效率翻倍
AgentCode v1.0 发布：一款极简高效的 AI 编程代理，让你的开发效率翻倍🎯 一句话介绍：AgentCode 是一款灵感源自 Claude Code 架构的 AI 编程代理，能深度理解项目代码、自主执行复杂工程任务，并完美兼容 OpenAI 标准接口与本地 Ollama 模型。作为一名长期关注 AI 辅助开发工具的个人开发者，我一直在寻找一款既能理解项目上下文、又能安全执行任务的轻量级编程代理。今天，很高兴向大家介绍我最新开源的项目 —— AgentCode v1.0，它或许就是你一直在等的那个"智能编程搭档"。🔍 为什么需要 AgentCode？在日常开发中，我们常常面临这样的场景：想要重构某个模块，但需要跨多个文件理解依赖关系需要批量检查项目中的 TODO、FIXME 并生成报告希望有一个"懂项目"的 AI 助手，而不是每次都要重新粘贴上下文传统 Chat 工具往往受限于上下文窗口，且缺乏对项目结构的深度理解；而大型 IDE 插件又过于重量级，配置复杂。AgentCode 的设计哲学：极简、高效、可控。它不追求花哨的 UI，而是专注于"理解代码 - 规划任务 - 安全执行"的核心闭环。🌟 七大核心特性，直击开发痛点1️⃣ 🤖 可定制的"代理灵魂"通过 sold.md 文件（OpenClaw 风格），你可以自由定义 Agent 的行为准则：# AgentCode 编程专家版 你是一个极高性能、追求完美代码质量的 AI 编程专家。 - **质量优先**：代码必须健壮、可读。 - **极简主义**：多写代码，少废话。 - **先读后写**：修改前必须读取文件上下文。💡 这意味着你可以为不同项目创建不同"人格"的代理：代码审查专家、文档生成助手、性能优化顾问……随心切换。2️⃣ ⚙️ 灵活的多级配置系统配置加载顺序：默认值 → config.json → .env → 环境变量{ "model": "gpt-4o", "api_key": "sk-...", "base_url": "https://api.openai.com/v1", "temperature": 0, "soul_file": "sold.md" }✅ 开发时用本地 Ollama，部署时切到云端 API，无需修改代码，只需切换环境变量。3️⃣ 🚀 并行工具执行，效率倍增AgentCode 能自动识别可并行任务，例如同时读取多个配置文件、并发执行多个 grep 搜索，显著减少等待时间。4️⃣ 📝 精确文件编辑，安全可控核心 edit_file 工具采用精确字符串替换策略：自动创建 .bak 备份文件匹配失败时提供智能上下文提示，避免"改错地方"支持多位置替换，满足批量重构需求5️⃣ 🧠 三层上下文压缩，突破 128k 限制智能剪裁冗余工具输出自动生成对话摘要硬折叠保护关键信息🎯 即使处理大型项目，也能在有限窗口内保持"长期记忆"。6️⃣ 🌍 全平台中文友好针对 Windows / Linux / macOS 进行了 UTF-8 编码深度优化，完美支持：中文注释的文件读取含中文路径的项目结构跨平台命令执行一致性7️⃣ 🛠️ 派生子代理，复杂任务拆解遇到大型重构或技术调研任务？使用 agent 工具派生独立子代理：子代理拥有独立上下文，避免污染主对话主代理负责协调与结果整合适合"分而治之"的工程策略🛠️ 快速上手：3 分钟开始使用环境准备# Python 3.11+ git clone https://github.com/qyhua0/AgentCode.git cd agentcode pip install -e .配置（任选其一）# 方式1：config.json（推荐） echo '{"model": "gpt-4o", "api_key": "sk-..."}' > config.json # 方式2：环境变量 export AGENTCODE_API_KEY=sk-... export AGENTCODE_MODEL=gpt-4o # 方式3：本地 Ollama export AGENTCODE_MODEL=qwen2.5-coder export AGENTCODE_BASE_URL=http://localhost:11434/v1开始交互# 进入 REPL 模式 agentcode # 或直接执行单条指令 agentcode -p "帮我检查项目中所有的 TODO 并生成报告"常用内置指令指令功能/help显示帮助菜单/reset重置会话，清空历史/stats查看 Token 使用与压缩日志/load <path>将指定文件注入上下文quit退出交互🧰 内置工具箱：9 大核心能力AgentCode 为 LLM 提供了精心设计的工具集，让 AI"知道能做什么"：🔧 bash - 安全执行 Shell 命令，支持目录追踪与危险指令拦截 📖 read_file - 带行号读取文件，自动处理编码与分页 ✏️ edit_file - 精确字符串替换，匹配失败时智能提示 📄 write_file- 创建或覆盖文件 🔍 grep - 正则表达式全局搜索 📁 ls - 详尽目录列表，含文件大小与修改时间 🌐 glob - 强大模式匹配（如 **/*.py），按时间排序 ✅ todo - 任务追踪系统，辅助多步任务规划 🤖 agent - 派生独立子代理，处理复杂子任务💡 所有工具调用均由 LLM 自主决策，你只需描述目标，AgentCode 负责规划执行路径。🔒 安全设计：保护你的代码与系统我们深知"给 AI 执行权限"的风险，因此在 bash 工具中内置了安全拦截机制：# 自动拦截的高危操作 - rm -rf / ~ 等根目录递归删除 - mkfs.* 文件系统格式化 - dd 直接磁盘写入 - curl ... | bash 执行远程未知脚本✅ 建议：首次使用时在测试项目中体验，熟悉行为模式后再用于生产环境。📈 版本规划与展望✅ v1.0.0（当前版本）核心代理引擎发布多级配置与灵魂系统上线全平台编码优化完成🚧 后续计划[ ] 支持更多模型提供商（Anthropic、Gemini 等）[ ] 增加 Web UI 模式，降低使用门槛[ ] 插件系统：允许社区贡献自定义工具[ ] 项目级知识库：自动索引代码语义，提升理解深度💬 写在最后AgentCode 的诞生，源于一个朴素的想法：让 AI 真正成为开发者的"延伸"，而不是另一个需要频繁切换的聊天窗口。它可能不是功能最丰富的，但力求在"理解 - 执行 - 安全"三角中找到最佳平衡点。如果你也认同"工具应该服务于人，而非增加认知负担"的理念，欢迎体验、反馈、贡献。🔗 项目地址：https://github.com/qyhua0/AgentCode 📄 开源协议：MIT License🙋‍♂️ 我是 zhenhua，一名热爱造轮子的独立开发者。如果你也对 AI + 开发工具感兴趣，欢迎关注我的博客 bloghua.com，一起探索效率开发的更多可能。✨ 小互动：你希望 AI 编程代理优先帮你完成哪类任务？欢迎在评论区留言，你的想法可能成为下一个版本的特性！
OpenClaw 本地部署超时不回复？5 分钟解决 embedded agent 预填充超时（2026 最新版 v2026.4.8 实测有效）
OpenClaw + Gemma-4-31b 本地部署超时不回复？5 分钟解决 embedded agent 预填充超时（2026 最新版 v2026.4.8 实测有效）关键词：OpenClaw Gemma-4-31b、LM Studio 预填充超时、embedded_run_failover_decision、agents.defaults.llm.idleTimeoutSeconds、本地大模型部署优化在本地运行 31B 参数级大模型（如 Gemma-4-31b）时，很多人都会遇到 OpenClaw 不回复、日志显示 embedded_run_failover_decision + failoverReason: "timeout" 的问题。本文手把手教你 5 分钟彻底解决，适用于 OpenClaw v2026.4.8 及以上版本。1. 问题现象与日志诊断1.1 典型症状OpenClaw 客户端显示“正在思考”但几秒后直接结束，无任何回复。LM Studio 日志显示提示词处理（prefill）已到 8192 tokens 且仍在进行，却突然出现：[INFO] [LM STUDIO SERVER] Client disconnected. Stopping generation...关键错误日志：{"event":"embedded_run_failover_decision","decision":"surface_error","failoverReason":"timeout","timedOut":true}1.2 根本原因分析Gemma-4-31b 是稠密大模型 + Sliding Window Attention（SWA），预填充阶段（prompt processing）耗时极长（8192 tokens 可能需要 30-90 秒）。 OpenClaw Embedded Agent 对 first-token / prefill 阶段存在独立超时保护，默认仅 15 秒左右，导致 timedOut: true 并直接 surface_error。注意：单纯设置 agents.defaults.timeoutSeconds 无效，必须同时配置 llm.idleTimeoutSeconds 才能覆盖 prefill 阶段。2. 解决方案：一键配置超时参数（最推荐）2.1 适用版本OpenClaw v2026.4.8 及以上 已验证有效（早期版本需源码修改）。2.2 步骤详解执行配置命令（推荐方式）：openclaw config set agents.defaults.timeoutSeconds 600 openclaw config set agents.defaults.llm.idleTimeoutSeconds 600完全重启 OpenClaw：pkill -f openclaw openclaw serve验证配置是否生效：openclaw config get agents.defaults配置效果对比表（强烈建议收藏）：配置项默认值（秒）推荐值（秒）效果说明agents.defaults.timeoutSeconds60600整体 Agent 执行超时agents.defaults.llm.idleTimeoutSeconds60600关键：prefill / first-token 空闲超时预填充 8192 tokens 成功率< 30%> 95%Gemma-4-31b 稳定运行3. 进阶优化：让预填充更快、更稳3.1 模型层优化（强烈推荐）优先切换到 Gemma-4-26b-a4b-it（MoE 版本）：激活参数仅 ~4B，预填充速度提升 3-5 倍。质量接近 31b，但显存占用和延迟大幅降低。3.2 LM Studio 参数推荐设置在 LM Studio 模型加载界面设置：GPU Offload：-1（全 offload）Flash Attention：开启Cache Type K/V：q4_0Context Length：先设为 163843.3 完整优化流程图（Mermaid）flowchart TD A[遇到 embedded_run_failover_decision timeout] --> B{检查 OpenClaw 版本} B -->|≥ v2026.4.8| C[执行 config set llm.idleTimeoutSeconds 600] B -->|旧版本| D[考虑源码修改或升级] C --> E[重启 OpenClaw] E --> F[测试长 Prompt] F -->|仍超时| G[切换 Gemma-4-26b-a4b-it MoE 模型] G --> H[优化 LM Studio Flash Attention + KV Cache] H --> I[问题解决]4. 常见问题排查与预防4.1 如果配置后仍无效确认使用的是 Embedded Agent 模式（非普通 LLM 调用）。清空聊天历史或新建 Session 测试短 Prompt。检查 LM Studio 是否在全 GPU Offload + Flash Attention 状态。4.2 预防措施定期执行 openclaw config validate 验证配置。优先使用 MoE / 量化版本模型（Q4_K_M 或更高）。监控 LM Studio 日志中的 Prompt processing progress 进度条。将配置写入 ~/.openclaw/openclaw.json 实现持久化：{ "agents": { "defaults": { "timeoutSeconds": 600, "llm": { "idleTimeoutSeconds": 600 } } } }5. 总结与效果验证通过设置 agents.defaults.llm.idleTimeoutSeconds 600，OpenClaw + Gemma-4-31b 的预填充超时问题已彻底解决。 实测效果：8192 tokens 预填充从“15 秒直接中断”变为“稳定 40-70 秒完成并正常回复”。行动建议：立即执行上面两条 config set 命令。欢迎在评论区贴出你的 OpenClaw 版本 + LM Studio 版本 + 显卡型号，一起交流更多本地大模型优化技巧。标签：OpenClaw 教程、Gemma-4 本地部署、LM Studio 大模型超时、embedded agent 优化、2026 AI 本地化本文基于 OpenClaw v2026.4.8 实测撰写，配置永久有效。如有更新会及时补充。
OpenClaw 报错解决：`GatewayClientRequestError: pairing required`
OpenClaw 报错解决：GatewayClientRequestError: pairing required一、问题现象在使用 OpenClaw 时，gateway 频繁报错，日志如下：01:51:30+00:00 error gateway connect failed: GatewayClientRequestError: pairing required 01:51:30+00:00 warn gateway/ws ... reason=scope-upgrade ... closed before connect 01:51:31+00:00 warn gateway security audit: device access upgrade requested reason=scope-upgrade 01:51:32+00:00 error gateway connect failed: GatewayClientRequestError: pairing required如下图：CLI 执行任何命令（如 openclaw tui、openclaw gateway status、openclaw devices list 等）均提示：gateway connect failed: GatewayClientRequestError: pairing required设备 ID（deviceId）通常为长字符串，例如：1d0aff946ddddf7c3021b4599d7583c753c8fb8d4a07d2f11ff8acf780ea0587二、根本原因这是 OpenClaw 首次配对（Pairing）流程 的正常行为，并非 Bug。OpenClaw 采用 设备级权限控制（scopes）机制。新设备（或新 token）首次连接时，gateway 会要求 pairing 权限进行授权。日志中的 reason=scope-upgrade 表示：当前连接的 scopes 不足（从 operator.read 升级到 operator.admin、operator.pairing 等）。CLI 默认使用低权限 token，导致“鸡生蛋”循环：想批准设备，却连不上 gateway。三、标准解决流程（推荐）步骤 1：在运行 gateway 的同一主机执行openclaw devices list会列出所有 pending 的配对请求，找到对应的 requestId。步骤 2：批准设备# 使用 list 里显示的 requestId openclaw devices approve <requestId> # 或者直接批准最新的请求（最常用） openclaw devices approve --latest步骤 3：重启 gatewayopenclaw gateway restart完成后，CLI 即可正常连接，日志不再刷 pairing required。四、特殊情况处理（CLI 自己也报 pairing required）部分新安装或 Docker 环境下，openclaw devices list 也会报错。此时需要手动提升 scopes：编辑配对配置文件：nano ~/.openclaw/devices/paired.json找到你的 deviceId，将 scopes 数组修改为："scopes": [ "operator.read", "operator.admin", "operator.approvals", "operator.pairing", "operator.talk.secrets", "operator.write" ]（同时检查 tokens.operator.scopes，同步修改）保存后重启：openclaw gateway restart五、Docker 部署专属方案# 进入容器执行（替换容器名） docker exec -e OPENCLAW_GATEWAY_TOKEN=你的token \ -it openclaw-gateway \ openclaw devices list # 批准同理 docker exec -e OPENCLAW_GATEWAY_TOKEN=你的token \ -it openclaw-gateway \ openclaw devices approve --latestToken 位置：宿主机 ~/.openclaw/openclaw.json六、其他快捷命令一键诊断修复：openclaw doctor --fix重启系统服务：systemctl --user restart openclaw-gateway查看完整设备列表：openclaw devices list --all七、总结与预防第一次安装/新增设备 必然会出现 pairing required，属于正常流程。记住 “list → approve → restart” 三步走。生产环境建议提前为管理 token 配置完整 scopes，避免循环授权问题。社区最常见 pairing 问题，99% 按本文操作即可解决。遇到问题？ 执行 openclaw devices list 后把输出（隐藏 requestId 和 deviceId 即可）贴出来，我可以给你精确的一行命令。欢迎收藏本文，OpenClaw 后续版本若有变更，本文会同步更新。标签：OpenClaw、Gateway、Pairing、scope-upgrade、设备授权、运维排查分享：欢迎转发给正在折腾 OpenClaw 的朋友～ 🦞
AMD Ryzen AI Max+ 395 Gemma 4 31B LM Studio 完整 GPU Offload 教程：96GB 统一显存全利用，告别系统 RAM 爆满
AMD Strix Halo Gemma 4 31B LM Studio 完整 GPU Offload 教程：96GB 统一显存全利用，告别系统 RAM 爆满关键词：Gemma 4 31B、LM Studio、AMD Ryzen AI Max+ 395、Strix Halo、GPU Offload、llama.cpp、统一显存、Gemma 4 GGUF在 AMD Ryzen AI Max+ 395（Radeon 8060S iGPU + 96GB 统一显存）上运行 Gemma 4 31B 时，你是否也遇到过以下经典卡顿现象？LM Studio 加载模型后，系统 32GB RAM 瞬间 98% 满；GPU Dedicated 显存只用到 38.7GB，剩余 57GB 完全浪费；GPU 利用率仅 19%，生成速度慢如龟速，Compute 0 偶尔 spike 但整体卡顿。解决前占用98-99% 如下图：解决后占用70%如下图：本文将从问题根因分析 → 完整解决方案 → 进阶优化一步步带你彻底解决，让 Gemma 4 31B（Q4_K_M 量化）100% 跑在 96GB 统一显存上，系统 RAM 占用降至 10GB 以下，生成速度提升 2-3 倍。1. 问题诊断：为什么模型先占满系统 RAM 才进 GPU？1.1 Gemma 4 31B 在 Strix Halo 上的典型加载行为Gemma 4 31B（-it 指令微调版）Q4_K_M 量化后权重约 18GB，16K 上下文 KV Cache 约 15-25GB，总需求远小于 96GB 统一显存。但 LM Studio 默认使用 llama.cpp mmap 机制，会导致：先把整个 GGUF 文件 mmap 到系统 RAM（32GB 先爆）；再逐步 offload 层到 GPU（部分成功）；KV Cache 默认部分留在系统内存。前后对比表格（基于用户实测截图）：项目优化前（默认设置）优化后（本文方案）提升幅度系统 RAM 占用30.9/31.6 GB（98%）≈10-12 GB↓ 70%+Dedicated GPU 显存38.7/96.0 GB65-80 GB+↑ 100%+GPU 利用率19%60-85%↑ 3-4 倍生成速度（tokens/s）8-15 t/s35-55 t/s（16K 上下文）↑ 2.5-3 倍卡顿现象严重（RAM 爆满）几乎无彻底解决1.2 硬件前提确认确保你的配置满足：AMD Ryzen AI Max+ 395 + Radeon 8060SVariable Graphics Memory（VGM）已设为 96GB（AMD Adrenalin → Performance → Tuning → Custom）驱动版本 ≥ 32.0.23033.1002（2026/3/9 及以后）LM Studio 版本 ≥ 0.3.14（推荐最新 0.4.x）2. 方案一：LM Studio GUI 一键全 Offload（最推荐，新手友好）2.1 第一步：彻底配置 AMD 可变显存（必须重启）右键桌面 → AMD Software: Adrenalin Edition；进入 Performance（性能）→ Tuning（调优）→ Variable Graphics Memory；选择 Custom → 96 GB；保存并重启电脑。重启后任务管理器 GPU 页面应显示 Dedicated GPU Memory: 96.0 GB。2.2 第二步：LM Studio 手动加载参数设置卸载当前模型（Unload）；点击模型右侧 齿轮图标 → 勾选 Manually choose model load parameters；按以下参数精确设置：参数名称推荐值说明GPU OffloadMAX / 999强制全层 offloadLimit Model Offload to Dedicated GPU Memory开启防止溢出到系统 RAM（关键！）Keep offload KV cache to GPU memory开启KV Cache 也进 GPUTry mmap / Use memory mapping关闭彻底解决 RAM 爆满根因Keep model in memory关闭避免重复占用Context Length8192 → 16384（逐步调大）Gemma 4 SWA Cache 开销较大BackendVulkan（优先）/ ROCmStrix Halo 最稳后端点击 Load，观察 LM Studio 底部状态栏应显示 “GPU Offload: XXX/XXX layers (Full)”。预期结果：GPU Dedicated 显存快速升至 65GB+，系统 RAM 回落至 10GB 左右，GPU 利用率显著提升。3. 方案二：llama.cpp CLI 终极稳定版（进阶玩家必备）如果你希望获得最大性能且不受 GUI 限制，推荐直接使用 llama.cpp。3.1 下载与命令# Windows 示例（llama-server.exe） llama-server.exe -m gemma-4-31b-it-Q4_K_M.gguf ^ --n-gpu-layers 999 ^ --no-mmap ^ # 关键：关闭 mmap --ctx-size 16384 ^ --flash-attn ^ # 加速 Attention --port 8080Ollama 用户可在 Modelfile 中添加：PARAMETER num_gpu 999 PARAMETER no_mmap true3.2 流程图：完整故障排除流程flowchart TD A[模型加载卡顿？] --> B{系统 RAM 98%？} B -->|是| C[关闭 mmap + Limit to Dedicated] B -->|否| D[GPU 显存 <60GB？] D -->|是| E[GPU Offload 拉满 + Keep KV Cache] C & E --> F[重启 LM Studio / llama-server] F --> G[检查任务管理器 GPU] G --> H{GPU 利用率 >60%?} H -->|是| I[成功！享受 40-55 t/s] H -->|否| J[更新驱动 / 切换 Vulkan → ROCm]4. 性能优化进阶技巧4.1 量化与上下文选择推荐量化：Q4_K_M（速度+质量最佳）或 Q5_K_M避免：Q8_0（显存占用过大）Gemma 4 31B SWA KV Cache 固定开销 ≈3.6GB，建议日常使用 16K-32K 上下文，128K 仅用于文档分析。4.2 额外加速参数（llama.cpp）--flash-attn --temp 0.8 --top-p 0.95 --repeat-penalty 1.14.3 常见问题排查表问题描述解决方案加载后仍提示 OOM确认 VGM 已设 96GB + 重启GPU 利用率始终 <30%切换 Backend 为 Vulkan上下文超过 32K 就崩溃先用小上下文验证全 Offload 成功LM Studio 版本过旧升级至 0.4.x 最新版5. 总结与预期效果通过关闭 mmap + 强制 Dedicated GPU Offload，你的 AMD Ryzen AI Max+ 395 + 96GB 统一显存将真正发挥潜力：Gemma 4 31B 实现全 GPU 运行，系统 RAM 压力几乎为零；生成速度从 10 t/s 提升至 40+ t/s，复杂 Agent、多模态任务流畅运行；完全离线、私密、本地最强开源大模型体验。行动建议：先按方案一操作 5 分钟验证效果。如果仍有问题，欢迎在评论区贴出加载后的任务管理器 GPU 截图 + LM Studio 状态栏，我将为你一对一诊断。版权声明：本文基于真实硬件测试与社区方案整理，欢迎转载但请保留原文链接。 标签：#Gemma4 #StrixHalo #LMStudio #GPUOffload #本地大模型 #AMD统一显存
在中国 WSL Ubuntu 中完美部署 OpenClaw：Telegram 代理 + Systemd 服务 + 自动重启完整教程（2026 最新）
在中国 WSL Ubuntu 中完美部署 OpenClaw：Telegram 代理 + Systemd 服务 + 自动重启完整教程（2026 最新）关键词：OpenClaw 部署、WSL Ubuntu 安装 OpenClaw、OpenClaw Telegram 代理、中国网络墙、openclaw gateway 服务、WSL systemd 启用、OpenClaw 2026.4.2OpenClaw 作为新一代本地 AI 助手，在国内部署时经常遭遇 Telegram Bot API 被墙导致的 telegram/network fetch fallback: DNS-resolved IP unreachable 错误。同时，在 Windows WSL Ubuntu 环境下运行 openclaw gateway 时，手动 kill 进程、重启繁琐，且官方 gateway install 命令常常失败。本文将完整整合在中国环境下只为 OpenClaw 设置代理、在 WSL 中启用 systemd 实现开机自启、解决服务安装失败等所有实用方案，一次性部署后永久无痛使用。无论你是使用原生 CLI 还是追求生产级稳定，本教程都适用。1. 问题背景与核心挑战1.1 OpenClaw 在中国网络下的典型痛点Telegram API（api.telegram.org）被墙，导致 UND_ERR_CONNECT_TIMEOUT 错误。代理必须只针对 OpenClaw，不能污染系统其他程序。WSL 默认未启用 systemd，导致 openclaw gateway install 报错：“Unit file openclaw-gateway.service does not exist”。每次重启都要手动 kill 进程，体验极差。1.2 为什么需要“只为 OpenClaw 设置代理”全局代理会影响国内模型（如 DeepSeek、Kimi）的直连速度。正确做法是通过环境变量 + 配置文件实现隔离代理，同时开启代理的“远程 DNS 解析”以彻底解决 DNS 泄漏。部署方式对比表（推荐阅读前快速了解）：部署方式稳定性开机自启代理隔离性适用场景推荐指数原生 CLI + 手动 kill★☆☆☆☆❌★★★★☆临时测试2/5Tmux 后台★★☆☆☆❌★★★★☆不想折腾 systemd3/5Systemd 用户/系统服务★★★★★✅★★★★★生产级推荐5/5Docker 容器★★★★☆✅★★★★★喜欢容器化管理4.5/52. 环境准备：WSL Ubuntu + Systemd 启用2.1 确认当前环境# 查看 OpenClaw 版本与路径 openclaw --version which openclaw（本文以 2026.4.2 版本为例，路径通常为 /usr/bin/openclaw 或 /root/.npm-global/bin/openclaw）2.2 关键一步：启用 WSL systemd（解决 install 失败根源）在 WSL Ubuntu 终端 执行：sudo tee /etc/wsl.conf > /dev/null <<'EOF' [boot] systemd=true EOF从 Windows PowerShell（非 WSL 内） 重启 WSL：wsl --shutdown重新进入 WSL 验证：systemctl --user status看到 “State: running” 即成功。3. 只为 OpenClaw 配置代理（核心解决 Telegram 报错）3.1 Telegram 通道专用代理（最推荐）编辑配置文件：nano ~/.openclaw/openclaw.json在 channels.telegram 节点下添加 proxy：{ "channels": { "telegram": { "botToken": "你的-bot-token", "proxy": "http://192.168.10.86:11808", } } }提示：如果你使用 SOCKS5 代理，改为 "proxy": "socks5://192.168.10.86:11808"3.2 全局环境变量隔离代理（所有通道生效）创建 .env 文件：cat > ~/.openclaw/.env << 'EOF' HTTP_PROXY=http://192.168.10.86:11808 HTTPS_PROXY=http://192.168.10.86:11808 NO_PROXY=localhost,127.0.0.1,::1 EOF代理设置流程图（Mermaid）：flowchart TD A[启动 OpenClaw gateway] --> B{检查配置文件?} B -->|有 proxy| C[Telegram 专用代理生效] B -->|无 proxy| D[读取 .env 环境变量] D --> E[HTTP/HTTPS_PROXY 生效] E --> F[NO_PROXY 排除本地服务] C & F --> G[Telegram API 连通 + 国内模型直连]4. Systemd 服务管理：告别手动 kill4.1 为什么官方 install 命令失败OpenClaw 2026.x 在 root 用户 + WSL 环境下，服务文件尚未创建时就执行 systemctl enable，导致循环报错。即使加 --force 也无效。4.2 手动创建 Systemd 服务（永久方案）4.2.1 用户级服务（推荐普通用户）mkdir -p ~/.config/systemd/user cat > ~/.config/systemd/user/openclaw-gateway.service << 'EOF' [Unit] Description=OpenClaw Gateway After=network-online.target Wants=network-online.target [Service] Type=simple WorkingDirectory=/root/.openclaw ExecStart=/usr/bin/openclaw gateway Restart=always RestartSec=5 EnvironmentFile=/root/.openclaw/.env [Install] WantedBy=default.target EOF4.2.2 系统级服务（root 用户更稳定）sudo cat > /etc/systemd/system/openclaw-gateway.service << 'EOF' [Unit] Description=OpenClaw Gateway After=network-online.target Wants=network-online.target [Service] Type=simple User=root WorkingDirectory=/root/.openclaw ExecStart=/usr/bin/openclaw gateway Restart=always RestartSec=5 EnvironmentFile=/root/.openclaw/.env [Install] WantedBy=multi-user.target EOF4.3 启动与日常管理命令# 加载服务 systemctl --user daemon-reload # 用户级 # 或 sudo systemctl daemon-reload # 系统级 # 启用并立即启动 systemctl --user enable --now openclaw-gateway.service # 日常操作（再也不用 kill） openclaw gateway restart systemctl --user restart openclaw-gateway.service systemctl --user status openclaw-gateway.service --no-pager # 查看实时日志 openclaw logs --follow # 或 journalctl --user -u openclaw-gateway -f5. 验证、测试与故障排除5.1 完整验证流程重启服务后等待 10 秒。执行 openclaw channels status --probe 查看 Telegram 通道状态。在 Telegram 中向 Bot 发送任意消息，确认响应正常。检查日志中不再出现 telegram/network 相关错误。5.2 常见问题对照表问题现象可能原因解决方法仍报 UND_ERR_CONNECT_TIMEOUT代理未开启远程 DNS在 Clash 等软件开启“远程 DNS 解析”服务启动后立即退出ExecStart 路径错误用 which openclaw 确认路径Telegram 能连但国内模型慢NO_PROXY 未配置在 .env 中补充国内域名WSL 重启后服务未启动未启用 systemd重新执行 wsl.conf + shutdown6. 进阶技巧与最佳实践6.1 Docker 方式（容器化备选）如果你更喜欢隔离性，可直接使用 Docker + 环境变量（与本文代理配置完全兼容）：# docker-compose.yml 片段 environment: - HTTP_PROXY=http://192.168.10.86:11808 - HTTPS_PROXY=http://192.168.10.86:118086.2 Tmux 极简备用方案（不想用 systemd 时）sudo apt install tmux -y tmux new -s openclaw -d "openclaw gateway" tmux attach -t openclaw # 进入管理6.3 安全与性能建议代理地址使用局域网 IP（192.168.x.x），避免 127.0.0.1 在容器/WSL 中的解析问题。定期 openclaw gateway update 保持最新版本。将 .env 和 openclaw.json 加入 Git 私有仓库实现配置版本化。结语 通过本文的 Systemd + 隔离代理 + WSL systemd 启用 组合，你已拥有一个在 Windows 环境下稳定运行、自动重启、只代理必要流量的 OpenClaw 生产环境。部署一次，终身受益。有任何新版本或特殊环境问题，欢迎在评论区留言，我会持续更新本教程。
极致压榨 96G 显存：Qwen3.5 122B (MoE) 大模型本地部署优化指南
极致压榨 96G 显存：Qwen3.5 122B (MoE) 大模型本地部署优化指南在本地运行超大规模模型（如 Qwen3.5 122B A10B）时，硬件性能的充分发挥往往取决于细微的参数配置。本文将针对 AMD 395max（128G 内存，其中 96G 分配为显存）这一典型硬件环境，分享如何解决主机内存溢出（OOM）、显存利用率不足以及模型崩溃等核心痛点。一、 环境挑战：为什么我的显存“吃不满”？在初始配置下，许多用户发现 GPU 显存仅占用不到 70GB，而主机内存却瞬间飙升至 95% 以上甚至导致系统挂掉。对于 Qwen3.5 122B 这种 MoE（混合专家）架构模型，其核心难点在于：参数量巨大： 总参数 122B，但每 token 仅激活 10B。专家权重分配： 默认情况下，llama.cpp 可能会将海量的专家权重留在主机内存中以防止显存溢出。加载逻辑： 若配置不当，系统会先尝试将模型全部塞入 RAM，导致加载过程中断。二、 核心优化步骤：从内存向显存的“大搬家”1. 彻底解决加载时的 RAM 满载问题如果你发现加载模型时内存先冲向 100% 然后才开始加载 GPU，请务必修改以下两项：开启 尝试 mmap() (Memory Mapping)： 允许模型从硬盘直接映射，避免一次性挤占主机内存。关闭 保持模型在内存中 (mlock)： 必须取消勾选！否则系统会强行将模型“锁死”在物理内存里，导致 32G 级别的主机内存直接打满。2. 强制提升 GPU 卸载率GPU 卸载 (GPU Offload)： 将层数设置为该模型支持的最大值。对于 Qwen3.5 122B 而言，总层数为 48 层，因此请直接填入 48。将 KV 缓存加载到 GPU： 必须打勾。KV Cache 是随着对话长度增长而迅速消耗资源的部分，将其移至 GPU 是降低主机内存压力最有效的一招。3. MoE 架构的特殊配置：避开“专家数量”陷阱在 Advanced 设置中，可能会看到“专家数量”或 expert_used_count 的选项：千万不要填 256： 虽然模型总共有 256 个专家，但每一步仅激活 8 个路由专家 + 1 个共享专家。正确做法： 保持为空或填入 8。强行填入 256 会导致计算图爆炸，触发 GGML_ASSERT 崩溃。三、 深度调优：平衡稳定性与性能1. 后端选择：Vulkan vs ROCm对于 AMD 硬件，ROCm 通常对统一内存架构的专家卸载支持更激进，能更好地利用 96G 显存。如果 Vulkan 表现保守（显存卡在 70G），建议切换至 ROCm v2.8.0 进行测试。2. 上下文长度限制不要盲目追求超长上下文。在测试阶段，建议将上下文长度 (Context Length) 先设定为 8192 或 16384。在确认稳定后，再根据显存剩余空间逐步向上调优。如果初始值设为 524,288 等极大值，会直接导致内存池空间不足而崩溃。3. 辅助参数微调CPU 线程池大小： 调小至 8~16，减少 CPU 侧不必要的内存开销。Unified KV Cache： 如果遇到不稳定的情况，可以尝试取消勾选，有时这能释放更多空间给专家权重。四、 总结：70GB 显存是正常的吗？从日志分析看，Q4_K_M 量化版本的 Qwen3.5 122B 完整权重大小约为 70.35GB。当你看到 GPU 占用稳定在 70GB+ 且显示 “offloaded 49/49 layers” 时，意味着模型权重已经完全载入显存。此时，剩下的 20GB+ 显存空间将由 KV Cache（取决于上下文长度）和计算缓冲区占用。通过上述优化，你可以在 32G 主机内存的机器上平稳运行这一百亿级参数的巨兽，并获得流畅的推理体验。技术提示： 如果 UI 界面依然无法满足你的需求，建议使用纯命令行版的 llama.cpp，配合 -ngl 999 --n-cpu-moe 0 参数强制所有专家权重上云（GPU）。
10分钟跑通 OpenClaw：本地部署 + 模型配置完整教程（普通用户版）
10分钟跑通 OpenClaw：本地部署 + 模型配置完整教程（普通用户版）很多人看完 OpenClaw 的介绍后，可能会觉得“怎么跑不起来？”这篇文章的目标是：在最短的时间内，使用最简单的方法跑通 OpenClaw。一、环境准备（3分钟）1）基础要求首先，确保你有以下基础工具：- 操作系统：Windows / macOS / Linux（支持多平台） - Python 3.10 以上版本 - Git（推荐安装）2）安装 OpenClaw打开终端（命令行）并输入以下命令来安装 OpenClaw：pip install openclaw这一步会自动下载并安装所需的依赖项。如果没有安装 Python，可以去 Python 官网 下载。二、模型配置（关键步骤）OpenClaw 本身不带模型，你需要配置模型（如 Ollama 或者 OpenAI API）。这里我们以使用 Ollama 本地模型 为例，步骤非常简单。1）安装 Ollama如果你还没有安装 Ollama，可以去 Ollama 官网 下载适合你系统的版本，安装后启动它。2）拉取模型打开命令行，运行以下命令来下载需要的模型：ollama pull qwen3:32b3）启动 Ollama 服务模型下载完成后，启动 Ollama 服务：ollama serve服务启动后，它会监听 11434 端口，这时模型已经准备好，可以在本地使用了。4）配置 OpenClaw接下来，你需要配置 OpenClaw 使用 Ollama 模型。找到 OpenClaw 配置文件，或者在代码中创建一个名为 config.toml 的文件，内容如下：[llm] api_type = "ollama" model = "qwen3:32b" base_url = "http://localhost:11434/v1" api_key = "ollama"注意：如果你使用的是 OpenAI 模型或其他服务，只需要修改 base_url 和 api_key 即可。三、创建第一个 Agent（核心操作）现在，我们来创建第一个 Agent，步骤非常简单。1）创建 Identity（角色定义）在项目根目录下新建一个 IDENTITY.md 文件，定义 Agent 的角色和行为。示例内容：你是一个专业的AI助手，回答要简洁、准确、有条理。2）运行 Agent在命令行中，进入 OpenClaw 的安装目录，运行以下命令启动 Agent：python main.py3）输入测试现在你可以在终端中输入一些测试问题，看看 Agent 的反应：请解释什么是AI Agent如果一切正常，你将看到类似如下的响应：AI Agent 是一种能自主决策并执行任务的人工智能系统...四、进阶：加入 Tool（可选）如果你想让 Agent 更智能，可以添加外部工具来增强它的能力。例如，我们可以添加一个简单的 时间查询工具：def get_time(): return "当前时间是：2026-03-30"然后，在配置文件中注册该工具，接着执行命令来调用它。五、常见问题及解决方法（必看）尽管我们已经做了很多简化，但仍然可能遇到一些常见问题。以下是解决方案。❌ 问题1：无法连接到模型错误信息：Connection refused解决方法：确保 Ollama 已启动并且没有错误。检查 base_url 配置是否正确。❌ 问题2：模型没有下载错误信息：model not found解决方法：运行命令：ollama list确保模型已正确下载。如果没有，重新拉取模型。❌ 问题3：没有返回任何结果解决方法：检查 IDENTITY.md 是否有内容。确保模型正常启动并能够正常响应。六、总结通过这篇文章，你已经掌握了如何：安装 OpenClaw 并配置模型创建并运行第一个 Agent解决一些常见的配置问题