> ## Documentation Index
> Fetch the complete documentation index at: https://api.xcompute.us/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenCode 接入

> 基于 OpenCode 官方文档，用统一的 Node 环境安装 OpenCode，并通过自定义 provider 接入 Xcompute。

OpenCode 是一个开源 AI 编程 Agent，支持终端、桌面和 IDE 扩展。它对自定义 provider 很友好，所以很适合拿来接 Xcompute。

<Frame>
  <img src="https://opencode.ai/docs/_astro/screenshot.CQjBbRyJ_1dLadc.webp" alt="OpenCode 官方截图" />
</Frame>

<caption>*OpenCode 官方文档中的终端界面截图*</caption>

## 这篇文章会带你完成什么

1. 安装 OpenCode
2. 创建全局配置文件
3. 把 Xcompute 注册成自定义 provider
4. 启动会话并完成第一次使用

## 官方安装方式

如果你还没准备 Node 环境，先看 [环境准备：NVM、Node.js 22 和 npm](/node-setup)。

OpenCode 官方推荐安装脚本，也支持 npm。

<Tabs>
  <Tab title="npm 安装（推荐本教程用这个）">
    ```bash theme={null}
    npm install -g opencode-ai
    ```
  </Tab>

  <Tab title="官方安装脚本">
    ```bash theme={null}
    curl -fsSL https://opencode.ai/install | bash
    ```
  </Tab>
</Tabs>

安装后验证：

```bash theme={null}
opencode --version
```

如果能看到版本号，就说明安装阶段已经完成。

## 配置 Xcompute

推荐使用全局配置文件：`~/.config/opencode/opencode.json`

```json theme={null}
{
  "$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": {
          "name": "GPT-5"
        },
        "claude-sonnet-4-5-20250929": {
          "name": "Claude Sonnet 4.5"
        },
        "gemini-2.5-pro": {
          "name": "Gemini 2.5 Pro"
        }
      }
    }
  },
  "model": "xcompute/gpt-5"
}
```

### 配置文件放在哪里

推荐放在：

* macOS / Linux：`~/.config/opencode/opencode.json`
* Windows：用户目录对应的 `opencode` 配置目录

## 也可以用全局环境变量

```bash theme={null}
export XCOMPUTE_API_KEY="YOUR_XCOMPUTE_API_KEY"
opencode
```

如果你只是先想测试一下是否能接通，用这种方式最快。

## 初始化项目

官方推荐在项目里第一次启动后执行：

```text theme={null}
/init
```

它会分析项目并生成 `AGENTS.md`，后续会话更稳定。

然后设置环境变量：

```bash theme={null}
export XCOMPUTE_API_KEY="YOUR_XCOMPUTE_API_KEY"
```

## 启动与验证

```bash theme={null}
opencode
```

如果你能正常进入界面并开始新会话，说明 OpenCode 已经可以通过 Xcompute 调用模型。

## 第一次正式使用：一步一步来

### 1. 进入项目目录

```bash theme={null}
cd your-project
```

### 2. 启动 OpenCode

```bash theme={null}
opencode
```

### 3. 先让它解释项目

```text theme={null}
请先告诉我这个项目是做什么的
```

### 4. 再让它出计划

```text theme={null}
先给我一个修改方案，不要直接改代码
```

### 5. 确认后再让它执行

```text theme={null}
方案可以，开始修改
```

## 日常使用教程

### 1. 解释仓库

```text theme={null}
How is authentication handled in this repo?
```

### 2. 做功能前先出计划

OpenCode 官方文档推荐先切到计划模式，再讨论实现方案。

```text theme={null}
先给我一个实现方案，再开始改代码
```

### 3. 让它直接改代码

```text theme={null}
请为设置页增加一个登录校验，并复用 notes 路由里的实现方式
```

### 4. 回滚不满意的改动

```text theme={null}
/undo
```

## 常见问题

### 为什么 OpenCode 很适合接中转站？

因为它本身就支持自定义 provider 和 `baseURL`，比很多只支持官方 API 的客户端更灵活。

### 为什么推荐先执行 `/init`？

因为它会自动帮你生成项目级说明文件，后续它更容易理解你的代码风格和项目结构。

## 什么时候适合用 OpenCode

1. 你想在同一套代码 Agent 工作流中切换不同模型。
2. 你希望把多个开发工具的调用都统一到一个平台管理。
3. 你想通过配置文件精细控制 provider、model 和权限策略。

## 为什么推荐 OpenCode 这样配

<Steps>
  <Step title="走 OpenAI 兼容协议">
    你只需要把 `baseURL` 指向 Xcompute 的 `/v1` 入口。
  </Step>

  <Step title="把密钥放到环境变量">
    避免把真实密钥直接写死在配置文件里。
  </Step>

  <Step title="按工具拆分密钥">
    建议给 OpenCode 单独一个 API Key，和 Claude Code、应用服务分开。
  </Step>
</Steps>

<Columns cols={2}>
  <Card title="控制台" icon="house" href="https://xcompute.us/dashboard/overview">
    管理 API Key、额度和调用记录。
  </Card>

  <Card title="API 参考" icon="square-terminal" href="/api-reference/texts/general/chat-completions">
    在正式接入前先核对请求格式和示例代码。
  </Card>
</Columns>