终端里跑 AI 编程助手,已经不是新鲜事——但大多数方案要么绑 IDE,要么要付费订阅。OpenCode 是一个开源的终端 AI 编程助手,支持多种 LLM 后端,其中最实用的组合是:OpenCode + Gemini 免费 API Key。零成本、纯命令行,直接对本地 Python 项目做代码审查和重构建议。
OpenCode 是什么,为什么值得试
OpenCode 是一个用 Go 写的开源 CLI 工具,定位类似 Cursor 的终端版,但不绑任何 IDE 或付费平台。核心能力:
- 在终端里以对话方式与 LLM 交互,上下文自动包含你指定的文件
- 支持多模型后端(Gemini、OpenAI、Anthropic、本地 Ollama 等)
- 可以直接读取本地代码文件,让 AI 基于真实代码做分析和修改建议
- 输出代码片段时带语法高亮,方便直接复制
和 Cursor、Copilot 的区别:OpenCode 不嵌入编辑器,而是把终端变成一个"AI 代码顾问"。你不需要换编辑器,不需要改工作流,只需要在旁边开一个终端窗口。
拿到 Gemini 免费 Key 并配置
Gemini API 目前提供免费额度(每分钟 15 次请求、每天 1500 次),对个人开发者日常使用足够。
第一步:获取 API Key
访问 Google AI Studio,登录后点击 "Get API Key",创建一个项目即可拿到 Key。
第二步:配置 OpenCode
OpenCode 的配置文件放在 ~/.config/opencode/config.json,也可以用环境变量。最简单的方式:
# 安装 OpenCode(macOS / Linux)
curl -fsSL https://opencode.ai/install.sh | bash
# 或者用 Go 直接编译
go install github.com/opencode-ai/opencode@latest
# 设置 Gemini API Key
export GOOGLE_API_KEY="你的-gemini-api-key-here"
# 在项目目录启动
cd ~/projects/my-python-app
opencode
启动后 OpenCode 会自动检测当前目录的文件结构,你可以在对话中引用任意文件。
如果想把 Key 写进配置文件持久化:
// ~/.config/opencode/config.json
{
"provider": {
"google": {
"apiKey": "你的-gemini-api-key-here"
}
},
"model": "gemini-2.5-flash"
}
推荐用 gemini-2.5-flash——速度快、免费额度内,对代码分析和重构任务足够胜任。复杂推理场景可以切换到 gemini-2.5-pro,但免费额度消耗更快。
实战:让 AI 审一段 Python 代码并给出重构方案
假设你项目里有个处理 CSV 数据的模块 data_loader.py,逻辑有点乱,想让它帮你审查和重构。
原始代码(data_loader.py):
import csv
from collections import defaultdict
def load_data(path):
result = []
with open(path, 'r') as f:
reader = csv.DictReader(f)
for row in reader:
if row['status'] != 'active':
continue
if row['amount'] == '' or row['amount'] is None:
row['amount'] = 0
else:
row['amount'] = float(row['amount'])
result.append(row)
return result
def summarize(data):
totals = defaultdict(float)
for row in data:
totals[row['category']] += row['amount']
return totals
在 OpenCode 终端里发起对话:
> /add data_loader.py
> 这段代码有几个问题:amount 字段的空值处理不安全,
summarize 函数没有处理 category 为空的情况,
load_data 里缺少异常处理。请审查并给出重构版本,
要求:用 dataclass 替代裸 dict,加上类型标注,
补上异常处理和边界情况。
OpenCode 会读取 data_loader.py 的内容,把完整代码作为上下文发给 Gemini,然后返回审查意见和重构代码。你大概率会收到类似这样的建议:
import csv
from collections import defaultdict
from dataclasses import dataclass
from pathlib import Path
from typing import Optional
@dataclass
class Record:
category: str
amount: float
status: str
class DataLoadError(Exception):
pass
def load_data(path: Path) -> list[Record]:
if not path.exists():
raise DataLoadError(f"File not found: {path}")
records: list[Record] = []
try:
with open(path, "r", encoding="utf-8") as f:
reader = csv.DictReader(f)
for row in reader:
if row.get("status", "").strip().lower() != "active":
continue
category = row.get("category", "uncategorized").strip()
amount = _parse_amount(row.get("amount"))
records.append(Record(category=category, amount=amount, status="active"))
except csv.Error as e:
raise DataLoadError(f"CSV parsing failed: {e}") from e
return records
def _parse_amount(raw: Optional[str]) -> float:
if raw is None or raw.strip() == "":
return 0.0
try:
return float(raw.strip())
except ValueError:
return 0.0
def summarize(records: list[Record]) -> dict[str, float]:
totals: dict[str, float] = defaultdict(float)
for r in records:
totals[r.category] += r.amount
return dict(totals)
关键改进点一目了然:dataclass 替代裸 dict、类型标注全覆盖、_parse_amount 抽成独立函数处理脏数据、Path 替代字符串路径、异常链保留原始错误信息。
你可以直接把建议代码复制回 data_loader.py,或者让 OpenCode 帮你写入:
> 把重构版本写入 data_loader.py
几个高频用法
除了代码审查和重构,OpenCode 在终端里还能做这些事:
1. 快速理解陌生代码
> /add src/core/engine.py
> 用中文解释这个文件的核心逻辑,列出关键函数和调用关系
2. 生成测试
> /add data_loader.py
> 为 load_data 和 summarize 写 pytest 测试,覆盖正常路径、
空文件、字段缺失、amount 为非数字字符串的情况
3. 逐文件排查问题
> /add tests/test_api.py src/api/handlers.py
> test_api.py 里第 3 个测试为什么失败?对比 handlers.py 找原因
/add 命令可以多次使用,把多个文件加入上下文。Gemini 的上下文窗口足够容纳几个中等规模的 Python 文件。
限制和取舍
| 方面 | 说明 |
|---|---|
| 免费额度 | Gemini Flash 每天 1500 次请求,重度使用可能不够;Pro 额度更少 |
| 上下文长度 | 单次对话能容纳的代码量受模型窗口限制,超大文件需要分段处理 |
| 不会自动改文件 | OpenCode 默认只输出建议,需要你确认后才写入,这是安全设计 |
| 终端体验 | 没有 IDE 内联补全的流畅感,更适合"对话式"场景而非实时补全 |
| 模型选择 | Gemini 对中文指令响应良好,但复杂多文件推理不如 Claude Sonnet |
上手清单
- 去 Google AI Studio 拿一个免费 Gemini API Key
- 安装 OpenCode,把 Key 写进配置或环境变量
- 选一个你想改善的 Python 项目,
cd进去,启动opencode - 用
/add把目标文件加入上下文,提一个具体的审查或重构请求 - 拿到建议后手动确认再写入——别让 AI 无审查地改你的代码
OpenCode 的价值不是替代你写代码,而是在终端里给你一个随时可问的、懂你项目上下文的代码顾问。免费、开源、不绑 IDE——试试看,最坏的结果也就是发现它不适合你的场景,成本为零。