[Bug]: Volcengine Ark Agent Plan Responses URL incorrectly appends /v1

[lijianmac]

Client or integration

Codex App

Provider or upstream service

Volcengine Ark (火山方舟) Agent Plan

OpenCodex version

2.7.33

Endpoint or capability

OpenAI Responses API at /api/plan/v3/responses

Current behaviour

When a key-auth provider uses the openai-responses adapter with this Agent Plan base URL:

https://ark.cn-beijing.volces.com/api/plan/v3

OpenCodex constructs the upstream URL as:

https://ark.cn-beijing.volces.com/api/plan/v3/v1/responses

The extra /v1 causes the upstream request to return 404 Not Found.

The current key-auth branch in src/adapters/openai-responses.ts always removes only a trailing /v1 and then appends /v1/responses:

const base = provider.baseUrl.replace(/\/v1\/?$/, "");
url = `${base}/v1/responses`;

As a temporary workaround, switching the provider to openai-chat succeeds through /api/plan/v3/chat/completions, but this translates the Codex Responses request to Chat Completions and does not use the provider's native Responses endpoint.

Expected behaviour

OpenCodex should support key-auth OpenAI-compatible providers whose configured base URL already contains a provider-specific version path. For Volcengine Ark Agent Plan, the request should be sent to:

https://ark.cn-beijing.volces.com/api/plan/v3/responses

Ideally this should be configurable (for example, an explicit Responses endpoint/path or a baseUrl mode that appends only /responses) rather than hard-coded specifically for Volcengine. Existing providers that expect /v1/responses should keep their current behaviour.

Minimal redacted request or reproduction

# Provider configuration (API key redacted)
{
  "adapter": "openai-responses",
  "baseUrl": "https://ark.cn-beijing.volces.com/api/plan/v3",
  "authMode": "key",
  "apiKey": "<REDACTED>",
  "defaultModel": "glm-5-2"
}

# Request sent to OpenCodex
curl -X POST http://127.0.0.1:10100/v1/responses \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "<provider-name>/glm-5-2",
    "input": "Reply exactly: OK",
    "stream": false
  }'

Actual response or error

unexpected status 404 Not Found: Unknown error,
url: http://127.0.0.1:10100/v1/responses

# Resolved upstream URL:
https://ark.cn-beijing.volces.com/api/plan/v3/v1/responses

Upstream documentation

• Volcengine Ark Responses API documentation: https://www.volcengine.com/docs/82379/1795150
• Volcengine Ark Agent Plan / Coding Plan documentation section: https://www.volcengine.com/docs/82379/1261474

The public Responses API example follows the same convention: a versioned base URL (for example, https://ark.cn-beijing.volces.com/api/v3) with the client appending /responses. The Agent Plan base is https://ark.cn-beijing.volces.com/api/plan/v3, so its concrete Responses endpoint is /api/plan/v3/responses.

Suggested mapping or implementation notes

Possible backward-compatible approaches:

1. Add an optional provider field such as responsesPath or responsesUrl.
2. Add a setting indicating that baseUrl is already the complete versioned API base, so the adapter appends only /responses.
3. As a narrower compatibility rule, recognize Volcengine Ark /api/plan/v3 and /api/coding/v3 bases and append /responses.

An explicit configurable endpoint/path seems the most general solution because other OpenAI-compatible providers may also use non-/v1 version paths.

Additional context and attachments

• The same provider and model work through OpenCodex's openai-chat adapter at /api/plan/v3/chat/completions (HTTP 200), confirming that authentication, model name, and the base service are valid.
• This report is specifically about native Responses URL construction, not model discovery.
• No API keys or credentials are included.

Checks

• I searched existing provider and compatibility issues.
• The request and response were redacted.
• The expected behaviour is based on upstream documentation and a concrete client requirement.

[lidge-jun]

Fixed on codex/bucket2-fixes-260723 (commit f464f96), scheduled for the next release.

Implemented as an optional, validated relative responsesPath provider field — your proposal 1. For Ark Agent Plan:

{
  "adapter": "openai-responses",
  "baseUrl": "https://ark.cn-beijing.volces.com/api/plan/v3",
  "responsesPath": "/responses",
  "authMode": "key"
}

The adapter now sends {trimmedBaseUrl}{responsesPath} → /api/plan/v3/responses. When the field is absent, the legacy /v1/responses construction is byte-identical, so existing providers are unaffected. Validation rejects URL schemes, query strings, and fragments. Documented in the configuration + adapters references (en/ja/ko/ru/zh-cn). Dashboard/management-API editing of the field is a tracked follow-up; config-file editing works today.

Ships in the next release — if the issue persists after that, please reopen.