简介：本文面向开发者与运维人员，详解在Windows平台以Claude Code为例搭建AI Agent在线与本地双模式运行环境。读者将掌握Node.js运行时安装、Ollama本地推理服务部署、模型下载与配置、环境变量设定及双模式切换等核心操作，并获得故障排查与运维优化建议，快速构建安全稳定的AI Agent工作环境。
本文旨在帮助技术人员在Windows 10或Windows 11环境下搭建一套AI Agent运行环境，该环境同时支持在线调用云端模型接口与本地模型推理两种工作模式。在线模式依赖云端接口，适合对响应质量要求高且网络稳定的场景；本地模式通过Ollama完成推理，适合数据敏感、离线运行或需控制成本的场景。
本文面向具备基础开发经验的技术人员，包括后端开发者、运维工程师、技术负责人及需快速搭建原型的研究人员。
部署核心对象为命令行形态的AI Agent客户端——本文以Anthropic官方的Claude Code为示例。客户端通过统一交互界面调用不同模型服务，需要完成运行时环境、客户端本体、本地推理服务及模型文件的准备。其中Ollama本地推理服务为可选项，仅在本地模式下部署。
建议读者先明确场景：若主要依赖在线接口，只需安装运行时与客户端；若需离线或内网使用，则额外部署Ollama并下载模型。本文将分别说明两种路径。
在线模式适用于开发调试、公开信息处理等场景，优点是模型能力强、无需高配硬件，缺点是依赖网络且数据外传。
本地模式适用于内部数据处理、敏感信息分析、离线运行等场景，优点是数据不出本机、无外部费用，缺点是对硬件有要求且模型能力受限。
混合部署则在同一客户端同时配置在线接口与本地服务，使用者根据任务灵活切换。具体操作为：完成全部组件部署后，通过环境变量ANTHROPIC_BASE_URL指向Ollama本地服务地址http://127.0.0.1:11434/v1即可将请求路由至本地；切换回在线模式时将该变量清空或注释即可。这种方案兼顾能力与隐私，适合大多数企业内部研发场景。
本文方案适用Windows 10/11，命令行使用PowerShell。硬件要求如下：
| 使用模式 | 最低配置 | 推荐配置 |
|---|---|---|
| 仅在线模式 | 4核CPU、8GB内存 | 8核CPU、16GB内存 |
| 本地模式（小模型） | 8核CPU、16GB内存 | 16核CPU、32GB内存 |
| 本地模式（大模型） | 16核CPU、32GB内存或8GB以上显存独显 | 16GB以上显存独显 |
部署前请逐项确认：Node.js不低于18.0（推荐20 LTS），执行node --version验证；npm 10.x以上，执行npm --version验证；Windows需安装Git，执行git --version验证。
若尚未安装Node.js，请访问官方网站下载LTS版Windows安装包。若非必要，建议以普通用户权限运行安装程序以遵循最小权限原则；若必须以管理员身份安装，请注意安装路径不含中文或空格，所有选项保持默认，完成后关闭并重开PowerShell使环境变量生效。
若git --version无返回，请从Git官网下载Windows版，选择默认组件安装后同样重开终端。
通过npm全局安装Claude Code：
npm install -g @anthropic-ai/claude-code
安装完成后执行claude --version验证。若提示命令不存在，请检查全局安装目录是否已加入系统PATH。
安全提醒：全局安装时请确保npm源可信，并定期审计全局包。
在PowerShell中输入claude启动，首次进入配置引导。在线模式需输入访问密钥，建议通过环境变量注入避免明文输入；本地模式需配置后端指向Ollama。
具体步骤：设置环境变量ANTHROPIC_BASE_URL=http://127.0.0.1:11434/v1，同时确保OLLAMA_HOST=127.0.0.1:11434已生效。在PowerShell中临时设置：$env:ANTHROPIC_BASE_URL = "http://127.0.0.1:11434/v1"；永久生效需通过”系统属性—高级—环境变量”添加。切换回在线模式时，清除该变量或设置为空值并重启终端即可。
Ollama本身不含模型，需单独下载。推荐使用当前官方维护的模型标签：
ollama pull llama3:8b-instruct-fp16
模型选择建议：
| 硬件条件 | 推荐模型 | 说明 |
|---|---|---|
| 独立显卡显存8GB以上 | llama3:13b | 推理质量较高 |
| 纯CPU或低配环境 | llama3:8b | 资源占用适中 |
| 极低配或测试环境 | phi3:mini | 占用资源最少 |
下载大模型可能达数GB，请预留空间并确认开源许可协议是否允许商用。
完成部署后输入claude启动，验证要点包括：客户端显示欢迎信息；在线模式发送测试消息正常返回；本地模式确认连接Ollama并合理时间响应；Ollama日志无异常。
上线验证清单：
| 验证项 | 预期结果 | 异常处理 |
|---|---|---|
| 运行时版本 | 符合要求 | 卸载旧版重装LTS |
| 客户端版本 | 正确显示 | 检查PATH |
| 本地服务状态 | 11434端口可访问 | 检查进程与端口 |
| 在线模式响应 | 正常返回 | 检查网络与密钥 |
| 本地模式响应 | 预期时间内返回 | 检查模型下载 |
| 模型与配置已备份 | 确认完成 | 先备份再上线 |
建议从简单任务逐步增加复杂度。
客户端命令无法识别：全局目录未加入PATH或终端未刷新，确认路径后加入PATH并重开终端。
本地服务端口无法访问：服务未启动、防火墙拦截或端口被占用，检查进程、放行回环访问。
在线模式返回错误：密钥错误、过期或网络受限，确认密钥格式与有效期，排查代理。
本地模型加载失败：显存不足、文件不完整或不兼容，换小模型重下、校验完整性、查看日志。
响应速度过慢：CPU算力不足或后台占用资源，关闭后台、换小模型或升级硬件。
为Ollama配置进程监控，异常自动拉起；每周检查客户端更新，保留运行日志。在线密钥建议每季度轮换并设额度告警；Ollama仅监听回环地址，不暴露到公网。根据任务复杂度动态选模型，简单任务用小模型降延迟，复杂任务切大模型或在线接口。定期清理旧模型文件释放空间。
进阶方向可考虑WSL2容器化部署以提升一致性（Windows原生Docker容器化对GPU支持有限，WSL2为更优替代）。
本文系统讲解了Windows平台Claude Code双模式部署全流程，覆盖运行时安装、Ollama搭建、模型下载、双模式切换配置及运维优化。核心价值在于灵活切换：在线模式提供高能力低门槛，本地模式保障数据安全。部署时务必注意终端刷新、Ollama常驻运行、模型与硬件匹配及环境变量正确配置，完成后逐项验证确保长期稳定运行。