OpenCode 接入 Xcompute（推荐）

OpenCode 是一个开源 AI 编程 Agent，可在终端（Terminal）、桌面应用和 IDE 插件中使用，支持 75+ 种 LLM 提供商。它对自定义 provider 很友好，是接入 Xcompute 中转站的理想选择。

核心特性

特性	说明
多模型支持	支持 OpenAI、Anthropic、Google、DeepSeek 等 75+ 提供商
终端 UI	精美的 TUI 界面，支持 WezTerm、Alacritty、Ghostty、Kitty 等现代终端
会话管理	多会话并行、历史记录、压缩、分享
MCP 集成	支持 Model Context Protocol，可接入外部工具
Plan/Build 模式	Plan 模式只分析规划，Build 模式执行修改，Tab 键切换
隐私优先	不存储代码或上下文，数据仅在本地与 LLM 间传输

与其他工具对比

对比维度	OpenCode	Cursor	GitHub Copilot	Claude Code
开源	完全开源	闭源	闭源	闭源
模型自由度	75+ 提供商随意切换	内置模型为主	OpenAI 模型	Anthropic 模型
费用	免费（自付 API 费用）	$20/月起	$10/月起	$20/月起
自定义 API	原生支持	有限支持	不支持	不支持
MCP 支持	完整支持	支持	不支持	支持
隐私保护	不存储代码	云端处理	云端处理	不存储

核心优势： OpenCode 原生支持通过 @ai-sdk/openai-compatible 适配器接入任何兼容 OpenAI 协议的 API，正是接入 Xcompute 的关键。

安装 OpenCode

macOS / Linux

一键脚本（推荐）
Homebrew
npm
Arch Linux

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

brew install anomalyco/tap/opencode

npm install -g opencode-ai

sudo pacman -S opencode

Docker

docker run -it --rm ghcr.io/anomalyco/opencode

Windows（推荐 WSL）

OpenCode 原生不支持 Windows。推荐使用 WSL：

# PowerShell（管理员权限）
wsl --install
# 重启后进入 WSL 终端执行一键安装
curl -fsSL https://opencode.ai/install | bash

从源码编译

git clone https://github.com/anomalyco/opencode.git && cd opencode
go build -o opencode .
sudo mv opencode /usr/local/bin/

验证安装

opencode --version

安装后提示「command not found」？

npm 全局安装路径可能不在 PATH 中：

npm bin -g
echo 'export PATH="$(npm bin -g):$PATH"' >> ~/.bashrc
source ~/.bashrc

核心概念

三种交互模式

模式	说明	适用场景
Agent (Build)	自主编码模式，可调用工具读写文件、执行命令	需要 AI 自动完成编码任务
Plan	计划模式，AI 分析需求并给出实施方案	复杂功能开发前先出方案
Ask	问答模式，纯对话，不调用工具	代码审查、知识问答

切换方式：按 Tab 键或在会话中输入 /agent、/plan、/ask。

Sub-agent

OpenCode 内部使用多种子代理处理不同任务：Codex（编程）、Planner（任务分解）、Browser（网页浏览）等，由 OpenCode 自动调度。

Xcompute API 对接配置（核心章节）

Xcompute API 概览

项目	信息
Base URL（OpenAI 协议）	`https://xcompute.us/v1`
Base URL（Anthropic 协议）	`https://xcompute.us`（不加 /v1）
加速入口（OpenAI）	`https://intl.dualseason.com/v1`
加速入口（Anthropic）	`https://intl.dualseason.com`

配置文件位置

OpenCode 支持两级配置：

级别	路径	适用场景
全局配置	`~/.config/opencode/opencode.json`	所有项目通用
项目配置	`./opencode.json`（项目根目录）	特定项目专用

首先创建配置目录：

mkdir -p ~/.config/opencode

方式一：OpenAI 兼容协议（推荐）

适用于 GPT、Gemini、DeepSeek 等所有兼容 OpenAI 协议的模型：

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "xcompute": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Xcompute",
      "options": {
        "baseURL": "https://xcompute.us/v1",
        "apiKey": "{env:XCOMPUTE_API_KEY}"
      },
      "models": {
        "gpt-5.6-sol": {
          "name": "GPT 5.6 Sol"
        },
        "gpt-5.5": {
          "name": "GPT 5.5"
        },
        "gemini-3.5-flash": {
          "name": "Gemini 3.5 Flash"
        },
        "deepseek-v4-flash": {
          "name": "DeepSeek V4 Flash"
        }
      }
    }
  },
  "model": "xcompute/gpt-5.6-sol"
}

方式二：Anthropic 协议（用于 Claude 模型）

覆盖官方 Anthropic provider 的 baseURL：

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "anthropic": {
      "options": {
        "baseURL": "https://xcompute.us",
        "apiKey": "{env:XCOMPUTE_API_KEY}"
      },
      "models": {
        "claude-sonnet-5": {
          "name": "Claude Sonnet 5 (via Xcompute)"
        },
        "claude-opus-4-8": {
          "name": "Claude Opus 4.8 (via Xcompute)"
        },
        "claude-fable-5": {
          "name": "Claude Fable 5 (via Xcompute)"
        }
      }
    }
  },
  "model": "anthropic/claude-sonnet-5"
}

重要区别： Anthropic 协议 Base URL 不加 /v1，OpenAI 协议必须加 /v1。

方式三：完整推荐配置（所有模型统一走 OpenAI 协议）

把所有模型都放在 OpenAI 兼容 provider 下，无需区分协议：

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "xcompute-gpt": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Xcompute GPT",
      "options": {
        "baseURL": "https://xcompute.us/v1",
        "apiKey": "{env:XCOMPUTE_API_KEY}"
      },
      "models": {
        "gpt-5.6-sol": {
          "name": "GPT 5.6 Sol",
          "maxTokens": 65536
        },
        "gpt-5.5": {
          "name": "GPT 5.5",
          "maxTokens": 32768
        },
        "gpt-5.4": {
          "name": "GPT 5.4",
          "maxTokens": 32768
        }
      }
    },
    "xcompute-claude": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Xcompute Claude",
      "options": {
        "baseURL": "https://xcompute.us/v1",
        "apiKey": "{env:XCOMPUTE_API_KEY}"
      },
      "models": {
        "claude-sonnet-5": {
          "name": "Claude Sonnet 5",
          "maxTokens": 65536
        },
        "claude-opus-4-8": {
          "name": "Claude Opus 4.8",
          "maxTokens": 65536
        },
        "claude-fable-5": {
          "name": "Claude Fable 5",
          "maxTokens": 65536
        }
      }
    },
    "xcompute-gemini": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Xcompute Gemini",
      "options": {
        "baseURL": "https://xcompute.us/v1",
        "apiKey": "{env:XCOMPUTE_API_KEY}"
      },
      "models": {
        "gemini-3.5-flash": {
          "name": "Gemini 3.5 Flash",
          "maxTokens": 65536
        },
        "gemini-3.1-pro-high": {
          "name": "Gemini 3.1 Pro High",
          "maxTokens": 65536
        }
      }
    },
    "xcompute-other": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Xcompute Other",
      "options": {
        "baseURL": "https://xcompute.us/v1",
        "apiKey": "{env:XCOMPUTE_API_KEY}"
      },
      "models": {
        "deepseek-v4-flash": {
          "name": "DeepSeek V4 Flash",
          "maxTokens": 65536
        },
        "deepseek-v4-pro": {
          "name": "DeepSeek V4 Pro",
          "maxTokens": 65536
        },
        "kimi-k2.5": {
          "name": "Kimi K2.5",
          "maxTokens": 65536
        },
        "qwen3.5-plus": {
          "name": "Qwen 3.5 Plus",
          "maxTokens": 65536
        },
        "grok-4.3": {
          "name": "Grok 4.3",
          "maxTokens": 65536
        }
      }
    }
  },
  "model": "xcompute-claude/claude-sonnet-5"
}

按提供商分组后，在 /models 面板中一目了然。你也可以只保留一个 xcompute provider 把所有模型放一起。

使用环境变量管理 API Key（推荐）

# 临时设置
export XCOMPUTE_API_KEY="YOUR_API_KEY"

# 永久设置
echo 'export XCOMPUTE_API_KEY="YOUR_API_KEY"' >> ~/.zshrc
source ~/.zshrc

在配置文件中用 {env:XCOMPUTE_API_KEY} 引用，避免 API Key 明文写入文件。

隐藏不需要的模型（blacklist）

{
  "provider": {
    "xcompute": {
      "whitelist": ["gpt-5.6-sol", "claude-sonnet-5"]
    }
  }
}

或使用 blacklist 排除不用的模型。

测试 API 连通性

curl -H "Authorization: Bearer $XCOMPUTE_API_KEY" https://xcompute.us/v1/models

多提供商配置

你可以同时配置 Xcompute 和官方 API，灵活切换：

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "xcompute": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Xcompute",
      "options": {
        "baseURL": "https://xcompute.us/v1",
        "apiKey": "{env:XCOMPUTE_API_KEY}"
      },
      "models": {
        "gpt-5.6-sol": { "name": "GPT 5.6 Sol (Xcompute)" },
        "claude-sonnet-5": { "name": "Claude Sonnet 5 (Xcompute)" }
      }
    },
    "anthropic": {
      "options": { "apiKey": "{env:ANTHROPIC_API_KEY}" }
    },
    "openai": {
      "options": { "apiKey": "{env:OPENAI_API_KEY}" }
    }
  },
  "model": "xcompute/gpt-5.6-sol"
}

通过 enabled_providers 和 disabled_providers 控制可用提供商：

{
  "enabled_providers": ["xcompute", "anthropic"],
  "disabled_providers": ["openai"]
}

按任务分配模型（自定义 Agent）

为不同任务类型分配不同模型：

{
  "agent": {
    "code-reviewer": {
      "description": "审查代码质量和安全性",
      "model": "xcompute-claude/claude-sonnet-5",
      "prompt": "你是一个代码审查专家。关注安全性、性能和可维护性。"
    },
    "quick-ask": {
      "description": "快速回答编程问题",
      "model": "xcompute-gpt/gpt-5.5",
      "prompt": "简洁回答编程问题，提供代码示例。"
    }
  }
}

会话中用 /agent code-reviewer 或 /agent quick-ask 切换。

权限控制

{
  "permissions": {
    "mode": "bySession",
    "rules": [
      { "match": "src/**/*.ts", "allow": ["read", "write", "edit"] },
      { "match": "package.json", "allow": ["read", "write"] }
    ]
  }
}

模式	行为
`byTool`	每次调工具都要确认
`bySession`	每轮会话开始确认一次（推荐）
`acceptAll`	自动授权所有工具调用

MCP 服务器配置

OpenCode 支持通过 MCP 协议连接外部工具：

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/dir"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "{env:GITHUB_TOKEN}" }
    },
    "playwright": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp"]
    },
    "sequential-thinking": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"]
    }
  }
}

常用命令速查

命令	功能
`/init`	初始化项目，生成 `AGENTS.md`
`/models`	查看和切换模型
`/session`	查看会话列表
`/new`	新建会话
`/compact`	压缩当前会话（节省 token）
`/share`	分享会话链接
`/undo`	撤销上一步操作
`/diff`	查看当前修改的 diff
`/run <command>`	在终端中执行命令
`/agent`	选择 Agent
Tab	切换 Plan / Build 模式
@	模糊搜索文件引用

启动与使用

初始化项目

opencode

进入界面后先执行 /init，OpenCode 会自动分析项目结构并生成 AGENTS.md（项目级 AI 指南）。

日常使用流程

Plan 模式先出方案：按 Tab 切换到 Plan 模式，描述需求
确认方案后执行：切回 Build 模式，让 AI 改代码
查看 diff：/diff 确认修改内容
不满意可回退：/undo
提交代码：/run git add -A && git commit -m "feat: xxx"

使用模型选择加速入口

如遇延迟，切换 Base URL 到加速入口：

# 测试哪个入口更快
curl -o /dev/null -s -w "%{time_total}\n" https://xcompute.us/v1/models
curl -o /dev/null -s -w "%{time_total}\n" https://intl.dualseason.com/v1/models

常见问题

配置文件格式错误？

# 验证 JSON 格式
cat ~/.config/opencode/opencode.json | python3 -m json.tool

提示：如需注释，将文件保存为 opencode.jsonc（JSONC 格式）。

模型连接失败？

# 测试 API 连通性
curl -H "Authorization: Bearer $XCOMPUTE_API_KEY" https://xcompute.us/v1/models

# 检查代理设置
env | grep -i proxy

常见原因：API Key 错误、Base URL 格式不对（OpenAI 协议要加 /v1）、网络问题。

适配器未找到（Cannot find module）？

确认 Node.js 环境正常。OpenCode 会自动下载 @ai-sdk/openai-compatible，无需手动安装。

响应速度慢？

切换到加速入口 https://intl.dualseason.com/v1
增加 timeout 值："timeout": 600000
使用更快的模型（如 gpt-5.5、deepseek-v4-flash）

如何升级 OpenCode？

npm update -g opencode-ai
# 或
brew upgrade anomalyco/tap/opencode

如何在 IDE 中使用？

VS Code：扩展市场搜索 “OpenCode” 安装
JetBrains：插件市场搜索 “OpenCode” 安装

IDE 扩展共享 ~/.config/opencode/opencode.json，无需额外配置。

控制台

管理 API Key、额度和调用记录。

API 参考

在正式接入前先核对请求格式和示例代码。

​核心特性

​与其他工具对比

​安装 OpenCode

​macOS / Linux

​Docker

​Windows（推荐 WSL）

​从源码编译

​验证安装

​安装后提示「command not found」？

​核心概念

​三种交互模式

​Sub-agent

​Xcompute API 对接配置（核心章节）

​Xcompute API 概览

​配置文件位置

​方式一：OpenAI 兼容协议（推荐）

​方式二：Anthropic 协议（用于 Claude 模型）

​方式三：完整推荐配置（所有模型统一走 OpenAI 协议）

​使用环境变量管理 API Key（推荐）

​隐藏不需要的模型（blacklist）

​测试 API 连通性

​多提供商配置

​按任务分配模型（自定义 Agent）

​权限控制

​MCP 服务器配置

​常用命令速查

​启动与使用

​初始化项目

​日常使用流程

​使用模型选择加速入口

​常见问题

​配置文件格式错误？

​模型连接失败？

​适配器未找到（Cannot find module）？

​响应速度慢？

​如何升级 OpenCode？

​如何在 IDE 中使用？

控制台