OpenCode：一款Claude Code的开源替代品

写在前面：为什么我要写这篇文章

作为Claude Code的用户，我用了它将近半年的时间。不可否认，Claude Code在代码理解和生成方面的效果最近，表现无可挑剔，但随着使用深入，闭源工具的局限性也越来越明显：因为闭源无法根据项目需求深度定制、不能本地部署存在数据安全隐患、长上下文价格昂贵、且很多功能被厂商锁定。

于是我开始寻找一款能替代Claude Code的开源AI编程工具。前后试了多款产品，要么功能残缺，要么体验糟糕，直到我遇到了OpenCode。它完全开源，可以更加灵活自定义环境，支持本地部署，能兼容Claude、GPT、Gemini等70+主流模型，核心功能不仅覆盖了Claude Code的全部能力，还在多代理协作、工作流定制等方面有一定优势。

用了近二个月之后，我彻底转向了OpenCode。这篇文章不是什么"革命性产品"的吹捧，尽管当前相比Claude Code在成熟度上仍有差距，但我作为一个模型开发者，Opencode已经能够满足一切使用要求。这里我整理出来一些OpenCode的实用用法和踩坑经验，希望能给同样在寻找开源AI编程工具的朋友一些参考。

准备好了吗？

我们开始了。

一、核心设计：OpenCode不是代码补全插件，是AI协作开发工具

很多人初次使用OpenCode时会感到不适应。

因为他们还带着传统AI编程工具的思维：AI就是躲在编辑器角落里的代码补全器，我写开头，它补结尾，我是绝对的主导者。但OpenCode的设计逻辑完全不同，它没有把AI定位成一个"打字助手"，而是定位成一个可以和你平等协作的开发伙伴。

它有自己的角色分工、工作流程和规则体系，你需要做的不是逐行指导它写代码，而是给它明确的目标和边界，让它帮你完成大部分重复性工作。

1.1 Plan vs Build：先规划后执行，避免AI擅自修改代码

这是OpenCode最基础也最核心的设计，它将AI的工作拆分成了两个完全独立的阶段。

只需要按下Tab键，或者输入对应的命令，就能在两个模式间切换：

Plan模式（命令：/plan）：AI只进行分析和规划，不会修改任何文件。你可以让它梳理代码逻辑、设计实现方案、评估改动风险、估算工作量。它会输出结构化的Markdown方案，包含步骤拆解、可能的问题和备选方案。

Build模式（命令：/build）：AI只执行你确认过的方案。它会严格按照Plan模式生成的步骤修改代码，不会自作主张添加额外功能或改动无关文件。

这个设计解决了闭源AI工具最让人头疼的问题：你只是想咨询一下优化建议，结果它直接把整个模块重写了。

Plan vs Build模式工作流：左侧Plan模式（分析规划），右侧Build模式（执行修改）

实用操作细节：

1.Plan模式下可以指定输出粒度：/plan --detail high会生成包含每一步具体操作的详细方案，/plan --detail low只生成核心步骤

2.可以只让AI规划特定范围的改动：/plan 只重构src/utils目录下的工具函数

3.Build模式支持精确执行：/build --step 3-5只执行Plan方案中的第3到第5步

4.可以导出Plan方案：/plan --export plan.md将生成的方案保存为文件，方便存档和团队分享

5.对于小于3个文件的简单改动，可以直接使用/build跳过Plan阶段，但建议复杂改动一定先规划

二、子代理系统：拆分任务，实现并行开发

如果说Plan/Build模式让你有了一个靠谱的搭档，那子代理系统就让你拥有了一个可以灵活调度的小型开发团队。

OpenCode支持创建和调用多个独立的子代理，每个子代理运行在自己的会话中，拥有独立的上下文。你可以给不同的子代理分配不同的任务，让它们并行工作，最后由主代理整合结果。

OpenCode内置了两个通用子代理，你也可以根据自己的需求创建任意数量的自定义子代理：

@general：全能型子代理，适合处理综合性任务，比如调研技术方案、编写文档、修复简单bug。它会自动读取相关代码和文档，输出完整的解决方案。

@explore：代码探索专用子代理，只读不写，运行速度极快。专门用于在大型项目中查找代码、梳理调用链路、生成项目结构。

2.1 子代理的核心优势和用法

子代理系统的价值主要体现在两个方面：上下文隔离和并行执行。

上下文隔离意味着每个子代理只专注于自己的任务，不会被其他对话的历史信息干扰。你可以给它一个非常纯粹的指令，让它不受任何历史包袱的影响。并行执行则能大幅提升复杂任务的处理效率，让你同时推进多个不相关的工作。

子代理并行工作架构：主代理调度多个子代理并行处理任务

操作细节：

1.调用子代理的语法：直接在prompt开头加上@代理名，例如@explore 查找JWT鉴权相关代码

2.查看和管理子代理：

▪/agents list：列出所有正在运行的子代理及其ID

▪/agents kill [id]：终止指定ID的子代理

▪/agents save [id] [name]：保存子代理的会话，下次可以直接调用

3.创建自定义子代理：在项目根目录的.opencode/agents/文件夹下创建[代理名].md文件，写入子代理的角色描述和默认指令。例如创建一个@backend子代理专门处理后端任务：

⚡ markdown片段
# @backend 后端开发代理
    专注于Node.js后端开发，遵循RESTful API规范，使用Express框架和Sequelize ORM。
    所有接口必须包含参数校验、错误处理和日志记录。

4.@explore高级用法：

▪@explore 生成项目的模块依赖关系图

▪@explore 查找所有调用了deprecatedFunction的文件和行号

▪@explore 梳理userService的调用链路，列出所有调用它的函数

5.子代理间的数据传递：主代理可以使用@agent [id] get [key]获取某个子代理的输出结果，再传递给另一个子代理

三、AGENTS.md：配置项目专属上下文，让AI适配你的规范

这是OpenCode生态中非常实用且容易被忽视的功能。

在你的项目根目录放置一个AGENTS.md文件，OpenCode会自动将其加载为所有代理的全局上下文。无论你创建多少个子代理，无论你在哪个会话中，AI都会自动遵守这个文件中定义的所有规则。

它就像一本项目专属的员工手册，告诉AI这个项目的架构是什么样的、编码规范是什么、有哪些必须遵守的约定。有了它，AI生成的代码就不会再出现和项目风格格格不入的情况。

AGENTS.md知识库概念图：项目结构、编码规范、常用命令被AI读取

3.1 如何编写一份高效的AGENTS.md

一份好的AGENTS.md应该包含四个核心部分：项目结构、编码规范、常用命令和禁止事项。越具体、越清晰，AI的表现就越好。

实用操作细节：

1.快速生成基础模板：在项目中运行opencode init，OpenCode会自动生成一个包含通用内容的AGENTS.md文件，你只需要根据自己的项目修改即可

2.完整的AGENTS.md示例：

⚡ markdown片段
# 项目全局配置
    本文件是所有AI代理必须遵守的项目规范，所有生成的代码和文档都必须符合以下要求。

    ## 项目结构
    - /src/components - React UI组件，只包含展示逻辑，业务逻辑放在/src/hooks中
    - /src/hooks - 自定义React Hooks，封装业务逻辑和状态管理
    - /src/utils - 纯工具函数，必须是无副作用的纯函数
    - /src/api - API接口封装，统一使用axios，所有请求都要添加拦截器
    - /src/types - TypeScript类型定义文件

    ## 编码规范
    1.  使用TypeScript，所有变量和函数都必须添加类型定义，禁止使用any类型
    2.  函数名使用动词+名词的驼峰命名法，如getUserInfo、updateProduct
    3.  组件名使用大驼峰命名法，如UserCard、ProductList
    4.  异步函数统一使用async/await，禁止使用Promise链式调用
    5.  注释只写"为什么这么做"，不写"做了什么"，代码本身应该是自解释的
    6.  提交前必须运行`npm run lint`和`npm run type-check`，禁止提交有警告的代码

    ## 常用命令
    - 启动开发服务器：`npm run dev`
    - 构建生产版本：`npm run build`
    - 运行所有测试：`npm test`
    - 运行单个测试文件：`npm test [文件路径]`
    - 代码格式化：`npm run format`

    ## 禁止事项
    1.  禁止在组件中直接写业务逻辑
    2.  禁止提交console.log、debugger等调试语句
    3.  禁止使用魔法数字，所有常量都要定义在/src/constants目录下

3.动态变量支持：AGENTS.md中可以使用{{PROJECT_ROOT}}表示项目根目录，{{CURRENT_FILE}}表示当前打开的文件

4.局部覆盖：如果某个子代理需要特殊的规则，可以在子代理的配置文件中添加，会覆盖AGENTS.md中的全局规则

5.实时更新：修改AGENTS.md后不需要重启OpenCode，所有新的会话会自动加载最新的配置

四、Skills：封装重复工作流，实现一键执行

如果说AGENTS.md是项目的员工手册，那Skills就是团队的标准作业程序（SOP）。

Skill本质上是一个Markdown文件，里面定义了一个完整的、可复用的工作流程。你可以把那些每天都要重复做的、步骤固定的工作封装成Skill，以后只需要一个简单的指令，AI就会自动按照你定义的流程完成全部工作。

这不仅能节省大量时间，还能保证每次执行的质量都是一致的，不会因为疏忽而遗漏步骤。

4.1 Skill的编写和使用方法

一个Skill文件包含两部分：元数据和工作流程。元数据定义了Skill的名称、描述和参数，工作流程定义了具体的执行步骤和输出规范。

实用操作细节：

1.Skill文件的存放位置：所有Skill都放在项目根目录的.opencode/skills/文件夹下

2.完整的Skill示例（单元测试生成器）：

⚡ markdown片段
---
    name: test-generator
    description: 为指定函数生成符合项目规范的Jest单元测试
    parameters:
      - name: file
        type: string
        description: 目标函数所在的文件路径
        required: true
      - name: function
        type: string
        description: 要生成测试的函数名，不指定则生成文件中所有函数的测试
        required: false
    ---

    # 单元测试生成器

    ## 执行流程
    1.  读取目标文件的内容，分析函数的输入参数、返回值和逻辑分支
    2.  生成覆盖以下场景的测试用例：
        - 正常输入场景
        - 边界条件场景（空值、最大值、最小值）
        - 异常输入场景（错误类型、非法参数）
    3.  按照Jest规范编写测试代码
    4.  自动运行测试，验证通过率
    5.  生成覆盖率报告，标注未覆盖的代码行

    ## 输出规范
    - 测试文件与源码文件放在同一目录，命名为`{原文件名}.test.ts`
    - 使用describe和it组织测试用例，每个测试用例只测试一个功能点
    - 所有断言必须使用expect的匹配器，禁止使用toBeTruthy/toBeFalsy

3.调用Skill的方法：

▪自然语言调用："帮我给src/utils/request.ts中的fetch函数生成测试"

▪命令行调用：/skill test-generator --file src/utils/request.ts --function fetch

4.调试Skill：在Skill的元数据中添加debug: true，运行时会输出详细的执行步骤和中间结果，方便排查问题

5.社区Skill：OpenCode有官方的Skill仓库，你可以直接下载别人写好的Skill，比如代码格式化、文档生成、Docker部署、Git提交规范检查等

五、Ultra Work模式：通过 Oh My OpenCode 插件实现自动并行调度

这是 OpenCode 生态中最硬核的高级玩法，但它不是原生功能，而是来自社区神级插件 Oh My OpenCode。

在普通模式下，AI 只能串行执行任务。而安装该插件并触发 Ultra Work 模式后，系统会自动将 OpenCode 爆改为一个多智能体团队。它会将大任务拆解，启动专门的代码探索（Librarian）、架构设计（Oracle）以及执行修复（Sisyphus）等多个子代理在后台并行执行，最后整合所有结果。

5.1 Ultra Work模式注意事项

Ultra Work模式适合处理那些步骤多、工作量大、可以并行拆分的任务，比如大型项目重构、批量文件处理、项目初始化、多模块开发等。不适合简单的代码补全或小bug修复，会造成不必要的Token浪费。

实用操作细节：

1.前置安装：必须先在终端运行 bunx oh-my-opencode install （或通过 npm）安装该插件引擎。

2.开启方式：在 prompt 任意位置包含 ultrawork 关键字或简写 ulw。该插件通过拦截关键字直接触发火力全开模式，例如：ulw 重构整个src/utils目录下的工具函数。

3.闭环验证：Ultra Work 模式内置了强制的 Todo 执行器和 LSP（语言服务器协议）诊断，遇到类型错误或导入报错会自动生成子任务继续修复，直到 100% 跑通为止。

六、MCP协议：扩展AI能力边界，连接外部工具

MCP（Model Context Protocol）是Anthropic推出的开放式扩展协议，它允许AI连接和操作外部工具，打破了"只能写代码"的限制。

通过MCP插件，你可以让AI直接操作数据库、控制浏览器、管理Docker容器、调用第三方API、操作Git仓库等。这让AI从一个单纯的代码助手，变成了一个能处理各种数字工作的全能助手。

6.1 常用MCP插件和使用方法

OpenCode社区已经开发了大量的MCP插件，覆盖了开发工作的各个方面。安装和配置都非常简单，只需要几步就能完成。

实用操作细节：

1.无需全局安装，直接通过 npx 调用：现代 MCP 服务器通常直接通过命令动态运行，无需繁琐的 npm 全局安装。

2.配置插件：在项目根目录的 opencode.json 或全局的 ~/.config/opencode/config.json 中添加标准 MCP 配置：

⚡ json片段
{
    "mcpServers": {
        "playwright": {
        "command": "npx",
        "args": [
            "-y",
            "@playwright/mcp@latest",
            "--headless"
        ]
        },
        "mysql": {
        "command": "npx",
        "args": [
            "-y",
            "mcp-mysql-server",
            "--host", "localhost",
            "--port", "3306",
            "--user", "root",
            "--password", "123456",
            "--database", "test"
        ]
        }
    }
    }

3.常用插件推荐：

▪@playwright/mcp：官方提供的浏览器控制插件，直接解析页面无障碍树（Accessibility Tree）而非消耗大量 Token 截图，实现纯结构化数据的精准自动化操作。

▪mcp-mysql-server 等数据库插件：连接 MySQL 数据库，执行查询、修改和数据迁移。

▪mcp-git / mcp-docker：操作 Git 仓库与容器管理。

4.使用示例：配置并启动后，AI 会自动读取工具 Schema。你可以直接下达自然语言指令：

▪浏览器自动化：打开 [https://example.com](https://example.com)，登录账号，提取第三页的表格数据为 CSV

▪数据库操作：查询 2026 年 1 月注册的所有用户，统计每个城市的用户数量

5.开发自定义插件：OpenCode提供了MCP插件开发模板，你只需要实现几个简单的接口，就能开发自己的插件，连接任何你需要的工具

七、Ralph Loop：持续迭代任务，确保100%完成

这是OpenCode的另一个高级功能，专门用于处理需要长时间运行、可能会遇到多次失败的任务。

开启Ralph Loop后，AI会进入一种持续迭代的工作状态。它会不断检查任务是否完成，如果没有完成，就自动拆解成更小的子任务继续执行；如果某个步骤失败了，它会自动重试，或者尝试其他方法，直到任务100%完成。

它不会像其他AI工具那样，遇到一点困难就说"我已经完成了大部分，剩下的你自己处理吧"。

7.1 Ralph Loop的工作原理和使用方法

Ralph Loop的核心是"闭环执行"：执行→检查→修正→再执行，直到满足完成条件。它特别适合处理那些步骤繁琐、容易出错、需要反复调整的任务。

实用操作细节：

1.开启方式：在终端使用专用的斜杠命令 /ralph-loop 后接任务描述，例如：

/ralph-loop 将所有旧的Markdown文档迁移到新的格式

2.配置参数：Ralph Loop 的规则主要通过命令行参数控制：

▪--max-iterations [number]：设置任务的最大迭代重试次数，防止无限死循环消耗成本（例如 --max-iterations 20）。

▪--completion-promise "[text]"：设置明确的“完成信标”。强烈建议在 prompt 中要求 AI 完成后输出特定字符串（如 MIGRATION_COMPLETE），让系统据此精确判断任务是否真正闭环。

3.工作流程：

i.AI将任务拆解成多个小步骤

ii.执行第一个步骤

iii.检查步骤是否成功完成

iv.如果成功，继续执行下一个步骤；如果失败，重试该步骤，或者尝试其他方法

v.所有步骤完成后，生成最终的执行报告

4.适用场景：

▪批量文档迁移和格式转换

▪大量数据的清洗和处理

▪批量修复代码中的同类bug

▪自动化测试和部署流程

5.注意事项：Ralph Loop可能会运行很长时间，建议在不需要实时交互的任务中使用，并且提前设置好超时时间，防止任务无限运行

写在最后：开源AI编程工具的未来

用了三个月OpenCode，我最大的感受是：开源AI工具已经不再是"能用但不好用"的代名词了。OpenCode作为Claude Code的平替，不仅在核心功能上完全达标，还因为开源的特性，拥有了闭源工具无法比拟的灵活性和可定制性。

你可以根据自己的需求修改它的代码，可以部署在本地保护数据安全，可以接入任何你喜欢的模型，可以和你的开发流程深度集成。这些都是闭源工具永远无法提供的。

当然，OpenCode也不是完美的。它的生态还在发展中，部分功能还不够完善，文档也还有待补充。但它让我看到了AI编程工具的另一种可能：不是由少数大公司垄断的黑盒产品，而是由整个社区共同建设的、开放的、属于开发者自己的工具。

如果你也受够了闭源AI工具的各种限制，不妨试试OpenCode。它可能不会让你一夜之间变成编程大神，但它一定会让你的开发效率提升一个档次。

附录：快速上手清单

如果你想开始使用OpenCode，这里是一份一步到位的上手指南：

1.安装OpenCode：npm install -g opencode-ai

2.初始化项目：在你的项目根目录运行opencode init，自动生成配置文件和AGENTS.md模板

3.配置模型：运行opencode connect，选择你要使用的模型，输入对应的API Key（支持Claude、GPT、Gemini等70+模型）

4.基础体验：

▪打开一个代码文件，按Tab切换到Plan模式，问它"这个函数有什么可以优化的地方"

▪确认方案后，按Tab切换到Build模式，让它执行修改

5.进阶尝试：

▪创建一个简单的自定义子代理

▪封装一个你经常做的工作为Skill

▪安装一个MCP插件，体验AI操作外部工具的能力

尾记：OpenCode的能力上限，取决于你如何定义它的规则和流程。