OpenCode 完全使用指南：从安装到精通的实战教程

前言

OpenCode 是由 Anomaly 团队（原 SST 团队）开发的开源 AI 编程代理，于 2025 年 6 月上线。短短几个月内，它凭借以下特点迅速获得开发者青睐：

  • GitHub Star 突破 12 万
  • 月活开发者超过 500 万
  • 支持 75+ LLM 提供商，包括 Claude、GPT、DeepSeek、Gemini 等
  • 隐私优先设计，代码不上传云端
  • 完全开源免费

相比其他 AI 编程工具，OpenCode 的独特优势在于：

  • 终端原生：专为命令行设计，适合习惯终端的开发者
  • 模型自由：不绑定任何模型，可自由切换 75+ 种模型
  • 隐私安全：本地优先，代码不会用于训练
  • 高度可配置：支持自定义工具、规则、快捷键等

这篇文章将带你从安装到精通，全面掌握 OpenCode 的使用方法。

安装与配置

系统要求

项目 要求
操作系统 macOS 10.15+ / Linux / Windows (WSL)
内存 8GB+ (推荐 16GB)
网络 需要稳定的网络连接
终端 支持 TUI 的终端（iTerm2、Windows Terminal 等）

安装步骤

方式一：一键安装（推荐）

1
2
# macOS / Linux
curl -fsSL https://opencode.ai/install | bash

方式二：包管理器安装

1
2
3
4
5
6
7
8
9
10
11
# Homebrew (macOS)
brew install opencode

# npm
npm install -g opencode

# bun
bun install -g opencode

# paru (Arch Linux)
paru -S opencode

方式三：桌面应用

OpenCode 桌面版支持 macOS、Windows、Linux，可从 官网 下载。

初始配置

安装完成后，运行 opencode 启动：

1
2
# 启动 OpenCode
opencode

首次启动会引导你完成配置：

  1. 选择登录方式：支持 GitHub 账号或邮箱登录
  2. 选择模型提供商：可选择 OpenAI、Anthropic、Google 等
  3. 配置 API Key：输入你的 API Key（支持多个提供商）

配置文件

OpenCode 的配置文件位于 ~/.config/opencode/config.json：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
  "providers": {
    "openai": {
      "apiKey": "sk-...",
      "model": "gpt-4"
    },
    "anthropic": {
      "apiKey": "sk-ant-...",
      "model": "claude-3-5-sonnet-20241022"
    }
  },
  "defaultProvider": "anthropic",
  "theme": "dark",
  "permissions": {
    "allowFileWrite": true,
    "allowCommandExecution": "ask"
  }
}

常用配置项

配置项 说明 示例
defaultProvider 默认使用的模型提供商 "anthropic"
theme 界面主题 "dark" / "light"
permissions.allowFileWrite 是否允许自动写文件 true / false
permissions.allowCommandExecution 命令执行权限 "always" / "ask" / "never"

核心功能详解

1. 智能代码生成

在 OpenCode 中，直接用自然语言描述需求：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
你: 帮我写一个 Python 函数，读取 CSV 文件并计算每列的平均值

OpenCode:
```python
import pandas as pd

def calculate_column_averages(file_path: str) -> dict:
    """
    读取 CSV 文件并计算每列的平均值
    
    Args:
        file_path: CSV 文件路径
        
    Returns:
        包含每列平均值的字典
    """
    df = pd.read_csv(file_path)
    # 只计算数值列的平均值
    numeric_columns = df.select_dtypes(include=['number'])
    return numeric_columns.mean().to_dict()
1
2
3
4
5

### 2. 代码解释

选中代码或粘贴代码，让 OpenCode 解释：

你: 解释这段代码的作用
[paste code]

OpenCode:
这段代码使用了 Python 的装饰器模式：

  1. @lru_cache(maxsize=128) - 缓存最近 128 次调用结果
  2. 递归计算斐波那契数列
  3. 时间复杂度从 O(2^n) 优化到 O(n)

潜在问题：递归深度过大时会导致栈溢出，建议使用迭代版本。

1
2
3
4
5

### 3. 代码重构

描述你的重构需求：

你: 将这个函数改为异步实现，并添加错误处理

OpenCode:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
import aiohttp
import asyncio
from typing import Optional

async def fetch_data(url: str) -> Optional[dict]:
    """
    异步获取 JSON 数据
    
    Args:
        url: 请求 URL
        
    Returns:
        JSON 数据，失败返回 None
    """
    try:
        async with aiohttp.ClientSession() as session:
            async with session.get(url, timeout=10) as response:
                response.raise_for_status()
                return await response.json()
    except aiohttp.ClientError as e:
        print(f"请求失败: {e}")
        return None
    except asyncio.TimeoutError:
        print("请求超时")
        return None
1
2
3
4
5

### 4. Bug 修复

粘贴错误信息和代码：

你: 修复这个错误
错误: TypeError: ‘NoneType’ object is not subscriptable
代码:
def get_user_name(user_id):
user = db.get_user(user_id)
return user[‘name’]

OpenCode:
问题：db.get_user() 可能返回 None，直接访问 user[‘name’] 会导致错误。

修复方案：

1
2
3
4
5
def get_user_name(user_id):
    user = db.get_user(user_id)
    if user is None:
        return None  # 或抛出异常
    return user.get('name')  # 使用 .get() 更安全
1
2
3
4
5
6
7
8
9
10
11
12
13
14

### 5. 多会话管理

OpenCode 支持在同一项目中启动多个会话：

```bash
# 会话 1：处理前端代码
opencode --session frontend

# 会话 2：处理后端 API
opencode --session backend

# 会话 3：处理数据库迁移
opencode --session migration

6. 项目初始化

使用 /init 命令快速初始化项目：

1
2
3
4
5
6
7
8
9
10
你: /init

OpenCode:
检测到这是一个 Python 项目，建议初始化以下配置：
- .gitignore
- requirements.txt
- pytest 配置
- black 格式化配置

是否继续? (y/n)

7. 魔法指令 ulw

ulw (Ultra Work) 是 OpenCode 的强力模式：

1
2
3
4
5
6
7
你: ulw 帮我重构整个项目的错误处理

OpenCode:
[自动分析项目结构]
[识别所有需要改进的地方]
[生成修改计划]
[逐步执行修改]

使用技巧

技巧 1：模型选择策略

不同场景选择不同模型：

场景 推荐模型 原因
日常开发 Claude 3.5 Sonnet 速度快，代码质量高
复杂重构 Claude 3 Opus 推理能力强
快速补全 GPT-3.5 Turbo 响应快，成本低
中文需求 DeepSeek Coder 中文理解好
预算敏感 Gemini Pro Google 免费额度大

切换模型：

1
你: /model claude-3-5-sonnet-20241022

技巧 2：用好上下文

OpenCode 能理解项目上下文：

1
2
3
4
5
你: 查看当前项目的依赖
[OpenCode 自动读取 package.json / requirements.txt 等]

你: 这个函数在哪里被调用了？
[OpenCode 自动搜索代码库]

技巧 3：自定义工具

在配置中添加自定义工具：

1
2
3
4
5
6
7
8
9
10
11
12
{
  "tools": {
    "run_tests": {
      "command": "pytest",
      "description": "运行测试套件"
    },
    "lint": {
      "command": "flake8",
      "description": "代码风格检查"
    }
  }
}

然后直接使用：

1
2
你: 运行测试
[OpenCode 调用 run_tests 工具]

技巧 4：权限控制

敏感操作可以设置权限：

1
2
3
4
5
6
7
{
  "permissions": {
    "allowFileWrite": true,        // 允许写文件
    "allowCommandExecution": "ask", // 执行命令前询问
    "allowNetworkAccess": false     // 禁止网络请求
  }
}

技巧 5：分享会话

1
2
3
你: /share

OpenCode: 会话链接已生成: https://opencode.ai/s/abc123

可以分享给别人查看或继续对话。

实战案例

案例 1：快速搭建 Web 应用

需求：创建一个用户管理 API

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
你: 用 FastAPI 创建一个用户管理 API，包含：
- 用户注册（POST /users）
- 用户登录（POST /login）
- 获取用户信息（GET /users/{id}）
- 使用 SQLite 数据库
- 添加 JWT 认证

OpenCode:
我来帮你创建这个项目。首先生成项目结构：

project/
├── main.py
├── models.py
├── schemas.py
├── auth.py
├── database.py
└── requirements.txt

[逐文件生成代码...]

运行命令：
pip install -r requirements.txt
uvicorn main:app --reload

案例 2：代码迁移

需求：将 Python 2 项目迁移到 Python 3

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
你: 分析这个 Python 2 项目，列出需要修改的地方
[粘贴代码]

OpenCode:
发现以下需要修改的地方：
1. print 语句 → print() 函数
2. xrange → range
3. .iteritems() → .items()
4. unicode 类型处理
5. 除法运算 / → //

需要我帮你逐文件迁移吗？

你: 是的，先迁移这个文件
[OpenCode 生成 Python 3 兼容代码]

案例 3：性能优化

需求：优化慢查询

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
你: 这个函数处理 10万条数据很慢，如何优化？
[粘贴代码]

OpenCode:
分析发现主要性能瓶颈：
1. 循环中重复计算
2. 没有使用向量化操作
3. 数据库查询在循环内

优化方案：
```python
import pandas as pd

def process_data_optimized(data):
    # 使用 pandas 向量化操作
    df = pd.DataFrame(data)
    df['result'] = df['value'] * 2  # 向量化计算
    return df.to_dict('records')

预计性能提升 50-100 倍。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61

---

## 常见问题

### Q1：OpenCode 和 GitHub Copilot 有什么区别？

| 特性 | OpenCode | GitHub Copilot |
|------|----------|----------------|
| 开源 | ✅ 完全开源 | ❌ 闭源 |
| 模型选择 | 75+ 模型自由切换 | 仅 Codex |
| 使用方式 | 终端/桌面/IDE | 仅 IDE 插件 |
| 价格 | 免费（仅付模型 API 费）| $10-19/月 |
| 隐私 | 本地优先，代码不上传 | 代码上传云端 |
| 可配置性 | 极高 | 有限 |

### Q2：OpenCode 会泄露我的代码吗？

不会。OpenCode 采用隐私优先设计：
- 代码在本地处理
- 不会用用户代码训练模型
- 支持本地模型（如 Ollama）

### Q3：Windows 能用吗？

可以，但需要 WSL（Windows Subsystem for Linux）：
1. 安装 WSL2
2. 在 WSL 中安装 OpenCode
3. 在 WSL 终端中使用

桌面版原生支持 Windows。

### Q4：支持哪些编程语言？

支持所有主流语言：Python、JavaScript、TypeScript、Java、Go、Rust、C++、C#、Ruby、PHP 等。

### Q5：如何提高代码生成质量？

1. **选择合适的模型**：复杂任务用 Claude 3 Opus
2. **提供清晰上下文**：先让 OpenCode 了解项目结构
3. **使用详细 Prompt**：描述越具体，结果越好
4. **多轮迭代**：不要期望一次完美，逐步优化
5. **使用 `ulw` 模式**：复杂任务开启强力模式

---

## 进阶配置

### 自定义规则

创建 `.opencode/rules.json`：

```json
{
  "rules": [
    "所有函数必须添加类型提示",
    "使用 Google 风格的文档字符串",
    "优先使用 pathlib 而不是 os.path",
    "异步代码使用 asyncio，不要用多线程"
  ]
}

OpenCode 会遵循这些规则生成代码。

团队配置

创建 .opencode/config.json：

1
2
3
4
5
6
7
8
9
10
11
12
13
{
  "team": {
    "codingStyle": "pep8",
    "docFormat": "google",
    "testFramework": "pytest",
    "linter": "ruff"
  },
  "rules": [
    "所有公共函数必须有文档字符串",
    "使用 logging 而不是 print",
    "异常必须继承自自定义异常类"
  ]
}

IDE 集成

VS Code

安装 OpenCode 插件后，在 VS Code 中直接使用：

1
2
3
4
5
// settings.json
{
  "opencode.enableInlineCompletion": true,
  "opencode.defaultModel": "claude-3-5-sonnet"
}

Cursor

Cursor 内置 OpenCode 支持，无需额外配置。

总结

OpenCode 是目前最灵活、最自由的 AI 编程工具，特别适合：

  • 习惯终端的开发者：原生 TUI 体验
  • 追求隐私的开发者：本地优先，代码不上传
  • 需要模型自由的开发者：75+ 模型任选
  • 预算敏感的开发者：免费开源，只需付 API 费
  • 喜欢自定义的开发者：高度可配置

快速上手清单

  • 安装 OpenCode: curl -fsSL https://opencode.ai/install | bash
  • 运行 opencode 完成初始配置
  • 尝试生成第一个函数
  • 使用 /init 初始化项目
  • 配置常用模型（推荐 Claude 3.5 Sonnet）
  • 尝试 ulw 魔法指令
  • 创建 .opencode/rules.json 自定义规则
  • 探索多会话功能

相关文章：

工具指南
#opencode #ai编程 #终端工具 #开源 #效率工具
OpenCode 完全使用指南：从安装到精通的实战教程
https://www.ohtudou.top/2026/03/27/2026-03-27-opencode-guide/
作者
Tudo
发布于
2026年3月27日
许可协议