OpenCode (AI Agent) 实战全纪录：从入门到部署

日期: 2026年2月5日
工具: OpenCode (CLI Agent)
核心模型: Big Pickle (官方免费模型) / GLM-4.7
目标: 零代码基础构建一个局域网即时聊天室

1. 工具背景

  • 名称: OpenCode (opencode.ai)
  • 定位: 开源 AI 编程 Agent，直接对标 Claude Code。
  • 特点:
    • 支持 CLI (命令行) 和 IDE 插件。
    • 免费/低成本: 内置 Big Pickle、GLM-4.7 等免费模型，支持接入 DeepSeek。
    • Agent 能力: 能自动规划任务、创建文件、安装依赖、修复 Bug。

2. 安装与环境配置

安装步骤

使用 npm 全局安装：

1
npm install -g opencode-ai

遇到的问题与解决方案

问题 A: PowerShell 权限报错

  • 现象: 提示 在此系统上禁止运行脚本。

  • 解决: 修改执行策略。

    1
    Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

问题 B: 初始化卡顿 (255MB)

  • 现象: 第一次运行时提示下载 Chromium/沙箱环境，进度条卡住。
  • 原因: 需要下载用于 AI 浏览网页的浏览器内核，且服务器在海外。
  • 解决:
    • 挂好网络代理（确保终端走代理）。
    • 耐心等待，或失败后重试（支持断点续传）。

3. 模型选择

启动命令：

1
opencode
  • 推荐模型: Big Pickle (默认免费，速度快，逻辑强)。
  • 备选模型: GLM-4.7 Free (智谱 AI，中文理解好)。

4. 实战案例：局域网聊天室

需求描述 (Prompt)

开发一个基于 Python FastAPI + Vue.js 3 的即时聊天室。

  • 后端: WebSocket 实现广播，无需数据库（消息存内存）。
  • 前端: 仿 WhatsApp 深色风格，左右气泡布局。
  • 执行: 自动创建所有文件结构。

生成过程

  1. Agent 自动创建了 main.py (后端)、templates/index.html (前端) 和 requirements.txt。
  2. 自动给出了运行命令。

Bug 修复 (Agentic Workflow)

  • 报错: 运行时出现 jinja2.exceptions.UndefinedError: 'message' is undefined。
  • 原因: 前端模板变量名 (message) 与后端传参 (msg) 不匹配。
  • 操作: 将报错信息直接复制回终端输入框 -> Agent 自动分析并修改了 index.html -> Bug 修复成功。

5. 运行与验证

启动服务

1
2
3
cd chatroom
pip install -r requirements.txt  # 安装依赖
python main.py                   # 启动服务

测试效果

图片描述

图片描述

  1. 本机测试:
    • 浏览器访问 http://localhost:8000。
    • 打开两个窗口（一个正常，一个无痕模式），互发消息实现秒级同步。
  2. 局域网联机:
    • 查询电脑 IP (ipconfig)。
    • 手机连接同一 WiFi，访问 http://192.168.x.x:8000。
    • 成功实现手机与电脑跨设备群聊。

6. 常用命令速查

  • 启动 Agent: opencode
  • 进入特定目录启动: cd 文件夹名 -> opencode
  • 切换模型: 在交互界面按 Ctrl + T (Variants) 或输入指令切换。
  • 强制退出: Ctrl + C

7. 总结

OpenCode 是目前体验极佳的免费编程 Agent。核心优势在于**“自我修复”**能力——遇到报错不需要人工介入，直接把 Log 扔给它，它就能自动改好文件。非常适合快速搭建原型 (MVP) 和全栈开发。