将 OpenCode CLI 与桌面版接入 Claude Code Router：Profile 配置全指南
将 OpenCode CLI 与桌面版接入 Claude Code RouterProfile 配置全指南【免费下载链接】claude-code-routerOne local control plane for every AI agent: route across models, fuse new capabilities, orchestrate tools, and stay fully in control.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-code-router导读OpenCode 是一类使用 OpenAI 兼容 Provider 模型的编程 Agent同时提供终端 CLI与桌面 App两种形态。在 Claude Code RouterCCR中你可以在Agent Config里为 OpenCode 建立 Profile把它的全部请求路由到 CCR 网关从而让 OpenCode 使用任何 CCR Provider 模型或 Fusion 模型甚至在 App 入口上绑定 AgentClaw 的 IM Bot。读完本文你将掌握 OpenCode Profile 的创建流程、字段含义、底层配置生成原理以及 CLI/App 两种打开方式与常见故障排查方法。Who this is for适用场景OpenCode 是一个基于 OpenAI 兼容 Provider 模型的编程 Agent。CCR 同时支持它的两个使用面OpenCode CLI—— 终端内的命令行 AgentOpenCode App—— 桌面应用。本页用于把 OpenCode 路由到任意 CCR Provider 或 Fusion 模型也可以为 App 绑定一个 IM Bot。初次接触 CCR建议先添加一个 Provider 和模型再开始创建 Profile。可参考 配置文件说明 与 Agent 使用指引 的既有内容。前置条件在开始配置前请确认以下三项均已满足CCR Desktop 正在运行且已配置至少一个 Provider 模型OpenCode CLI 已安装且opencode命令可用即存在于PATH环境变量中如果使用 App 模式还需安装 OpenCode Desktop 应用你已进入 CCR 的Agent Config页面准备点击Add profile。创建 Profile 的完整步骤在Agent Config上点击Add profile并选择OpenCode。填写一个Config name例如OpenCode - Work该名称将用于后续的启动命令。选择Effect scope生效范围与Entry mode入口模式。确认Provider ID、Provider name与OpenCode model三项内容。仅在本地环境确有需要时再调整高级设置。如果入口模式包含 App 且你正在使用 AgentClaw请绑定一个Bot。点击Save然后从 CCR 中打开 OpenCodeCLI 使用终端按钮App 使用播放按钮。打开按钮背后的实际工作从 CCR 打开 OpenCode 并不只是简单唤起进程对于桌面 AppCCR 会先定位已安装的可执行文件再以注入配置环境变量的方式启动它。在 App 启动实现 中可以看到CCR 会设置以下环境变量后再 spawn 进程CCR_PROFILE_SURFACEapp标识当前是 App 入口OPENCODE_CLIENTdesktopOPENCODE_CONFIGconfigFile与OPENCODE_CONFIG_CONTENTinlineConfig用于把 CCR 生成的配置直接投递给 OpenCode 进程而不依赖用户手改配置文件。同时它会把ELECTRON_RUN_AS_NODE从环境中删除避免 Electron 以 Node 模式被误启动。如果找不到 App会抛出带检测路径的错误提示Checked: ...并建议安装 OpenCode App 或设置OPENCODE_APP_PATH环境变量。App 可执行文件的探测顺序在 findInstalledOpenCodeAppExecutable 中CCR 依次尝试以下候选Profile 中显式配置的appPath环境变量CCR_OPENCODE_APP_PATH或OPENCODE_APP_PATH指向的路径各平台的常见安装位置macOS/Applications/OpenCode.app或~/Applications/OpenCode.app并从Info.plist中读取CFBundleExecutableWindows在OpenCode、opencode、OpenCode Desktop等目录中查找OpenCode.exe/opencode-desktop.exe必要时调用whereLinux从PATH、/opt/OpenCode、/usr/local/bin、/usr/bin下查找ai.opencode.desktop、opencode-desktop、OpenCode等命令名。配置参考字段说明表下表完整列出 OpenCode Profile 的核心字段、填写方式与作用字段如何设置作用Agent选择OpenCode在 CCR 中创建 OpenCode 的启动条目。Config name自由文本如OpenCode - Work用于标识该 Profile。桌面命令使用ccr-app nameCLI 命令使用ccr name。Enabled开关切换被关闭Disabled的 Profile 不会被应用也不会作为启动条目提供给用户。Effect scopeOnly opened from CCR/System default前者把改动限制在从 CCR 启动的会话内后者让该 Profile 成为系统默认的 OpenCode 配置。只允许存在一个启用的系统默认 OpenCode Profile。Entry modeCLI APP/CLI only/App only决定暴露哪些启动条目终端命令和/或 App。Provider ID默认claude-code-router该 OpenCode Profile 引用的 Provider 标识。Provider name自由文本默认Claude Code Router在 OpenCode 界面中展示的名称。OpenCode model一个 Provider 模型或 Fusion 模型OpenCode 经由 CCR 使用的默认模型。Config file路径仅用于系统默认System default的 OpenCode Profile。Environment variablesKey/value 行可选的高级覆盖项常规使用下保持为空即可。Bot选择一个已保存的 Bot仅 App 入口为 OpenCode App 条目绑定一个 AgentClaw IM Bot。配置写入的位置与文件路径规则不同Effect scope会决定配置写入哪个文件。在 resolveOpenCodeConfigFile 中可以看到如下规则ccr/custom范围配置写入 CCR 自己的配置目录路径为configDir/profiles/{slug}/opencode/opencode.jsonc其中{slug}由 Profile 名称规范化而来System default 范围若 Profile 指定了configFile则写入该路径否则写入 OpenCode 的标准配置目录macOS/Linux 取XDG_CONFIG_HOME默认~/.config优先写opencode/opencode.jsonc若该目录下只有opencode.json存在则改为写入opencode.json。当 CCR 将 Profile 应用于 OpenCode 时会生成一个 OpenAI 兼容的 Provider 条目并写入上述文件。核心逻辑在 openCodeGatewayOverrides生成结果的关键结构如下{ $schema: https://opencode.ai/config.json, model: claude-code-router/Provider/model, small_model: claude-code-router/Provider/model, provider: { claude-code-router: { name: Claude Code Router, npm: ai-sdk/openai-compatible, models: { // 为每个可用模型写入限流与模态信息 }, options: { apiKey: ccr 下发的访问令牌, baseURL: http://127.0.0.1:gateway-port/v1, headers: { x-ccr-client: opencode, x-ccr-profile: profile id/name } } } } }几个值得注意的底层细节均有对应实现与测试印证Provider ID 默认为claude-code-router模型引用格式为claude-code-router/Provider/model例如测试用例中的claude-code-router/Provider/model-a见 profile-config 测试baseURL指向 CCR 网关的/v1端点gatewayEndpoint会把0.0.0.0/::归一化为127.0.0.1从而保证 OpenCode 的所有请求都经过 CCR 的请求日志与路由x-ccr-client: opencode这个标识头同时用于后续判断“该配置是否为 CCR 托管”见 isManagedOpenCodeConfigContentsmall_model默认与主model相同供 OpenCode 的轻量任务复用每个模型条目会带上limit.context/limit.output与modalities输入模态自动并入text其数值来自 CCR 的模型目录与 ProvidermodelMetadata若解析不到则回退为默认 128000 上下文窗口与 8192 最大输出 token默认值定义在 profile-config.ts 顶部Fusion 视觉模型还会正确携带image输入模态所有生成的配置文件权限会被收紧为0o600在覆盖用户的原始配置文件前CCR 会先保留快照追加.ccr-original后缀并生成带时间戳的.ccr-backup-*备份文件确保用户原有设置可回滚。这一点在“全局配置保留用户原有设置并快照原始 JSONC”的测试中得到了验证。也就是说当你选择 OpenCode 作为 Agent 时CCR 不仅创建了“启动条目”还会像为一个普通 Provider 客户端写配置那样把网关端点、访问令牌、模型白名单完整注入到 OpenCode 的opencode.jsonc中——这正是“从 CCR 打开才生效”这一机制的实现来源。打开并使用创建并保存 Profile 后有 CLI 与 App 两种打开方式CLI点击桌面应用中的终端按钮并运行复制到的命令ccr-app OpenCode - Work对于纯 CLI 场景运行ccr OpenCode - WorkApp点击播放按钮以当前 Profile 打开 OpenCode Desktop。由于 OpenCode Desktop 是单实例应用CCR 会为你自动切换当前激活的 Profile而不是再启动第二个 App 实例。注意区分这两条命令的用途ccr-app用于从桌面环境启动并注入 App 所需配置而ccr直接驱动 CLI 场景。两条命令中的OpenCode - Work都是你在Config name中填写的名称。关于单实例openCodeAppLaunchArgs 的注释给出了原因OpenCode Desktop 在获取单实例锁之前会重置 Electron 的userData路径因此--user-data-dir会被忽略。CCR 据此把 OpenCode App 视为单实例并在 launch-service 中负责 Profile 的切换托管而不是依赖透传用户数据目录。相应的单测也确认了启动参数中不会出现被忽略的--user-data-dir见 opencode-profile-config.test.mjs。多实例多 Profile使用当你希望用不同模型或 Provider 工作时可以创建多个相互独立的 OpenCode Profile。但请记住OpenCode Desktop App 本身是单实例的因此不要在系统中强行启动第二个 App而应从 CCR 中切换 Profile。CLI 形态则天然支持按命令参数启动不同 Profile即运行多次ccr name即可。AgentClawBot 绑定当你在 Profile 中绑定了一个 Bot并且是从 CCR 打开 App 时OpenCode 就可以通过所选的 IM 渠道进行对话转发。也就是说你可以把聊天窗口里的 Agent 接力请求交给 OpenCode 会话处理。关于 Bot 的完整配置可参见 AgentClaw 文档。验证路由是否生效完成配置并打开 OpenCode 后建议按以下三步验证从 CCR 打开 OpenCode发送一条消息并确认它得到正常回复打开 CCR 中的Request logs请求日志确认该请求确实经过了网关。只有当请求出现在 CCR 的 Request logs 中才说明路由真正生效否则 OpenCode 可能仍在直连你自己的 Provider并未经过 CCR。常见问题排查请求绕过了 CCR请确认 Profile 是Enabled状态并且你是从 CCR 打开 OpenCode。直接手动启动的 OpenCode 不会受影响除非该 Profile 的范围是System default。opencode命令找不到请确保 OpenCode CLI 已安装并且opencode在启动 CCR Desktop 所用的同一个 shell 环境中可用即同一条PATH。App 没有切换 ProfileOpenCode Desktop 是单实例应用——请回到 CCR 中切换 Profile而不是尝试再开一个新 App 窗口。小结把 OpenCodeCLI 与 App接入 Claude Code Router 的核心思路是在 CCR 中创建一个 OpenCode Agent Profile明确生效范围仅 CCR 启动 / 系统默认与入口模式CLI / App由 CCR 向 OpenCode 的opencode.jsonc注入指向网关/v1的 OpenAI 兼容 Provider。之后无论是命令行里的ccr、桌面里的ccr-app还是 App 播放按钮OpenCode 的每次调用都会带上x-ccr-client: opencode标识进入 CCR从而实现统一路由、统一计费口径、统一请求日志与 IM 接力。如果你想进一步研究本文涉及的实现可以从这些仓库文件入手Profile 生成与文件路径规则packages/core/src/agents/opencode/profile-config.tsApp 探测与启动packages/core/src/agents/opencode/app-launch.ts生成结果与备份行为的验证用例packages/core/test/unit/agents/opencode-profile-config.test.mjs本文档原文docs/src/content/docs/en/configuration/agents/opencode.md【免费下载链接】claude-code-routerOne local control plane for every AI agent: route across models, fuse new capabilities, orchestrate tools, and stay fully in control.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-code-router创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考