3.3 配置 Opencode

Opencode 配置流程

3.3.1 首次启动与模型连接

安装完成后，创建一个练习目录并启动 Opencode：

mkdir ~/opencode-lab
cd ~/opencode-lab
opencode

首次启动后，你会看到 Opencode 的 TUI 界面：

Opencode 初始化界面

界面顶部显示当前智能体和模型信息，底部是输入框。目前还没有连接 AI 提供商，需要先完成配置。

连接模型提供商

在输入框中输入 /connect 命令：

/connect

系统会弹出提供商列表，选择你要连接的服务商并输入 API 密钥：

连接模型提供商界面

本教材推荐以下三个提供商，选择任意一个即可开始：

提供商 注册地址 API 密钥获取 适合场景
智谱 GLM open.bigmodel.cn 注册后在控制台「API 密钥」菜单生成 通用场景，中文能力强
MiniMax platform.minimaxi.com 注册后在「密钥管理」菜单生成 通用场景，性价比高
Ollama（本地） ollama.com 下载客户端即可，无需密钥 离线使用，数据敏感场景

连接成功后，在 Opencode 中输入一句话测试：

你好，请简单介绍一下自己

如果模型正常回复，说明 API 连接成功。

3.3.2 API 密钥安全

API 密钥是访问 AI 服务的凭证，务必妥善保管。

三条基本原则：

  1. 不公开分享——不要提交到 Git 仓库，不要在社交媒体展示
  2. 用环境变量存储——不要把密钥写死在配置文件里
  3. 定期轮换——如怀疑泄露，立即在提供商控制台吊销旧密钥并生成新的

推荐做法：

将 API 密钥存储在环境变量中：

# macOS/Linux：在 ~/.zshrc 或 ~/.bashrc 中添加
export GLM_API_KEY="你的API密钥"

# 使配置生效
source ~/.zshrc

在项目目录的 .gitignore 文件中排除敏感文件：

.env
.env.local
*.key
opencode.local.json
警告安全提示

如果密钥不慎泄露，立即登录对应提供商的控制台，吊销泄露的密钥并生成新密钥。然后检查使用日志，确认是否有异常调用。

3.3.3 安装 Skills 扩展包

sysu-awesome-cc 扩展包内容

Skills 是 Opencode 的能力扩展机制。通过安装 Skills 扩展包，你的 AI 助手可以获得更多专业技能。

sysu-awesome-cc 扩展包

sysu-awesome-cc 是中山大学岭南学院师生共建的扩展包集合，包含 2 个智能体和 8 个 Skills：

智能体（Agents）：

名称 功能
Paper Reviewer 经济学论文评审
Web Researcher 信息采集与事实核查

技能（Skills）：

名称 功能
CC Insights 交互历史分析
Chat History Summarizer 对话提取与总结
Chinese Quote Converter 中文标点格式化
Fetch4ai 网页抓取
Marp Slides Creator 幻灯片制作（14 种主题）
MD to DOCX Markdown 转 Word
MinerU PDF Converter PDF 转 Markdown
Web Research 结构化信息综合

安装方法

这个仓库里的 Skills 和 Agents 需要部署到全局配置目录才能生效。不必手动操作，直接让 Opencode 帮你完成：

请帮我安装 Skills 扩展包。步骤如下：
1. 克隆仓库 https://github.com/Xueheng-Li/sysu-awesome-cc.git 到临时目录
2. 将仓库中 skills 文件夹下的所有子文件夹复制到 ~/.config/opencode/skills/
3. 将仓库中 agents 文件夹下的所有文件复制到 ~/.config/opencode/agents/
4. 完成后删除临时目录

Opencode 会自动执行上述步骤，将 Skills 和 Agents 部署到全局配置目录（~/.config/opencode/skills/ 和 ~/.config/opencode/agents/）。部署到全局目录意味着这些扩展在所有项目中都可用，无需每个项目单独安装。

注记知识卡片

Opencode 的 Skills 存放路径有两级：项目级目录 .opencode/skills/ 仅对当前项目生效，全局目录 ~/.config/opencode/skills/ 对所有项目生效。扩展包安装到全局目录，方便跨项目复用。

验证安装成功：

  1. 输入 /agent 命令，应看到新增的 Paper Reviewer 和 Web Researcher
  2. 在对话中提及某个 Skill 名称（如「请用 Marp Slides Creator 制作一份幻灯片」），Opencode 会自动调用对应 Skill
提示教学提示

Skills 的详细开发原理和自定义方法将在第 8 章介绍。本章只需完成安装，确认扩展在 /agent 列表中可见即可。

3.3.4 安装 Miniconda

后续章节涉及数据分析、量化研究等任务，需要 Python 环境。Miniconda 是 Python 环境管理工具，体积小、安装快。

直接在 Opencode 中请求安装：

请帮我安装 Miniconda。我的操作系统是 [Windows/macOS/Linux]。
安装完成后帮我验证 conda 命令是否可用。

Opencode 会根据你的系统自动下载并执行安装脚本，完成后验证安装结果。整个过程无需你手动操作。

3.3.5 配置 Python 环境

安装好 Miniconda 后，创建一个专门的 Python 环境：

# 创建名为 econ-ai 的环境，Python 版本 3.11
conda create -n econ-ai python=3.11 -y

# 激活环境
conda activate econ-ai

# 安装常用数据分析包
pip install pandas numpy matplotlib

验证安装是否成功：

python -c "import pandas; print(pandas.__version__)"

看到版本号输出，说明环境配置完成。

注记知识卡片

conda 环境是隔离的 Python 运行空间。每个环境有独立的 Python 版本和软件包，互不干扰。为不同课程或项目创建不同环境，可以避免软件包版本冲突。

注意故障排除

如果执行 conda activate econ-ai 后提示 conda: command not found，按以下步骤操作：

  1. 执行 conda init bash（Linux）或 conda init zsh（macOS）
  2. 重启终端
  3. 再次执行 conda activate econ-ai

如仍无法解决，检查 Miniconda 安装路径是否已添加到 PATH 环境变量。