mirror of
https://github.com/Kaelio/ktx.git
synced 2026-06-07 07:55:13 +02:00
docs: document codex llm backend
This commit is contained in:
parent
64b8a416fe
commit
074c9c3d97
5 changed files with 58 additions and 5 deletions
|
|
@ -51,8 +51,9 @@ prompts.
|
|||
|
||||
| Flag | Description |
|
||||
|------|-------------|
|
||||
| `--llm-backend <backend>` | LLM backend: `anthropic`, `vertex`, or `claude-code` |
|
||||
| `--llm-backend <backend>` | LLM backend: `anthropic`, `vertex`, `claude-code`, or `codex` |
|
||||
| `--llm-backend claude-code` | Use the local Claude Code session for **ktx** LLM calls |
|
||||
| `--llm-backend codex` | Use local Codex authentication for **ktx** LLM calls |
|
||||
| `--llm-model <model>` | LLM model ID or backend model alias to validate and save |
|
||||
| `--anthropic-api-key-env <name>` | Environment variable containing the Anthropic API key |
|
||||
| `--anthropic-api-key-file <path>` | File containing the Anthropic API key |
|
||||
|
|
@ -65,6 +66,9 @@ valid with the Anthropic backend; Vertex flags are only valid with the Vertex
|
|||
backend. The `claude-code` backend uses local Claude Code authentication instead
|
||||
of Anthropic API key or Vertex flags. For Claude Code, `--llm-model` accepts
|
||||
`sonnet`, `opus`, `haiku`, or a full Claude model ID.
|
||||
The `codex` backend uses local Codex authentication instead of Anthropic API key
|
||||
or Vertex flags. For Codex, `--llm-model` accepts `gpt-5.3-codex`, `gpt-5.4`,
|
||||
or another `gpt-*` or `codex-*` model ID.
|
||||
|
||||
### Embeddings
|
||||
|
||||
|
|
@ -191,6 +195,9 @@ ktx setup \
|
|||
--llm-backend claude-code \
|
||||
--llm-model opus
|
||||
|
||||
# Configure ktx to use local Codex authentication for LLM work
|
||||
ktx setup --llm-backend codex --llm-model gpt-5.3-codex --no-input
|
||||
|
||||
# Script a Postgres connection that reads its URL from the environment
|
||||
ktx setup \
|
||||
--project-dir ./analytics \
|
||||
|
|
|
|||
|
|
@ -21,7 +21,7 @@ ktx status [options]
|
|||
| `--json` | Print JSON output | `false` |
|
||||
| `-v`, `--verbose` | Show every check, including passing ones | `false` |
|
||||
| `--validate` | Only validate the `ktx.yaml` schema; skip readiness checks | `false` |
|
||||
| `--fast` | Skip checks that require external communication (query-history readiness probes and Claude Code auth probe) | `false` |
|
||||
| `--fast` | Skip checks that require external communication (query-history readiness probes, Claude Code auth probe, and Codex auth probe) | `false` |
|
||||
| `--no-input` | Disable interactive terminal input | - |
|
||||
|
||||
## Examples
|
||||
|
|
@ -39,7 +39,7 @@ ktx status --verbose
|
|||
# Validate ktx.yaml without running readiness checks
|
||||
ktx status --validate
|
||||
|
||||
# Skip slow probes (query-history readiness, Claude Code auth)
|
||||
# Skip slow probes (query-history readiness, Claude Code auth, Codex auth)
|
||||
ktx status --fast
|
||||
|
||||
# Check a project from another directory
|
||||
|
|
@ -57,6 +57,10 @@ flow, then rerun `ktx status`. Use `--fast` to skip this probe (useful in CI
|
|||
or offline contexts); skipped checks render as `-` and carry
|
||||
`"status": "skipped"` in JSON output.
|
||||
|
||||
For `llm.provider.backend: codex`, `ktx status` runs a minimal non-interactive
|
||||
Codex request. If the probe fails, authenticate Codex locally with the Codex CLI
|
||||
and verify the Codex CLI installation.
|
||||
|
||||
A `Local data` section summarises what the project has accumulated locally:
|
||||
ingest run counts, last completed timestamp per connection, knowledge page
|
||||
counts by scope, semantic-layer source and dictionary value counts, and the
|
||||
|
|
|
|||
|
|
@ -376,13 +376,24 @@ llm:
|
|||
|
||||
| Field | Type | Default | Purpose |
|
||||
|-------|------|---------|---------|
|
||||
| `provider.backend` | `none` \| `anthropic` \| `vertex` \| `gateway` \| `claude-code` | `none` | Selected backend. `none` disables LLM features. `claude-code` uses the local Claude Code session and needs no API key. |
|
||||
| `provider.backend` | `none` \| `anthropic` \| `vertex` \| `gateway` \| `claude-code` \| `codex` | `none` | Selected backend. `none` disables LLM features. `claude-code` uses the local Claude Code session and needs no API key. `codex` uses local Codex authentication. |
|
||||
| `provider.anthropic.api_key` | `string` | - | Anthropic API key. Required when `backend: anthropic`. Accepts `env:` or `file:` references. |
|
||||
| `provider.anthropic.base_url` | `string` | - | Override the Anthropic API base URL (proxy, self-hosted gateway). |
|
||||
| `provider.gateway.api_key` / `base_url` | `string` | - | Credentials for an AI Gateway provider. Required when `backend: gateway`. |
|
||||
| `provider.vertex.project` | `string` | - | Google Cloud project ID hosting the Vertex AI endpoint. |
|
||||
| `provider.vertex.location` | `string` | - | Vertex AI region (for example `us-east5`). Required when the `vertex` block is present. |
|
||||
|
||||
Use `codex` when you want **ktx** LLM work to run through local Codex
|
||||
authentication:
|
||||
|
||||
```yaml
|
||||
llm:
|
||||
provider:
|
||||
backend: codex
|
||||
models:
|
||||
default: gpt-5.3-codex
|
||||
```
|
||||
|
||||
### Model roles
|
||||
|
||||
`models` overrides the per-role model. Keys are fixed; values are
|
||||
|
|
|
|||
|
|
@ -37,7 +37,13 @@ ktx ingest --all
|
|||
```
|
||||
|
||||
Enriched ingest needs a configured model and embeddings. Run `ktx setup` first;
|
||||
connections without that configuration fail before any work starts.
|
||||
connections without that configuration fail before any work starts. Local-auth
|
||||
LLM options include Claude Code and Codex:
|
||||
|
||||
```bash
|
||||
ktx setup --llm-backend claude-code --no-input
|
||||
ktx setup --llm-backend codex --llm-model gpt-5.3-codex --no-input
|
||||
```
|
||||
|
||||
With `claude-code`, **ktx** agent loops can invoke only the **ktx** MCP tools for the
|
||||
current run.
|
||||
|
|
|
|||
|
|
@ -16,6 +16,7 @@ Set `llm.provider.backend` to one of these values:
|
|||
- `gateway`: Use AI Gateway-compatible Anthropic model ids.
|
||||
- `claude-code`: Use your local Claude Code session through the Claude Agent
|
||||
SDK. **ktx** strips provider-routing environment variables from child processes.
|
||||
- `codex`: Use your local Codex authentication through the Codex SDK.
|
||||
|
||||
## Claude Code
|
||||
|
||||
|
|
@ -47,6 +48,30 @@ model IDs are also accepted.
|
|||
metadata may still list host slash commands, skills, and subagents; **ktx** does not
|
||||
grant execution access to them.
|
||||
|
||||
## Codex backend
|
||||
|
||||
Use `codex` when you want **ktx** to run LLM-backed workflows through your
|
||||
local Codex authentication instead of a direct provider API key.
|
||||
|
||||
```yaml
|
||||
llm:
|
||||
provider:
|
||||
backend: codex
|
||||
models:
|
||||
default: gpt-5.3-codex
|
||||
```
|
||||
|
||||
Configure it non-interactively:
|
||||
|
||||
```bash
|
||||
ktx setup --llm-backend codex --llm-model gpt-5.3-codex --no-input
|
||||
```
|
||||
|
||||
This is separate from Codex agent-client setup. `ktx setup --agents --target
|
||||
codex` installs instructions and MCP access for an end-user Codex session.
|
||||
`ktx setup --llm-backend codex` makes **ktx** itself execute ingest, scan
|
||||
enrichment, memory, and other LLM-backed work through Codex.
|
||||
|
||||
## Prompt caching
|
||||
|
||||
`llm.promptCaching` has partial parity on `claude-code`. Status and doctor warn
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue