Skip to content

Configuration

Jump to bottom
alf edited this page Mar 15, 2026 · 35 revisions

Configuration

FreeCAD AI stores all settings in a single JSON file and provides a GUI dialog for editing them. No environment variables or .env files are needed.

Settings Dialog

Open the settings dialog in any of these ways:

  • Menu: FreeCAD AI > AI Settings
  • Toolbar: click the "AI Settings" button in the FreeCAD AI toolbar
  • Chat panel footer: click the gear icon at the bottom of the chat dock widget

The dialog has six sections: LLM Provider, Parameters, Behavior, MCP Servers, User Tools, and a Test Connection button.

Settings dialog

LLM Provider Section

Field Description
Provider Dropdown to select the LLM backend. Changing this auto-fills Base URL and Model with defaults.
API Key Your provider's API key. Stored in plaintext in the config file. Leave empty for Ollama.
Base URL The API endpoint. Auto-filled from provider presets but can be overridden.
Model The model name to use. Auto-filled with the provider's recommended default.

Parameters Section

Field Description Default
Max Output Tokens Maximum number of tokens the LLM can generate per response. Range: 256--262,144. This controls output length only, not the context window. 4096
Context Window Context window size in tokens. Older messages are automatically compacted when the conversation exceeds this limit. Set to your model's context limit, or lower to control API costs (e.g., 200,000 for Claude to avoid the expensive >200k tier). Range: 4,000--1,000,000. 20,000
Temperature Controls randomness. Lower values (0.1--0.3) produce more deterministic output; higher values (0.7--1.0) produce more creative output. Range: 0.0--2.0. 0.3

Behavior Section

Field Description Default
Auto-execute code in Act mode When checked, the assistant executes tool calls immediately without asking for confirmation. When unchecked, each tool call shows a confirmation dialog. Off
Thinking Controls LLM reasoning chains. See the Thinking Mode section below. Off
Viewport capture Automatically attach viewport screenshots to chat messages. Off = disabled, Every Message = always, After Changes = only when tools modify the document. Off
Capture resolution Resolution preset for viewport screenshots: Low (400x300), Medium (800x600), High (1600x1200). Medium
Model supports vision Whether the LLM can process images natively. Auto-detected via Test Connection probe, or set manually. See Vision Routing below. Not tested

MCP Servers Section

A list of configured Model Context Protocol servers. See MCP Integration for details.

  • Add... -- opens a dialog to add a new MCP server (name, command, args, deferred, enabled).
  • Remove -- removes the selected server from the list.

Each server in the list shows its status tags (e.g., (deferred), (disabled)).

User Tools Section

Register your own Python functions as LLM-callable tools. Files in ~/.config/FreeCAD/FreeCADAI/tools/ are automatically discovered and validated.

  • Tool list -- shows all discovered tool files with status indicators:
    • ✓ valid (green) -- tool loaded successfully
    • ⚠ warning (yellow) -- loaded with warnings (e.g., missing docstring)
    • ✗ error (red) -- validation failed (e.g., syntax error, no typed functions)
  • Add... -- opens a file picker to copy a .py or .FCMacro file into the tools directory.
  • Remove -- deletes the selected file from the tools directory.
  • Reload -- re-scans and re-validates all tool files.
  • Also scan FreeCAD macro directory -- when checked, also scans ~/.config/FreeCAD/Macro/ for compatible tool functions.

See Creating Custom Tools for the function convention and examples.

Test Connection

Click Test Connection to verify your provider settings. The workbench sends a small test request to the configured endpoint and displays the result:

  • Green text -- connection successful, shows a snippet of the response.
  • Red text -- connection failed, shows the error message.

After a successful connection test, a vision probe runs automatically. A small image containing a random 3-digit number is sent to the LLM. If the LLM reads the number correctly, vision is marked as supported. The result appears below the connection status:

  • "Vision: supported" (green) -- the model can process images natively.
  • "Vision: not supported" (gray) -- the model cannot process images. If an MCP server provides a describe_image tool, images will be auto-described via that tool instead.

The test temporarily applies whatever values are currently in the dialog (you do not need to save first).

After verifying, click Save to persist settings or Cancel to discard changes.

Provider Setup

Provider Comparison

Provider API Key Required API Style Default Model Tool Calling Notes
Ollama No OpenAI-compatible llama3 Yes Local, free, no data leaves your machine
Anthropic Yes Native Anthropic claude-sonnet-4-20250514 Yes Best tool calling quality
OpenAI Yes OpenAI gpt-4o Yes Wide model selection
Gemini Yes OpenAI-compatible gemini-2.0-flash Yes Google AI, generous free tier
OpenRouter Yes OpenAI-compatible anthropic/claude-sonnet-4-20250514 Yes Multi-provider gateway, pay-per-token
Custom Varies OpenAI-compatible (none) No* Any OpenAI-compatible endpoint

* Custom providers have tool calling disabled by default. If your custom endpoint supports tool calling, the assistant will fall back to code generation.

Ollama (Local)

No API key needed. Install Ollama and pull a model (see Installation#Ollama Setup (Local Models)).

  1. Set Provider to Ollama.
  2. Leave API Key empty.
  3. Base URL: http://localhost:11434/v1 (default).
  4. Model: enter the model name you pulled, e.g., qwen3, llama3, qwen2.5-coder.
  5. Click Test Connection, then Save.

Recommended models for FreeCAD AI:

  • qwen3 -- good tool calling, 8B parameters, runs on most hardware
  • qwen2.5-coder -- strong at code generation, 7B parameters
  • llama3 -- fast general-purpose model, 8B parameters

Anthropic

  1. Go to console.anthropic.com and create an account.
  2. Navigate to API Keys and create a new key.
  3. In FreeCAD AI settings:
    • Provider: Anthropic
    • API Key: paste your key (starts with sk-ant-)
    • Base URL: https://api.anthropic.com (default)
    • Model: claude-sonnet-4-20250514 (default, recommended)
  4. Click Test Connection, then Save.

Anthropic uses its own native API format (not OpenAI-compatible). The workbench handles this automatically.

Available models: claude-sonnet-4-20250514, claude-haiku-3-20250414, claude-opus-4-20250514

OpenAI

  1. Go to platform.openai.com and create an account.
  2. Navigate to API Keys and create a new key.
  3. In FreeCAD AI settings:
    • Provider: OpenAI
    • API Key: paste your key (starts with sk-)
    • Base URL: https://api.openai.com/v1 (default)
    • Model: gpt-4o (default, recommended)
  4. Click Test Connection, then Save.

Available models: gpt-4o, gpt-4o-mini, gpt-4-turbo, o1, o1-mini

Gemini (Google AI)

  1. Go to aistudio.google.dev and sign in with your Google account.
  2. Click Get API Key and create a new key.
  3. In FreeCAD AI settings:
    • Provider: Gemini
    • API Key: paste your key
    • Base URL: https://generativelanguage.googleapis.com/v1beta/openai (default)
    • Model: gemini-2.0-flash (default, recommended)
  4. Click Test Connection, then Save.

Gemini uses an OpenAI-compatible endpoint provided by Google, so no special handling is needed.

Available models: gemini-2.0-flash, gemini-2.0-flash-lite, gemini-1.5-pro

OpenRouter

OpenRouter is a gateway that routes requests to many providers (Anthropic, OpenAI, Google, Meta, Mistral, and more). You get a single API key and pay per token.

  1. Go to openrouter.ai and create an account.
  2. Navigate to Keys and create a new key.
  3. In FreeCAD AI settings:
    • Provider: OpenRouter
    • API Key: paste your key
    • Base URL: https://openrouter.ai/api/v1 (default)
    • Model: anthropic/claude-sonnet-4-20250514 (default) or any model from the OpenRouter catalog
  4. Click Test Connection, then Save.

Model names on OpenRouter use the provider/model format. Browse the model list to find alternatives.

Custom (Any OpenAI-Compatible Endpoint)

Use this for self-hosted models (vLLM, text-generation-inference, LM Studio, etc.) or any endpoint that implements the OpenAI /chat/completions API.

  1. Set Provider to Custom.
  2. Enter the Base URL of your endpoint (e.g., http://localhost:8000/v1).
  3. Enter an API Key if your endpoint requires one, or leave it empty.
  4. Enter the Model name your endpoint expects.
  5. Click Test Connection, then Save.

Note: tool calling is disabled for custom providers by default. The assistant will fall back to generating Python code directly instead of using structured tool calls.

Config File Reference

Settings are stored at:

~/.config/FreeCAD/FreeCADAI/config.json

This file is created automatically on first launch. You can edit it by hand, but using the settings dialog is recommended.

Full Schema

{
  "provider": {
    "name": "anthropic",
    "api_key": "sk-ant-...",
    "base_url": "https://api.anthropic.com",
    "model": "claude-sonnet-4-20250514"
  },
  "mode": "plan",
  "max_tokens": 4096,
  "context_window": 20000,
  "temperature": 0.3,
  "auto_execute": false,
  "max_retries": 3,
  "enable_tools": true,
  "thinking": "off",
  "viewport_capture": "off",
  "viewport_resolution": "medium",
  "mcp_servers": [],
  "user_tools_disabled": [],
  "scan_freecad_macros": false,
  "hooks_disabled": [],
  "vision_detected": null,
  "vision_override": null
}

Field Reference

Field Type Default Description
provider.name string "anthropic" Provider identifier. One of: anthropic, openai, ollama, gemini, openrouter, custom.
provider.api_key string "" API key for the provider. Stored in plaintext. Leave empty for Ollama.
provider.base_url string "https://api.anthropic.com" API endpoint URL. Auto-filled from provider presets.
provider.model string "claude-sonnet-4-20250514" Model name to use for completions.
mode string "plan" Operating mode. "plan" shows generated code for review before execution. "act" executes tool calls directly (with optional confirmation dialog).
max_tokens integer 4096 Maximum output tokens per LLM response. Does not affect context window size. Range: 256--262,144.
context_window integer 20000 Context window size in tokens. Conversation is automatically compacted when it exceeds this limit. Set to model's limit or lower to control costs. Range: 4,000--1,000,000.
temperature float 0.3 Sampling temperature. Lower = more deterministic, higher = more creative. Range: 0.0--2.0.
auto_execute boolean false When true and mode is "act", tool calls execute without a confirmation dialog.
max_retries integer 3 Number of times to retry a failed tool call before giving up.
enable_tools boolean true When true, the assistant uses structured tool calls. When false, it falls back to generating raw Python code.
thinking string "off" LLM reasoning mode. "off" = no reasoning (fastest). "on" = standard thinking. "extended" = extended thinking with higher token budget. See Thinking Mode below.
viewport_capture string "off" Auto-capture viewport screenshots. "off" = disabled. "every_message" = attach screenshot with every message. "after_changes" = attach after tool calls modify the document. Can be overridden per-session via the Capture button.
viewport_resolution string "medium" Resolution preset for viewport screenshots. "low" = 400x300. "medium" = 800x600. "high" = 1600x1200.
mcp_servers array [] List of MCP server configurations. See MCP Servers below.
user_tools_disabled array of strings [] Filenames of user tool files to skip when loading (e.g., ["broken_tool.py"]).
scan_freecad_macros boolean false Also scan FreeCAD's macro directory (~/.config/FreeCAD/Macro/) for compatible tool functions.
hooks_disabled array of strings [] Hook directory names to skip when loading (e.g., ["log-tool-calls"]).
vision_detected boolean or null null Result of the vision probe. null = not tested, true = vision supported, false = vision not supported. Set automatically by Test Connection.
vision_override boolean or null null Manual override for vision support. When set, takes precedence over vision_detected. Set via the "Model supports vision" checkbox in Settings.

MCP Server Entry Format

Each entry in the mcp_servers array has this structure:

{
  "name": "filesystem",
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
  "env": {},
  "enabled": true,
  "deferred": true
}
Field Type Default Description
name string Display name for the server.
command string Executable to launch (e.g., npx, python3, node).
args array of strings [] Command-line arguments.
env object {} Additional environment variables to set when spawning the process.
enabled boolean true Whether to connect to this server on startup.
deferred boolean true Load tool schemas lazily on first use. Set to false to load all schemas eagerly on connect.

See MCP Integration for full documentation on MCP support.

Thinking Mode

Thinking mode enables the LLM to show its reasoning process before producing a final answer. This is useful for complex multi-step modeling tasks.

Setting Behavior
Off No reasoning output. Fastest response time. Recommended for simple tasks.
On Standard thinking/reasoning. The LLM produces a reasoning chain before its response.
Extended Extended thinking with a higher token budget. Best for complex multi-step tasks but slower and more expensive.

How thinking is implemented depends on the provider:

  • Anthropic: uses the thinking block with budget_tokens and the beta header.
  • OpenAI: uses the reasoning_effort parameter.
  • Ollama (qwen3): uses /think and /no_think tags in the system prompt.

Not all models support thinking. If your model does not support it, the setting is silently ignored.

Vision Routing

FreeCAD AI can attach images (viewport screenshots, pasted images, drag-and-drop) to chat messages. How these images are handled depends on whether the LLM supports vision:

Detection

Vision support is detected automatically when you click Test Connection in Settings. After a successful connection test, a small image containing a random 3-digit number is sent to the LLM. If the LLM reads the number correctly, vision is marked as supported.

You can also manually set vision support via the "Model supports vision" checkbox in the Behavior section of Settings. A Reset button appears when you have set a manual override, allowing you to return to the auto-detected value.

Vision detection resets when you change the provider or model (since different models have different capabilities). The manual override is preserved across provider/model changes.

Image Handling by Scenario

Scenario Behavior
Vision supported Images are sent inline to the LLM as base64 content blocks (native vision).
Vision not supported, MCP fallback available Images are automatically described by an MCP tool (e.g., describe_image from llm-vision-mcp) and the text description is sent to the LLM instead. A note appears in the chat for each described image.
Vision not supported, no MCP fallback Image controls (Capture, Attach, drag-drop, paste) are disabled. A tooltip explains how to enable vision.
Vision not tested Image controls remain enabled (optimistic). On first image use, a hint suggests running Test Connection to enable auto-detection.

MCP Fallback

If your LLM does not support vision, you can configure an MCP server that provides a describe_image tool. The workbench automatically searches registered MCP tools for one with describe_image in the name. When found, images are routed through that tool transparently — you do not need to invoke it manually.

A compatible MCP vision server is available at ghbalf/llm-vision-mcp. It routes images to a vision-capable model (OpenAI, Anthropic, Google, Ollama, or any OpenAI-compatible endpoint) and returns text descriptions.

Installing llm-vision-mcp

git clone https://github.com/ghbalf/llm-vision-mcp.git
cd llm-vision-mcp
npm install
npm run build

Configuring in FreeCAD AI

Open Settings > MCP Servers and click Add.... Fill in:

Field Value
Name llm-vision-mcp
Command node
Args dist/index.js --provider openai --openai-api-key sk-...
Deferred checked (recommended)

Adjust the args for your vision provider. Examples:

# OpenAI (default model: gpt-4o)
dist/index.js --provider openai --openai-api-key sk-...

# Anthropic (default model: claude-sonnet-4-latest)
dist/index.js --provider anthropic --anthropic-api-key sk-ant-...

# Google Gemini (default model: gemini-2.0-flash)
dist/index.js --provider google --google-api-key AIza...

# Ollama local (default model: llava)
dist/index.js --provider ollama

The --provider and API key can also be set via environment variables (VISION_DEFAULT_PROVIDER, OPENAI_API_KEY, etc.) or a .env file in the llm-vision-mcp directory.

Important: The dist/index.js path must be absolute (e.g., /home/you/llm-vision-mcp/dist/index.js) or relative to your working directory.

After adding the server, click Test Connection. If the vision probe detects that your main LLM does not support vision, the workbench will automatically find the describe_image tool from the MCP server and use it to describe images before sending them to the LLM.

See MCP Integration for general MCP server documentation.

Skill Optimizer

The /optimize-skill command automatically improves a skill's SKILL.md instructions by iteratively running test cases, scoring results, and using the LLM to fix errors.

How to Use

  1. Type /optimize-skill in the chat (Act mode)
  2. Select a skill from the dropdown and add test cases (e.g., 100x60x40mm, 2mm walls, snap-fit lid)
  3. Configure iterations, runs per test, and strategy
  4. Click Start Optimization

The optimizer runs all iterations automatically inside a single tool call. Each iteration:

  • Evaluates the SKILL.md against all test cases
  • Scores: completion, error rate, geometric correctness, efficiency
  • Asks the LLM to fix errors in the SKILL.md
  • Keeps improved versions, discards regressions

Dialog Settings

Field Default Description
Skill -- Skill to optimize
Test cases -- Arguments to test with (at least one required)
Iterations 10 Number of evaluate-modify cycles
Runs per test 2 Runs per test case (averaged for noise reduction)
Strategy Balanced Conservative (targeted fixes only), Balanced (+ periodic restructuring), Aggressive (frequent restructuring)

Advanced settings:

Field Default Description
Tool call budget 30 Max tool calls per evaluation run
Run timeout 300s Max seconds per evaluation run
Keep tolerance 0.05 Score margin for keeping lateral moves
Network retries 2 Extra retry attempts on network/timeout errors (exponential backoff: 5s, 10s, 20s...)

Version History

The optimizer saves all versions under ~/.config/FreeCAD/FreeCADAI/skills/<name>/.optimize/:

  • SKILL.md.original -- backup of the original (never overwritten)
  • v1.md, v2.md, ... -- each iteration's SKILL.md
  • history.json -- score progression, kept/discarded status, model info

The best version is automatically written to SKILL.md. You can always restore the original from SKILL.md.original.

Hooks

Hooks are user-defined Python scripts that fire on lifecycle events. They can block dangerous operations, modify user input, or log activity.

Hook Structure

Each hook is a named directory under ~/.config/FreeCAD/FreeCADAI/hooks/ containing a hook.py file:

~/.config/FreeCAD/FreeCADAI/hooks/
├── safety-guard/
│   └── hook.py
└── my-logger/
    └── hook.py

Built-in hooks ship with the workbench (in the repo's hooks/ directory) and are discovered automatically.

Writing a Hook

Define functions named on_<event> in hook.py:

def on_pre_tool_use(context):
    """Block dangerous operations."""
    if context["tool_name"] == "execute_code":
        code = context["arguments"].get("code", "")
        if "removeObject" in code:
            return {"block": True, "reason": "Blocked: removeObject is dangerous"}
    return {}

def on_post_tool_use(context):
    """Log every tool call."""
    with open("/tmp/tool_log.txt", "a") as f:
        f.write(f"{context['tool_name']}: {context['success']}\n")

Events

Event When Can block? Thread
pre_tool_use Before a tool executes Yes Worker
post_tool_use After a tool completes No Worker
user_prompt_submit Before user message sent to LLM Yes (block or modify) Main
post_response After LLM response processed No Main

Worker thread hooks (pre_tool_use, post_tool_use) must NOT call FreeCAD GUI APIs (App.ActiveDocument, FreeCADGui). They can read/write files, log, or make HTTP requests.

Main thread hooks (user_prompt_submit, post_response) can safely access the FreeCAD API.

Return Values

Return Effect Events
{"block": True, "reason": "..."} Block the action pre_tool_use, user_prompt_submit
{"modify": "new text"} Replace the user's message text user_prompt_submit
{} or None No effect All

Multiple hooks on the same event run in alphabetical order by directory name. If any hook blocks, the action is blocked. Modifications chain (each hook sees the previous hook's output).

Context Keys

pre_tool_use: tool_name (str), arguments (dict), turn (int)

post_tool_use: tool_name, arguments, success (bool), output (str), error (str), turn

user_prompt_submit: text (str), images (list), mode ("plan"/"act")

post_response: response_text (str), tool_calls_count (int), mode

Managing Hooks

In Settings > Hooks:

  • Add -- copy a hook.py file into a new hook directory
  • Edit -- open hook.py in your system editor
  • Remove -- delete the hook directory (built-in hooks can only be disabled)
  • Reload -- re-scan and reload all hooks without restarting FreeCAD

Disable a hook by adding its name to hooks_disabled in config.json, or by unchecking it in Settings.

Built-in Hooks

Hook Event Description
log-tool-calls post_tool_use Logs tool calls to the FreeCAD Report View

Other Configuration Directories

FreeCAD AI creates several directories under ~/.config/FreeCAD/FreeCADAI/:

Directory Purpose
~/.config/FreeCAD/FreeCADAI/ Root config directory. Contains config.json.
~/.config/FreeCAD/FreeCADAI/conversations/ Auto-saved chat sessions. The last 20 sessions are available for reload via the "Load" button in the chat footer.
~/.config/FreeCAD/FreeCADAI/skills/ User-created skills. Each skill is a subdirectory containing a SKILL.md file. See Skills.
~/.config/FreeCAD/FreeCADAI/tools/ User extension tools. .py and .FCMacro files with typed functions. See Creating Custom Tools.
~/.config/FreeCAD/FreeCADAI/hooks/ User-defined hooks. Each hook is a subdirectory containing a hook.py file. See Hooks section above.
~/.config/FreeCAD/FreeCADAI/logs/ Session logs. latest_session.json contains the most recent session's tool call log.

Security Notes

  • API keys are stored in plaintext in config.json. Protect this file with appropriate file permissions (chmod 600).
  • Auto-execute mode lets the LLM run arbitrary Python code in your FreeCAD session without confirmation. Use with caution, especially with cloud providers.
  • MCP servers are spawned as child processes. Only configure servers you trust.

Test Connection

To verify your configuration is working:

  1. Open FreeCAD AI > AI Settings.
  2. Fill in your provider details.
  3. Click Test Connection.
  4. If successful, you will see a green "Connected!" message with a snippet of the LLM's response.
  5. If it fails, the red error message will indicate the problem:
    • Connection refused -- the server is not running (common with Ollama).
    • 401 Unauthorized -- invalid or missing API key.
    • 404 Not Found -- wrong base URL or model name.
    • Timeout -- the server took too long to respond. For Ollama, this can happen on first request while the model loads into memory; try again.

Next Steps

After configuring your provider, proceed to Getting Started to learn how to use the chat interface, switch between Plan and Act modes, and build your first 3D model.

FreeCAD AI Wiki

Clone this wiki locally