OpenClaude 本地 Agent 实战手册：基于 Ollama 的本地模型配置、健康诊断与日常使用指南

OpenClaude 本地 Agent 实战手册基于 Ollama 的本地模型配置、健康诊断与日常使用指南【免费下载链接】openclauderuns anywhere. uses anything项目地址: https://gitcode.com/GitHub_Trending/op/openclaude本指南以仓库根目录 PLAYBOOK.md 为主体骨架结合 package.json 中的脚本定义与scripts/目录下的 provider 启动、推荐、诊断源码系统讲解 OpenClaude 如何以本地模型Ollama驱动完整的 CLI Agent 循环读写文件、执行终端命令、辅助编码并覆盖日常启动、一次性初始化、健康检查、故障排查、模型推荐与安全操作规范。读完本文你将掌握一套可直接复制执行的本地 Agent 工作流并理解其背后的 provider profile 机制与运行时自检原理。1. 你拥有什么OpenClaude 的本地 Agent 能力栈OpenClaude 是一个可以运行在任何环境、接入任意 LLM 的编码 Agent CLI。当它搭配本地模型Ollama使用时你获得的是这样一套能力完整的 Agent 主循环能够读写文件、执行终端命令、完成编码类工作流而不依赖云端账户本地 Provider 档案系统通过profile:init初始化、dev:profile启动将模型 端点 密钥打包成一个可持久化的 profile 文件运行时自检与报告doctor:runtime做人类可读的健康检查doctor:report输出可复现的 JSON 诊断快照默认本地模型配置当前档案默认指向llama3.1:8b。从源码看这套能力分别由三个脚本承担能力脚本核心职责档案初始化scripts/provider-bootstrap.ts解析--provider/--model/--base-url/--api-key/--goal构建环境变量并写盘模型推荐scripts/provider-recommend.ts按目标latency/balanced/coding对已安装模型打分排序可选实测基准档案启动scripts/provider-launch.ts加载档案、拼装启动环境、先跑 doctor 再构建并拉起 CLI运行时诊断scripts/system-check.ts检查 Node/Bun/构建产物/Provider 可达性/生成就绪度等2. 每日启动快速路径在项目根目录直接运行bun run dev:profile需要快速切换预设时# low latency preset低延迟预设 bun run dev:fast # better coding quality preset更优编码质量预设 bun run dev:code如果一切健康OpenClaude 会直接启动。dev:fast与dev:code在 package.json 中的定义值得拆解dev:fast: bun run profile:fast bun run dev:ollama:fast, dev:code: bun run profile:code bun run dev:profile即dev:fast先写入llama3.2:3b的 Ollama 档案再用--fast --bare启动dev:code先写入qwen2.5-coder:7b档案再按档案正常启动。--fast标志的实质作用见 scripts/provider-launch.ts 的applyFastFlags它会为子进程注入CLAUDE_CODE_SIMPLE1、CLAUDE_CODE_DISABLE_THINKING1、DISABLE_INTERLEAVED_THINKING1、DISABLE_AUTO_COMPACT1、CLAUDE_CODE_DISABLE_AUTO_MEMORY1、CLAUDE_CODE_DISABLE_BACKGROUND_TASKS1从而以牺牲部分能力换取更低的响应延迟。启动链路内部发生了什么dev:profile对应bun run scripts/provider-launch.ts其主流程scripts/provider-launch.ts依次是解析命令行选项--fast、--goal、profile 名、透传 CLI 参数loadProfileFile()读取已持久化的档案未指定 provider 时走auto逻辑有档案用档案本地有 Ollama 则selectAutoProfile否则回退到 openai校验各 provider 的凭据Ollama 无密钥要求OpenAI/Gemini/Mistral/Codex 缺凭据直接报错退出做到 fail fast先运行bun run scripts/system-check.ts做运行时 doctor失败则拒绝启动bun run build构建产物以node bin/openclaude启动 CLI并透传额外参数。这意味着dev:profile不是简单启动而是自检 → 构建 → 启动的完整安全链路。3. 一次性初始化按需执行3.1 初始化本地档案bun run profile:init -- --provider ollama --model llama3.1:8b也可以让 OpenClaude 根据目标自动推荐最合适的本地模型bun run profile:init -- --provider ollama --goal coding保存前先预览推荐结果bun run profile:recommend -- --goal coding --benchmarkprofile:init实际调用 scripts/provider-bootstrap.ts它解析--provideropenai/ollama/codex/gemini/mistral/atomic-chat缺省为 auto、--model、--base-url、--api-key、--goal对 Ollama 会先通过listOllamaModels探测本地已安装模型再调用recommendOllamaModel选模型最后由buildOllamaProfileEnv构造环境变量并saveProfileFile写盘最后提示Next: bun run dev:profile。以--goal coding为例推荐器src/utils/providerRecommendation.ts会优先命中名称/家族中包含coder、codellama、codegemma、codestral、qwen2.5-coder等编码提示词的模型coding 目标下加分最高 24 分再叠加参数规模与量化档位得分排序。3.2 确认档案文件Get-Content .\.openclaude-profile.json关于档案的落盘位置src/utils/providerProfile.ts 定义了PROFILE_FILE_NAME .openclaude-profile.json与两条读取路径新档案默认写入用户配置目录getClaudeConfigHomeDir()而项目工作区下的.openclaude-profile.json被视为 legacy 兼容路径。写盘时使用mode: 0o600并chmodSync(filePath, 0o600)确保密钥类环境变量仅当前用户可读。因此Get-Content .\.openclaude-profile.json通常适用于旧版遗留档案新档案请到用户配置目录查看。一个典型的 Ollama 档案内容形如{ profile: ollama, env: { OPENAI_BASE_URL: http://localhost:11434/v1, OPENAI_MODEL: llama3.1:8b }, createdAt: 2026-01-01T00:00:00.000Z }3.3 校验环境bun run doctor:runtime若所有检查项 PASS 并输出Runtime checks completed successfully.说明环境就绪。4. 健康与诊断4.1 人类可读检查bun run doctor:runtime4.2 JSON 诊断适合自动化/日志采集bun run doctor:runtime:json注意控制台 JSON 输出中的env字段会被脱敏为占位说明[redacted in console JSON output; use --out-file for the full report]见 scripts/system-check.ts避免密钥泄入终端日志。4.3 持久化运行时报告bun run doctor:report报告输出路径reports/doctor-runtime.json。该报告包含时间戳、cwd、通过/失败统计、脱敏后的环境摘要仅记录密钥是否已设置不记录明文以及逐项检查结果是向他人求助或归档 CI 制品时的标准快照。doctor:report对应的脚本为bun run scripts/system-check.ts --out reports/doctor-runtime.json。完整的检查清单scripts/system-check.ts包括检查项说明Node.js 版本要求满足MIN_NODE_ENGINE_RANGE见 package.json 的enginesNode 22.0.0Bun runtime非强制仅报告Build artifacts校验dist/cli.mjs是否存在缺失则提示先bun run buildSandbox runtime检查沙箱运行时的 stub/真实状态与 fail-closed 行为Memory guardAuto-compact 开关、消息数硬上限、内存预算默认 1536MBWeb search backend根据WEB_SEARCH_PROVIDER校验各搜索后端凭据Provider env按CLAUDE_CODE_USE_*标志分支检查模型/端点/密钥Provider reachability对{baseUrl}/models或 Codex 的/responses发起 4 秒超时探测401/403 视为可达Provider generation readiness本地 Ollama 会实际发一次最小生成请求num_predict: 8的 Reply with OK.Ollama processor mode运行ollama ps判断 CPU/GPU 模式4.4 加固检查# 实用检查smoke runtime doctor bun run hardening:check # 严格检查额外包含 typecheck bun run hardening:stricthardening:check等价于bun run smoke bun run doctor:runtime而smoke是bun run build node dist/cli.mjs --version即先验证构建与入口可用再验证运行时环境。5. Provider 模式5.1 本地模式Ollamabun run profile:init -- --provider ollama --model llama3.1:8b bun run dev:profile预期行为无需任何 API KeyOPENAI_BASE_URL应为http://localhost:11434/v1。这个端点是getOllamaChatBaseUrl生成的它把OLLAMA_BASE_URL或默认值http://localhost:11434src/utils/providerDiscovery.ts归一化后拼上/v1作为 OpenAI 兼容聊天端点探测与基准则走/api/tags、/api/chat原生端点。doctor 对本地地址做特殊放行——当 base URL 属于本地如 Ollama/Atomic Chat/LM Studio且无凭据时密钥检查直接 PASS。5.2 OpenAI 模式bun run profile:init -- --provider openai --api-key sk-... --model gpt-4o bun run dev:profile预期行为必须提供真实 API Key占位值会快速失败fail fast。buildOpenAIProfileEnvsrc/utils/providerProfile.ts会解析OPENAI_API_KEYS/OPENAI_API_KEY若凭据池中包含占位符SUA_CHAVE则直接返回 null 拒绝保存resolveOpenAICredentialEnvState的invalid状态也会被 doctor 标红。同时模型默认值与--goal绑定见 src/utils/providerRecommendation.tslatency → gpt-4o-minicoding/balanced → gpt-5.5。6. 故障排查矩阵6.1Script not found dev原因在错误的目录下执行了命令。修复cd PATH bun run dev:profile即在包含 package.json 的仓库根目录执行。6.2ollama: term not recognized原因Ollama 未安装或当前终端的 PATH 未加载。修复安装 OllamaWindows 可通过winget install Ollama.Ollama然后新开一个终端验证ollama --version6.3Provider reachability failed针对 localhost原因Ollama 服务未启动。修复先启动服务ollama serve然后在另一个终端重新自检bun run doctor:runtime从源码看checkBaseUrlReachabilityscripts/system-check.ts对 base URL 的/models端点做 4 秒超时 GET 探测Ollama 未运行时该请求必然失败并报Failed to reach ...。6.4Missing key for non-local provider URL原因OPENAI_BASE_URL指向了远程端点但没有配置密钥。doctor 的判定逻辑是仅当无凭据且base URL 非本地时才 FAILscripts/system-check.ts。修复为 ollama 重新初始化档案bun run profile:init -- --provider ollama --model llama3.1:8b或者按目标自动挑选本地 Ollama 档案bun run profile:init -- --provider ollama --goal balanced6.5 占位 KeyYOUR_KEY报错原因使用了占位符而非真实密钥。修复OpenAI使用真实 KeyOllama无需 Key保持 localhost base URL 即可。doctor 会检测占位凭据SUA_CHAVE等并直接 FAIL避免带病启动。7. 推荐的本地模型场景模型说明快速/通用llama3.1:8b默认档案模型延迟与质量均衡更优编码质量硬件允许时qwen2.5-coder:14b编码系模型质量更高但更吃资源低资源回退更小的 instruct 模型如llama3.2:3b等紧凑指令模型快速切换模型bun run profile:init -- --provider ollama --model qwen2.5-coder:14b bun run dev:profile已配置的预设快捷键对应 package.json 中profile:fast与profile:codebun run profile:fast # llama3.2:3b bun run profile:code # qwen2.5-coder:7b基于目标的本地模型自动选择bun run profile:init -- --provider ollama --goal latency bun run profile:init -- --provider ollama --goal balanced bun run profile:init -- --provider ollama --goal coding推荐机制的评分原理推荐并非随机或硬编码。rankOllamaModelssrc/utils/providerRecommendation.ts会综合以下维度打分排序模型族提示词coder/codegemma/qwen2.5-coder等编码系在 coding 目标下 24 分llama/qwen/mistral/gemma等通用系在 balanced 下 8 分参数规模档位latency 目标偏好 ≤4B 小模型32coding 目标偏好 7B–14B24与 14B–34B28balanced 以 14B 为最优中心量化档位Q4/Q5/Q8 分别计分Q4 在 latency 目标下更受青睐排除项embed/rerank/whisper等非聊天模型扣 40 分并被过滤vision 模型扣 2 分。加--benchmark时scripts/provider-recommend.ts会对得分最高的前 3 个可用聊天模型各发一次最小生成请求实测延迟benchmarkOllamaModel使用temperature: 0, num_predict: 8的 Reply with OK.20 秒超时见 src/utils/providerDiscovery.ts再用applyBenchmarkLatency按目标除数latency 120 / coding 500 / balanced 240折算延迟惩罚分已实测的模型排在未实测之前。profile:auto的定位注意profile:auto即bun run provider-recommend.ts --apply是可用 provider 的全局择优器并非仅限本地的命令——当探测不到本地 Ollama 时它会转而推荐 OpenAI 模式。想始终留在本地模型请显式加--provider ollama。8. 实用 Prompt 手册可直接复制8.1 代码理解Map this repository architecture and explain the execution flow from entrypoint to tool invocation.Find the top 5 risky modules and explain why.8.2 重构Refactor this module for clarity without behavior change, then run checks and summarize diff impact.Extract shared logic from duplicated functions and add minimal tests.8.3 调试Reproduce the failure, identify root cause, implement fix, and validate with commands.Trace this error path and list likely failure points with confidence levels.8.4 可靠性Add runtime guardrails and fail-fast messages for invalid provider env vars.Create a diagnostic command that outputs JSON report for CI artifacts.8.5 审查模式Do a code review of unstaged changes, prioritize bugs/regressions, and suggest concrete patches.这些 Prompt 的设计与仓库中的自检理念一致强调可复现、可验证、fail fast与doctor:report生成可复现快照、启动前强制自检的工程哲学同源。9. 安全操作规则调试 provider 问题之前先运行doctor:runtime优先使用dev:profile避免手动改环境变量启动器会先自检再注入档案环境降低手滑风险旧的 workspace 级.openclaude-profile.json保持本地不动新档案默认写入用户配置目录求助前先doctor:report让对方拿到可复现的运行时快照。此外从源码实现看还有三点隐性保障档案写入权限为0600仅当前用户可读写console 的 JSON 诊断自动脱敏密钥doctor 报告中的环境摘要只记录密钥是否已设置的布尔值而非明文serializeSafeEnvSummaryscripts/system-check.ts。10. 快速恢复清单出问题时按顺序执行bun run doctor:runtime bun run doctor:report bun run smoke如果回答非常慢检查处理器模式ollama ps若PROCESSOR列显示CPU说明配置有效但大模型在 CPU 下延迟会更高doctor 的checkOllamaProcessorMode同样会检测并提示这一点scripts/system-check.ts。如果本地模型模式整体失败ollama --version ollama serve bun run doctor:runtime bun run dev:profile11. 命令速查表# profile bun run profile:init -- --provider ollama --model llama3.1:8b bun run profile:init -- --provider openai --api-key sk-... --model gpt-4o # launch bun run dev:profile bun run dev:ollama bun run dev:openai # diagnostics bun run doctor:runtime bun run doctor:runtime:json bun run doctor:report # quality bun run smoke bun run hardening:check bun run hardening:strict其中dev:ollama与dev:openai分别是bun run scripts/provider-launch.ts ollama|openai的快捷方式适合明确指定 provider 的场景dev:profile则优先复用已保存档案。12. 成功标准以下三条全部满足即视为配置健康bun run doctor:runtime的 provider 与 reachability 检查全部通过bun run dev:profile正常打开 CLIUI 中显示的模型与你选定的档案模型一致。延伸阅读本文涉及的实现细节可继续在仓库中深入档案读写与路径策略src/utils/providerProfile.ts本地模型推荐评分算法src/utils/providerRecommendation.tsOllama 探测/基准实现src/utils/providerDiscovery.ts启动链路scripts/provider-launch.ts、scripts/provider-bootstrap.ts、scripts/provider-recommend.ts运行时 doctor 检查项scripts/system-check.ts脚本总览package.jsonscripts字段【免费下载链接】openclauderuns anywhere. uses anything项目地址: https://gitcode.com/GitHub_Trending/op/openclaude创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考