# opencode 日常使用参考

## 启动方式

opencode 是 CLI 工具，不是 web 服务，直接在终端运行：

```bash
opencode                          # 进入 TUI 交互界面
opencode run "你好"               # 单次对话运行
opencode web                      # 启动 web 界面（端口 4096）
```

## 本地模型池（vLLM）

opencode 通过 wrapper 脚本 `~/.local/bin/opencode` 动态注入 qwen provider 到 `~/.cache/opencode/models.json`。

**可用模型**（2026-05-07）：
- `qwen/qwen3-coder-480b-a35b-instruct`

**API 端点**：`http://127.0.0.1:3000/v1`
**API Key**：`sk-0ExNiLblJvIWBDpkS50fwOBw4MmqLyKdHJK5iQtlw9dOMWBP`

## 指定模型运行

```bash
opencode run "你好" -m qwen/qwen3-coder-480b-a35b-instruct
```

## TUI 界面中选模型

进入 TUI 后：
- 按 `m` 或输入 `/model qwen` 切换模型
- 用 `qwen/qwen3-coder-480b-a35b-instruct` 模型 ID

## 验证模型可用性

```bash
opencode models qwen        # 列出 qwen provider 下所有模型
opencode run "say ok" -m qwen/qwen3-coder-480b-a35b-instruct
```

## wrapper 脚本原理

`~/.local/bin/opencode` 在每次启动时执行 Python 片段，将 qwen provider 注入 `~/.cache/opencode/models.json`：

```python
# 关键逻辑（每次启动都执行，保证 provider 存在）
d['qwen'] = {
    'id': 'qwen',
    'api': 'http://127.0.0.1:3000/v1',
    'models': {
        'qwen3-coder-480b-a35b-instruct': {
            'id': 'qwen/qwen3-coder-480b-a35b-instruct',
            'name': 'Qwen3-Coder-480B',
            ...
        }
    }
}
```

如果 wrapper 被修改或失效，qwen provider 不会自动出现在 `opencode models` 列表中。

## 常见问题

**症状**：TUI 界面提示 "no model configured" 或无法对话。
**原因**：未在启动时指定 `-m`，也没在 TUI 里选模型。
**解决**：`/model qwen` 选模型后再对话。