# OpenCode (/docs/cookbook/coding-agents/opencode)







把 Praxis 接入 [OpenCode](https://opencode.ai)——开源终端编程智能体。项目里放一个 `opencode.json` 声明 provider，密钥走环境变量，`opencode run` 即通。

每一步都标了**期望结果**：照做即可，也可以把本页直接交给能操作电脑的 AI 助手，让它替你完成安装、配置与验证。

## 你将完成 [#你将完成]

* 在终端用 `opencode run` 调 Praxis 的模型
* 完成标志：`opencode run "…"` 收到模型回复
* 预计耗时：**3–5 分钟**（不含 Node.js 安装）
* 支持协议：OpenAI 兼容（`/openai/v1`）

## 前提 [#前提]

开始前逐项确认：

* **一个 Praxis API Key**（`sk-praxis-` 开头）。没有就到 [控制台 → API Keys](https://console.deepraxis.ai/keys) 创建：点「创建 Key」，名称必填，有效期可选 30/60/90 天或永久、默认 90 天；创建成功弹窗会展示完整 Key 并带「复制 Key」，关闭后列表只显示掩码，随时可点行内复制图标重新获取完整 Key。期望：弹出「创建 API Key」对话框，提交后弹窗展示完整 Key 与「复制 Key」按钮。新账号自带 **$1 免费额度**。完整流程见[快速开始](/docs/cloud/services/model/quickstart)。
* **Node.js 18 或更高**（`node --version` 检查）。
* **安装 OpenCode**：

  ```bash
  npm install -g opencode-ai
  ```

  期望：`opencode --version` 输出版本号（本页以 1.19.0 为准）。若 npm 提示平台包问题，按提示补装对应平台包（Linux x64 为 `npm install -g opencode-linux-x64`）。

## 配置 [#配置]

**第 1 步：设置密钥环境变量**

```bash
export PRAXIS_API_KEY=sk-praxis-你的Key
```

想持久化就把这行加进 `~/.bashrc` 或 `~/.zshrc`。Windows PowerShell：`$env:PRAXIS_API_KEY="你的Key"`。

期望：`echo $PRAXIS_API_KEY` 输出你的 Key（PowerShell 用 `echo $env:PRAXIS_API_KEY`）。

**第 2 步：在项目里声明 provider**

进入你的代码项目目录，创建 `opencode.json`：

```json
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "praxis": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Praxis",
      "options": {
        "baseURL": "https://api.deepraxis.ai/openai/v1",
        "apiKey": "{env:PRAXIS_API_KEY}"
      },
      "models": {
        "deepseek-flash": {}
      }
    }
  },
  "model": "praxis/deepseek-flash"
}
```

三处说明：

* `npm` 指定 OpenCode 用 `@ai-sdk/openai-compatible` 驱动对话——OpenCode 的 provider 体系建立在 AI SDK 之上，首次运行会自动装驱动。
* `apiKey` 用 `{env:PRAXIS_API_KEY}` 引用环境变量——密钥不落文件。
* 模型以 `provider/模型ID` 的命名空间引用；`deepseek-flash` 是平台示例模型。

期望：文件保存即生效。

<img alt="终端里查看 opencode.json 的实际内容" src="__img0" />

## 验证 [#验证]

在项目目录里运行：

```bash
opencode run "用中文回复四个字：连接成功"
```

期望：末行为模型回复 `连接成功`（其前有一行会话标题，如 `> build · deepseek-flash`）——**收到回复即接入成功**。去掉 `run` 直接运行 `opencode`，进入交互式终端界面。

<img alt="终端运行 opencode run 的真实输出" src="__img1" />

也可以在命令行完成等价验证。以下命令为 macOS / Linux / WSL（bash）写法；Windows PowerShell 用户：上面的 `opencode run` 已成功即可跳过；如需命令行验证，先执行 `$env:PRAXIS_API_KEY="你的Key"`，用 `curl.exe`（PowerShell 的 `curl` 是别名，语法不同），并把命令并成一行（去掉行尾 `\`）。

```bash
export PRAXIS_API_KEY=sk-praxis-你的Key
```

```bash
curl https://api.deepraxis.ai/openai/v1/chat/completions \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "deepseek-flash", "messages": [{"role": "user", "content": "你好"}]}' \
  -w '\nHTTP %{http_code}\n'
```

期望：HTTP 200 即接入成功，`choices[0].message.content` 是回复文本（响应出现 `reasoning` / `reasoning_details` 字段也正常——推理模型的思维链）。

最后看一眼 [控制台 → 用量与费用](https://console.deepraxis.ai/usage)：刚才的调用已经记在账上——每一次调用都有账、可追溯。用量页默认按资源聚合展示，点「查看用量明细」或某资源行可逐笔核对。

## 常见问题 [#常见问题]

| 症状                                                 | 原因                               | 解法                                                                              |
| -------------------------------------------------- | -------------------------------- | ------------------------------------------------------------------------------- |
| 401 / Missing authentication                       | 密钥未导出，或 `apiKey` 没用 `{env:…}` 引用 | 先 `echo $PRAXIS_API_KEY` 检查；确认 `apiKey` 写的是 `{env:PRAXIS_API_KEY}`              |
| 报 `EACCES`（mkdir `~/.local/share` 或 `~/.config` 等） | OpenCode 需要可写的用户数据目录，当前环境不可写     | 把 `XDG_DATA_HOME`/`XDG_CONFIG_HOME`/`XDG_STATE_HOME`/`XDG_CACHE_HOME` 指向可写目录后重试 |
| 报平台包安装失败                                           | npm 没装对平台的二进制包                   | 按报错提示补装（Linux x64 为 `opencode-linux-x64`）                                       |
| 404 / 路径不存在                                        | `baseURL` 写错                     | 必须是 `https://api.deepraxis.ai/openai/v1`（以 `/openai/v1` 结尾）                     |
| 模型不存在                                              | 模型 ID 与目录不一致                     | 到[控制台 → 模型 → 模型目录](https://console.deepraxis.ai/models)复制确切 ID                  |

## 进阶 [#进阶]

* **查这次对话花了多少钱**：[控制台 → 用量与费用](https://console.deepraxis.ai/usage)，按次计费、无闲置费
* **换模型**：在 `models` 里加目录中的其他 ID（如 `claude-opus-5`），并把 `model` 改成 `praxis/<新ID>`
* **在项目里用**：交互模式能读文件、改代码、执行命令，敏感动作会先征求你的确认

## 相关食谱 [#相关食谱]

* [Claude Code](/docs/cookbook/coding-agents/claude-code) · [Codex](/docs/cookbook/coding-agents/codex)（姊妹篇）
* 偏好 SDK 编程？看 [Vercel AI SDK](/docs/cookbook/sdk/vercel-ai-sdk)（OpenCode 的 provider 体系同源）