Open Code 的使用与配置

OpenCode 是开源免费的 AI 编码工具，区别于传统 VS Code、普通 IDE，深度集成大模型能力，可让 AI 辅助完成各类代码开发工作，支持终端命令行、桌面客户端、IDE 扩展插件三种方式。

• GitHub 项目地址
• 官方文档地址

与 Cloud Code 核心对比

OpenCode 好比开源 MySQL，自由可控无绑定；Cloud Code 好比商业 Oracle，功能强大但收费、封闭、绑定生态。

为什么优先选择 OpenCode

1. 地缘与使用安全：Cloud Code 官方曾限制国内企业使用，国内用户易出现账号封禁、服务受限；OpenCode 开源无限制，不被卡脖子。
2. 模型自由选择：可随意切换国产模型（智谱、阿里千问等），也能用 Cloud Code 同款模型，体验差距极小。
3. 支持本地私有化部署：电脑硬件足够可通过 Ollama 本地跑编码模型，无需调用第三方 API，零 Token 成本。
4. 生态发展趋势：开发社区大力拥抱 OpenCode，各类插件、工具持续完善，未来会成为开发者主流选择。
5. 本质逻辑一致：两者都是 AI 编程助手，核心交互依赖大模型，工具本身使用逻辑相通，学会一个即可通用。

VS Code 安装 OpenCode 插件（免切终端）

1. 日常习惯用 VS Code 不想切换命令行，可直接安装官方插件。
2. 安装步骤

• 打开 VS Code 扩展商店，搜索 OpenCode；
• 直接点击安装，安装完成后左侧出现 OpenCode 图标；
• 点击图标自动在当前项目目录唤起命令行窗口，和独立终端功能完全一致。

3. 使用建议：习惯命令行可直接用终端启动，统一管理所有项目，不依赖 VS Code 插件。

基础配置

全局配置 + 项目配置内容自动合并，不是互相覆盖。

1. 全局配置（所有项目生效）

• Windows 路径：C 盘 → 用户目录 → .config/opencode/OpenCode.json
• Mac 路径：当前用户根目录 → .config/opencode/OpenCode.json
• 作用：配置全局模型、供应商、插件，所有项目共用一套配置。

2. 项目级配置（仅当前项目生效）

• 路径：项目根目录新建 OpenCode.json
• 作用：单独为某个项目定制模型、插件，不影响其他项目。

目录命名兼容规则

1. 早期目录名用单数 agent，新版统一推荐复数 agents；
2. OpenCode 单数、复数目录完全兼容，都能正常识别插件 / 技能；
3. 统一规范：后续全部使用复数 agents /skills，适配未来版本。

基础使用

打开项目

1. 先终端 cd 进入项目文件夹，输入 OpenCode 直接启动；
2. 任意目录下输入 OpenCode 项目路径，直接指定项目启动。

界面基础布局

• 底部输入框：输入指令、命令、对话；
• 上部区域：AI 回复内容、执行日志；
• 模式标识：显示当前运行模式（Plan / Edit）；
• 模型标识：显示当前选用大模型；
• 路径 / Git 分支：显示当前项目目录、Git 所在分支。

重置终端：clear 清空界面

退出终端：

• /q
• /exit
• Ctrl+D

核心工作模式

1. Plan 模式（规划只读模式）

• 定位：相当于架构师、顾问，只读不修改文件；
• 特点：涉及文件增删改会先给出规划、方案、步骤，需要人工确认，安全性高；
• 适用：老旧项目、敏感项目、担心 AI 误改代码的场景。

2. Edit 模式（直接编辑模式）

• 定位：直接执行操作，自动创建 / 修改 / 删除文件，无需反复确认；
• 特点：效率高、全自动执行，适合普通新项目、信任 AI 操作的场景；
• 日常推荐：绝大多数开发场景直接用 Edit 模式。

实操区别

• Plan 模式下达「生成 README」指令：AI 只分析项目结构、给出文档规划，不创建文件；
• Edit 模式下达同样指令：AI 自动分析项目、生成完整 README.md 并保存到目录。

项目初始化

/INIT：OpenCode 的基础入门命令，所有项目开发的第一步。

执行逻辑：全自动扫描当前项目目录 → 分析代码 / 框架（Java/SpringBoot/Maven 等）→ 生成核心配置文件，项目根目录的 agents.md

agents.md 两大核心作用：

1. 官方作用

agents.md 是 OpenCode 的项目上下文手册 + AI 行为准则，用于：

• 记录项目结构、构建命令、测试命令
• 存储项目核心信息，让 AI 快速理解项目
• 下次打开 OpenCode 无需重新扫描整个项目，直接读取该文件
• 自定义 AI 的工作规则、代码风格、交互方式

2. 可自定义的核心内容

你可以手动编辑文件，添加专属规则，相当于给 AI 定「工作规矩」：

AI 角色定位：你是资深 C/C++ 程序员，熟练前后端交互、BUG 调试与修复

代码风格规范：大括号独占一行、函数名小写 + 下划线、必须加注释、命名约定

交互原则：删除文件前必须确认、实事求是、不凭感觉编写代码

优化技巧：生成英文文件后，用 @agents.md 指令让 AI 转为简体中文版

agents.md 的双层级配置

agents.md，不同的存放位置，作用范围完全不同：

1. 项目根目录（如 game/agents.md）
   生效范围：局部生效，仅对当前项目及子目录生效
   用途：定义单个项目专属规则（如特定项目的代码规范）

2. 用户目录（如 .config/opencode/agents.md）
   Windows 示例：C:\Users\你的用户名.config\opencode\agents.md
   生效范围：所有 OpenCode 会话、所有项目生效
   用途：定义通用规则（如你的个人代码风格、通用交互原则）

加载优先级

OpenCode 启动时，先加载全局规则，再加载项目规则（项目规则覆盖全局规则）

关键补充说明
无 agents.md 也能运行：OpenCode 可正常工作，但 AI 不了解你的风格和规则，输出更通用、不贴合你的习惯。

LSP 工具作用：执行 /init 时调用，用于代码语法分析、高亮、结构解析，提升项目扫描精度。

类比理解：agents.md 就是 AI 的「实习生手册」，你把工作要求写清楚，AI 就会严格按照你的方式工作。

供应商与模型切换

1. /connect：连接模型供应商（对接厂商 API、填写 API Key）；
2. /models：切换具体大模型（已连接厂商后，可任意切换旗下模型）。

OpenCode 自带几十家厂商：OpenAI、谷歌、GitHub、DeepSeek、阿里、小米、亚马逊等，直接选择即可连接。

自定义添加第三方供应商 （列表没有的厂商）

打开全局配置文件 OpenCode.json；

复制固定配置模板，修改 3 个关键信息：

① 自定义供应商名称（展示在列表中）；
② 厂商开放平台 API 地址、APIKey；
③ 厂商提供的模型名称；

保存配置，重启 OpenCode，即可在 /connect 列表看到自定义供应商；

选择供应商，输入平台申请的 APIKey 即可完成连接。

本地 Ollama 私有模型配置

1. 在全局 OpenCode.json 中粘贴 Ollama 专属配置模板；
2. 填写本地 Ollama 已下载的模型名称（如千问 Coder、7 B/30 B 编码模型）；
3. connect 选择 ollama-local，无需 APIKey，直接回车即可连接本地模型；
4. 优势：完全离线、零 Token 费用、隐私性高。

不推荐的配置方式

不要使用官方一键配置命令，会直接覆盖你的 OpenCode.json 自定义配置，手动修改配置文件是最安全稳妥的方式。

撤销 / 重做

用于快速回滚 AI 对代码的修改，无需手动操作文件：

1. undo ：一键撤销上一步所有操作（如生成注释、修改代码）
2. redo：恢复被撤销的操作

示例：给 Service 加注释 → undo 清空注释 → redo 恢复注释

会话管理（Session）：多任务隔离

区分不同的开发任务，避免操作混乱：

1. 核心命令：

   • sessions：查看所有会话列表
   • new：新建独立会话
   • 快捷键：Ctrl+A 重命名、Ctrl+D 删除会话、Ctrl+X+L

2. 核心特性：会话完全隔离
   每个会话的操作历史独立，undo/redo 仅作用于当前会话，不影响其他会话

3. 重要警告：

   ❌ 不是专业版本控制（无法替代 Git）

   ❌ 禁止多个会话操作同一个文件，会导致代码混乱

   ✅ 最佳实践：不同会话对应不同业务模块，配合 Git 管理代码版本

技能扩展：Skills 系统

OpenCode 的能力拓展核心，支持自定义 / 复用标准化功能：

1. 本质：固定格式的 skill.md 文件（文件名不可修改），封装功能（前端设计、代码检查、生成文档等）

2. 两级目录规则：

   • 🔹 全局技能（所有项目可用）：~/.config/opencode/skills/
   • 🔹 项目级技能（仅当前项目可用）：项目根目录/.opencode/skills/

3. 使用方式：

   • skills：列出所有可用技能
   • /技能名：调用指定技能（如 /front-end-design 生成前端页面）

零代码实战开发流程

掌握基础命令后，我们全程不写一行代码，只用指令让 OpenCode 完整开发项目。

案例 1：纯前端 1024 小游戏

1. 准备工作

新建项目文件夹，创建 rules.md 文件，写入 1024 完整游戏规则：4×4/5×5 网格、方向键移动、相邻数字合并、随机生成新数字、合成 1024 获胜等规则。

2. 下达开发指令

读取项目里的 rules.md 游戏规则，帮我开发一个完整版前端 1024 小游戏，生成完整 HTML+CSS+JS。

3. AI 自动开发过程

AI 自动读取规则、分析需求、创建页面结构、编写样式、实现移动合并逻辑、生成完整 index.html。

等待两分钟左右自动完成，直接在浏览器打开就能玩，完整实现所有游戏规则。

4. 二次优化迭代

继续下达指令：给游戏增加主题切换功能，提供多款配色风格，可自由切换并本地保存偏好。

AI 自动新增主题样式、UI 选择按钮、切换逻辑、本地存储，还自动检查代码 bug、修复样式错误，最终生成多主题可切换的完整版小游戏。

案例 2：零代码开发前后端分离博客系统

完整实战：不用写一行代码，开发SpringBoot 后端 + 前端 H5 页面完整博客系统。

项目提前建好两个文件夹：

• backend：存放 Java SpringBoot 后端
• frontend：存放前端页面

1. 自动创建 SpringBoot 后端

在 backend 目录生成 SpringBoot 项目，整合 MySQL、MyBatis、Lombok，适配指定版本，集成 Swagger 接口文档，配置数据库账号密码。

AI 自动生成完整项目结构、Pom 依赖、启动类、配置文件。

启动后发现 Swagger 依赖坐标报错，直接发指令让 AI 自动修复依赖版本冲突。

2. 自动生成数据库 SQL 脚本

生成博客系统全套业务建表 SQL，包含用户表、博客表、分类表、评论表、收藏表，附带模拟测试数据。

AI 自动生成完整 SQL 文件，手动在数据库客户端执行，批量建好所有业务表、导入测试数据。

3. 根据 SQL 自动生成后端代码

AI 自动分析表结构，生成全套分层代码。

4. 修复各类项目 Bug

实体类名和 Java 集合 Collection 命名冲突，启动报错，发指令让 AI 改名修复；

博客与点赞模块循环依赖，启动失败，指令让 AI 解耦修复；

Swagger 被登录拦截无法访问，移除多余安全拦截配置；

自动剔除多余 SpringSecurity 依赖，解决权限拦截问题。

修复完成后，Swagger 接口全部正常可访问，后端开发完成。

5. 调用 Skill 生成前端页面

使用 front-end-design 前端设计 skill，下达指令：

在 frontend 目录开发博客系统响应式 H 5 页面，对接后端所有接口，包含首页、分类、博客详情、点赞评论、个人中心、修改头像密码、发布博客等功能，风格简约时尚。

AI 自动生成全套前端页面、样式、接口请求逻辑。

6. 前后端联调逐一修复 Bug

• 前端接口能请求到数据但页面不展示，指令修复渲染逻辑；
• 博客详情页 ID 请求路径错误，404 访问失败，修复路由参数；
• 发布博客、修改头像提交报 401 权限未认证，修复请求头 Token 携带逻辑；
• 图片上传成功但预览无法显示，修复后端静态资源访问策略、前端资源解析格式。

逐一通过下发指令迭代修复，最终实现：

后端正常启动、接口完整可用；前端页面完整、主题正常、登录发布点赞收藏评论全部功能正常。

项目运行方式

1. 启动 SpringBoot 后端服务；
2. 在前端目录用 Python 启动简易静态服务器；
3. 浏览器访问前端端口，手机适配模式正常展示所有博客系统功能。

核心总结

1. 核心流程：/INIT 初始化 → 配置 agents.md 规范 → 指令开发 → 撤销 / 重做调试 → 会话管理 → Skills 扩展
2. 核心文件：agents.md（项目规范 + 说明书，OpenCode 的 “规则手册”）
3. 核心价值：零代码开发、自动遵循团队规范、技能可拓展
4. 关键注意：必须配合 Git 做版本控制，复杂项目需手动修复少量 AI 生成的 bug

场景 1：挖掘波兰华沙本地企业高质量潜在客户

前置准备
MCP‑Chrome 已连接，允许 OpenCode 操控浏览器；模型使用 OpenAI（GPT‑4o 或 GPT‑52），支持多语言识别。
你输入的完整提示词
我需要你为我的业务寻找高质量的潜在客户，我们专门为本地企业提供 AI 和 AIO 自动化解决方案，我住在波兰华沙，需要你帮我找些合适的商家，查好联系方式，整理成清晰的 Markdown 文件，开工简短回答。
你的手动操作
输入提示词发送；
按两下 ESC 键，强制 OpenCode 使用 Chrome Dev Tools MCP 执行网页抓取任务；
全程无需操作，仅观察浏览器自动运行。
OpenCode 自动分步执行
生成代办清单：研究适合 AI/AIO 自动化的理想业务类型；
调用 MCP‑Chrome 自动打开浏览器，搜索华沙本地企业；
自动识别波兰语网页内容，筛选电商、营销机构、房地产、会计类商家；
批量抓取企业名称、地址、官网、联系方式；
汇总数据，自动创建并生成 Markdown 线索文件。
输出 & 耗时
耗时：1 分 41 秒（101 秒）
成果：33 家华沙本地目标企业完整线索（含地址、网站、联系方式）
关键细节
无需你懂波兰语；适配健身、建筑、电工、实体店等任意行业，只需替换业务关键词即可复用。

场景 2：整理电脑下载文件夹，清理最大 / 最老文件、释放空间

前置准备
OpenCode 拥有本地文件读写权限，无需额外配置。

你输入的完整提示词
分析我设备里的下载文件夹，找出里面最老的 20 个文件，还有那 20 个最大的文件也一并整理好，先别急着删掉它们，之后把最老的 20 个文件和最大的 20 个文件都删掉。

你的手动操作
仅发送指令，等待执行，最后右键文件夹查看属性确认空间。
OpenCode 自动分步执行
扫描系统下载文件夹，读取全部文件元数据；
统计文件总情况：2400 个文件、占用 20GB；
排序筛选：找出最大 20 个（多为视频、照片）、最老 20 个文件；
列出清单给你预览；
确认后批量删除选中文件。
输出 & 耗时
几秒内完成；

成果：下载文件夹从 20GB 缩减至约 5GB，释放 15GB 存储空间

关键细节
手动整理需要 10 + 分钟，AI 几秒完成；可复用指令用于桌面、文档、视频文件夹清理。

场景 3：批量分析 250+AI 创业点子，生成黑曜石风格知识图谱 PNG
前置准备
允许 OpenCode 安装 Python 依赖、创建虚拟环境、运行代码。
你输入的完整提示词
我这份文件里有 250 多个创业点子，帮我阅读文件，分析里面所有想法，把它们整理成不同类别，做成一个视觉化的知识图谱，类似黑曜石那种风格，把相关点子归成集群，最后把这个图谱导出成 PNG 文件。
你的手动操作
上传 / 指定创业点子文件，发送指令，等待执行，打开生成的 PNG 查看。
OpenCode 自动分步执行
读取文件，提取 234 个有效创业点子；
遵循 “大任务拆成 3–5 个小步骤” 原则，分步执行；
自主编写400 行 Python 代码，用于分类、聚类、绘图；
检测缺少依赖，自动安装 matplotlib 等库；
创建独立虚拟环境，隔离运行脚本；
完成聚类分类（21 个大类），生成黑曜石风格知识图谱；
导出为 PNG 图片文件，更新内部待办清单。
输出 & 耗时
耗时：2 分钟；
成果：234 个点子分为 21 类（AI 基础设施、HR 工具、个人效率工具、B2B 自动化等），高清 PNG 图谱；
对比：手动做需要 60–90 分钟。
关键细节
OpenCode 不会一次性做超大任务，会拆分步骤，是高效工作逻辑，可迁移到日常工作。

场景 4：深度定制研究：降低销售电话爽约率
前置准备
MCP‑Chrome 开启，允许调用 Python 库、抓取 YouTube 字幕；OpenCode 可本地运行第三方库（ChatGPT 网页版无法实现）。
你输入的完整提示词
深入研究如何降低销售电话的爽约率。
你的手动操作
发送指令；
关闭浏览器安全警告；
全程无需操作，等待报告生成。
OpenCode 自动分步执行
调用 MCP‑Chrome 自动打开浏览器，搜索相关 YouTube 教学视频；
自主编写 Python 脚本，尝试使用 youtubedlp、YouTube Transcript API 提取视频字幕；
多次调试、更换方法，不轻易放弃，最终成功提取完整字幕；
把截断的转录内容保存为本地文件，读取完整数据；
汇总多个视频字幕（75 万条数据）、发布时间、摘要；
整理成结构化深度研究简报，输出 300 行完整报告。
输出 & 耗时
耗时：5 分 15 秒；
成果：完整行业深度报告，可替代付费顾问，手动整理需要一整天；
关键细节
本地运行优势：可调用网页版 AI 无法使用的库；
安全对比：OpenCode 直接操作本地文件有风险，隐私 / 安全类深度研究优先用 Agent Zero（作者有配套教程）。

场景 5：一键排查 Mac 电脑卡顿原因

前置准备
OpenCode 拥有系统进程、磁盘、内存读取权限，禁止修改 / 删除文件。

你输入的完整提示词
最近电脑为啥变慢啦，查查负载、内存压力、磁盘读写、进程、堆栈和交换活动，帮我全面分析电脑，找出变慢的原因，然后给我报告，先别改、也别删文件，我就是想排查问题。

你的手动操作
发送指令，等待 20 秒，直接读取生成的诊断报告。
OpenCode 自动分步执行
调取 Mac 系统实时监控数据：CPU 负载、内存、磁盘 IO、交换分区、进程列表；
识别高占用进程、系统运行时长；
归纳五大卡顿原因；
输出清晰的问题诊断报告。
输出 & 耗时
耗时：20 秒；
卡顿原因结果：
系统连续运行 11 天未重启；
Brave 浏览器多窗口占用大量资源；
本地运行 Agent Zero 的 Docker 虚拟机常驻；
OBS 录屏软件占用 CPU；
后台多程序堆积；
可直接按报告逐个解决。

场景 6：全流程打造面向 AI 流量（AEO）的单页网站

前置准备
MCP‑Chrome 开启；AEO = 答案引擎优化 / 生成式智能体优化，面向 AI 代理流量（区别传统 SEO）。

你输入的完整提示词
用 MCP Chrome 工具浏览各种资源，对比现有的代码审查 AI 工具，研究怎么优化文章来吸引 AI 流量（AEO），围绕这个话题构思五篇不同文章，写成单篇深度文章，存为 MD 文件，在代码库里建个单页 HTML 网站，把文章放进去，优化设计让它独特又专业，最后用 MCP 工具打开网站。

你的手动操作
发送指令，等待完成，自动弹出浏览器查看成品网站。

OpenCode 自动分步执行
调用 MCP‑Chrome 全网调研现有 AI 代码审查工具；
研究 AEO 流量优化规则；
撰写 354 行深度行业文章，保存为 Markdown；
自主编写千行 HTML 代码，构建可交互单页网站；
加入动画、专业 UI 设计；
自动调用 MCP 在浏览器打开成品页面。
输出 & 耗时
耗时：10 分钟；
成果：可交互、带动画的独立网站，完整行业文章；
关键细节
这是最复杂的单指令任务，全程不崩溃；替代全职岗位（研究 — 写作 — 建站全流程）；可替换成饮食、健身、行业产品等任意主题复用。

场景 7：代码库自动补全、更新全套技术文档
前置准备
OpenCode 拥有代码库读写、Git 提交权限；目标：给加速器项目的问责软件补全文档。
你输入的完整提示词
分析代码库，找出缺少文档的地方，第一列出需要文档的文件 / 功能，第二解释代码功能，第三编写文档；如果不存在 /docs 文件夹就新建，更新 README.md；结构规范，直接修改 / 新建文档。
你的手动操作
发送指令，等待执行，可随时查看待办清单，最后检查 Git 提交记录。
OpenCode 自动分步执行
批量读取整个代码库源文件；
识别文档缺口：README 内容过时、函数无注释、架构无说明；
生成文档补全待办清单；
新建 /docs 文件夹，拆分 API 参考、架构、部署、流程文档；
补全函数注释、更新 README；
并行处理大量文件，批量生成上千行文档；
拉取最新 Git 代码、添加注释、提交推送至仓库。
输出 & 耗时
耗时：8 分钟；
成果：完整代码库文档体系，README 更新，可直接给其他开发者 / AI 接手；
关键细节
作者预判：2025–2026 年可实现代码注释 100% 自动化；大量开发者一半工作都在写文档，此功能可完全替代。

场景 8：一键生成创业项目交互式投资人融资路演 PPT
前置准备
MCP‑Chrome 开启；创业方向：社交视频一键多平台发布 APP；可针对投资人做个性化定制。
你输入的完整提示词
基于这个社交视频一键发布的手机应用创意，创建交互式的投资者演示文稿，包含角色、目标、技术栈、创意提案、市场、竞品、定价、解决方案、动画演示，可针对投资人个性化定制，输出可直接发给投资人的成品。
你的手动操作
发送指令，等待执行，查看最终交互式演示网站。
OpenCode 自动分步执行
拆解复杂任务，生成代办清单；
新建专用文件夹，使用 White 框架搭建交互式演示；
自动运行脚本自检，主动发现代码错误并修复；
完整撰写：项目痛点、解决方案、市场规模、竞品分析、定价、团队、商业计划；
生成可交互、带动画的网页版路演 PPT。
输出 & 耗时
耗时：7 分钟；
成果：完整专业融资方案，可直接发送投资人，成本极低，可撬动大额融资；
关键细节
可加入投资人个人信息，实现高度个性化，大幅提升邮件打开率、广告 / 融资转化率；小团队靠 AI 可打造跨国企业。

UI-UX Pro Max Skills