OpenCode

文档说明

开源 AI 编码代理，支持终端/IDE/桌面多平台，通过 FastAiToken 配置获得稳定高效的编程体验

概述

OpenCode 是一款完全开源的 AI 编码代理，基于 TypeScript 和 AI SDK 构建，提供终端 TUI、IDE 集成和桌面应用多种使用方式。项目在 GitHub 拥有 94.9k+ Star，社区活跃。

通过配置 FastAiToken 服务，您可以获得：

终端 TUI、VS Code 扩展、桌面应用一应俱全 通过 Models.dev 支持 75+ LLM 提供商 语言服务器协议支持，智能代码理解 支持多会话并行处理和会话共享 项目信息：OpenCode 是活跃维护的开源项目，官网 opencode.ai，项目地址 github.com/anomalyco/opencode。

环境准备

安装 OpenCode

curl -fsSL https://opencode.ai/install | bash
```text

i -g opencode-ai@latest

```bash
brew install anomalyco/tap/opencode
```text

Scoop:

scoop install opencode

Chocolatey:

choco install opencode

paru -S opencode-bin

从官网 `opencode.ai` 下载对应系统的桌面应用：

* macOS (Apple Silicon / Intel)
* Windows
* Linux (AppImage / deb)

验证安装：

```text
opencode --version

快速配置

OpenCode 使用 JSON 配置文件，支持多种配置位置（按优先级从低到高）：

1. 远程配置（.well-known/opencode）
2. 全局配置：~/.config/opencode/opencode.json
3. 自定义配置：OPENCODE_CONFIG 环境变量指定的路径
4. 项目配置：项目根目录 opencode.json
5. .opencode 目录配置
6. 内联配置：OPENCODE_CONFIG_CONTENT 环境变量

方法一：自定义 Provider（推荐）

创建或编辑配置文件 ~/.config/opencode/opencode.json：

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
"fastaitoken": {
  "npm": "@ai-sdk/openai-compatible",
  "name": "FastAiToken",
  "options": {
    "baseURL": "https://fastaitoken.com/v1",
    "apiKey": "{env:FASTAITOKEN_API_KEY}"
  },
  "models": {
    "claude-sonnet-4-20250514": {
      "name": "Claude Sonnet 4",
      "limit": { "context": 200000, "output": 8192 }
    },
    "gpt-4.1": {
      "name": "GPT-4.1",
      "limit": { "context": 1047576, "output": 32768 }
    },
    "deepseek-chat": {
      "name": "DeepSeek V3",
      "limit": { "context": 65536, "output": 8192 }
    },
    "gemini-2.5-pro-preview-05-06": {
      "name": "Gemini 2.5 Pro",
      "limit": { "context": 1048576, "output": 65536 }
    }
  }
}
  },
  "model": "fastaitoken/claude-sonnet-4-20250514"
}

然后设置环境变量：

# zsh

echo 'export FASTAITOKEN_API_KEY="sk-你的FastAiToken密钥"' >> ~/.zshrc
source ~/.zshrc

bash

echo 'export FASTAITOKEN_API_KEY="sk-你的FastAiToken密钥"' >> ~/.bashrc source ~/.bashrc

PowerShell：

[System.Environment]::SetEnvironmentVariable('FASTAITOKEN_API_KEY', 'sk-你的FastAiToken密钥', 'User')

或在系统环境变量中添加 `FASTAITOKEN_API_KEY`。

方法二：/connect 命令认证

OpenCode 提供 /connect 命令快速连接新的 Provider：

1. 启动 OpenCode 后输入 /connect
2. 选择 "Other"
3. 输入 provider ID（如 fastaitoken）
4. 输入 API 密钥

然后在配置文件中补充 provider 和 models 定义即可使用。

方法三：覆盖现有 Provider

如果只想快速使用，可以覆盖内置 OpenAI provider 的 baseURL：

{ "provider": { "openai": { "options": { "baseURL": "https://fastaitoken.com/v1", "apiKey": "{env:FASTAITOKEN_API_KEY}"

} } } }

方法四：项目级配置

在项目根目录创建 opencode.json 文件，配置仅对当前项目生效：

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
"fastaitoken": {
  "npm": "@ai-sdk/openai-compatible",
  "name": "FastAiToken",
  "options": {
    "baseURL": "https://fastaitoken.com/v1",
    "apiKey": "{env:FASTAITOKEN_API_KEY}"
  },
  "models": {
    "claude-sonnet-4-20250514": {
      "name": "Claude Sonnet 4",
      "limit": { "context": 200000, "output": 8192 }
    }
  }
}
  },
  "model": "fastaitoken/claude-sonnet-4-20250514"
}

Agent 系统

OpenCode 内置三种 Agent，各司其职：

Agent	说明	使用方式
build	默认代理，拥有完全访问权限，负责代码生成和修改	直接对话
plan	只读代理，用于代码分析和规划，不会修改文件	/plan 命令
general	复杂搜索子代理，用于多步骤信息检索	@general 调用

Agent 模型配置

可以为不同 Agent 配置不同模型：

{
  "provider": {
"fastaitoken": {
  "npm": "@ai-sdk/openai-compatible",
  "name": "FastAiToken",
  "options": {
    "baseURL": "https://fastaitoken.com/v1",
    "apiKey": "{env:FASTAITOKEN_API_KEY}"
  },
  "models": {
    "claude-sonnet-4-20250514": {
      "name": "Claude Sonnet 4",
      "limit": { "context": 200000, "output": 8192 }
    },
    "deepseek-chat": {
      "name": "DeepSeek V3",
      "limit": { "context": 65536, "output": 8192 }
    },
    "gpt-4.1-mini": {
      "name": "GPT-4.1 Mini",
      "limit": { "context": 1047576, "output": 32768 }
    }
  }
}
  },
  "agents": {
"build": {
  "model": "fastaitoken/claude-sonnet-4-20250514"
},
"plan": {
  "model": "fastaitoken/deepseek-chat"
},
"general": {
  "model": "fastaitoken/gpt-4.1-mini"
}
  }
}

推荐模型

OpenCode 通过 FastAiToken 支持 400+ 主流 AI 模型，可根据不同任务选择合适的模型。

查看最新的编程模型推荐、性能对比和使用建议。包括顶级性能模型、高性价比模型、推理增强模型等详细分类。

场景化模型推荐

Agent	用途	推荐模型
build	代码生成和修改	Claude Sonnet 4、GPT-4.1
plan	任务规划和分析	DeepSeek V3、Gemini 2.5 Pro
general	快速搜索和问答	GPT-4.1 Mini（低成本）

核心功能

终端交互界面

启动 OpenCode 进入交互式 TUI 界面：

# 在当前目录启动

opencode

# 指定项目目录

opencode /path/to/project

文件操作

OpenCode 可以读取、搜索和修改项目文件：

> 查看 src/index.ts 的内容

> 在项目中搜索所有包含 "TODO" 的文件

> 将 utils.ts 中的 calculateSum 函数重构为更高效的实现

命令执行

支持在终端中执行命令并查看结果：

> 运行 npm test 并分析失败的测试

> 执行 npm install 并检查是否有依赖冲突

会话管理

• 多会话并行：可以同时运行多个会话
• 会话共享：支持会话导出和分享
• 自动保存：所有会话自动持久化
• 上下文保持：会话期间保持完整的对话上下文

使用技巧

1. 快捷键操作

快捷键	功能
Ctrl+C	中断当前操作
Ctrl+D	退出 OpenCode
Tab	自动补全
↑/↓	浏览历史命令

2. 常用命令

命令	功能
/connect	连接新的 Provider
/model	切换当前模型
/plan	使用 plan agent 进行分析
/clear	清除当前会话
/help	查看帮助信息

3. 调用子代理

使用 @general 调用搜索子代理处理复杂查询：

> @general 在代码库中找到所有处理用户认证的文件，并总结它们的功能

4. 增量式开发

{/* 第一步：生成基础框架 */}
> 创建一个 REST API 的基础结构

{/* 第二步：添加具体功能 */}
> 添加用户认证中间件

{/* 第三步：完善细节 */}
> 添加请求参数验证和错误处理

故障排除

1. 检查环境变量是否正确设置：

echo $FASTAITOKEN_API_KEY  # macOS/Linux

echo %FASTAITOKEN_API_KEY%  # Windows

1. 确认配置文件中的 baseURL：

"baseURL": "https://fastaitoken.com/v1"

1. 测试 API 连通性：

curl -H "Authorization: Bearer $FASTAITOKEN_API_KEY" \
 https://fastaitoken.com/v1/models

确认模型 ID 正确，可在 FastAiToken 控制台查看支持的模型列表。

常见模型 ID：

* `claude-sonnet-4-20250514`
* `gpt-4.1`
* `deepseek-chat`
* `gemini-2.5-pro-preview-05-06`

配置文件加载优先级（从低到高）：

1. 远程配置（`.well-known/opencode`）
2. 全局配置：`~/.config/opencode/opencode.json`
3. `OPENCODE_CONFIG` 环境变量
4. 项目配置：`opencode.json`
5. `.opencode` 目录配置
6. `OPENCODE_CONFIG_CONTENT` 环境变量

确保配置文件位于正确位置，且 JSON 格式正确。
1. 尝试使用更轻量的模型（如 GPT-4.1 Mini）
2. 减少上下文长度，开启新会话
3. 检查网络连接稳定性

最佳实践1. 模型选择策略任务类型推荐模型原因复杂代码生成Claude Sonnet 4编程能力强，上下文理解好代码审查GPT-4.1分析能力强，细节把控好快速问答DeepSeek V3响应快，性价比高长文档分析Gemini 2.5 Pro支持超长上下文2. 高效提示词❌ 不好的提示：帮我写代码

✅ 好的提示：使用 TypeScript 编写一个 HTTP 中间件，
实现请求日志记录，包含请求方法、路径、
响应时间和状态码，使用 pino 输出3. 安全注意事项
不要在代码中硬编码 API 密钥
使用环境变量管理敏感信息
审查 AI 生成的代码，特别是涉及安全的部分
注意不要让 AI 执行危险的系统命令

4. 成本控制
为不同 Agent 配置不同模型（build 用强模型，general 用轻量模型）
简单任务使用轻量模型
定期查看 FastAiToken 控制台监控用量

替代方案如果 OpenCode 不能满足需求，可以考虑以下工具：

Anthropic 官方终端编程助手

OpenAI 官方命令行工具

Google 官方终端编程助手

VS Code AI 编程插件

相关资源

管理 API 密钥和查看使用量

查看编程场景模型推荐