[DOCS] OTEL client-certificate env vars docs omit trust confirmation requirement for project settings

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/monitoring-usage

Section/Topic

The "mTLS authentication" subsection under "OpenTelemetry > Common configuration variables". The table that lists CLAUDE_CODE_CLIENT_CERT, CLAUDE_CODE_CLIENT_KEY, OTEL_EXPORTER_OTLP_CLIENT_KEY, and OTEL_EXPORTER_OTLP_CLIENT_CERTIFICATE as the OTLP mTLS env vars.

Current Documentation

The "mTLS authentication" section currently reads:

How you configure client certificates for the OTLP exporter depends on the OTLP protocol in use for that signal, set via OTEL_EXPORTER_OTLP_PROTOCOL or the per-signal override. The same configuration applies to metrics, logs, and traces. | Protocol | Client certificate variables | Trust the collector's CA with | | :--- | :--- | :--- | | http/protobuf, http/json | CLAUDE_CODE_CLIENT_CERT, CLAUDE_CODE_CLIENT_KEY, and optionally CLAUDE_CODE_CLIENT_KEY_PASSPHRASE. See Network configuration | NODE_EXTRA_CA_CERTS | | grpc | OTEL_EXPORTER_OTLP_CLIENT_KEY and OTEL_EXPORTER_OTLP_CLIENT_CERTIFICATE, or the per-signal variants such as OTEL_EXPORTER_OTLP_METRICS_CLIENT_KEY to use a different certificate per signal | OTEL_EXPORTER_OTLP_CERTIFICATE | For grpc, the OpenTelemetry SDK reads the standard OTLP variables directly, so existing configurations that set the per-signal metrics variables continue to work.

The corresponding entries in the env vars reference describe each variable in isolation:

| CLAUDE_CODE_CLIENT_CERT | Path to client certificate file for mTLS authentication | | CLAUDE_CODE_CLIENT_KEY | Path to client private key file for mTLS authentication | | CLAUDE_CODE_CLIENT_KEY_PASSPHRASE | Passphrase for encrypted CLAUDE_CODE_CLIENT_KEY (optional) |

The "Client certificate for authentication" snippet in network-config.md similarly documents the env vars but says nothing about where they may be set:

# Client certificate for authentication export CLAUDE_CODE_CLIENT_CERT=/path/to/client-cert.pem

None of these locations call out that the OTEL client-certificate path env vars are protected from untrusted project settings, or that setting them from project settings requires trust confirmation.

What's Wrong or Missing?

A. The v2.1.169 hardening is not reflected in the docs

The changelog entry for v2.1.169 states:

Fixed untrusted project settings being able to set OTEL client-certificate paths without trust confirmation

This means CLAUDE_CODE_CLIENT_CERT, CLAUDE_CODE_CLIENT_KEY, CLAUDE_CODE_CLIENT_KEY_PASSPHRASE, and the OTEL_EXPORTER_OTLP_*_CLIENT_KEY / OTEL_EXPORTER_OTLP_*_CLIENT_CERTIFICATE family can no longer be silently supplied by .claude/settings.json in an untrusted repository. They require workspace trust confirmation. The mTLS documentation, the env vars reference, and the network configuration page all still describe these variables as freely settable environment variables with no mention of this restriction, so an operator who copies an OTLP mTLS example into a project settings file would not expect the values to be ignored or to trigger a trust prompt.

B. No pointer to the trust model used for other dangerous settings

settings.md documents the same kind of protection for other settings that an untrusted repository should not be able to influence. Representative examples that the OTEL client-cert docs do not point to:

• defaultMode: "As of Claude Code v2.1.142, auto is ignored when set in project or local settings (.claude/settings.json, .claude/settings.local.json) so a repository cannot grant itself auto mode."
• skipDangerousModePermissionPrompt: "Ignored when set in project settings (.claude/settings.json) to prevent untrusted repositories from auto-bypassing the prompt"
• autoMemoryDirectory: "From project or local settings, this is honored only after you accept the workspace trust dialog, since a cloned repository can supply this file"

The OTEL mTLS section has no equivalent note, so a reader who skims the env vars table to wire up mTLS for a collector has no way to learn that those four env vars are now in the same restricted category. Users configuring mTLS via project settings (a common pattern when distributing an enterprise collector endpoint through .claude/settings.json) will silently lose the certificate paths and the OTLP exporter will fall back to the system trust store or fail to connect, with no in-doc explanation of why.

Suggested Improvement

Option A: Comprehensive fix

Add a paragraph immediately under the mTLS table in monitoring-usage.md that explains the trust model for these variables:

The OTEL client-certificate path variables above are sensitive: they let the OTLP exporter present a specific certificate (and trust its private key) to your collector. As of v2.1.169, setting CLAUDE_CODE_CLIENT_CERT, CLAUDE_CODE_CLIENT_KEY, CLAUDE_CODE_CLIENT_KEY_PASSPHRASE, OTEL_EXPORTER_OTLP_CLIENT_KEY, OTEL_EXPORTER_OTLP_CLIENT_CERTIFICATE, or the per-signal variants from .claude/settings.json in a repository you have not trusted is ignored. To take effect from project settings, accept the workspace trust dialog for that repository, or set the variables in user, local, or managed settings instead. See Settings for the precedence and trust rules, and Network configuration for the mTLS example.

Also annotate the rows in the env vars table at https://code.claude.com/docs/en/env-vars for CLAUDE_CODE_CLIENT_CERT, CLAUDE_CODE_CLIENT_KEY, and CLAUDE_CODE_CLIENT_KEY_PASSPHRASE with a one-line note such as: "Honored from project settings only after workspace trust is accepted (v2.1.169+)."

Option B: Minimum fix

Add a single sentence under the mTLS table in monitoring-usage.md:

Note: The certificate path variables in this table are not honored from untrusted project settings. Accept the workspace trust dialog, or set them in user, local, or managed settings.

Impact

High - Prevents users from using a feature

Additional Context

Affected Pages:

| Page | Line(s) | Context |
|------|---------|---------|
| https://code.claude.com/docs/en/monitoring-usage | ~96-103 | mTLS authentication section and the table of CLAUDE_CODE_CLIENT_CERT / OTEL_EXPORTER_OTLP_CLIENT_KEY / OTEL_EXPORTER_OTLP_CLIENT_CERTIFICATE variables |
| https://code.claude.com/docs/en/env-vars | ~147-149 | CLAUDE_CODE_CLIENT_CERT, CLAUDE_CODE_CLIENT_KEY, CLAUDE_CODE_CLIENT_KEY_PASSPHRASE env var entries |
| https://code.claude.com/docs/en/network-config | ~88-92 | "Client certificate for authentication" bash example using CLAUDE_CODE_CLIENT_CERT |

Total scope: 3 pages affected.

Related behavior in the same release (v2.1.169): The same release added autoMemoryDirectory to the trust-required list and documented that in settings.md. The OTEL mTLS trust restriction is the v2.1.169 equivalent for the telemetry env vars and should be documented in the same style.

Cross-reference to existing trust-requirement docs: settings.md is the single source of truth for the "ignored from project settings to prevent untrusted repositories from doing X" pattern. The OTEL mTLS page should link to it rather than restate the trust dialog flow.