OpenCode安装配置保姆级教程,5分钟上手

OpenCode安装配置保姆级教程，5分钟上手

手把手教学，包教包会

上次介绍了 OpenCode 的概念，很多人已经迫不及待想试试了。

但第一步就被卡住了——怎么安装？怎么配置？

别慌，这篇教程就是来解决问题的。我会手把手带你完成整个配置过程，保证你 5 分钟内能用上。

安装前准备

在开始之前，你需要准备：

1. 一个终端

Mac/Linux 用户直接用系统终端就行。

Windows 用户建议用 PowerShell 或者安装 WSL（Windows Subsystem for Linux）。也可以用 Git Bash。

2. Node.js 18+

OpenCode 是用 Node.js 写的，需要先安装 Node.js。

检查是否已安装：

node --version

如果没有安装，去 Node.js 官网下载 LTS 版本。

3. API Key（可选）

如果使用 Claude、GPT 等模型，需要去对应官网申请 API Key。

Claude：https://console.anthropic.com/^[1]
OpenAI：https://platform.openai.com/^[2]
国内模型通常在对应官网申请

注意： OpenCode 也支持完全免费的本地模型（Ollama），如果只是想体验，可以先不申请 API Key。

安装 OpenCode

最简单的方式是用 npm：

npm install -g opencode

或者用 pnpm：

pnpm add -g opencode

安装完成后，检查一下：

opencode --version

看到版本号就说明安装成功了。

首次运行

直接在终端输入：

opencode

如果是第一次运行，会让你选择模型。

方式一：使用在线模型（需要 API Key）

输入数字选择模型提供商会引导你输入 API Key。

以 Claude 为例：

选择 Anthropic
输入你的 API Key
选择模型版本（一般选最新的）

API Key 会保存在本地，后续不需要重复输入。

方式二：使用本地模型（免费）

如果不想付费，可以用本地模型 Ollama。

先安装 Ollama：

# Mac/Linux
curl -fsSL https://ollama.com/install.sh | sh

# Windows（需要 WSL）

然后告诉 OpenCode 使用 Ollama：

opencode --provider ollama

或者在配置文件中指定。

配置文件详解

OpenCode 的配置文件在 ~/.opencode/ 目录下。

主要文件：

config.json：主配置文件
history.json：对话历史
cache/：缓存目录

config.json 配置

默认配置大概是这样的：

{
  "provider": "anthropic",
  "model": "claude-3-5-sonnet-20241022",
  "temperature": 0.7,
  "maxTokens": 4096
}

你可以修改这些参数：

参数	说明	默认值
provider	模型提供商	anthropic
model	使用的模型	claude-3-5-sonnet
temperature	创造性程度，0-1	0.7
maxTokens	单次回复最大 token 数	4096

使用国内模型

如果觉得 Claude/ GPT 太贵，或者访问不稳定，可以换国内模型。

以阿里通义千问为例：

去阿里云申请 API Key：https://dashscope.console.aliyun.com/^[3]
在配置文件中添加：

{
  "provider": "azure-openai",
  "model": "qwen-turbo",
  "apiKey": "your-api-key",
  "baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1"
}

或者更简单的方式，在运行 OpenCode 时指定：

opencode --provider azure-openai --model qwen-turbo

快速开始

配置完成后，就可以开始使用了！

基本交互

# 启动交互式对话
opencode

# 或者直接提问（单次对话）
opencode "帮我写一个Hello World"

在项目中运行

进入你的项目目录，然后运行：

opencode

OpenCode 会自动扫描项目结构，你可以在对话中：

询问代码问题
让它帮你写新功能
让它帮你修 bug
让它帮你写测试

常用命令

# 查看帮助
opencode --help

# 查看版本
opencode --version

# 指定模型
opencode --model claude-3-opus

# 指定提供商
opencode --provider openai

# 指定配置文件
opencode --config /path/to/config.json

常见问题

Q: 安装报错怎么办？

A: 首先确认 Node.js 版本够高（18+）。如果还是不行，尝试清除 npm 缓存：npm cache clean -f

Q: API Key 怎么获取？

A: 去对应官网注册账号，在开发者/API 页面创建 Key。部分模型需要绑卡才能获取 Key。

Q: 国内访问不稳定怎么办？

A: 可以使用国内模型（通义千问、DeepSeek 等），或者配置代理。

Q: 如何切换模型？

A: 在对话中输入 /model 可以切换模型。或者修改配置文件。

Q: 免费能用什么模型？

A: Ollama 本地模型完全免费，但需要一台有显卡的电脑。配置要求不高，MacBook M 系列可以带动。

配置代理（可选）

如果你的网络访问国外 API 不稳定，可以配置代理：

# 方式1：环境变量
export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890

# 方式2：在配置文件中指定
{
  "proxy": "http://127.0.0.1:7890"
}

下一章预告

到这里，环境配置就完成了。你已经具备了使用 OpenCode 的基本条件。

下一期，我会详细介绍 OpenCode 的日常使用操作：如何对话、如何让 AI 帮你写代码、如何使用各种功能。

学会了这些，你就能真正开始用 OpenCode 干活了。

敬请期待！

觉得有帮助的话，点个赞再走呗！有问题评论区见~

引用链接

[1]https://console.anthropic.com/

[2]https://platform.openai.com/

[3]https://dashscope.console.aliyun.com/