Configuration¶

OpenMed configuration spans local config files, auth files, session storage, workflow output directories, and environment variables.

Files And Directories¶

Path	Purpose
`~/.openmed/auth.json`	Single OpenMed OAuth credential file created by `openmed login`
`~/.openmed/provider_secrets.json`	Optional per-user OpenAI / Anthropic API keys created by `openmed config provider-set`
`~/.openmed/audit.json`	Optional private audit-trail destination and PHI payload policy
`~/.openmed/traces/`	Local audit trace store and HF-write fallback path
`~/.openmed/sessions/`	Persisted TUI session data
`~/.config/openmed/config.toml`	General CLI configuration
`~/.config/openmed/profiles/`	Custom configuration profiles
`~/.config/openmed/skills/`	User-installed local skills
`~/.config/openmed/mcp_servers.json`	MCP server configuration
`~/.config/openmed/mcp_tools_cache.json`	Cached MCP tool discovery results
`./.openmed/OPENMED_PLAN.md`	Human-readable durable global plan for long workspace-scoped runs
`./.openmed/OPENMED_PLAN.json`	Machine-readable durable global plan ledger and validation state
`/tmp/openmed/artifacts/`	Default workflow artifact root
`/tmp/openmed/cases/`	Default case-run root

Runtime Settings¶

OpenMed loads per-project and per-user runtime settings that control permission policy, tool filtering, and result persistence. These are separate from the general CLI config and profiles.

Path	Purpose
`./OPENMED.md`	Project instructions injected into the system prompt (loaded from git root)
`./.openmed/settings.json`	Project-level runtime settings (loaded from git root)
`~/.openmed/settings.json`	User-level runtime settings

Settings cascade: CLI arguments > project settings > user settings > defaults.

Supported runtime settings keys:

Key	Type	Default	Purpose
`permission_mode`	`auto` / `acceptall` / `denyall` / `plan`	`auto`	Tool execution gating mode
`allow_tools`	list of tool name patterns	none	Tools always allowed (supports wildcards)
`deny_tools`	list of tool name patterns	none	Tools always blocked (supports wildcards)
`ask_tools`	list of tool name patterns	none	Tools that always prompt for approval
`tool_result_persist_threshold_chars`	integer	`50000`	Oversized results written to disk above this threshold

In acceptall, ask_tools does not trigger per-call approval prompts; use deny_tools to block tools that should never run in full-access mode.

Use /config in the TUI to see the effective runtime configuration at any time.

Core Environment Variables¶

Variable	Purpose	Default / behavior
`OPENAI_API_KEY`	Use the OpenAI SDK path directly	unset
`ANTHROPIC_API_KEY`	Use the Anthropic SDK path directly	unset
`OPENMED_ANTHROPIC_PROMPT_CACHE`	Enable Anthropic prompt caching for stable tool/system prefixes	`1`
`OPENMED_ANTHROPIC_PROMPT_CACHE_TTL`	Anthropic cache TTL for tool/system breakpoints; supported values: `5m`, `1h`	`5m`
`OPENMED_ANTHROPIC_AUTOMATIC_CACHE`	Enable Anthropic top-level automatic caching for growing multi-turn conversations	`1`
`OPENMED_ANTHROPIC_RATE_LIMIT_GUARD`	Pace and compact Claude requests before input-token-per-minute limits are exceeded	`1`
`OPENMED_ANTHROPIC_ITPM_LIMIT`	Override Claude input-token-per-minute limit for local throttling	model-family default
`OPENMED_ANTHROPIC_ITPM_SAFETY_RATIO`	Fraction of the ITPM limit OpenMed will use before pacing	`0.85`
`OPENMED_ANTHROPIC_RATE_LIMIT_RETRIES`	Number of automatic retries after Claude `429` rate-limit responses	`2`
`OPENMED_HOME`	Override the `~/.openmed` root used for global auth and sessions	`~/.openmed`
`OPENMED_CONFIG`	Override the config file path	`~/.config/openmed/config.toml`
`OPENMED_PROFILE`	Select a config profile at runtime	unset
`OPENMED_WORKFLOW_ARTIFACTS_DIR`	Override workflow artifact root	`/tmp/openmed/artifacts`
`OPENMED_WORKFLOW_CASES_DIR`	Override case-run root	`/tmp/openmed/cases`
`OPENMED_SKILLS_DIR`	Override the user skills directory	`~/.config/openmed/skills`

Audit And Trace Storage¶

Audit trails are off by default. When enabled, OpenMed writes one JSON trace per agent run to a private destination owned by the operator.

Supported destinations:

hf_dataset — private Hugging Face Dataset repo, recommended for versioned audit history
hf_bucket — private Hugging Face Storage Bucket, when your local huggingface_hub supports bucket APIs
local — local JSON traces only

Enable a private dataset destination:

export OPENMED_AUDIT_HF_TOKEN=hf_...
openmed audit enable --destination hf_dataset --dataset "<user-or-org>/openmed-traces"

Environment variables:

Variable	Purpose	Default
`OPENMED_AUDIT_ENABLED`	Override audit on/off at runtime	config file / off
`OPENMED_AUDIT_DESTINATION`	`hf_dataset`, `hf_bucket`, `local`, or `none`	config file / `none`
`OPENMED_AUDIT_HF_TOKEN`	HF token for private audit writes	`HF_TOKEN` fallback if present
`OPENMED_AUDIT_HF_REPO`	Target private HF dataset repo	config file
`OPENMED_AUDIT_HF_BUCKET`	Target private HF bucket	config file
`OPENMED_AUDIT_PHI_PAYLOAD`	`none`, `fingerprint`, `preview`, or `payload`	`payload`
`OPENMED_AUDIT_FLUSH_MODE`	`per_run` or `manual`	`per_run`
`OPENMED_AUDIT_LOCAL_FALLBACK`	Write local trace if HF write fails	`1`
`OPENMED_AUDIT_LOCAL_PATH`	Local audit trace path	`~/.openmed/traces`

Default phi_payload=payload stores full private transcript and tool payloads. Use preview, fingerprint, or none for smaller traces. See Audit Trail for the trace schema and CLI commands.

Model Provider Keys¶

Codex OAuth and provider API keys are separate auth paths:

openmed login stores Codex OAuth tokens in ~/.openmed/auth.json.
OpenAI and Anthropic API keys can be set with environment variables or stored in ~/.openmed/provider_secrets.json.
~/.openmed/settings.json is for runtime behavior such as permission mode and tool policies, not secrets.

Store provider keys without hand-editing JSON:

openmed config provider-set openai --api-key "sk-..."
openmed config provider-set anthropic --api-key "sk-ant-..."
openmed config provider-show

You can also edit ~/.openmed/provider_secrets.json directly. OpenMed supports literal values and environment-variable references:

{
  "provider": {
    "openai": {
      "options": {
        "apiKey": "{env:OPENAI_API_KEY}"
      }
    },
    "anthropic": {
      "options": {
        "apiKey": "{env:ANTHROPIC_API_KEY}"
      }
    }
  }
}

Provider base URLs are intentionally not part of this user config surface during preview. OpenMed controls the provider endpoints internally.

If you are evaluating OpenMed and need a preview build, request preview access.

Remove a stored key:

openmed config provider-set openai --unset-api-key
openmed config provider-set anthropic --unset-api-key

Provider-key precedence is explicit runtime config, environment variables, then ~/.openmed/provider_secrets.json. Provider config is cached for the running process, so edit it before launching OpenMed.

Anthropic prompt caching is enabled by default. OpenMed marks the stable tool schema block and the system prompt as 5-minute cache breakpoints, and also enables Anthropic's top-level automatic cache control for the growing conversation. This keeps long tool runs from resending the entire prior transcript as fresh input on every turn. Set OPENMED_ANTHROPIC_PROMPT_CACHE=0 to disable all Anthropic caching, or OPENMED_ANTHROPIC_PROMPT_CACHE_TTL=1h for longer-lived workflow sessions.

OpenMed also guards Claude's input-token-per-minute limits locally. Cache reads are excluded by Anthropic's rate-limit accounting, but cache writes and uncached conversation growth still count. The Anthropic SDK tracks uncached input usage, paces requests near the local budget, compacts stale history when a cache miss would make a request too large, and retries transient 429 responses using Claude's retry-after header.

Anthropic works the same way as OpenAI: store an Anthropic key with openmed config provider-set anthropic --api-key ..., export ANTHROPIC_API_KEY, or pass explicit SDK config at launch. Then select a Claude model in the TUI or launch with an explicit provider/model pair.

openmed agent --provider anthropic --model claude-sonnet-4-6

When multiple auth methods are configured, model selection determines the SDK:

Claude models use Anthropic when Anthropic credentials are available.
GPT-5 models use Codex OAuth first when ~/.openmed/auth.json exists, then fall back to the OpenAI provider key.
GPT-4 models use the OpenAI provider key.

Native Medical Services¶

OpenMed ships native medical tools, but many of them use OpenMed's native medical service plane rather than an embedded local model binary.

These are native OpenMed tools. They are not remote MCP servers.

The service split is intentional:

extraction and de-identification run on a dedicated native service plane
terminology, HCC, RAF, RxNorm, LOINC, MedlinePlus, and PubMed run on a dedicated native service plane

The point of that split is not locality for its own sake. It is to keep sensitive or high-volume clinical processing on dedicated service planes that are easier to govern, faster on long unstructured inputs, and more cost-efficient than routing every page through a frontier-model path. General agent reasoning still uses the configured model provider.

During preview, OpenMed operates these native medical services for approved evaluators. Later deployments can keep the same workflow surface while moving the service tier to customer-managed cloud or on-prem infrastructure.

Preview binaries are provisioned for approved evaluators. Request preview access if you do not have an install link yet.

See Native Medical Services for the deployment story and hosting patterns.

MCP Configuration¶

Variable	Purpose	Default
`OPENMED_MCP_CONFIG_PATH`	Override MCP config file path	`~/.config/openmed/mcp_servers.json`
`OPENMED_MCP_TOOLS_CACHE_PATH`	Override tool-cache path	`~/.config/openmed/mcp_tools_cache.json`
`OPENMED_MCP_TOOLS_CACHE_TTL_SECONDS`	Override discovery cache TTL	`3600`
`OPENMED_MCP_<SERVER_ID>_ENABLED`	Override a server's enabled state	unset
`OPENMED_MCP_<SERVER_ID>_URL`	Override a server's URL	unset
`OPENMED_MCP_<SERVER_ID>_HEADERS_JSON`	Override a server's auth headers	unset

Model And SDK Selection¶

The TUI defaults to model name gpt-5.5 with low reasoning.

SDK selection works like this:

If Anthropic provider credentials are present, OpenMed can use Claude models
If Codex OAuth credentials are present, OpenMed can use the Codex SDK path
If OpenAI provider credentials are present, OpenMed can use the OpenAI SDK path
If neither is available, the native fallback remains available

You can choose the model at launch:

openmed agent --model gpt-5.5 --reasoning-effort low

Or at runtime via Ctrl+M or /model.

Reasoning effort¶

Supported values in the current build:

low
medium
high
extra_high

OAuth¶

Authentication commands:

openmed login             # OAuth auth -> ~/.openmed/auth.json
openmed oauth status
openmed oauth logout

Stored credentials are reused until they expire or you replace them. If login/auth status reports that the token is no longer valid, run openmed login -f to refresh the single global auth file.

Session PHI Mode¶

OpenMed exposes a session PHI mode in the CLI/TUI:

full
deid
strict

This mode is stored in session state and shown in the UI. It should be treated as workflow context, not as a universal enforcement layer by itself. Real PHI handling still depends on the tool path and active service boundaries.

Profiles¶

openmed config profiles
openmed config profile-show dev
openmed config profile-use prod

See Profiles for built-in and custom profile details.