Xpersona
agentCLAWHUBUnverified

opencode-responses-bridge-skill

Local stdlib-only proxy that adapts OpenAI Chat Completions to/from the Responses API so any OpenAI-compatible agent client (WorkBuddy, Cursor, Open WebUI, LobeChat, ...) can use Responses-API-only models such as OpenCode Go gpt-5.6-luna. Use when: setting up a Chat Completions to Responses API bridge, local proxy for responses-only models, fixing 'model only supports responses API', 'invalid_prompt' HTTP 400, 'custom model error 10000', or protocol transcoding for any Responses API endpoint (OPENCODE_UPSTREAM). 使用场景：协议转接/本地代理/把只支持 Responses API 的模型接入 OpenAI 兼容客户端/模型报 invalid_prompt 或自定义模型错误 10000。

OpenClaw
View on ClawHubHomepage

Rank

62

Safety

84

Downloads

2.3k

Updated

Oct 9, 2026

Version

0.1.0

Source

CLAWHUB

About

What it does, and when to use it.

Capability contract not published. No trust telemetry is available yet. 2.3K downloads reported by the source. Last updated 10/9/2026.

Avoid when

  • Contract metadata is missing or unavailable for deterministic execution.

Risk flags: missing_or_unavailable_contract, trust_data_unavailable, schema_references_missing

Public facts

Every fact links back to the source it came from.

Vendor
Clawhubvendor · observed Oct 9, 2026
Protocol compatibility
OpenClawcompatibility · observed Oct 9, 2026
Adoption signal
2.3K downloadsadoption · observed Oct 9, 2026
Latest release
0.1.0release · observed Aug 8, 2026
Handshake status
UNKNOWNsecurity

Install and run

Setup complexity: low.

clawhub skill install s179287h5dgtt822wrwrcv6nes8b3c0y:opencode-responses-bridge-skill
  1. Install using `clawhub skill install s179287h5dgtt822wrwrcv6nes8b3c0y:opencode-responses-bridge-skill` in an isolated environment before connecting it to live workloads.
  2. No published capability contract is available yet, so validate auth and request/response behavior manually.
  3. Review the upstream CLAWHUB listing at https://clawhub.ai/andypeng09/opencode-responses-bridge-skill before using production credentials.

Contract: missing

curl -s "https://www.xpersona.co/api/v1/agents/clawhub-andypeng09-opencode-responses-bridge-skill/snapshot"

Documentation

CLAWHUB

30,110 characters of source documentation, loaded on request.

Extracted files

5 files captured from the source.

SKILL.md

---
name: opencode-responses-bridge-skill
version: 1.1.0
description: "Local stdlib-only proxy that adapts OpenAI Chat Completions to/from the Responses API so any OpenAI-compatible agent client (WorkBuddy, Cursor, Open WebUI, LobeChat, ...) can use Responses-API-only models such as OpenCode Go gpt-5.6-luna. Use when: setting up a Chat Completions to Responses API bridge, local proxy for responses-only models, fixing 'model only supports responses API', 'invalid_prompt' HTTP 400, 'custom model error 10000', or protocol transcoding for any Responses API endpoint (OPENCODE_UPSTREAM). 使用场景：协议转接/本地代理/把只支持 Responses API 的模型接入 OpenAI 兼容客户端/模型报 invalid_prompt 或自定义模型错误 10000。"
agent_created: true
allowed-tools: python3, curl
metadata:
  openclaw:
    requires:
      bins:
        - python3
    envVars:
      - name: OPENCODE_UPSTREAM
        required: false
        description: Responses API endpoint to forward to (default https://opencode.ai/zen/go/v1/responses).
      - name: PROXY_HOST
        required: false
        description: Local listen host (default 127.0.0.1).
      - name: PROXY_PORT
        required: false
        description: Local listen port (default 8787).
    emoji: "🔄"
    homepage: https://github.com/ANDYPENG09/opencode-responses-bridge-skill
    os:
      - windows
      - macos
      - linux
---

# OpenCode Responses Bridge（Responses API ↔ Chat Completions 本地转接）

## Overview

许多 AI 客户端的自定义模型通道只发 OpenAI **Chat Completions** 请求，而部分上游模型
（典型：OpenCode Go 的 `gpt-5.6-luna`）只暴露 OpenAI **Responses API**，直接配置必然不可用
（典型报错：`invalid_prompt` / `Invalid Responses API request` / WorkBuddy「自定义模型错误 10000」）。

本技能提供**零依赖本地转接代理**：客户端把 Chat Completions 打到本机代理，代理翻译成
Responses API 转发给上游，再把返回翻回 Chat Completions（含流式 SSE、工具调用、reasoning、
多模态输入）。任何能配置 OpenAI 兼容模型地址的客户端都可以接入。

## 快速开始

### 1. 获取代理脚本
从本技能 `scripts/` 复制两个文件到任意稳定目录（例如 `~/responses-bridge/`）：
- `proxy.py`（纯 Python 标准库，Python 3.8+，无需安装依赖）
- `start_proxy.bat`（Windows 一键启动，双击即可；macOS/Linux 直接 `python3 proxy.py`）

### 2. 启动代理
```
python3 proxy.py        # 默认监听 http://127.0.0.1:8787
```
可选环境变量：`OPENCODE_UPSTREAM`（上游 Responses 端点，默认 OpenCode Go）、
`PROXY_HOST`（默认 127.0.0.1）、`PROXY_PORT`（默认 8787）。代理从入站请求的
`Authorization: Bearer <key>` 头取上游密钥透传，密钥只在客户端配置里维护一份。

### 3. 冒烟测试（不经客户端）
```
curl http://127.0.0.1:8787/v1/chat/completions \
	-H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" \
	-d '{"model":"gpt-5.6-luna","messages":[{"role":"user","content":"hi"}],"stream":false}'
```
返回 HTTP 200 且为 `chat.completion` 结构即通过。

### 4. 配置客户端
把客户端的自定义模型 URL 指向 `http://127.0.0.1:8787/v1/chat/completions`，模型名填上游
实际模型 ID（OpenCode Go 网关的模型 ID **不带前缀**，如 `gpt-5.6-luna`）。
分客户端示例见 `examples/`（WorkBuddy `models.json`、通用 OpenAI 兼容客户端、curl）。

### 5. 验证
在客户端发送一条消息，正常流式返回即成功。

## 核心能力

- **文本与流式**：非流式返回标准 `chat.completion`；流式输出标准 SSE（role 开头 → content 增量 → `[DONE]`）。
- **工具调用**：`tools`/`tool_choice` 双向映射；多轮 tool 循环（assistant `tool_calls` → `function_call`，tool 消息 → `function_call_output`）；流式多函数并发按 `item_id`

README.md

# OpenCode Responses Bridge (Chat Completions ↔ Responses API local adapter)

> **🌏 Languages:** [English](README.md) · [中文](README.zh-CN.md)

> **Skill Overview**
>
> **OpenCode Responses Bridge** is a zero-dependency local proxy that adapts OpenAI
> **Chat Completions** ↔ **Responses API**. It lets any OpenAI-compatible agent client
> (WorkBuddy, Cursor, Open WebUI, LobeChat, ...) use Responses-API-only models such as
> OpenCode Go `gpt-5.6-luna` — with streaming SSE, tool calls, reasoning passthrough and
> multimodal input. Python 3.8+, standard library only, no installs.
>
> **How to install**
>
> - **WorkBuddy / SkillHub:** install the skill from SkillHub (zip or CLI), then copy
>   `scripts/proxy.py` + `scripts/start_proxy.bat` to a stable folder and run it.
> - **ClawHub:** `clawhub install opencode-responses-bridge-skill`
> - **GitHub:** `git clone https://github.com/ANDYPENG09/opencode-responses-bridge-skill`
>
> **How to invoke**
>
> - Start the proxy: `python3 proxy.py` (defaults to `http://127.0.0.1:8787`).
> - Point your client's custom model URL at `http://127.0.0.1:8787/v1/chat/completions`.
> - Smoke test: `curl http://127.0.0.1:8787/v1/chat/completions -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" -d '{"model":"gpt-5.6-luna","messages":[{"role":"user","content":"hi"}],"stream":false}'`

---

## What problem does it solve

Custom-model channels in AI agent clients typically only speak the OpenAI **Chat Completions**
protocol, while some upstream models (typically OpenCode Go's `gpt-5.6-luna`) only expose the
OpenAI **Responses API**. Direct configuration always fails, with common errors:

- `HTTP 400 invalid_prompt` / `Invalid Responses API request`
- WorkBuddy "custom model error 10000"
- First message works, but **any message after history fails** (assistant history message
  `content` arrays are not converted)

This proxy performs a **local protocol translation**: client → Chat Completions → proxy →
Responses API → upstream → and back.

## Features

- **Zero dependencies**: pure Python standard library, Python 3.8+, no pip install
- **Streaming SSE**: fully translated (role first → content deltas → `[DONE]`)
- **Tool calls**: `tools`/`tool_choice` bidirectional mapping, multi-round tool loops,
  concurrent streaming function calls with no lost arguments
- **Reasoning**: upstream reasoning summaries → `reasoning_content` passthrough
- **Multimodal**: `image_url` (URL / base64 data URL) → `input_image`
- **Configurable upstream**: `OPENCODE_UPSTREAM` points to any Responses API endpoint,
  not limited to OpenCode Go
- **Single-point key management**: the proxy relays the key from the inbound `Authorization`
  header; it never writes keys to disk or code

## Quick start

```
# 1. Start the proxy (on Windows, double-click scripts/start_proxy.bat)
python3 proxy.py                      # defaults to http://127.0.0.1:8787
# 2. Smoke test
curl http://127.0.0.1:8787/v1/chat/completions \
	-H "Authorization: Bearer

_meta.json

{
  "ownerId": "kn778b36z5e9wm29y1m36g4m7h8b269f",
  "slug": "opencode-responses-bridge-skill",
  "version": "0.1.0",
  "publishedAt": 1786174229304
}

references/protocol-mapping.md

# Responses API <-> Chat Completions 协议映射参考

本文件记录代理 `scripts/proxy.py` 的协议转换细节，供排障或扩展时查阅。
映射遵循 OpenAI 官方 Responses API / Chat Completions 规范，适用于任意 OpenAI 兼容上游；
文中结论来自 2026-08-06 对 OpenCode Go 网关的实测（模型 `gpt-5.6-luna`、`deepseek-v4-flash`）。

## 1. 端点到模型能力对照（OpenCode Go，实测）

| 模型 | 端点 | 协议 | WorkBuddy 是否可直接用 |
|---|---|---|---|
| `deepseek-v4-flash` | `https://opencode.ai/zen/go/v1/chat/completions` | Chat Completions | ✅ 直接配置即可 |
| `gpt-5.6-luna` | `https://opencode.ai/zen/go/v1/responses` | Responses API | ❌ 需本代理转接 |

## 2. 关键坑

- **模型 ID 不带前缀**：Go 网关模型 ID 是 `gpt-5.6-luna` / `deepseek-v4-flash`。
  加 `opencode-go/` 前缀会返回 **HTTP 401**（网关按模型名做权限判定，误以为无权限）。
- **Cloudflare 拦截**：urllib 默认 UA 会触发 Cloudflare `error code: 1010`（403）。
  代理已内置浏览器 UA + `Accept: application/json, text/event-stream`。
- **鉴权**：`Authorization: Bearer <key>`，Go 与 Zen 共用控制台同一把 API key；
  订阅 Go 后该 key 对 Go 端点生效。
- **assistant/content 数组必须转换（重要 bug，2026-08-06 修复）**：WorkBuddy 的会话历史
  会把 assistant 消息的 `content` 序列化成数组（`[{"type":"text","text":...}]`）。
  Chat Completions 的 part 类型 `text` 在 Responses API 里**不存在**，原样透传会被网关判
  `HTTP 400 invalid_prompt`（`Invalid Responses API request`）。代理必须把所有文本 part
  统一重写为 `input_text`（user）或 `output_text`（assistant），图片 part → `input_image`。
  症状：新会话第一条能用，一旦对话有历史（含 assistant 数组消息）就报
  `自定义模型 xxx 错误 10000`（Trace ID 只出现在 WorkBuddy 侧）。

## 3. 请求转换（Chat Completions -> Responses API）

| Chat Completions | Responses API |
|---|---|
| `messages[]` role=system | 顶层 `instructions`（多条拼接；content 为数组时拼接其文本 part） |
| `messages[]` role=user content=string | `{"role":"user","content":[{"type":"input_text","text":...}]}` |
| user content part `{"type":"text","text":...}` | `{"type":"input_text","text":...}` |
| user content part `{"type":"image_url","image_url":{"url":...}}` | `{"type":"input_image","image_url":...}` |
| assistant content=string | `{"role":"assistant","content":[{"type":"output_text","text":...}]}` |
| assistant content=数组 `[{"type":"text",...}]` | `{"role":"assistant","content":[{"type":"output_text","text":...}]}`（**必须重写类型，否则 invalid_prompt**） |
| assistant `tool_calls[]` | `{"type":"function_call","call_id","name","arguments"}`（arguments 为 JSON 字符串） |
| role=tool 消息 | `{"type":"function_call_output","call_id","output"}` |
| `tools[]` `{type:function,function:{name,description,parameters}}` | `{type:function,name,description,parameters}` |
| `tool_choice` `{type:function,function:{name}}` | `{type:function,name}` |
| `max_tokens` / `max_completion_tokens` | `max_output_tokens` |

## 4. 响应转换（Responses API -> Chat Completions）

| Responses API | Chat Completions |
|---|---|
| `output[].type=message` + `content[].type=output_text` | `choices[0].message.content` |
| `output[].type=function_call`（含 `call_id`/`name`/`arguments`） | `choices[0].message.tool_calls[]`，`finish_reason=tool_calls` |
| `output[].type=reasoning` + `summary[].text` | `message.reasoning_content` |
| `usage.input_tokens/output_tokens/total_tokens` | `usage.prompt_tokens/completion_tokens

examples/basic.md

# 示例：curl 输入/输出对

以下请求直接打向本地代理 `http://127.0.0.1:8787/v1/chat/completions`，密钥放在
`Authorization: Bearer <你的上游key>` 头。返回均为标准 OpenAI Chat Completions 结构。

## 1. 文本（非流式）

```
curl http://127.0.0.1:8787/v1/chat/completions \
	-H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" \
	-d '{"model":"gpt-5.6-luna","messages":[{"role":"user","content":"What is 2+3? Answer in one short sentence."}],"max_tokens":80,"stream":false}'
```

期望输出（节选）：
```
{
	"object": "chat.completion",
	"model": "gpt-5.6-luna",
	"choices": [
		{"index": 0, "message": {"role": "assistant", "content": "2 + 3 equals 5."}, "finish_reason": "stop"}
	],
	"usage": {"prompt_tokens": 19, "completion_tokens": 12, "total_tokens": 31}
}
```

## 2. 流式（SSE）

```
curl -N http://127.0.0.1:8787/v1/chat/completions \
	-H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" \
	-d '{"model":"gpt-5.6-luna","messages":[{"role":"user","content":"Count 1 to 5, one per line."}],"max_tokens":80,"stream":true}'
```

期望输出（节选）：
```
data: {"choices":[{"delta":{"role":"assistant"},"finish_reason":null}]}
data: {"choices":[{"delta":{"content":"1\n2\n3\n4\n5"},"finish_reason":null}]}
data: {"choices":[{"delta":{},"finish_reason":"stop"}]}
data: [DONE]
```

## 3. 工具调用

```
curl http://127.0.0.1:8787/v1/chat/completions \
	-H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" \
	-d '{"model":"gpt-5.6-luna",
		"messages":[{"role":"user","content":"What is the weather in Shanghai? Use the get_weather tool."}],
		"tools":[{"type":"function","function":{"name":"get_weather","description":"Get weather for a city",
			"parameters":{"type":"object","properties":{"city":{"type":"string"}},"required":["city"]}}}],
		"tool_choice":"auto","stream":false}'
```

期望输出（节选）：
```
{
	"choices": [
		{"index": 0,
			"message": {"role": "assistant", "content": null,
				"tool_calls": [{"id": "call_...", "type": "function",
					"function": {"name": "get_weather", "arguments": "{\"city\":\"Shanghai\"}"}}]},
			"finish_reason": "tool_calls"}
	]
}
```

## 4. 多模态输入（图片）

```
curl http://127.0.0.1:8787/v1/chat/completions \
	-H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" \
	-d '{"model":"gpt-5.6-luna",
		"messages":[{"role":"user","content":[
			{"type":"text","text":"What color is this image? Answer in one word."},
			{"type":"image_url","image_url":{"url":"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg=="}}
		]}],
		"max_tokens":300,"stream":false}'
```

期望输出（节选）：`content` 为模型对图片的回答（如 "Gray"），上游推理摘要出现在
`reasoning_content` 字段。

Related agents

Same protocol, similar job.

Github ReposUpdated 9h agoRank 70

AionUi

Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!

MCPOPENCLAW
Github ReposUpdated 6mo agoRank 70

activepieces

AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents

OPENCLAW
Github ReposUpdated 6mo agoRank 70

cherry-studio

AI productivity studio with smart chat, autonomous agents, and 300+ assistants.

MCPOPENCLAW
Github ReposUpdated 7mo agoRank 70

CopilotKit

The Frontend for Agents & Generative UI. React + Angular

OPENCLAW

Machine-readable data

The same record, as JSON, for agents and crawlers.

{
  "facts": [
    {
      "factKey": "vendor",
      "category": "vendor",
      "label": "Vendor",
      "value": "Clawhub",
      "href": "https://clawhub.ai/andypeng09/skills/opencode-responses-bridge-skill",
      "sourceUrl": "https://clawhub.ai/andypeng09/skills/opencode-responses-bridge-skill",
      "sourceType": "profile",
      "confidence": "medium",
      "observedAt": "2026-10-09T16:34:36.719Z",
      "isPublic": true
    },
    {
      "factKey": "protocols",
      "category": "compatibility",
      "label": "Protocol compatibility",
      "value": "OpenClaw",
      "href": "https://www.xpersona.co/api/v1/agents/clawhub-andypeng09-opencode-responses-bridge-skill/contract",
      "sourceUrl": "https://www.xpersona.co/api/v1/agents/clawhub-andypeng09-opencode-responses-bridge-skill/contract",
      "sourceType": "contract",
      "confidence": "medium",
      "observedAt": "2026-10-09T16:34:36.719Z",
      "isPublic": true
    },
    {
      "factKey": "traction",
      "category": "adoption",
      "label": "Adoption signal",
      "value": "2.3K downloads",
      "href": "https://clawhub.ai/andypeng09/opencode-responses-bridge-skill",
      "sourceUrl": "https://clawhub.ai/andypeng09/opencode-responses-bridge-skill",
      "sourceType": "profile",
      "confidence": "medium",
      "observedAt": "2026-10-09T16:34:36.719Z",
      "isPublic": true
    },
    {
      "factKey": "latest_release",
      "category": "release",
      "label": "Latest release",
      "value": "0.1.0",
      "href": "https://clawhub.ai/andypeng09/opencode-responses-bridge-skill",
      "sourceUrl": "https://clawhub.ai/andypeng09/opencode-responses-bridge-skill",
      "sourceType": "release",
      "confidence": "medium",
      "observedAt": "2026-08-08T07:30:29.304Z",
      "isPublic": true
    },
    {
      "factKey": "handshake_status",
      "category": "security",
      "label": "Handshake status",
      "value": "UNKNOWN",
      "href": "https://www.xpersona.co/api/v1/agents/clawhub-andypeng09-opencode-responses-bridge-skill/trust",
      "sourceUrl": "https://www.xpersona.co/api/v1/agents/clawhub-andypeng09-opencode-responses-bridge-skill/trust",
      "sourceType": "trust",
      "confidence": "medium",
      "observedAt": null,
      "isPublic": true
    }
  ],
  "events": [
    {
      "eventType": "release",
      "title": "Release 0.1.0",
      "description": "- Major update: introduces a zero-dependency local proxy to bridge OpenAI Chat Completions with Responses API-only models. - Supports seamless use of OpenAI-compatible clients with Responses-API-only models like OpenCode Go gpt-5.6-luna. - Enables streaming, tool call/function support, reasoning content, and multi-modal input through protocol conversion. - Provides easy setup via Python script; configurable upstream endpoint and proxy host/port. - Adds troubleshooting guide, compatibility notes, and extensive usage examples and protocol mapping docs.",
      "href": "https://clawhub.ai/andypeng09/opencode-responses-bridge-skill",
      "sourceUrl": "https://clawhub.ai/andypeng09/opencode-responses-bridge-skill",
      "sourceType": "release",
      "confidence": "medium",
      "observedAt": "2026-08-08T07:30:29.304Z",
      "isPublic": true
    }
  ]
}

Record generated Oct 10, 2026.

Sponsored

Ads related to opencode-responses-bridge-skill and adjacent AI workflows.