Skip to content

configuration.md

Latest commit

 

History

History
340 lines (278 loc) · 12.5 KB

configuration.md

File metadata and controls

340 lines (278 loc) · 12.5 KB
Raw

Configuration

Qwen Code Rust resolves configuration from four layers, merged in order (later layers win):

  1. Built-in defaults
  2. Global settings file (~/.qcr/settings.json)
  3. Project-local settings file (.qcr/settings.json in project root)
  4. Environment variables

Settings File Format

Both ~/.qcr/settings.json and .qcr/settings.json use the same JSON schema.

{
  "model": {
    "model_id": "qwen3-coder",
    "provider": "dashscope",
    "max_tokens": 8192,
    "temperature": 0.0
  },
  "providers": {
    "openai": {  // optional — add other providers here
      "name": "openai",
      "api_key": "sk-...",
      "base_url": "https://api.openai.com/v1",
      "max_retries": 3,
      "timeout_secs": 120
    },
    "anthropic": {
      "name": "anthropic",
      "api_key": "sk-ant-..."
    },
    "dashscope": {
      "name": "dashscope",
      "api_key": "sk-..."
    }
  },
  "approval_mode": "suggest",
  "max_turns": 20,
  "system_prompt": "You are a helpful coding assistant.",
  "custom_instructions": "Always prefer Rust idioms.",
  "ignore_patterns": ["node_modules", "target", ".git"],
  "telemetry_enabled": false,
  "auto_compress_threshold": 30,
  "memorix": {
    "enabled": true,
    "url": "http://localhost:8420",
    "project": "my-project"
  },
  "team": {
    "enabled": false,
    "teams_dir": "~/.qcr/teams",
    "tasks_dir": "~/.qcr/tasks"
  },
  "serve": {
    "host": "127.0.0.1",
    "port": 4200,
    "cors_origins": []
  },
  "a2a": {
    "agent_name": "qcr",
    "agent_description": "AI coding agent"
  }
}

Model Configuration

Field Type Default Description
model.model_id string "qwen3-coder" Model identifier sent to the provider API (e.g. minimax-m2.5, gemini-2.5-flash)
model.provider string "dashscope" Provider name (see Providers)
model.max_tokens integer null Maximum tokens in the response
model.temperature float null Sampling temperature (0.0–2.0)

Provider Configuration

Each entry under providers is keyed by provider name.

Field Type Default Description
name string (key) Provider identifier
api_key string null API key (prefer env vars)
base_url string provider default Override the API endpoint
max_retries integer 3 Retry count on transient errors
timeout_secs integer 120 Per-request timeout in seconds
custom_headers object {} Extra HTTP headers

Top-Level Fields

Field Type Default Description
approval_mode enum "suggest" always, never, suggest — not prompt
max_turns integer 20 Max agent loop iterations per prompt
auto_compress_threshold integer 30 Auto-compress history when message count exceeds this. Set to 0 to disable
system_prompt string null Prepended to every conversation
custom_instructions string null Appended to system prompt
ignore_patterns array [] Glob patterns excluded from file tools
telemetry_enabled bool false Usage telemetry (no PII)
team.enabled bool false Enable the experimental agent-teams feature
team.teams_dir string ~/.qcr/teams Root directory for team configs and mailboxes
team.tasks_dir string ~/.qcr/tasks Root directory for team task files

Approval Modes

Value Behavior
always Deny all tool calls — agent can only read and respond
never Auto-approve all tool calls (headless/CI usage)
suggest Interactive prompt in TUI for each write/execute tool

Memorix Configuration (Semantic Memory)

Qwen Code Rust can integrate with memorix -- a local semantic memory engine -- to automatically recall relevant context from past sessions and store session summaries for future use.

When enabled, qcr performs three invisible operations:

  1. Session start with objective (P11) -- starts a memorix session (POST /session) with the user's first prompt as the objective, so future recalls show what the user was working on. Runs in parallel with context fetch for zero added latency.
  2. Auto-recall at session start -- fetches a compact context summary from memorix via GET /context (~60% fewer tokens than raw search), including active tasks. Falls back to POST /search on older memorix versions. Injected into the system prompt alongside any QCR.md content.
  3. Auto-store at session end -- extracts the last assistant message, stores it with structured metadata (title, memory_type, topic_key for dedup) to prevent duplicate daily summaries.

Additionally, the MemorixClient exposes task CRUD methods (create_task, update_task, list_tasks) for programmatic work tracking via the memorix P11 API.

All memorix operations are non-blocking and resilient. If memorix is unreachable or returns errors, qcr continues normally with no visible impact.

{
  "memorix": {
    "enabled": true,
    "url": "http://localhost:8420",
    "tenant": "default",
    "project": "my-project",
    "agent": "qcr",
    "auto_recall_top_k": 20,
    "auto_store": true,
    "api_key": null,
    "use_context_endpoint": true
  }
}
Field Type Default Description
memorix.enabled bool false Enable memorix integration (opt-in)
memorix.url string "http://localhost:8420" Memorix HTTP API base URL
memorix.tenant string "default" Tenant identifier for multi-tenant setups
memorix.project string null Project identifier. When null, auto-derived from the basename of the current working directory
memorix.agent string "qcr" Agent identifier sent to memorix
memorix.auto_recall_top_k integer 20 Number of memories to retrieve at session start
memorix.auto_store bool true Store a session summary in memorix when the session ends
memorix.api_key string null Optional Bearer token for memorix authentication
memorix.use_context_endpoint bool true Use GET /context for compact recall (~60% fewer tokens). Falls back to search if unavailable

Minimal setup -- only enabled is required, all other fields use sensible defaults:

{
  "memorix": { "enabled": true }
}

The QCR_MEMORIX_URL environment variable overrides memorix.url from settings files.

System Prompt Assembly Order

When both QCR.md memory files and memorix are active, the system prompt is assembled in this order:

  1. User-level memory (~/.qcr/QCR.md) -- human-curated pinned notes
  2. Project-level memory (.qcr/QCR.md) -- project-specific conventions
  3. Memorix context (<memorix-context>) -- compact structured markdown from GET /context
  4. Base system prompt
  5. Custom instructions

Each section is only present if it has content. Human-curated notes take highest priority (appear first in context), then semantic recall, then the base prompt.

Memorix vs QCR.md

Both memory systems are complementary:

Aspect QCR.md Memorix
Content type Human-curated, pinned rules and conventions Automatic session summaries
Growth Manual edits, 100KB cap Unbounded, searched by relevance
Retrieval Full file dump into prompt Semantic search, top-K results
Storage Local .qcr/ files Local RocksDB via memorix engine

Environment Variables

Environment variables override values from any settings file.

Variable Overrides Notes
QCR_MODEL model.model_id
QCR_PROVIDER model.provider
QCR_MAX_TOKENS model.max_tokens Integer
QCR_TEMPERATURE model.temperature Float
OPENAI_API_KEY providers.openai.api_key
ANTHROPIC_API_KEY providers.anthropic.api_key
DASHSCOPE_API_KEY providers.dashscope.api_key
OPENROUTER_API_KEY providers.openrouter.api_key
OPENAI_API_BASE providers.openai.base_url Useful for proxies and local LLMs
QCR_API_BASE providers.openai.base_url Alias for OPENAI_API_BASE
QCR_APPROVAL_MODE approval_mode always, never, or suggest
QCR_MAX_TURNS max_turns Integer
QCR_MEMORIX_URL memorix.url Memorix API base URL
QCR_DISABLE_CRON -- Set to 1 to disable the session-scoped cron scheduler. Cron tools return errors and /loop is rejected.
QCR_LOG -- Tracing filter for debug logging. Logs are written to ~/.qcr/qcr.log (not the TUI). E.g. QCR_LOG=warn or QCR_LOG=qcr_core=debug.
QCR_EXPERIMENTAL_AGENT_TEAMS team.enabled Set to 1, true, or yes to enable the experimental agent-teams feature.
QCR_TEAMS_DIR team.teams_dir Override the root directory for team configs and mailboxes.
QCR_TASKS_DIR team.tasks_dir Override the root directory for team task files.

Plugin Directories

Plugins are loaded from two directories. No settings file entry is needed — qcr scans these paths automatically on startup.

Path Scope
~/.qcr/plugins/ Global — available in every project
.qcr/plugins/ Project-local — current project only

Project-local plugins shadow global plugins with the same name.

Project-level lifecycle hooks (outside any plugin) go in:

.qcr/hooks/hooks.json

See docs/plugins.md for the full plugin reference.

Serve Configuration (A2A + AG-UI)

Configure the HTTP server started by qcr serve:

{
  "serve": {
    "host": "127.0.0.1",
    "port": 4200,
    "cors_origins": ["http://localhost:3000"]
  },
  "a2a": {
    "agent_name": "my-agent",
    "agent_description": "My custom AI coding agent",
    "agent_version": "1.0.0"
  }
}

Serve Fields

Field Type Default Description
serve.host string "127.0.0.1" Bind address for the HTTP server
serve.port integer 4200 Port number
serve.cors_origins array [] Allowed CORS origins. Empty = allow all (permissive)

A2A Fields

Field Type Default Description
a2a.agent_name string "qcr" Agent name in the A2A agent card
a2a.agent_description string "AI coding agent powered by qcr" Agent description in the agent card
a2a.agent_version string crate version Agent version in the agent card

CLI flags --host and --port on qcr serve override the config values.

MCP Server Configuration

Model Context Protocol servers are configured under mcp_servers:

{
  "mcp_servers": {
    "my-server": {
      "transport": "stdio",
      "command": "/usr/local/bin/my-mcp-server",
      "args": ["--port", "8080"],
      "env": { "SERVER_KEY": "secret" },
      "auto_approve": false
    },
    "remote-server": {
      "transport": "http",
      "url": "http://localhost:9000/mcp",
      "auto_approve": true
    }
  }
}
Field Type Description
transport "stdio" or "http" Connection type
command string Executable path (stdio only)
args array Arguments to pass to the command
env object Extra environment variables for the process
url string HTTP endpoint (http only)
auto_approve bool Auto-approve all tool calls from this server

Configuration Precedence Example

Given:

  • ~/.qcr/settings.json: model.model_id = "qwen3-coder"
  • .qcr/settings.json: model.model_id = "qwen-turbo"
  • QCR_MODEL=qwen3-235b-a22b

The effective model is qwen3-235b-a22b (env wins).

Quick Setup

# Minimal setup — OpenAI-compatible proxy (e.g. aiproxies.win)
mkdir -p ~/.qcr
cat > ~/.qcr/settings.json <<'EOF'
{
  "model": { "model_id": "minimax-m2.5", "provider": "openai" },
  "providers": {
    "openai": {
      "name": "openai",
      "base_url": "https://aiproxies.win/v1",
      "api_key": "YOUR_PROXY_KEY"
    }
  },
  "approval_mode": "suggest"
}
EOF

# Switch to gemini-2.5-flash for one session (same proxy, no settings change needed)
qcr --model gemini-2.5-flash

# Or use a native provider via env vars
export DASHSCOPE_API_KEY=sk-YOUR_KEY
export QCR_MODEL=qwen3-coder
export QCR_PROVIDER=dashscope

Note: approval_mode accepts only always, never, or suggest. Using "prompt" causes a parse error and qcr silently falls back to defaults (no provider config → 401 errors).