第一次运行

目标：配置 API 密钥、初始化项目、完成第一次对话

配置 API 密钥

OpenCode 需要 LLM 提供商的 API 密钥才能工作。首次运行时会提示配置。

首次配置流程图

手动配置 auth.json

如果 /connect 不适合你的环境，可以直接编辑认证文件：

mkdir -p ~/.local/share/opencode
cat > ~/.local/share/opencode/auth.json << 'EOF'
{
  "providers": {
    "anthropic": {
      "apiKey": "sk-ant-api03-xxxxxxxx"
    },
    "openai": {
      "apiKey": "sk-xxxxxxxx"
    }
  }
}
EOF
 
# 设置安全权限
chmod 600 ~/.local/share/opencode/auth.json

多提供商配置示例

OpenCode 支持 75+ 提供商，以下是常见配置：

配置 1：Anthropic + OpenAI 双备份

{
  "providers": {
    "anthropic": {
      "apiKey": "${ANTHROPIC_API_KEY}",
      "defaultModel": "claude-sonnet-4-5"
    },
    "openai": {
      "apiKey": "${OPENAI_API_KEY}",
      "defaultModel": "gpt-4o"
    }
  },
  "defaultProvider": "anthropic"
}

使用环境变量更安全：

export ANTHROPIC_API_KEY="sk-ant-api03-..."
export OPENAI_API_KEY="sk-..."
opencode

配置 2：国产模型（DeepSeek + 火山引擎）

{
  "providers": {
    "deepseek": {
      "apiKey": "sk-xxxxxxxx",
      "baseUrl": "https://api.deepseek.com"
    },
    "volcengine": {
      "apiKey": "xxxxxxxx",
      "baseUrl": "https://ark.cn-beijing.volces.com/api/v3"
    }
  }
}

配置 3：本地模型（Ollama 完全离线）

{
  "providers": {
    "ollama": {
      "baseUrl": "http://localhost:11434",
      "defaultModel": "codellama:13b"
    }
  },
  "defaultProvider": "ollama"
}

先启动 Ollama：

ollama run codellama:13b
# 另一个终端
opencode

配置 4：多模型路由（按任务切换）

{
  "providers": {
    "anthropic": {
      "apiKey": "sk-ant-...",
      "models": {
        "complex": "claude-opus-4",
        "daily": "claude-sonnet-4-5",
        "fast": "claude-haiku"
      }
    }
  },
  "profiles": {
    "refactor": { "model": "anthropic/claude-opus-4" },
    "quickfix": { "model": "anthropic/claude-haiku" }
  }
}

初始化项目

配置好密钥后，进入你的项目目录：

cd /path/to/your/project
opencode

在 TUI 中运行：

/init

OpenCode 会分析项目结构，在根目录创建 AGENTS.md 文件。

AGENTS.md 是什么

这是项目的"说明书"，告诉 AI：

项目技术栈（React + Node.js？Python？Go？）
代码规范
目录结构
特殊约定

务必提交到 Git：

git add AGENTS.md
git commit -m "Add AGENTS.md for OpenCode"

AGENTS.md 完整模板

模板 1：Next.js 全栈项目

# 项目说明
 
这是一个使用 Next.js 14 + Prisma + PostgreSQL 的全栈应用。
 
## 技术栈
 
- **前端**: Next.js 14 (App Router), Tailwind CSS, Shadcn/UI
- **后端**: Next.js API Routes, tRPC
- **数据库**: PostgreSQL, Prisma ORM
- **认证**: NextAuth.js
 
## 代码规范
 
- 使用 TypeScript，严格模式
- 组件使用函数式组件 + Hooks
- API 路由使用 `src/app/api/...`
- 数据库操作放在 `src/lib/db/...`
- 所有 API 返回统一格式 `{ success: boolean, data?: T, error?: string }`
 
## 目录结构

src/ app/ # Next.js App Router components/ # React 组件 lib/ # 工具函数和数据库 types/ # TypeScript 类型定义 prisma/ # Prisma schema 和迁移 public/ # 静态资源


## 环境变量

复制 `.env.example` 到 `.env.local` 并填写

## 常用命令

- `npm run dev` — 开发服务器
- `npm run build` — 生产构建
- `npm run db:migrate` — 数据库迁移
- `npm run db:seed` — 种子数据

模板 2：Python 后端项目

# 项目说明
 
基于 FastAPI + SQLAlchemy + PostgreSQL 的 REST API 服务。
 
## 技术栈
 
- **框架**: FastAPI
- **ORM**: SQLAlchemy 2.0
- **数据库**: PostgreSQL
- **任务队列**: Celery + Redis
- **测试**: pytest
 
## 代码规范
 
- 遵循 PEP 8，使用 black 格式化
- 类型注解必须完整
- API 端点使用依赖注入
- 数据库会话使用上下文管理器
 
## 目录结构

app/ api/ # API 路由 core/ # 配置和安全性 models/ # SQLAlchemy 模型 schemas/ # Pydantic 模型 services/ # 业务逻辑 db/ # 数据库连接 tests/ # 测试文件


## 环境变量

`.env` 文件必需：DATABASE_URL、REDIS_URL、SECRET_KEY

模板 3：Go 微服务项目

# 项目说明
 
Go 微服务，使用 Gin + GORM + MySQL。
 
## 技术栈
 
- **框架**: Gin
- **ORM**: GORM
- **数据库**: MySQL
- **配置**: Viper
- **日志**: Zap
 
## 代码规范
 
- 遵循 Effective Go
- 接口定义在顶层
- 错误处理必须完整，不忽略 error
- 使用 context 传递请求上下文
 
## 目录结构

cmd/ # 入口文件 internal/ handlers/ # HTTP 处理器 models/ # 数据模型 services/ # 业务逻辑 middleware/ # 中间件 pkg/ # 公共库 configs/ # 配置文件

第一次对话

初始化完成后，你可以开始提问了！

示例 1：了解代码库

这个项目是怎么处理用户认证的？

提示：用 @ 键可以模糊搜索文件：

How is authentication handled in @packages/functions/src/api/index.ts

示例 2：添加简单功能

给登录页面添加一个"忘记密码"链接，跳转到 /forgot-password

示例 3：解释代码

解释一下 @src/lib/auth.ts 中 verifyToken 函数的逻辑

✅ 应该	❌ 不应该
使用环境变量注入密钥	把密钥写在代码或配置文件里提交到 Git
设置 `auth.json` 权限为 `600`	在共享服务器上保存明文密钥
为不同项目使用不同密钥	所有项目共用同一个密钥
定期轮换 API 密钥	一个密钥使用数年不更换
使用 `.env` + `.gitignore`	把 `.env` 提交到仓库

安全的 .gitignore 配置

# OpenCode
.opencode/
AGENTS.md.backup
*.opencode-cache
 
# 密钥和环境变量
.env
.env.local
.env.production
auth.json
secrets/
 
# 日志
*.log
logs/

环境变量加载示例

# .env 文件（已加入 .gitignore）
ANTHROPIC_API_KEY=sk-ant-api03-xxxxxxxx
OPENAI_API_KEY=sk-xxxxxxxx
DEEPSEEK_API_KEY=sk-xxxxxxxx
 
# 启动脚本 start-opencode.sh
#!/bin/bash
set -a
source .env
set +a
opencode "$@"

基本操作总结

操作	命令/快捷键
发送消息	Enter
切换计划/构建模式	Tab
搜索文件	@
撤销修改	`/undo`
重做修改	`/redo`
分享对话	`/share`
退出	Ctrl+C 或 `/quit`

避坑指南

❌ 不要做的

不要在未经确认的生产环境运行 OpenCode
不要把 API 密钥提交到 Git（已自动加入 .gitignore）
不要期望一次提示就得到完美结果 — 迭代是关键
不要在公共机器上保存 auth.json 而不加密
不要向 AI 暴露密码、token、私钥等敏感信息

✅ 最佳实践

要提供充足的上下文 — 把 AI 当作初级开发者
要使用计划模式处理复杂任务
要及时审查修改，不满意就 /undo
要保持 AGENTS.md 更新
要在运行 AI 生成的命令前仔细检查

常见问题

Q: /connect 后浏览器没有打开？ A: 手动访问 https://opencode.ai/auth，完成认证后复制密钥粘贴到终端。

Q: 配置多个提供商时如何切换？ A: 使用 /models 命令查看所有可用模型，输入数字即可切换。

Q: 公司网络有代理，连接失败怎么办？ A: 设置环境变量 HTTPS_PROXY=http://proxy.company.com:8080 后启动 OpenCode。

Q: 如何测试 API 密钥是否有效？ A: 运行 opencode 后发送任意消息，如果 AI 正常回复则密钥有效。

Q: auth.json 位置在哪里？ A: Linux/macOS: ~/.local/share/opencode/auth.json；Windows: %LOCALAPPDATA%\opencode\auth.json。

真实场景案例

案例 1：新成员快速上手

场景：新成员加入团队，需要快速理解一个使用了 50 个 npm 包的 React 项目。

流程：

cd project
opencode
/init  # 生成 AGENTS.md

然后询问：

🤖 这个项目的路由是怎么组织的？特别是认证相关的中间件在哪个文件？

AI 通过读取 AGENTS.md 和代码文件，5 分钟内给出完整的路由图和关键文件位置。

案例 2：多模型故障切换

场景：正在紧急修复 Bug，主用的 Claude API 突然服务不可用。

解决方案：

// ~/.local/share/opencode/auth.json
{
  "providers": {
    "anthropic": { "apiKey": "sk-ant-..." },
    "openai": { "apiKey": "sk-..." }
  }
}

当 Claude 不可用时：

/models
# 选择 OpenAI 模型，继续工作，无需中断

案例 3：完全离线的金融项目

场景：金融内网项目，任何代码不能外传，需要完全离线使用 AI。

配置：

# 内网服务器安装 Ollama
ollama pull codellama:13b
ollama serve
 
# OpenCode 配置指向本地
{
  "providers": {
    "ollama": { "baseUrl": "http://localhost:11434" }
  }
}

代码完全不离开内网，同时享受 AI 辅助编程。

下一篇：04. TUI 界面导航