custom-endpoint

Imported from sagemoyi/moagent (extensions/custom-endpoint/AGENTS.md). Install upstream with npx skills add sagemoyi/moagent --skill custom-endpoint. Copyright stays with the author.

Module: 自定义端点 (custom-endpoint)

Session owner: 自定义端点
Status: shipped (0.5.0+) — usable; refine matching / UX as needed.
Global rules: root AGENTS.md.

Purpose

Let the moagent profile use custom model endpoints (relays, local OpenAI-compatible servers, Claude-compatible proxies) without hand-editing JSON.

Goals:

1. Interactive add via /login →「自定义端点」 and /custom-endpoint
2. Multi-protocol: Completions / Responses / Anthropic Messages
3. Auto-fill context window, maxTokens, reasoning, thinkingLevelMap from models.dev (lab-first)
4. Make max / xhigh thinking levels actually selectable (unlike painful OpenClaw custom-model setups)

Owns / does not own

Primary paths (repo)

extensions/custom-endpoint/
├── index.ts          # registerProvider(moagent-custom) + thin entrypoint
├── commands.ts       # /custom-endpoint command dispatch + refresh orchestration
├── wizard.ts         # multi-step add/update flow
├── ui.ts             # AuthInteraction ↔ WizardUI adapters
├── endpoint-url.ts   # URL normalize + metadata/link-local/DNS guard
├── remote-models.ts  # bounded /models fetch + safe manual redirects
├── endpoint-store.ts # multi-file preflight + refresh merge operations
├── catalog.ts        # 兼容重导出门面
├── catalog/client.ts # models.dev fetch/cache/timeout
├── catalog/matcher.ts # normalize/index/score + 可替换匹配数据表
├── catalog/thinking.ts # thinkingLevelMap + model config enrich
├── models-json.ts    # models.json + auth.json + managed list I/O
├── paths.ts          # getAgentDir()-relative paths
├── types.ts
└── AGENTS.md
examples/custom-endpoint-models.json   # shape template (not live secrets)

Package: listed under package.json → pi.extensions → ./extensions (auto-discovered as subdir index.ts).

Runtime files (moagent home only, not git)

Model entries may include non-secret moagentModelsDevKey (e.g. moonshotai/kimi-k3) for /custom-endpoint refresh. Web 人工编辑 catalog 字段时会写 moagentManualFields[]；refresh 必须跳过这些字段，同时继续刷新未人工覆盖的 metadata。

Do not commit real keys. Prefer auth.json over literal apiKey in models.json (ENV/$VAR style preserved if already present).

Commands / UX

Wizard flow (summary)

1. Provider id (e.g. na, my-proxy)
2. Base URL
3. API protocol (default Completions; suggest Responses for api.openai.com; Anthropic for Claude-ish URLs)
4. API key → auth.json
5. Model ids: try GET {base}/models if key present, else manual
6. Per model: models.dev match → preview ctx/out/reasoning/levels → write

Protocols (v1)

No Google in v1 (out of scope unless Moyi asks).

Default compat for Completions: supportsDeveloperRole: false, maxTokensField: "max_tokens", supportsReasoningEffort: true when any model has reasoning.

models.dev matching (lab-first)

Problem: same basename appears on many resellers with conflicting reasoning_options (overclaiming max/xhigh).

Pipeline:

1. Normalize id (basename, alnum fold)
2. Prefer canonical models.json (~lab catalog) for identity / context / output / modalities
3. Prefer lab provider row in api.json (deepseek, moonshotai, zhipuai, …) for reasoning_options
4. Family hints: kimi*→moonshotai, glm*→zhipuai, qwen*→alibaba, mimo*→xiaomi, deepseek*→deepseek, …
5. Ambiguous → UI pick among top candidates
6. No match (AA): ask reasoning? if yes → reasoning: true + thinkingLevelMap.max = "max"

thinkingLevelMap vs Pi

Pi behavior (getSupportedThinkingLevels): with reasoning: true, off–high default on; xhigh / max only appear if explicitly mapped (non-null).

So lab efforts that include max / xhigh must be written into thinkingLevelMap or the UI never offers them.

Meta-provider moagent-custom

• Registered via createProvider so it appears in /login
• check / resolve always unconfigured → not a usable inference provider
• Stream stubs error if mis-selected
• Login success stores a placeholder under moagent-custom; real keys go under the user-chosen provider id

Overlap with setup login step

Shared: WizardUI / AuthInteraction patterns; setup uses auth-interaction.ts + model-runtime.ts under moagent-setup; custom-endpoint has its own ui.ts for AuthInteraction from createProvider login.

Do not reimplement OAuth for Anthropic/OpenAI here — use Pi /login / setup login step.

Test checklist

PI_CODING_AGENT_DIR=~/.moagent/agent pi install .

# interactive
moagent
# /login → 自定义端点
# or: /custom-endpoint add
# /custom-endpoint list
# /model → pick provider/model; set thinking to max if mapped

# headless catalog sanity (optional): load catalog.ts via pi -e selftest

Verify:

• models.json provider has correct api / baseUrl / contextWindow / maxTokens
• reasoning models have thinkingLevelMap.max (and xhigh when lab lists it)
• auth.json has key under provider id, not only moagent-custom
• moagent-custom-endpoints.json lists the provider
• Coding profile ~/.pi/agent unchanged

Decisions

1. Persist as official Pi models.json (hot-reload on /model), not a parallel runtime registry.
2. Keys in auth.json, not repo.
3. models.dev lab rows for thinking metadata; never “longest reseller effort list wins”.
4. Completions default; Responses first-class but not default.
5. Meta-provider only for login discoverability.
6. Unmatched + reasoning → expose max (product choice AA).
7. Prefer /v1/models discovery when key present (AA).

Refactor status (2026-08-02)

• 2026-08-03：Web 完整模型编辑器写入 moagentManualFields[] 标记人工覆盖；扩展侧 mergeRefreshedModels() 按最新模型重读后跳过这些字段，防 /custom-endpoint refresh 把 context/maxTokens/reasoning/thinking/cost 等手工值改回 catalog，同时仍保留未知字段和未覆盖 metadata。

• index.ts 已收敛为薄入口；命令调度、端点网络边界、组合存储分别移入 commands.ts / remote-models.ts / endpoint-store.ts。

• /models 发现改为手动、限次 redirect：每一跳重新做 URL + DNS 校验，阻断云元数据/链路本地，跨 origin 不转发 API key；响应按 1 MiB 有界读取，结构、模型数量与 id 长度均有守卫。

• 向导无 scheme 地址默认 http://（适配 Ollama/vLLM/CPA），拒绝凭据/query/fragment；models.dev 每次操作只加载一次，refresh 在 await 后重读 provider 并按 model id 合并，保留并发变化与未知高级字段。

• managed state 文件“缺失迁移”与“已存在但为空”已区分；models/auth/managed 写前统一预检结构，新增 URL、redirect、凭据转发、托管空状态、refresh merge、损坏 auth 回归测试。

• models.json / auth.json / managed state 已接入 extensions/lib/config-io.ts：tmp 创建即 0600、fsync+rename；损坏 JSON 先备份并拒绝静默清空；removeApiKey 不再把 auth.json 退回 0644。

• catalog 已拆成 client / matcher / thinking 三层，旧 catalog.ts 仅作兼容门面；所有外部 fetch 都有默认 10 秒超时，匹配数据表可替换，死的 PI_LEVELS 已删除。

• catalog matcher / thinking-level 映射及 client 超时边界已由 root node --test 直接覆盖；hintLab / scoreMatch 为纯函数测试导出。

• ExtensionContext 的 string[] select bridge 使用共享 selectById，AuthPrompt/WizardUI 选择结果不再依赖显示 label 前缀。

Open issues / debt

• Extension input is not secret-masked (keys visible in slash-command path; /login secret type is better)
• modelRegistry.runtime is used by setup login, not here — keep boundary clear
• Fuzzy match still imperfect for heavily aliased gateway ids
• No Google / Azure-specific protocols yet
• Refresh does not re-probe remote /models list (metadata only)
• Optional: setup-only shortcut that only opens custom-endpoint wizard

Related modules