WARNING

本文档由 AI 自动翻译，仅供参考。涉及关键操作或信息时，请以英文原文为准。

将 OpenCode 设置为你的 AI 编码代理

适用 Olares 版本: 1.12.7+▾

Olares 1.12.7+Olares 1.12.6

OpenCode 是一个 AI 驱动的编码代理，允许你通过自然语言编写、测试和管理代码。它支持多个 AI 提供方，并可以从聊天界面运行 shell 命令、创建文件和安装开发环境。

在 Olares 上，你可以通过两种方式使用 OpenCode：

• 浏览器：在 Olares 上将 OpenCode 安装为应用，并通过浏览器访问它。
• 本地 CLI：在你的计算机上安装 OpenCode，并将其连接到 Olares 上的模型，以获得原生终端体验。

学习目标

在本教程结束时，你将学习如何：

• 在 Olares 上安装 OpenCode，并将其连接到本地模型或 OpenAI。
• 通过聊天界面或基于终端的 UI（TUI）创建项目和运行编码任务。
• 通过 LarePass VPN 从你的本地计算机使用 OpenCode，或从 VS Code 内部使用。
• 编辑 OpenCode 配置文件以管理提供方、模型和工具。

前提条件

开始前，你需要：

• 一台运行 Olares 1.12.7 或更高版本、具有足够磁盘空间和内存的 Olares 设备。

• 使用本地模型时，能够访问 Router。

• 从 Market 安装应用的管理员权限。

• 其他条件取决于 OpenCode 的使用方式：

  使用方式	所需条件
  在浏览器中使用本地模型	从 Market 安装 Qwen3.8-27B (llama.cpp)
  在浏览器中使用 OpenAI	ChatGPT Plus/Pro 账号或 OpenAI API key
  在计算机上使用 OpenCode CLI	Olares 上已配置 Router 默认聊天模型，并已创建 Router API 密钥。

可选：使用其他模型

从应用市场安装其他聊天模型，或通过引擎基座应用创建模型实例，然后在 Router 的 Default models 页面将其设为默认聊天模型。使用 default-chat 的客户端会调用新的默认模型，无需修改客户端的模型设置。

如果希望某个客户端始终使用指定模型，可改填 Router 的 How to call this model 窗口中显示的完整模型名称。

在浏览器中运行 OpenCode

此选项在你的 Olares 设备上将 OpenCode 安装为应用。你通过浏览器访问它。

安装 OpenCode

1. 打开 Market 并搜索 "OpenCode"。

2. 点击 Get，然后点击 Install，等待安装完成。

安装后，你将在 Launchpad 上看到两个图标：

• OpenCode：OpenCode 的主界面。
• OpenCode Terminal：OpenCode 的命令行终端。如果你更喜欢在 TUI 中工作，请使用此选项。

获取模型连接信息

计划使用 oh-my-openagent？

对于 oh-my-openagent 下的多本地模型设置，请使用单一模型应用。每个模型都有自己的端点，这允许你将其注册为单独的提供方，并调整每个模型的设置（如并发限制）。

模型连接的工作原理

在 Olares 1.12.7 及以上版本中，AI 客户端通过 Olares Router 连接模型。Router 提供 Base URL，并将 default-chat 的请求转发给**默认模型（Default models）**页面中设置的聊天模型。

本教程使用 Qwen3.8-27B (llama.cpp) 作为默认聊天模型。连接格式和 API 密钥要求详见连接 AI 应用。

本示例中，OpenCode 通过 OpenAI-compatible API 格式连接 Qwen3.8-27B：

1. 从启动台打开 Router。在 Default models 页面将 Qwen3.8-27B (llama.cpp) 设为默认聊天模型。

2. 进入 LLM 页面，找到 Qwen3.8-27B (llama.cpp)，点击模型所在行的 View connection example 图标。

3. 在 How to call this model 窗口中，选择 Apps in Olares，复制完整的 Base URL，保留末尾的 /v1。

4. 模型名称使用 default-chat。

   在应用中选择模型

   default-chat 是路由名称，不会出现在从 Router 获取的模型列表中。如果要连接 Router 的应用会加载模型列表，请手动添加 default-chat。如果应用只允许选择列表中的模型，请选择 Router 的 How to call this model 窗口中显示的完整模型名称。

5. API 密钥留空。如果要连接 Router 的应用要求填写此字段，请填入 olares。

连接到自定义提供方

在 OpenCode 中将 Qwen3.8-27B 添加为自定义提供方。

1. 在 OpenCode 中，点击左下角的 settings。

2. 选择 Providers，然后向下滚动并选择 Custom Provider 旁边的 Connect。

3. 输入以下详细信息：

   • Provider ID：输入唯一标识符，例如 olares。
   • Display name：输入提供方列表中显示的名称，例如 Router chat。
   • Base URL：粘贴从 Router 复制的 Base URL，并按显示内容原样使用。
   • Models：
     • Model ID：填写 default-chat。
     • Display Name：输入该模型的显示名称，例如 Router chat。

4. 点击 Submit 保存配置。你新添加的提供方将出现在提供方列表中。

连接到 OpenAI

OpenCode 支持两种连接 OpenAI 的实用方式：

• 浏览器登录：推荐用于 ChatGPT Plus 或 Pro 账户。
• API key：简单直接。即使你也有 ChatGPT 订阅，OpenAI 也会根据 token 使用量单独计费 API 使用。

不要使用无头登录

无头登录方法容易出现 OpenAI 安全检查导致的已知故障。失败后，登录流可能会在短时间内无法恢复。请改用浏览器登录或 API key。

创建项目

默认工作空间是 Files 中的 Home/Code。点击左侧导航栏中的 + 创建项目。

要处理多个项目，首先在 Home/Code 下创建子文件夹：

1. 打开 Files 并导航到 Home/Code/。

2. 为每个项目创建一个子文件夹。

3. 返回 OpenCode，点击 +，然后打开带有子文件夹名称的项目。

开始编码

你现在可以通过聊天界面与 OpenCode 交互。

1. 选择一个项目以打开编码代理界面。

2. 在聊天框下方，选择 Big Pickle 打开模型选择器，然后从列表中选择 Router chat。

3. 用自然语言输入编码任务。

4. 点击 folder_open 打开文件浏览器并查看生成的代码。

5. 使用 @ 在聊天窗口中提及文件，并要求 OpenCode 编辑它。

使用 TUI

OpenCode 还提供基于终端的 UI（TUI）。你可以通过两种方式启动它：

• 在 OpenCode UI 内部：在 OpenCode UI 底部打开终端面板，类似于 VS Code 的集成终端。代理聊天在上方保持可见，而 TUI 在面板中运行。
• 从 OpenCode Terminal：从 Launchpad 打开 OpenCode Terminal。它直接打开到命令行，没有聊天 UI。

从你的计算机运行 OpenCode

此可选流程在你的计算机上安装 OpenCode CLI，并通过 API 密钥连接 Olares Router。

安装 OpenCode CLI

1. 使用官方安装程序安装 CLI：

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

2. （可选）如果你遇到 No config file found for zsh 错误，请通过运行以下命令将 export 行添加到你的 ~/.zshrc 文件：

   echo 'export PATH="$HOME/.opencode/bin:$PATH"' >> ~/.zshrc

   错误消息示例：

   No config file found for zsh. You may need to manually add to PATH:
   export PATH=/Users/{username}/.opencode/bin:$PATH

3. 重新加载你的 shell 配置：

   source ~/.zshrc

4. 验证安装：

   opencode --version

   显示版本，例如 1.15.6。

5. 运行以下命令初始化 OpenCode 并创建配置文件：

   opencode

   配置文件在 ~/.config/opencode/opencode.jsonc 创建。

获取 Router 连接信息

1. 打开 Router，在 Default models 页面将 Qwen3.8-27B (llama.cpp) 设为默认聊天模型。然后在 LLM 页面找到该模型，点击 View connection example。
2. 在 How to call this model 窗口选择 Devices in LAN 或 Remote，复制 Base URL。
3. 在 API keys 页面创建密钥，供电脑上的 OpenCode 使用。使用 VPN 也需要此密钥。

配置连接

1. 在运行 OpenCode 的终端中，将 OLARES_ROUTER_API_KEY 环境变量设为刚创建的 Router 密钥。
2. 打开 ~/.config/opencode/opencode.jsonc，添加以下配置。将 <router-base-url> 替换为从 Router 复制的完整地址，保留 /v1。

{
  "$schema": "https://opencode.ai/config.json",
  "model": "olares/default-chat",
  "provider": {
    "olares": {
      "name": "Olares Router",
      "npm": "@ai-sdk/openai-compatible",
      "options": {
        "baseURL": "<router-base-url>",
        "apiKey": "{env:OLARES_ROUTER_API_KEY}"
      },
      "models": {
        "default-chat": { "name": "Router chat" }
      }
    }
  }
}

3. 保存文件，重新启动 OpenCode。

启动 OpenCode TUI

1. 在你的终端中，运行 opencode 启动 TUI：

2. 使用 /models 命令切换到 Router chat。

3. 开始与你的自托管模型聊天。

首次连接

首次连接可能需要更长时间才能建立。

在 VS Code 中使用 OpenCode

要直接使用你的代码库，请在 VS Code 中打开终端并从项目目录运行 opencode。

编辑配置文件

OpenCode 将其配置存储在 JSON 文件中。你可以直接编辑此文件以管理提供方、模型和工具。

1. 打开 Files 并导航到 Application/Data/opencode/.config/opencode/。

2. 右键点击 opencode.jsonc 并选择 Rename。

3. 将文件重命名为 config.json，以便你可以在 Files 中直接编辑它。OpenCode 识别这两个扩展名。

4. 打开 config.json 并点击 edit_square 编辑它。

5. 保存更改。

6. 从 Settings > Applications 重启 OpenCode 以应用更改。

了解更多

• 管理包：安装系统级和语言特定的包。
• 技能和插件：通过技能和插件添加功能。
• 使用 Olares CLI 管理 Olares：认证 Olares CLI，让 Agent 管理设备上的文件和应用。
• 使用 oh-my-openagent 编排多代理工作流：启用 OMO 以在 OpenCode 中运行多代理协作。
• 常见问题：已知问题的解决方案。
• 使用 Context7 将 AI 编码助手连接到最新文档：在 OpenCode 中将 Context7 注册为远程 MCP 服务器。
• OpenCode 官方文档