让 AI 替你写代码：OpenCode 完全配置与高效使用手册

gyx_这个杀手不太冷静
3,799 阅读8分钟

前言

相信大家对 Cursor、Trae、Github Copilot、通义灵码等 AI 辅助编程工具已经很熟悉了，今天主要想聊一款不止是补全代码的工具 —— OpenCode。

social-share.png

简介

OpenCode 是一个开源的 AI 编程代理（AI coding agent），支持在终端（Terminal）、桌面应用和主流 IDE（如 VS Code）中与 AI 交互完成代码相关任务。

OpenCode 可以帮助我们理解代码库、编写新功能、重构代码、修复 Bug 等，大幅提升开发效率。

OpenCode 支持 75+ 家模型提供商，内置 GLM-4.7、MiniMax M2.1 等免费模型，可对接 OpenAI、Anthropic、Google 等商业模型，也能配置本地模型（如 Llama 3），按需适配轻量脚本、复杂架构等不同场景。

安装

安装 OpenCode 最简单的方式是通过安装脚本。

curl -fsSL https://opencode.ai/install | bash

或者通过命令安装

  • Node.js
npm install -g opencode-ai
  • 在 macOS 和 Linux 上使用 Homebrew
brew install anomalyco/tap/opencode

配置

  1. 运行 /connect 命令
/connect
  1. 输入你的 API 秘钥
┌ API key
│
└ enter
  1. opencode.json 加载

加载优先级：

远程配置 (.well-known/opencode)
  → 全局配置 (~/.config/opencode/opencode.json)
    → 环境变量 (OPENCODE_CONFIG)
      → 项目配置 (./opencode.json)

最小配置：

{
  "model": "anthropic/claude-sonnet-4-20250514",
  "small_model": "anthropic/claude-haiku-3-5-20241022"
}
  1. 目录
~/.config/opencode/
├── opencode.json       # 全局配置
├── auth.json           # 已弃用，迁移到 ~/.local/share/
├── agents/             # 自定义 Agent
├── commands/           # 自定义命令（.md 文件）
├── modes/              # 自定义模式
├── plugins/            # 全局插件
├── skills/             # 全局 Skills
├── tools/              # 自定义工具
└── themes/             # 自定义主题

.opencode/              # 项目级目录（同上结构）

初始化

项目目录下打开 OpenCode

cd xxx/project

运行

opencode

初始化，生成 AGENTS.md 文件

/init

AGENTS.md 文件提交强烈建议提交到 Git 仓库。opencode.json 则一定要在 .gitignore 里面忽略掉，防止 API 密钥、模型偏好等信息泄露。或者放在全局目录C:\Users\你的用户名\.config\opencode\opencode.json

这里主要是帮助 OpenCode 理解项目结构

使用方法

现在配置完了，可以上手用 OpenCode 操作项目了。OpenCode 提供了两种核心工作模式，分别对应不同的使用场景。

对话（Plan）

Plan 模式是 OpenCode 的思考与规划模式，适用于需要 AI 辅助分析、设计的场景。在这个模式下，你可以：

  • 排查问题：将错误信息或异常现象告诉 AI，它会帮你定位问题根因
  • 梳理项目流程：让 AI 分析项目结构，理解业务逻辑和数据流向
  • 制定开发计划：描述需求，让 AI 输出可执行的任务清单和实现步骤
  • 技术方案设计：讨论架构选型、性能优化策略等技术决策

使用示例：

帮我分析一下这个项目可以做哪些性能优化

Plan 模式的典型用法：

# 代码审查与优化建议
帮我 review 一下这段代码，看看有哪些问题

# 架构设计讨论
我想在这个项目中引入状态管理，有什么建议？

# 故障排查
这个接口返回 500 错误，帮我分析一下可能的原因

# 重构规划
这个文件有 2000 多行，帮我规划一下如何拆分成小组件

在 Plan 模式下，AI 会给出详细的分析和建议，但不会直接修改代码。这是与 AI 进行深度技术交流的最佳模式。

写代码（Build）

Build 模式是 OpenCode 的代码生成与编辑模式，这是真正让 AI 替你写代码的核心功能。

切换方式：

  • 在对话界面中，按 Tab 键即可在 Plan 和 Build 模式间切换
  • 或者在输入框中直接输入 /build 快速进入 Build 模式

Build 模式的核心能力：

  1. 代码生成

    帮我创建一个用户登录表单，包含用户名、密码和验证码

  2. 代码重构

    把这个类组件重构为函数组件，使用 Hooks

  3. Bug 修复

    修复这个文件中的内存泄漏问题

  4. 批量修改

    把所有 console.log 替换成统一的日志工具

  5. 文件操作

    创建一个新的 API 服务文件，包含用户相关的 CRUD 操作

Build 模式的工作流程：

  1. 你描述需求或问题
  2. AI 分析代码上下文
  3. AI 生成代码变更方案
  4. 你确认后，AI 自动应用修改
  5. 可以查看 git diff 确认变更内容

重要提示：

  • Build 模式下 AI 会直接修改文件，建议先确保代码已提交到 git
  • 可以使用 /check 命令让 AI 先分析变更方案，不直接应用
  • 配合 .gitignore 和 AGENTS.md 使用，可以控制 AI 的行为范围

撤销变更

在 Build 模式下，如果 AI 的修改不符合预期，你可以随时撤销：

方式一：使用 Git 撤销

# 查看变更
 git diff

# 撤销所有变更
git checkout -- .

# 撤销特定文件
git checkout -- src/components/Button.tsx

方式二：使用 OpenCode 指令

# 撤销最近的修改
/undo

# 撤销特定文件的修改
/undo src/components/Button.tsx

方式三：让 AI 帮你回滚

把我刚才的修改撤销，恢复到修改前的状态

最佳实践：

  • 在让 AI 进行大规模修改前，先提交当前代码（git commit）
  • 使用 /check 先让 AI 分析方案，确认后再应用
  • 定期查看 git status 了解变更状态
  • 如果修改涉及多个文件，可以分批确认，降低风险

分享

协作是开发工作的重要环节。OpenCode 提供了便捷的分享功能，让你可以将 AI 对话内容分享给团队成员。

生成分享链接

在任意对话中，输入以下指令：

/share

执行后，OpenCode 会：

  1. 将当前对话内容生成一个唯一的 URL
  2. 自动复制该 URL 到你的剪贴板
  3. 在终端中显示分享链接

分享链接包含的内容：

  • 完整的对话历史（包括你的提问和 AI 的回答）
  • 代码片段和文件变更记录
  • AI 的思考过程和执行步骤
  • 相关的文件路径和代码引用

分享链接的使用场景

场景一：技术评审

你：帮我 review 一下这个组件的设计
AI：给出了详细的分析和建议
你：/share
# 将链接发给同事进行技术评审

场景二：问题求助

你：这个 bug 我排查了很久没找到原因
AI：分析后给出了解决方案
你：/share
# 将链接发到团队群，让大家了解问题根因

场景三：知识沉淀

你：总结一下 React 性能优化的最佳实践
AI：输出了完整的优化指南
你：/share
# 保存到团队 Wiki，作为技术文档

场景四：远程协作

你：帮我生成一个用户管理模块的代码
AI：完成了代码生成
你：/share
# 链接发给远程同事，对方可以查看完整实现过程

分享链接的安全性

  • 访问控制：分享链接默认是公开的，任何拥有链接的人都可以查看
  • 有效期：链接长期有效，不会自动过期
  • 敏感信息：分享前请检查对话中是否包含敏感信息（如密码、密钥等）
  • 企业版：OpenCode Enterprise 支持私有部署和访问权限控制

分享链接示例

执行 /share 后，你会看到类似这样的输出：

✓ 分享链接已生成并复制到剪贴板

https://opencode.ai/s/abc123def456

该链接包含：
- 24 条对话记录
- 5 个代码片段
- 3 个文件变更

提示：链接已复制，直接粘贴即可分享

打开链接后，其他人可以看到完整的对话界面：

OpenCode 分享链接示例

链接页面功能：

  • 查看完整的对话历史
  • 复制代码片段
  • 查看文件 diff
  • 导出对话为 Markdown
  • 在本地用 OpenCode 打开相同项目

进阶技巧

组合使用 Plan + Build

最高效的工作方式是先 Plan 后 Build：

# Step 1: 在 Plan 模式下讨论方案
> 我想重构这个模块，有什么建议？
AI: 给出了重构方案和步骤

# Step 2: 切换到 Build 模式执行
[Tab 切换]
> 按照刚才讨论的方案，帮我重构 UserModule
AI: 自动执行重构操作

使用上下文指令

# 引用特定文件
@src/components/Button.tsx 帮我优化这个组件

# 引用代码范围
@src/utils.ts:10-50 这段代码有什么问题？

# 引用函数
@formatDate 函数帮我添加参数校验

批量操作

# 批量修改多个文件
修改所有组件，统一添加 loading 状态

# 批量重命名
把所有 User 相关的变量名改为 Member

# 批量删除
删除项目中所有未使用的 import

掌握这些使用方法后，你就可以充分发挥 OpenCode 的 AI 能力，大幅提升开发效率。记住：Plan 模式用于思考，Build 模式用于执行，分享功能用于协作。灵活组合这三种能力，AI 就能真正成为你的得力助手。

avatar
文章
阅读
粉丝