OpenCode 打造个人 AI 智能体（一）：从安装到高效使用技巧

这是「OpenCode 打造个人 AI 智能体」系列的第一篇。

---

前言：为什么是 OpenCode？

如果你还在手动写重复代码、手动查文档、手动跑测试，那你大概还没遇到 OpenCode。

简单说，OpenCode 是一个开源 AI 编程助手，但跟市面上那些仅限聊天补全的工具不同，它能直接在你的终端里操作文件、运行命令、使用 Git、甚至操控浏览器。

这意味着什么？你的 AI 助手可以做真实的开发工作，而不只是建议你应该怎么写。

更重要的一点——它完全开源，而且支持接入 75+ 种 LLM 模型，包括 OpenAI、Claude、DeepSeek，甚至本地模型。你的代码和数据你自己控制。

---

一、OpenCode 是什么

OpenCode 是一个终端里的 AI 智能体（Agent）系统。

它有这几个核心概念需要先理解：

1.1 多代理架构

OpenCode 不是单一 AI 对话窗口，它内置了不同类型的代理（Agent），各自负责不同的任务：

代理类型	角色	能做什么
Build	主力开发者	读写文件、执行命令、操作 Git
Plan	架构师	只分析不修改，适合先做方案
Explore	搜索员	快速搜索代码库、查文件
General	通用执行者	独立执行多步骤复杂任务

日常使用中，你用 Tab 键可以在不同代理间切换。想搜索代码按一下切到 Explore，想分析方案切到 Plan，要真正改代码回到 Build。

1.2 工具系统

OpenCode 能调用的工具（Tools）包括：

• 文件操作：读、写、编辑、搜索文件
• 终端命令：直接在你的 Shell 中执行命令
• Git 操作：提交、分支管理、查看历史
• Playwright：浏览器自动化，能看到网页内容、截图
• Web Search：实时联网搜索
• Memory：跨会话记忆（后续文章会详细讲）

这些才是 OpenCode 真正的价值——它不是一个只会聊天的 AI，而是一个能动手干活的智能体。

1.3 AGENTS.md（项目的AI说明书）

每个项目可以通过 /init 命令生成自己的 AGENTS.md 文件。这个文件告诉 AI 你的项目是什么、目录结构怎么组织、有哪些规范。

这是 OpenCode 非常聪明的设计：AI 不用猜你的项目结构，你（或者 OpenCode 自己）写好说明书，AI 照着做。

---

二、安装 OpenCode

安装方式很多，我推荐以下几种。

2.1 一行命令安装（推荐）

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

这是最快的方式，自动检测系统并安装二进制版本。

2.2 Homebrew 安装（Mac / Linux）

brew install anomalyco/tap/opencode

2.3 NPM 全局安装

npm install -g opencode-ai

2.4 Docker 运行

docker run -it --rm ghcr.io/anomalyco/opencode

适合不想在本地装太多东西的场景。

2.5 Arch Linux

sudo pacman -S opencode

2.6 验证安装

装完之后在终端跑一下：

opencode --version

看到版本号就说明装好了。

---

三、快速上手：从 0 到第一次对话

3.1 连接模型

第一次运行需要配置一个 LLM 模型作为 AI 的大脑。最简单的做法是用 OpenCode Zen（官方托管的模型服务）：

# 在 OpenCode 界面中执行
/connect

然后跟着提示登录 opencode.ai 获取 API Key。

当然你也可以自己配置 API Key。OpenCode 支持的模型非常多——

如果你用 Claude：

export ANTHROPIC_API_KEY=sk-ant-xxxxxxxx

如果你用 OpenAI：

export OPENAI_API_KEY=sk-xxxxxxxx

如果你用 DeepSeek：

export DEEPSEEK_API_KEY=sk-xxxxxxxx

3.2 进入一个项目

找一个你熟悉的代码项目，进去启动 OpenCode：

cd /path/to/your/project
opencode

3.3 初始化项目

/init

这个命令会让 OpenCode 扫描你的项目，生成 AGENTS.md，并自动加载到内存中。之后 AI 就"认识"你的项目了。

3.4 开始对话

现在你可以像聊天一样让 AI 干活了。试一下：

“帮我看看这个项目的目录结构”
“解释一下 main 函数的逻辑”
“这里的类型定义有问题，帮我修一下”

---

四、使用技巧

4.1 善用 Tab 切换代理

我日常使用频率最高的操作就是按 Tab。需要快速搜索代码的时候切到 Explore，需要做方案设计切到 Plan，真正要改代码回到 Build。一个代理干一件事，效率比一个代理干所有事高得多。

4.2 用 /init 保持项目上下文

每进一个新项目先跑 /init，让 OpenCode 读取项目配置。如果是大项目，AGENTS.md 写详细一点，AI 的准确率会明显提升。

4.3 Agent @mention 调用

在对话中可以直接 @ 某个子代理让它执行特定任务：

@explore 帮我找一下所有用到 JWT 的地方

这和按 Tab 切换效果一样，但更直观。

4.4 自定义 opencode.json

在项目根目录建一个 opencode.json，可以配置：

{
  "model": "claude-sonnet-4-20250514",
  "temperature": 0.3,
  "max_steps": 50
}

不同任务我可能会用不同的模型——复杂架构用高智商模型，简单任务用快模型。

4.5 /compact 手工压缩上下文

长对话用久了上下文会膨胀，显式执行 /compact 可以让 AI 总结长上下文，释放 Token 空间。

---

五、一个真实场景

给你看看我实际是怎么用的。

上周接到一个需求：给库存账簿加一个仓库禁用状态。我的流程是：

1. Tab 切到 Plan → “分析仓库模块的代码结构，给出添加禁用状态的最小改动方案”
2. Plan 分析完告诉我：数据库加字段、枚举加状态、列表页加开关、下拉列表加过滤
3. 切回 Build → 按方案执行
4. 遇到一个下拉列表的 SQL 需要改 → @explore 找到所有查询仓库列表的代码
5. 改完之后 → “帮我跑一下测试”

全程没有手动搜过一次文件，没有打开过一个 IDE。 这就是 OpenCode 的日常。

---

最后

OpenCode 是我目前用过最顺手的 AI 编程工具。它跟那些仅限界面内操作的 AI 不同——它是直接在你的电脑上干活，读你的文件、跑你的命令、管你的 Git。

下一篇我会讲 OpenCode 的子代理系统：Build、Plan、Explore 这些 Agent 到底怎么配置、怎么用、什么场景用哪个。

如果你还没装，现在可以试一下：

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

装完启动后跑 /connect 配好模型，然后 /init 初始化项目，就可以开始用了。

---

系列预告

• 第一篇：OpenCode 介绍、安装、使用技巧（本篇）
• 第二篇：子代理系统详解——Build、Plan、Explore 怎么用
• 第三篇：记忆体 Memory——让 AI 真正了解你的项目
• 第四篇：技能系统——内置与自定义技能
• 第五篇：工具链深度探索
• 第六篇：实战——用 OpenCode 搭建完整开发工作流