开源AI编码神器OpenCode

一、OpenCode 简介

OpenCode 是一个开源的 AI 原生代码编辑器，类似于 Cursor 或 Windsurf。它支持通过 OpenAI 兼容 API 接入各种模型，包括通过第三方中转代理（如 OpenRouter、OneAPI、NewAPI 等）使用 Claude、Gemini、DeepSeek 等模型。

二、安装 OpenCode

1. 通过官方安装包安装（推荐）

# macOS (使用 Homebrew)
brew install opencode

# 或下载 dmg 安装包
# 访问 https://opencode.ai 下载对应系统版本

命令介绍：

brew install opencode：使用 macOS 的包管理器 Homebrew 安装 OpenCode。Homebrew 会自动处理依赖并安装到 /Applications 目录。

# Windows (使用 winget)
winget install OpenCode.OpenCode

# 或下载 exe/msi 安装包

命令介绍：

winget install OpenCode.OpenCode：使用 Windows 的包管理器 winget 从官方源安装软件。

# Linux (使用 Snap)
sudo snap install opencode --classic

# 或使用 AppImage
# 下载后赋予执行权限
chmod +x OpenCode-*.AppImage
./OpenCode-*.AppImage

命令介绍：

sudo snap install opencode --classic：使用 Snap 包管理器安装，--classic 表示授予完全系统访问权限（IDE 需要访问文件系统）。
chmod +x：修改文件权限，添加可执行权限（+x），使 AppImage 可以运行。

2. 通过源码编译安装（开发者）

# 克隆仓库
git clone https://github.com/opencode-ai/opencode.git

# 进入目录
cd opencode

# 安装依赖
npm install

# 编译并运行
npm run build
npm start

命令介绍：

git clone：从 GitHub 克隆源代码到本地。
npm install：安装 Node.js 项目依赖（读取 package.json）。
npm run build：执行构建脚本，编译 TypeScript/Electron 源码。
npm start：启动开发服务器或应用。

三、配置第三方中转代理模型

OpenCode 支持通过 OpenAI 兼容格式 接入第三方代理。以下是常见代理平台的配置方法。

通用配置原理

所有配置都遵循以下格式：

Base URL：代理平台的 API 地址
API Key：你在代理平台生成的密钥
Model ID：模型标识符（如 gpt-4o、claude-3-5-sonnet 等）

方式一：通过 OpenCode 图形界面配置

打开 OpenCode，点击左下角 ⚙️ 设置（Settings）
选择 Models 或 AI Provider
点击 Add Custom Provider
填写以下信息：
- Provider Name：自定义名称（如 OpenRouter）
- Base URL：代理的 API 基础地址
- API Key：你的密钥
- Model：选择或输入模型 ID

方式二：通过配置文件手动设置（高级）

配置文件位置：

macOS：~/Library/Application Support/OpenCode/config.json
Windows：%APPDATA%\OpenCode\config.json
Linux：~/.config/OpenCode/config.json

# 查看配置文件路径（macOS/Linux）
echo ~/Library/Application\ Support/OpenCode/config.json

# 使用编辑器打开配置文件
code ~/Library/Application\ Support/OpenCode/config.json
# 或
nano ~/.config/OpenCode/config.json

命令介绍：

echo：输出文本，用于确认路径。
code：使用 VS Code 打开文件（如果你已安装）。
nano：终端文本编辑器，适合在 SSH 或纯终端环境使用。

四、常见第三方代理平台配置示例

1. OpenRouter 配置

OpenRouter 是一个聚合多种模型的平台，支持 Claude、Gemini、Llama 等。

# 配置参数
Base URL: https://openrouter.ai/api/v1
API Key: sk-or-v1-xxxxxxxxxxxxxxxx
Model: anthropic/claude-3.5-sonnet

配置示例（config.json）：

{
  "aiProviders": [
    {
      "name": "OpenRouter",
      "baseUrl": "https://openrouter.ai/api/v1",
      "apiKey": "sk-or-v1-your-key-here",
      "models": [
        {
          "id": "anthropic/claude-3.5-sonnet",
          "name": "Claude 3.5 Sonnet"
        },
        {
          "id": "openai/gpt-4o",
          "name": "GPT-4o"
        }
      ],
      "defaultModel": "anthropic/claude-3.5-sonnet"
    }
  ]
}

2. OneAPI / NewAPI 配置

OneAPI 和 NewAPI 是开源的 API 聚合中转系统，通常自建或购买服务。

# 假设你的 OneAPI 地址是 https://api.your-domain.com
Base URL: https://api.your-domain.com/v1
API Key: sk-xxxxxxxxxxxxxxxx
Model: gpt-4o 或 claude-3-opus

配置示例：

{
  "aiProviders": [
    {
      "name": "OneAPI",
      "baseUrl": "https://api.your-domain.com/v1",
      "apiKey": "sk-your-oneapi-key",
      "models": [
        {
          "id": "gpt-4o",
          "name": "GPT-4o"
        },
        {
          "id": "claude-3-opus-20240229",
          "name": "Claude 3 Opus"
        }
      ]
    }
  ]
}

3. 阿里云百炼 / 灵积平台

Base URL: https://dashscope.aliyuncs.com/compatible-mode/v1
API Key: sk-xxxxxxxxxxxxxxxx
Model: qwen-max 或 qwen-coder-plus

配置示例：

{
  "aiProviders": [
    {
      "name": "阿里云百炼",
      "baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1",
      "apiKey": "sk-your-dashscope-key",
      "models": [
        {
          "id": "qwen-coder-plus-latest",
          "name": "通义千问 Coder"
        }
      ]
    }
  ]
}

4. 腾讯云 / 百度千帆 / 其他国内平台

原理相同，只需替换对应的 Base URL 和 Model ID：

平台	Base URL 示例
腾讯云	`https://api.lkeap.cloud.tencent.com/v1`
百度千帆	`https://qianfan.baidubce.com/v2`
硅基流动	`https://api.siliconflow.cn/v1`
DeepSeek 官方	`https://api.deepseek.com/v1`

五、验证配置是否成功

1. 测试 API 连通性（命令行）

# 使用 curl 测试代理是否正常工作
curl https://openrouter.ai/api/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-or-v1-your-key" \
  -d '{
    "model": "anthropic/claude-3.5-sonnet",
    "messages": [{"role": "user", "content": "Hello"}],
    "max_tokens": 10
  }'

命令介绍：

curl：命令行 HTTP 客户端，用于发送请求。
-H：添加 HTTP Header，Content-Type 声明 JSON 格式，Authorization 携带 API Key。
-d：POST 请求的数据体（payload）。
\：行续符，将多行命令连接为一行。

如果返回 JSON 包含 choices 字段，说明配置正确。

2. 在 OpenCode 中测试

打开 OpenCode
新建文件或打开项目
使用快捷键 Ctrl+L（或 Cmd+L）打开 AI 聊天面板
输入简单指令如 "你好" 或 "解释这段代码"
观察是否能正常返回回复

六、进阶配置：多模型切换与路由

OpenCode 支持配置多个 Provider，并根据需求切换：

{
  "aiProviders": [
    {
      "name": "OpenRouter-Claude",
      "baseUrl": "https://openrouter.ai/api/v1",
      "apiKey": "sk-or-v1-xxx",
      "models": [{"id": "anthropic/claude-3.5-sonnet", "name": "Claude 3.5"}]
    },
    {
      "name": "DeepSeek-官方",
      "baseUrl": "https://api.deepseek.com/v1",
      "apiKey": "sk-deepseek-xxx",
      "models": [{"id": "deepseek-chat", "name": "DeepSeek V3"}]
    },
    {
      "name": "本地-Ollama",
      "baseUrl": "http://localhost:11434/v1",
      "apiKey": "ollama",
      "models": [{"id": "codellama", "name": "CodeLlama 本地"}]
    }
  ],
  "defaultProvider": "OpenRouter-Claude"
}

七、常见问题排查

问题	排查方法
连接超时	检查网络是否能访问代理地址，`ping api.xxx.com`
401 认证失败	检查 API Key 是否正确，是否包含多余空格
404 模型不存在	确认 Model ID 与代理平台文档一致
额度不足	登录代理平台查看余额或调用配额

# 排查网络连通性
ping openrouter.ai

# 查看 DNS 解析
nslookup openrouter.ai

# 测试端口连通性（macOS/Linux）
nc -zv openrouter.ai 443

命令介绍：

ping：发送 ICMP 包测试网络延迟和连通性。
nslookup：查询域名对应的 IP 地址，排查 DNS 问题。
nc -zv：Netcat 工具，-z 扫描模式，-v 显示详细信息，测试 TCP 端口是否开放。

八、安全建议

不要将 API Key 硬编码在代码中，使用环境变量或配置文件
定期轮换 API Key，尤其是使用第三方代理时
使用本地代理或 VPN 时，确保连接安全（HTTPS）
配置文件权限设置：
```
chmod 600 ~/.config/OpenCode/config.json
```
命令介绍：
- chmod 600：设置文件权限为仅所有者可读写（rw-------），防止其他用户读取敏感配置。