Use local and API models in Smart Chat
Smart Chat API Extension is the Smart Chat path for configured local and cloud models inside Obsidian.
Use it when the job is not just saving a provider thread link, but choosing a configured model, attaching or retrieving sources, reviewing those sources, and keeping the response inside a saved Smart Chat thread.
Use Smart Chat codeblocks when you only need to keep an official ChatGPT, Claude, Gemini, Grok, Perplexity, or other provider thread attached to the note it serves.
First win: start one grounded thread
Do not start by configuring everything.
Start with one grounded thread:
- Open Smart Chat.
- Confirm one configured model.
- Attach one known source.
- Ask one outcome-focused question.
- Review the response before promoting anything into a trusted note.
You know it worked when:
The model, attached source, current thread, and response are visible before you trust the answer.
The response is not the deliverable yet.
Use it to improve the note, work item, review area, or next action that owns the assignment.
Quick start
Goal: ask one question using a model and source set you can see.
1. Open Smart Chat
Launch Smart Chat from the ribbon, command palette, or a hotkey you assign.
You should see the current thread or a new thread ready for input.
2. Confirm the model
Use the status/model indicator to confirm the model path before sending.
Current behavior:
- the status bar model picker updates the default chat completion model for future completions
- each response records the model/provider used for its request
Use settings if the model is missing, fails, or needs to be changed:
3. Attach one known source
Use Add context when you already know which note or source matters.
Keep the first source path simple.
Do not start by testing every source feature.
4. Ask one outcome-focused question
Good first prompts:
Based on the attached source, summarize the current state and list the next 5 actions.
Extract constraints from this source and propose a plan that satisfies every constraint.
Find contradictions in the attached source and list what needs clarification.
5. Review before promotion
The thread can help you think.
Your note remains the trusted place where reviewed learning, decisions, and deliverables belong.
Configure one model
Smart Chat uses models configured through Smart Environment.
Use the settings page to add, edit, test, or choose the default chat model.
A model may fail because:
- provider credentials are missing or invalid
- the selected model is unavailable to your account or local setup
- a local model server is not running
- the selected model cannot handle the attached source type
- rate limits, quota, or provider availability changed
Fast recovery:
- Confirm the selected model and provider.
- Retry once.
- Check credentials or local server state.
- Switch to another configured model if needed.
- Recheck sources before judging the next response.
Review sources before sending
Most weak AI answers start with missing, noisy, or unreviewed context.
Smart Chat gives you three source paths.
Add context when you know the source
Use Add context when you already know which note or source should ground the answer.
This is the best first-use path because the source is known and easy to check.
Lookup when you know the question, not the notes
Use Lookup context when you know the question but do not know which notes matter.
The workflow is:
- write the question
- run Lookup
- review the candidate sources
- remove anything that should not count as truth
- send the message with the approved set
Lookup proposes sources.
You decide what belongs in the request.
Drag known notes or supported files
Drag notes or supported files into Smart Chat when the source should travel with the current question.
Media, PDF, and image behavior depends on the current model and setup.
Use this path only where the selected model/provider supports the attached source type.
Sending without sources can be intentional
If no sources are attached, Smart Chat can offer a choice before sending:
Typical choices:
- Lookup context: retrieve likely sources for review
- Select context: choose sources manually
- Continue without context: run general chat on purpose
- Cancel: stop and adjust the request
Continuing without sources can be valid.
The important part is making the choice deliberate.
Keep long threads useful
A useful Smart Chat thread should stay recoverable, named, and reviewable.
Name the thread by outcome
Use a thread name that future-you can recognize.
Weak:
Chat with notes
Better:
API integration page rewrite - source review
Use custom instructions for stable behavior
Use custom instructions when repeated threads need stable rules.
Good instruction blocks are short and concrete:
Use only the attached context when answering.
If context is missing, say what source is needed.
Return outputs as checklists.
Cite note titles when making claims.
Custom instructions guide behavior.
They do not remove the need to review the response.
Exclude old detours when the thread drifts
Long threads can inherit old assumptions.
Use include/exclude controls when an old exchange should not affect later replies.
Simple rule:
- keep decisions, constraints, and ground truth
- exclude false starts, discarded drafts, and wrong assumptions
Find and manage saved threads
Smart Chat stores its own API-model thread records.
Use history or Thread Manager when you need to:
- open a saved thread
- rename a thread by outcome
- search or filter by currently supported fields, such as name or key
- delete selected stale threads with confirmation
Do not assume full-message search unless current docs and UI confirm it.
A separate Chat Inbox can list Core codeblock chat-active and chat-done links from Markdown.
That dashboard is different from Smart Chat Thread Manager.
| Thread view | What it manages |
|---|---|
| Chat Inbox with Dataview | Core codeblock links and chat-active / chat-done Markdown state |
| Smart Chat Thread Manager | saved API-model thread records |
Mobile and sync expectations
Core thread-link continuity and API-model thread storage are different.
Core codeblocks store provider thread links in Markdown, so those links sync like normal notes.
Smart Chat API-model thread data lives in .smart-env records, including chat_threads/ and smart_completions/, with possible references to smart_contexts/.
Syncing .smart-env is currently not the recommended default because it can be risky and may cause overwritten data.
For the full answer, see:
Smart Chat mobile and sync FAQ
When codeblocks are enough
Use Core Smart Chat codeblocks when your main job is:
- saving provider thread URLs into the originating note
- marking threads active or done
- using web-based provider UIs inside Obsidian desktop
- keeping mobile useful as a thread bookmark list
- preserving continuity without model/provider setup inside Obsidian
Use this page when you need a configured model, reviewed sources, custom instructions, include/exclude controls, or saved API-model threads.