#18204: feat(memory): add native Telnyx embedding provider

## Summary - **Problem:** Telnyx embeddings currently require a `provider: "openai"` + custom `baseUrl` workaround, which hits config redaction bugs and provider resolution fallthrough (see Linked Issues below) - **Why it matters:** Users with a `TELNYX_API_KEY` (common for voice/messaging) can't reliably use it for embeddings without hitting these issues - **What changed:** New native `provider: "telnyx"` option — same pattern as the Voyage provider. Raw fetch, no SDK, token limits declared for automatic enforcement - **What did NOT change:** No changes to existing providers. No new dependencies. The existing `baseUrl` workaround still works - **Incidental fix:** Added missing `voyage` to the fallback provider list in `docs/concepts/memory.md` (pre-existing omission, not related to the Telnyx feature) I work at Telnyx and we run OpenClaw internally — happy to own this provider long-term. ## Change Type - [ ] Bug fix - [x] Feature - [x] Docs - [ ] Refactor - [ ] Security hardening - [ ] Chore/infra ## Scope - [ ] Gateway / orchestration - [ ] Skills / tool execution - [x] Auth / tokens - [x] Memory / storage - [ ] Integrations - [ ] API / contracts - [ ] UI / DX - [ ] CI/CD / infra ## Linked Issue/PR - Related #7078 (Voyage provider — same pattern followed here) - Related #11268, #12078 (config redaction corrupts numeric settings in `baseUrl` workaround) - Related #8131 (provider resolution ignores `remote.baseUrl`, falls through to `OPENAI_API_KEY`) ## User-visible / Behavior Changes - New config option: `provider: "telnyx"` for `agents.defaults.memorySearch` - New env var: `TELNYX_API_KEY` (resolved via standard `resolveApiKeyForProvider`) - `openclaw doctor` auto-detects `TELNYX_API_KEY` when selecting embedding provider - Models: `thenlper/gte-large` (default, 1024 dims), `intfloat/multilingual-e5-large` (multilingual) ## Security Impact - New permissions/capabilities? `No` - Secrets/tokens handling changed? `No` — uses existing `resolveApiKeyForProvider` path - New/changed network calls? `Yes` — new outbound HTTPS to `api.telnyx.com/v2/ai/openai/embeddings` - Risk: standard embedding API call, same pattern as Voyage (`api.voyageai.com`) - Mitigation: only activated when user explicitly sets `provider: "telnyx"`. No calls made otherwise. - Command/tool execution surface changed? `No` - Data access scope changed? `No` ## Repro + Verification ### Environment - OS: Ubuntu 24.04 (gateway), macOS 15.5 (dev) - Runtime: Node 22.18.0 - Model/provider: Telnyx `thenlper/gte-large` - Relevant config: ```json { "provider": "telnyx", "model": "thenlper/gte-large" } ``` ### Steps 1. Set `TELNYX_API_KEY` in environment 2. Configure `agents.defaults.memorySearch.provider: "telnyx"` in `openclaw.json` 3. Restart gateway, run `openclaw memory search "test query"` ### Expected - Memory search returns results using Telnyx embeddings ### Actual - Memory search returns results, provider confirmed as `telnyx` ## Evidence - [x] Failing test/log before + passing after - [x] Trace/log snippets Unit tests (7 new, 939 total memory+config+agents tests pass): ``` ✓ src/memory/embeddings-telnyx.test.ts (4 tests) 30ms ✓ src/config/config.schema-regressions.test.ts (4 tests) 36ms [+2 new telnyx] ✓ src/agents/model-auth.e2e.test.ts (13 tests) 48ms [+1 new telnyx] Test Files 136 passed (136) Tests 939 passed (939) ``` Live gateway verification: ``` Provider: telnyx (requested: telnyx) Model: thenlper/gte-large Indexed: 19/19 files · 752 chunks Vector: ready (1024 dims) Embedding cache: enabled (1133 entries) ``` ## Human Verification - Verified scenarios: native `provider: "telnyx"` config → gateway restart → memory search returns results with correct model and dimensions; `openclaw doctor` detects `TELNYX_API_KEY` - Edge cases checked: model normalization (`"telnyx/gte-large"` → `"gte-large"`), empty input arrays, missing API key error messages, fallback provider resolution - What I did **not** verify: batch indexing (Telnyx doesn't expose a batch file-upload endpoint like OpenAI/Gemini/Voyage, so this correctly uses the standard per-request path) ## Compatibility / Migration - Backward compatible? `Yes` — purely additive, no changes to existing providers - Config/env changes? `Yes` — new optional `provider: "telnyx"` value, new optional `TELNYX_API_KEY` env var - Migration needed? `No` ## Failure Recovery - How to disable/revert: change `provider` back to previous value in `openclaw.json`, restart gateway - Files/config to restore: `openclaw.json` only - Known bad symptoms: if `TELNYX_API_KEY` is missing/invalid, `openclaw doctor` will report the missing key and memory search will fail with a clear auth error ## Risks and Mitigations - Risk: Telnyx API availability/changes - Mitigation: raw fetch with standard error handling; I work at Telnyx and will maintain this provider code ## AI Disclosure This PR was developed with AI assistance. - **Testing level:** Fully tested — 7 new tests (4 provider unit, 2 schema regression, 1 auth e2e), all 939 existing memory/config/agents tests passing, plus live end-to-end verification on a running gateway. - **Understanding:** I understand the changes — follows the established Voyage provider pattern (#7078). The provider sends embedding requests to Telnyx's OpenAI-compatible endpoint, with token limits (512) declared in `embedding-model-limits.ts` for automatic chunk enforcement by the existing pipeline. <!-- greptile_comment --> <h3>Greptile Summary</h3> Added native Telnyx embedding provider following the established Voyage pattern. The implementation includes proper API key resolution via `resolveApiKeyForProvider`, token limit enforcement (512 tokens), and complete integration across config schema, docs, and `openclaw doctor`. The PR correctly excludes Telnyx from batch processing since the API does not support batch uploads. All 939 existing tests pass plus 7 new tests. <h3>Confidence Score: 5/5</h3> - This PR is safe to merge with no significant risk - The implementation follows the established Voyage provider pattern exactly, is purely additive with no changes to existing providers, includes comprehensive tests (7 new tests + all 939 existing tests passing), has proper error handling and API key resolution, and the author has verified it works end-to-end on a live gateway. - No files require special attention _{Last reviewed commit: 38169c8} <!-- greptile_other_comments_section --> <!-- /greptile_comment -->