> ## Documentation Index
> Fetch the complete documentation index at: https://docs.4096bytes.com/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenCode

> 在 OpenCode 中配置 4096bytes 接入参数

OpenCode 可以通过 OpenAI 兼容 Provider 接入 4096bytes。你需要把控制台生成的 `opencode.json` 配置写入 OpenCode 配置文件。

推荐从控制台的 **使用密钥** 弹窗复制配置。弹窗会按 OpenCode 的格式带入当前 API Key、Base URL 和模型名。

## 准备工作

* 已完成 [创建账号](/quickstart/create-account)。
* 已完成 [获取 API Key](/quickstart/get-api-key)。
* 已安装 OpenCode，并确认 `opencode --version` 可以正常运行。
* 已从控制台打开目标 API Key 的 **使用密钥** 弹窗。

<Warning>
  `opencode.json` 中的 API Key 是明文保存的本机凭证。不要把包含完整 API Key 的配置文件、截图或终端输出提交到仓库，也不要发到聊天工具里。
</Warning>

## 安装客户端

如果你还没有安装 OpenCode，请先参考 [OpenCode 官方文档](https://opencode.ai/docs) 的最新说明。

macOS 或 Linux 可以使用官方安装脚本：

```bash theme={null}
curl -fsSL https://opencode.ai/install | bash
```

如果你更习惯用包管理器，也可以使用 npm：

```bash theme={null}
npm install -g opencode-ai
```

安装完成后，重新打开终端并确认命令可用：

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

## 从控制台复制配置

<Steps>
  <Step title="进入 API 密钥页面">
    打开控制台，进入 **API 密钥** 页面。
  </Step>

  <Step title="选择 OpenCode">
    找到要给 OpenCode 使用的 Key，点击 **使用密钥**，然后选择 **OpenCode**。
  </Step>

  <Step title="复制配置">
    复制控制台生成的 `opencode.json` 内容。示例仅用于参考，Base URL、API Key 和模型名都以控制台显示为准。
  </Step>

  <Step title="写入配置文件">
    如果要全局生效，写入 `~/.config/opencode/opencode.json`。如果只想在当前项目生效，也可以写入项目根目录的 `opencode.json`。
  </Step>
</Steps>

<img src="https://mintcdn.com/4096bytes/7pWq1xzEcc7dxxRs/images/screenshots/clients/opencode/opencode-api-key-use-dialog-header.png?fit=max&auto=format&n=7pWq1xzEcc7dxxRs&q=85&s=3451305bcb441125115bf5497bf7fb9e" alt="复制配置" width="720" style={{ maxWidth: "100%", height: "auto" }} data-path="images/screenshots/clients/opencode/opencode-api-key-use-dialog-header.png" />

## 配置文件位置

| 范围   | 路径                                 | 适合场景                 |
| ---- | ---------------------------------- | -------------------- |
| 全局配置 | `~/.config/opencode/opencode.json` | 让所有项目默认使用 4096bytes。 |
| 项目配置 | `opencode.json`                    | 只让当前项目使用这组配置。        |

如果文件不存在，请手动创建。项目配置优先级高于全局配置。

## 验证

保存配置后，进入一个项目目录并运行：

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

打开 OpenCode 后，可以先输入一个低风险任务：

```text theme={null}
请用一句话说明当前目录的用途，不要修改文件
```

如果 OpenCode 可以正常回复，并且没有认证失败或找不到模型的错误，说明配置已生效。

## 常见问题

<AccordionGroup>
  <Accordion title="OpenCode 报认证失败">
    检查 `opencode.json` 是否是合法 JSON。确认 `apiKey` 没有漏字符、换行或多余空格。
  </Accordion>

  <Accordion title="OpenCode 找不到模型">
    模型 ID 必须使用控制台显示的模型名。不要直接复制其他用户截图里的模型名。
  </Accordion>

  <Accordion title="配置后仍然没有生效">
    确认你修改的是 OpenCode 实际读取的配置文件。项目根目录的 `opencode.json` 会覆盖全局配置里的同名字段。
  </Accordion>

  <Accordion title="我可以用 /connect 配置 API Key 吗？">
    可以，但 `/connect` 只保存凭证。Provider、Base URL 和模型列表仍然建议使用控制台生成的 `opencode.json`。
  </Accordion>
</AccordionGroup>